Retail

Overview

This guide covers the necessary steps for setting up a successful referral program with Extole.

1. Brand Your Program
2. Tag Your Site
3. Enable Site-to-Store
4. Reward Your Customer
5. Retrieve Your Opt-Ins
6. Design Your Experience

Brand your Program

Create a CNAME for your Domain

📘

Task Duration

This task will typically take an IT/Ops engineering team 10–15 minutes to complete.

You'll want to create a CNAME for your domain so that you can create branded Promotion Links and Share Links.

To set up your CNAME, please complete the steps outlined in Extole DNS Requirements.

Send from Your Branded Email

The referral program will send program emails from you to your customers:

• Welcome Email
• Advocate Stats Email
• Earned Reward Email

The from address for this will typically be something similar to [email protected]. Once this email has been identified, Extole can check if it is configured to allow Extole to send emails from this address.

For details on how to update your SPF DNS records and install Extole DKIM keys, please reference Extole DNS Requirements.

Tag your Site

📘

Task Duration

This task typically takes a web developer 1–2 days to complete.

Extole works with your site using lightweight JavaScript tags. They can go anywhere in the HTML of the page and do not need to be loaded in any specific order. They are asynchronous to ensure fast page loading.

Add the Core Tag (Extole's JavaScript Library)

Extole's JavaScript (JS) library goes on all of your pages. It enables all Extole functionality: call-to-action delivery, sharing experience display, and event tracking.

Add Extole's JS Library as follows:

<!-- BRANDED -->
<script type="text/javascript" src="https://share.companyname.com/core.js" fetchpriority="high" async></script>

<!-- UNBRANDED until CNAME is complete -->
<script type="text/javascript" src="https://companyname.extole.io/core.js" fetchpriority="high" async></script>

Add Marketing Tags

Extole displays CTAs that promote the program directly. Marketing tags tell Extole where to serve CTAs on your website. They also enable tracking, so that you can monitor which marketing placements are driving participation in the program.

Your Extole referral campaign comes with standard marketing tags, which you can enable or disable in the Campaign Editor of your My Extole account:

• global_header
• global_footer
• product
• confirmation
• overlay

To create other marketing tags, please contact [email protected].

For inline call-to-action, there is an HTML snippet to locate it on the page:

<span id="extole_zone_global_header"></span>

An example marketing tag looks like the following:

<script type="text/javascript">
(function(c,e,k,l,a){c[e]=c[e]||{};for(c[e].q=c[e].q||[];a<l.length;)k(l[a++],c[e])})(window,"extole",function(c,e){e[c]=e[c]||function(){e.q.push([c,arguments])}},["createZone"],0);

   extole.createZone({
     name: 'global_header',
     element_id: 'extole_zone_global_header',
     data: {
       "partner_user_id": REPLACE, // RECOMMENDED IF AVAILABLE
       "email": REPLACE,  // RECOMMENDED IF AVAILABLE
       "first_name": REPLACE,  // RECOMMENDED IF AVAILABLE
       "last_name": REPLACE  // RECOMMENDED IF AVAILABLE
     }    
 });
</script>

🚧

Important Note

The values listed above as REPLACE should be replaced with actual values surrounded by quotes. For example: "email": "[email protected]".

Track Conversions

In order to reward your customers for completing a desired action, such as a conversion, you need to communicate to Extole that the event has happened by adding the conversion tag—typically to your order confirmation page. This passes information about the conversion to allow Extole to attribute the purchase to a referral when possible, run quality rules, and run reward rules.

🚧

Important Note

Make certain that you fire the Extole tag for all purchases so Extole will correctly detect referrals and manage the fraud and business rules. Extole ignores the purchases that are not attributed to a referral after processing rules.

An example conversion tag looks like the following:

<script type="text/javascript">
(function(c,e,k,l,a){c[e]=c[e]||{};for(c[e].q=c[e].q||[];a<l.length;)k(l[a++],c[e])})(window,"extole",function(c,e){e[c]=e[c]||function(){e.q.push([c,arguments])}},["createZone"],0);

   extole.createZone({
     name: 'conversion',
     data: {
       "first_name": REPLACE, // RECOMMENDED DYNAMIC VALUE
       "last_name": REPLACE, // RECOMMENDED DYNAMIC VALUE
       "email": REPLACE, // REQUIRED DYNAMIC VALUE
       "partner_user_id": REPLACE, // REQUIRED DYNAMIC VALUE
       "order_id": REPLACE, // REQUIRED DYNAMIC VALUE
       "cart_value": REPLACE, // REQUIRED IF AVAILABLE
       "products": REPLACE, // RECOMMENDED IF AVAILABLE
       "coupon_code": REPLACE // REQUIRED IF AVAILABLE
     }
  });
</script>

🚧

Important Note

If you have a guest checkout flow, ensure the data is being passed properly. The logic used to pass the email address on the converted tag needs to accommodate both a logged in account as well as a guest checkout.

Manage Site to Store

📘

Task Duration

This task typically takes a web developer 1 week to design, build, and integration test with Extole.

In a typical web-to-store flow for a Refer A Friend program, the advocate shares to the friend online, the friend is redirected to your site and, on the friend landing experience, the friend will be asked to provide their email address. In Extole, this step is known as a signup or registration event, which serves the friend a single-use coupon that can either be redeemed online or taken into the store.

In order for Extole to properly reward advocates for the offline referral purchases, you will need to communicate when such purchases occur.

There are two options for sending offline purchase events to your referral program at Extole:

• API
• File upload

Track Offline Purchases - API

Extole requires API calls from the account systems to authenticate with an API identifier provided in the header (OAuth key). Your keys are managed through the Security Center of My Extole.

Create your first key via the "Create New Access Token" button. Our system will temporarily display the newly created random key for you.

Once your API key is created, you can test successful authentication using the Admin API method:

curl -H "Authorization: Bearer XXXX" https://api.extole.io/v2/me/clients

[
  {
    "client_id": "1",
    "name": "<CLIENT_NAME>"
  }
]

Event API Call

For each purchase that occurs in store, an API request is sent to Extole. It is fine for the same order to be sent by the tag as well as by the API as Extole will automatically deduplicate based on the order ID.

An example API call looks like the following:

{
  "event_name": "purchased",
  "data": {
    "first_name": REPLACE, // RECOMMENDED DYNAMIC VALUE
    "last_name": REPLACE, // RECOMMENDED DYNAMIC VALUE
    "email": REPLACE, // REQUIRED DYNAMIC VALUE
    "partner_user_id": REPLACE, // REQUIRED DYNAMIC VALUE
    "order_id": REPLACE, // REQUIRED DYNAMIC VALUE
    "cart_value": REPLACE, // REQUIRED IF AVAILABLE
    "products": REPLACE, // RECOMMENDED IF AVAILABLE
    "coupon_code": REPLACE // REQUIRED IF AVAILABLE
  }
}

The response will be an ID like the following:

{
  "id":"6747711822563808783"
}

Track Offline Purchases - File Upload

If you are looking for a low-technical-lift alternative to API calls, then you can leverage Extole’s batch processing functionality. You can compile all your purchases onto a CSV file and upload the file for processing directly from your My Extole account.

To upload a file, complete the following steps:

• Go to Tech Center > Batch Jobs
• Click + New Batch Job
• Descriptively name your file
• Drag and drop or browse for your file (your file must have an extension of CSV, PSV, or JSON)
• Save the job (it may take some time for your file to process)

An example file looks like the following:

Event_name,first_name,last_name,email,order_id,partner_user_id,cart_value,coupon_code,product 
purchased,Julio,Jones,[email protected],302002754,200728,654.35,RAF507509,“sku01,sku02”
purchased,Caitlyn,Wong,[email protected],304002876,201354,498.35,RAF507588,“sku03,sku02”
purchased,Debbie,Allman,[email protected],302001984,288753,1123.35,RAF988765,“sku03,sku02”

If you would like to upload your file programmatically, you can set up SFTP access. Navigate to the Tech Center main hub and click the + New Server button. You can follow the step-by-step instructions found in the Extole's SFTP Server guide.

Reward your Customers

Your Refer A Friend programs can be configured to reward your advocates and friends with any combination of reward types. These could be either coupons, account credits, gift cards, etc.

📘

Reward Types

Read about Extole reward types in our Product Docs Rewards Overview.

To reward the friends with coupons, the coupon reward supplier will be created from the Rewards page in My Extole. Once the coupon reward supplier is created, coupons can be uploaded via a headless, single-column CSV. You have the ability to subscribe to reward alerts, which will notify you when the rewards fall below your threshold.

Retrieve your Marketing Opt-ins

Your referral program will typically have a checkbox on the advocate share experience and the friend email landing experience allowing the friend to opt in to marketing messages by accepting. After optin, you’ll be able to send additional marketing to these customers beyond the referral program.

Extole is able to push these new opt-ins to your email marketing platform by pushing a file via SFTP server or by calling out to your API at Braze, Klaviyo, etc.

Design your Experience

Your entire referral consumer experience can be configured in the My Extole Campaign Editor. This part of setting up the solution can be done entirely by your marketing and creative team and doesn't require technical involvement. Each template is a comprehensive guide for your designer or marketer to customize.

Creatives are organized in a manner that is easy to understand. For Refer A Friend programs, all creatives that are part of the advocate experience can be found under the advocate tab of your campaign. Similarly, those creatives the friends interact with can be found under the friend tab of your campaign.

Recommended Additional Steps

Product and Category Sharing

If you want to enable advocates to share specific products, then the product_page marketing tag may be placed on your category and product pages to allow advocates to share specific categories or products. Extole will read the Facebook OpenGraph meta tags off of the page and incorporate the product name, description, and image into the share message.

Add Web Analytics Tracking Parameters

You can set up Extole to send web tracking information to various web and email analytics tools through the use of URL parameters.

URL parameters for Google Analytics, Adobe Analytics, etc. can typically be added directly by your marketing or IT team using the Campaign Edit screens.

When passing URL parameters for analytics, there are two configurable destination URLs that can be used:

Promote Destination: This is the URL that is used for all of your promotional links, like you would use in outbound email, Facebook advertising, etc.
Share Destination: This is the URL that is used when friends click on a Share Link and are taken back to your site.

For these URLs you will typically add parameters such as:

• utm_campaign
• utm_medium
• utm_source

For the Share Destination, you may also include a variable {{ share.channel || "SHARE_LINK" }} which will pull in the share channel such as “EMAIL”, “FACEBOOK”, “TWITTER”, “SHARE_LINK”.

Uncommon Additional Steps

Below are some of the topics regarding parts of the process that aren't requirements for most retail experiences, but might be for yours.

Cancellations and Returns

After a referred friend makes a qualifying purchase, Extole will automatically email the advocate a reward after a period of time (typically 3 days). If you have a high return rate for your business, you can send Extole the list of canceled transactions and those orders will not be rewarded. An alternative option would be to reward on shipped events.

To cancel a reward, provide Extole the order numbers that have been canceled before the pending window is over through our API. You can send Extole all cancellations and Extole will discard any that don't match a referral.

An example for sending a canceled event to Extole is as follows:

POST https://api.extole.io/v5/events

{
  "event_name": "canceled",
  "data": {
    "order_id": REPLACE, // REQUIRED DYNAMIC VALUE
    "partner_canceled_id": REPLACE // RECOMMENDED DYNAMIC VALUE
  }
}

Use Your Opt-out List

All emails sent by Extole are CAN-SPAM compliant and honor customer preferences. Referral programs are typically treated as their own segment of emails unique from the normal marketing opt-out list, making this step optional. Each email sent to an advocate or friend will include an unsubscribe link, managed by Extole, that will opt the customer out of the referral program.

If you need to do a more complex opt-out synchronization, Extole can check your opt-out list with a webhook API, or you can upload a list of opt-outs to Extole's SFTP server.