The Rave Custom Integration (1.0.0)

The Rave offers bespoke integration options, which allow you to integrate The Rave onto your site / store. By integrating with the rave, you are enabling your customers to have the best referral experience available.

1. Our simple referral experience is generally shown to customers after they have have completed a purchase at your site (see below).
2. Once the customer refers to their friend via a link, that friend is then redirected to your store. At this stage we append the URL with some metadata which shows that the customer has been referred via The Rave. (see more in Redirection)
3. Generally this friend will be granted a discount (subject to how you configure The Rave).
4. Once the friend completes their transaction, you will need to notify The Rave that the transaction has occurred (see more in Redemption)
5. The Rave performs billing with your company, and disburses rewards to the original customer.

The Rave custom post-purchase widget is used to display an interactive experience to your customers after they have made a purchase. It facilitates serving the referral link to the user and prompts them to share and be reminded of your referral offer in future.

An example of the post-purchase widget is shown below:

The widget supports operating in two modes:

• API-driven Mode: In this mode, you supply the widget with your merchantId and the Id of a referral link you created using The Rave API. The widget will then pull and display any required information automatically.
• Script-driven Mode: In this mode, you populate a special global JavaScript object in your users browser with customer and order information, and the widget will create and serve the referral link on your behalf.

API-driven Mode is generally preferred for more granular control over your integration with The Rave. However, services powered by server-side rendering (e.g. PHP, Razor Pages etc.) may struggle to use this setup due to the additional page-load delay introduced by the API calls. For this reason, Script-driven Mode is provided as an alternative.

Before injecting the script in API-driven mode, you need to call out to The Rave API to:

• Create a customer record for the customer if one does not already exist. You should persist the returned customerId for future use.
• Create a referral for the customer. The returned referralId will need to be provided to the widget.

You can then inject The Rave Post-Purchase Widget into your site by including the following HTML snippet at your desired rendering location. Note that the widget will occupy all the horizontal space you offer it, so you may need to perform some styling on the container.

<div id="rave_goesHere"></div>
<script src="https://scripts.therave.co/custom-post-purchase.js?merchantId={{YOUR_MERCHANT_ID}}&referralId={{CREATED_REFERRAL_ID}}">

Be sure to replace the {{YOUR_MERCHANT_ID}} and {{CREATED_REFERRAL_ID}} placeholders with your actual merchant Id and referral Id. If you are testing in our staging environment, simply exchange the hostname for the script above with scripts.staging.therave.dev .

In Script-driven Mode, you populate a global JavaScript object with all the information The Rave needs to create a referral link for your customer. You then inject the script into your site.

An example of building up this object in JavaScript is shown below:

window._raveCustomIntegration = {
    customerEmailAddress: "john.smith@gmail.com",
    customerFirstName: "John",
    customerLastName: "Smith",
    customerIntegrationId: "YOUR_INTERNAL_CUSTOMER_ID",
    referralTitle: "White Sneakers",
    referralImageUrl: "https://cdn.someserver.com/img/1234.jpg",
    referralIntegrationId: "YOUR_INTERNAL_ORDER_ID"
};

JavaScript Parameters

You can then inject The Rave Post-Purchase Widget into your site by including the following HTML snippet at your desired rendering location. Note that the widget will occupy all the horizontal space you offer it, so you may need to perform some styling on the container.

<div id="rave_goesHere"></div>
<script src="https://scripts.therave.co/custom-post-purchase.js?merchantId={{YOUR_MERCHANT_ID}}">

Be sure to replace the {{YOUR_MERCHANT_ID}} placeholders with your actual merchant Id. If you are testing in our staging environment, simply exchange the hostname for the script above with scripts.staging.therave.dev .

When a referred customer is redirected to your site from The Rave, they will be redirected to your site with a query string parameter of (rave=[referralId]). The [referralId] is a unique id which is atttributed to the original sharer of the link. This code will need to be passed back to The Rave (see create redemption), once the referred customer has completed their transaction.

Below are the details for the API endpoints available.

Someone who will refer or be referred

A customer's intent to refer

A successful referral conversion

A refund against a Redemption