Membership & Loyalty

Overview

This guide will walk you through the five necessary steps for setting up a successful referral program:

1. Brand your Program
2. Tag your Website
3. Reward your Customers
4. Design your Experience (done by your creative team)
5. Add to your Mobile App

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.

📘

Related Content

• Find your domain in the settings page of My Extole
• How to set up your program domain

Tag your Website

Extole works with your site using lightweight JavaScript tags. The core tag must be included on every page of your site and contains Extole's JavaScript Library.

Extole tags 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.

Marketing tags display CTA s inline on your page. These tags will reference a specific span tag by id and should be placed into the HTML inline where they will be displayed.

Add the Core Tag (Extole's JavaScript Library)

Extole's JavaScript library must be placed on all of your pages using the core tag. This tag is used to activate the Extole system and ensures that any other Extole tags on your page work properly.

The core tag can be found under your program’s branded domain (refer.brand.com). If you haven't set up your branded domain yet, you can load the tag from the Extole unbranded domain.

Find your active referral domain and use that for your core tag. It will look like brand.extole.io (unbranded) or refer.brand.com (branded).

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

<!-- UNBRANDED -->
<script type="text/javascript" src="https://brand.extole.io/core.js" fetchpriority="high" async></script>

Add Marketing Tags

In order to drive participation, Extole displays CTAs that promote the program. For example, a global_header CTA will add a banner element to the top of the screen that will say something like “Refer a friend.” When clicked or tapped, the banner will take the user to the Share Experience.

Marketing tags tell Extole where to serve CTAs onto your website. These CTAs are clickable entities that advertise your program to your customers and visitors. These marketing tags also enable tracking, so that you can know which marketing placements are driving participation in the program.

Extole recommends rewarding your advocates by having Extole email advocates a promotion code they can use to apply credits to their account. If your membership program will reward the advocate automatically with account credits (and not by emailing a promo code to the advocate), then you will need to restrict all sharing behind login and include advocates' information in the marketing tags.

An Extole campaign comes with a standard marketing names:

• global_header
• global_footer
• product
• confirmation
• overlay

It's easy to create additional marketing tags if you want to add CTAs to additional pages like your blog, help pages, and so on. As you're getting started, contact your Customer Success Manager to help learn how to create these additional tags.

Marketing Tag Placement

There is a span section that goes into your web page where the content will appear. This is typically done through your CMS or on site. It is required for all tags that put content inline (but not required for overlay and confirmation tags).

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

Additionally, there is the script tag that loads the targeted content from the program and inserts it onto the page in the span tag.

Below is an example of a global_header tag:

<span id="extole_zone_global_header"></span>
<script type="text/javascript">
  /* Start Extole */
  (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);
  /* End Extole */

   extole.createZone({
     name: 'global_header',
     element_id: 'extole_zone_global_header',
     data: {
       "partner_user_id":"00O40000004SA1AA", // DYNAMIC VALUE
       "email": "[email protected]",  // DYNAMIC VALUE
       "first_name": "April",  // DYNAMIC VALUE
       "last_name": "Advocate"  // DYNAMIC VALUE
     }     
  });
</script>

🚧

Important Note

Extole uses the visitor's name, email, and id to personalize their experience. This practice also aids in matching advocates and friends for rewards, customizing emails and shares, and recognizing when the user at a given browser has changed, which can occur on shared computers.

Track Signups and Purchases

Track Signups with Registration Tags

Because your business model requires the friend to create an account, you need to track those account creations. In order to capture that the friend signed up and is eligible for their reward, you add a registration tag to your post-signup page.

The registration tag passes information about the new customer to allow Extole to attribute the account to a referral when possible, run quality rules on the account, and run reward rules on the account. This helps successful tracking when the lead goes on to complete the purchase.

This tag should only fire if the account created is new. This will solidify the goal of rewarding for new customer memberships.

<script type="text/javascript">
  /* Start Extole */
  (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);
  /* End Extole */

   extole.createZone({
     name: 'registration',
     data: {
       "first_name":"Julio",  // DYNAMIC VALUE
       "last_name":"Friend", // DYNAMIC VALUE
       "email":"[email protected]", // DYNAMIC VALUE
       "partner_user_id":"00O40000004SQbO", // DYNAMIC VALUE
       "advocate_code":"ref3lb" // IF USED
     }
  });
</script>

🚧

Important Note

Make certain that you fire the Extole tag for all new registrations so that Extole will correctly attribute registrations and manage the fraud and business rules. Please provide all customer information so that our customer support tools can be used to handle inquiries.

Track Purchase Events with Conversion Tags

It is our recommendation that you reward the advocate after their friend purchases, not after sign-up. In order to do this, you need to communicate to Extole a purchase has happened by adding the conversion tag to your order thank you page.

The conversion tag passes information about the purchase to allow Extole to attribute the conversion to a referral when possible, run quality rules, and run reward rules. Extole will discard the conversions that are not attributed to a referral after processing rules.

🚧

Important Note

Make certain that you fire the Extole tag for all conversions so that Extole will correctly attribute conversions and manage the fraud and business rules.

<script type="text/javascript">
  /* Start Extole */
  (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);
  /* End Extole */

   extole.createZone({
     name: 'conversion',
     data: {
       "first_name":"Julio", // DYNAMIC VALUE
       "last_name":"Friend", // DYNAMIC VALUE
       "email":"[email protected]", // DYNAMIC VALUE
       "partner_user_id":"00O40000004SQbO", // DYNAMIC VALUE
       "partner_conversion_id":"00O415320037eWy", // DYNAMIC VALUE
       "cart_value":"20.00", // DYNAMIC VALUE
       "coupon_code":"QA754AZ" // DYNAMIC VALUE
     }
  });
</script>

Track Purchases In Store / Offline

After registration, your new customer's first purchase might be made in store or after a home setup. The conversion, therefore, will need to be sent via an API call that occurs after the offline purchase or via a file delivered through an SFTP connection.

Create Extole API Keys

Extole requires API calls from account systems to authenticate with an API identifier provided in the header (OAuth key).

Your keys are managed through the My Extole Security Center.

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

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

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

[
  {
    "client_id": "1",
    "name": "Demo"
  }
]

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.

POST https://api.extole.io/v5/events
Authorization: Bearer XXX

{
  "event_name": "purchased",
  "data": {
    "first_name": REPLACE,
    "last_name": REPLACE,
    "email": REPLACE,
    "partner_user_id": REPLACE,
    "order_id": REPLACE,
    "cart_value": REPLACE
  }
}

{
  "id":"6747711822563808783"
}

📘

Additional Fields

In addition the above fields, any additional fields can be added onto any event.

Additional fields added on can be used for:

• Reward Tiering
• Customer Segmentation
• Reporting

Reward your Customers

The advocate reward should be delivered directly into their account after the friend purchase is approved, and the friend code is delivered via overlay or email after they sign up to become a customer. The friend purchases should be automatically approved or declined after Extole's quality rules run.

Reward Friends

The friend coupon codes are uploaded into My Extole by your marketing team. You may need to create an easy process for them to generate batches of one-time-use or multi-use coupon codes.

Extole can be configured to pass these coupon codes into your friend landing URL using your parameter to display the coupon code to the friend.

You will then go into My Extole > Rewards to create and upload rewards.

Reward using Webhooks

Issue Account Credits via Webhook

When an approved conversion occurs, Extole will track an issued account credit to the account. Extole can be configured to make a real-time API to your system to inform it a reward needs to be issued.

In My Extole, you will provide a web service name, URL, and shared secret. After each reward is earned, Extole will make an outbound API call to the service name you provided.

POST https://YOURWEBHOOK
Authorization: Bearer 7049bee0bcbb149b597e2c3d0d334e3daea0f97410bd38bd5a9f15f053937b4d
Content-Type: application/json

{
    "type": "reward_earned",
    "event_id": "qb3jju459ugjr2aojk5e",
    "event_time": "2020-05-29T14:14:18.548Z",
    "reward_id": "bf67905b4e1b41daf39c30f0",
    "reward_supplier_name": "Advocate Account Credit",
    "reward_supplier_id": "701e681a9e46c8b6778f3452",
    "partner_reward_supplier_id": "Advocate Account Credit",
    "reward_supplier_type": "CUSTOM_REWARD",
    "person_id": "6816411215104951917",
    "partner_user_id": "1036950000",
    "face_value": 50,
    "face_value_type": "USD",
    "data": [
      "recipient_email": "[email protected]"
    ],
    "message": null,
    "schema_version": 1
}

Reward using APIs

Issue Account Credits via API

Extole can make rewards available via an API. Schedule a process on your side that will call into the Extole Rewards API on a regular basis to pull back the rewards that have been earned by each consumer. You can then apply these rewards to each account.

POST https://api.extole.io/v2/rewards?state=earned&reward_supplier_type=custom-reward
Authorization: Bearer XXXX
Content-Type: application/json

[
  {
    "reward_id": "6626084585458921557",
    "cause_event_id": "6625713485380188505",
    "reward_supplier_id": "fd6d46833d459fb13071e261",
    "campaign_id": "6624279975852929111",
    "person_id": "6620831314790485965",
    "partner_user_id": "06e2077f-80af-4b67-89cb-2fddd7de0f4f",
    "email": "[email protected]",
    "state": "EARNED",
    "face_value": 9,
    "face_value_type": "USD",
    "partner_reward_id": null,
    "created_at": "2018-11-20T15:12:18.461-08:00"
  },
]

🚧

Important Notes

In the call above replace XXXX with your access token.

Fulfill Events via API

Let Extole know that rewards have been fulfilled via an API. Schedule a process on your side that will call into the Extole Events API on a regular basis to share the rewards that have been fulfilled.

POST https://api.extole.io/v5/events
{
  "event_name": "reward_fulfilled",
  "data": {
    "reward_id" : "bf67905b4e1b41daf39c30f0",
    "partner_reward_id" : "RewardId123459",
    "message": "successful fulfillment"
  }
}

{
  "id":"6747711822563808783"
}

🚧

Response Field

The API results can contain various IDs that will be ignored. The preferred method to reconcile with Extole is to use your Partner Conversion Id (order number).

Reward using Files (SFTP)

Issue Account Credits via File

When an approved conversion occurs, Extole will track an issued account credit to the account. The earned rewards report will be automatically made available in your account on the Extole SFTP server on a daily basis.

The conversion file can be downloaded from the Extole SFTP system or pushed to your SFTP system.

📘

SFTP Resources

Using Extole's SFTP Server

Our system uses the following naming convention:
earned-reward-report-YYYY-MM-DDTHHMMSS.csv

Fulfill Rewards via File

After the rewards have been fulfilled, you can upload a response file back to the Extole SFTP to transition the reward to fulfilled.

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.

Integrate with your Mobile App

If you have a mobile app, then it is essential that you connect to Extole's API to make certain:

1. That clicks on links shared to friends on mobile devices go to the right landing experience to register a new customer
2. That Extole knows about the registrations and conversions on mobile (because we need to reward the advocates!)
3. That we add appropriate promotion (remember Calls to Action?) in menu items and on account screens.
4. That we enable sharing from the mobile phone, whether in the app or using the native sharing dialogs

Please take a look at our Mobile App Guide for more details about how to implement.

Recommended Additional Steps

Embed the Advocate Stats Dashboard Directly onto a Page

If you want to have an advocate stats dashboard directly onto one of your pages after the user is logged in, for example on the My Account Page, you will want to verify the user and tell Extole who they are.

You will need to do 2 things:

1. Add an advocate_stats_embedded tag, which looks exactly like a marketing tag, to the page where you want to serve the creative.
2. Verify consumers so that their data displays: Verifying Consumers

Embed a Share Experience Directly onto a Page

If you want to embed a sharing experience on a dedicated referral page or account page, the tag looks exactly same as marketing tags, you would just call the zone referral_page or account_page.

Enable Product Sharing

If you want to enable your advocates to share specific products, then the product 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.

Optional 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.

Creating your own Advocate Code or Link

Extole will automatically create a unique code for every advocate that comes through the program. If you want to create your own codes for your customers you will need to take the following steps:

1. Create Token to call the Extole API
 Get Token
2. Identify the Advocate
 Create or Update User Profile
3. Get Share Code (if one exists):
 Get My Share Links (Shareables)
4. Create Share Code: Create Share Link (Shareable)

Use your Opt-out List

All mails sent by Extole are CAN-SPAM compliant and honor the 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.

1. Extole Opt-out Check: Opt Out API
2. File-based Opt-Out List Management: Opt Out Files

Upload an SSL Certificate for your Branded Domain

When you created your branded domain at Extole and notify your CSM, Extole will automatically procure a certificate from LetsEncrypt for your domain.

Verify Advocate Codes

When a potential customer is going become a member of your business, there is a good likelihood that they will not click on a referral link but will rather go to your site directly and enter an advocate code they received from their friend.

That advocate code, provided it is valid, will tell Extole to capture the sign up in our system and then run quality rules to reward to the friend.

If you want your implementation to return feedback to the customer right when they attempt to apply the code, you can find those integration details here. That means that in the code capture field you will need to call Extole to ask if the code is a valid referral code.

You only need to implement the code below if you want to tell the user before she signs up that it was a valid code or not (similar to an apple coupon code button on a cart page).

// SCENARIO: Person on has submitted an advocate code, verify it is real, apply a coupon:

function promptForAdvocateCode() {
    // TODO - implemented by client
}

submitAdvocateCode("ADVOCATE_CODE", function (error, response) {

    if (error) {
        // handle error
        return;
    }

    isRewardable(function (error, response) {
        if (error) {
            //handle error
            return
        }
        applyReward();
    });
});

function isRewardable(callback) {
    extole.require(["core-root:///shared/person-rewardable-service.js"], function (personRewardableService) {
        personRewardableService.isRewardable(callback);
    });
}

function submitAdvocateCode(advocateCode, callback) {
    extole.require(["core-root:///shared/person-relationship-service.js"], function (personRelationShipService) {
        personRelationShipService.createRelationship(advocateCode, callback);
    });
}