Membership & Loyalty

Overview

Use this guide to set up a membership and loyalty referral program that tracks signups and purchases, then rewards advocates and friends.

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.

Create a CNAME (a DNS record that points one domain to another) for your domain so 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 (Sender Policy Framework) DNS records and install Extole DKIM (DomainKeys Identified Mail) keys, 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 CTAs (calls to action) inline on your page. These tags reference a specific span tag by id and should be placed in the HTML where they will appear.

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

Extole displays CTAs that promote the program. For example, a global_header CTA can add a banner at the top of the screen that says “Refer a friend.” When a customer selects the banner, it opens the Share Experience.

Marketing tags tell Extole where to show CTAs on your website. These tags also enable tracking so you can see which placements drive participation.

Extole recommends emailing advocates a promotion code they can use to apply credits to their account. If your membership program applies account credits automatically instead, restrict sharing to logged-in advocates and include advocate information in the marketing tags.

An Extole campaign comes with these standard marketing tag names:

• global_header
• global_footer
• product
• confirmation
• overlay

You can create additional marketing tags for pages such as your blog or help center. As you get started, contact your Customer Success Manager for help creating these tags.

Marketing Tag Placement

Add a span element to the page where the content should appear. You typically add this element through your CMS or site code. Inline tags require this element; overlay and confirmation tags do not.

<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 data also helps match advocates and friends for rewards, customize emails and shares, and recognize when a different person uses the same browser on a shared device.

Track Signups and Purchases

Track Signups with Registration Tags

Because your business model requires the friend to create an account, track new account creation with a registration tag on your post-signup page. This tag captures that the friend signed up and is eligible for their reward.

The registration tag passes information about the new customer so Extole can attribute the account to a referral when possible, run quality rules, and run reward rules. This supports accurate tracking when the lead completes a purchase.

Fire this tag only when the created account is new. This keeps rewards focused on 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

Reward the advocate after their friend purchases, not after signup. To do this, add the conversion tag to your order thank-you page so Extole receives the purchase event.

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 in the request 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

Send an API request to Extole for each purchase that occurs in store. You can send the same order by tag and API because Extole automatically deduplicates events based on the order ID.

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

{
  "event_name": "purchased",
  "data": {
    "first_name": "Julio",
    "last_name": "Friend",
    "email": "[email protected]",
    "partner_user_id": "00O40000004SQbO",
    "order_id": "122948302lala",
    "cart_value": "10000.00"
  }
}

{
  "id":"6747711822563808783"
}

📘

Additional Fields

In addition to the fields above, you can add fields to any event.

Additional fields added on can be used for:

• Reward Tiering
• Customer Segmentation
• Reporting

Reward your Customers

Deliver the advocate reward directly into their account after the friend purchase is approved. Deliver the friend code through an overlay or email after the friend signs up to become a customer. Extole's quality rules automatically approve or decline friend purchases.

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 tracks an issued account credit to the account. Configure Extole to make a real-time API call to your system when a reward needs to be issued.

In My Extole, provide a web service name, URL, and shared secret. After each reward is earned, Extole makes an outbound API call to the service name you provided. Never publish a real shared secret or bearer token in documentation or client-side code.

POST https://YOURWEBHOOK
Authorization: Bearer REPLACE_WITH_SHARED_SECRET
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 through an API. Schedule a process on your side to call the Extole Rewards API regularly, retrieve rewards earned by each consumer, and apply those 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, connect it to Extole's API so that:

1. Clicks on shared links from mobile devices open the right landing experience for new customer registration.
2. Extole receives mobile registrations and conversions so advocates can be rewarded.
3. Mobile menu items and account screens include the right CTAs.
4. Customers can share from the app or through native mobile sharing dialogs.

See Headless and Mobile API for implementation details.

Optional: Recommended Additional Steps

Add Web Analytics Tracking Parameters

You can set up Extole to send web tracking information to web and email analytics tools with URL parameters, such as UTMs (tracking parameters used by analytics tools).

URL parameters for Google Analytics, Adobe Analytics, etc. can typically be added directly by your marketing or IT team within Extole's Campaign Editor.

Within Campaign Edit, configure two URLs: one for the Advocate and one for the Friend.

Promote Destination

You can find this under the Advocate tab in Campaign Edit. This controls the behavior of your Promotion Links.

When advocates click a promotion link, you can choose to send them to:

• An Extole-hosted zone (such as the advocate Microsite)
• An external URL that you host

In the Advanced settings, you can edit the UTM parameters that are automatically included in the URL.

Share Destination

You can find this under the Friend tab in Campaign Edit. This controls the behavior of your Share Links.

When friends click a share link, you can choose to send them to:

• An Extole-hosted zone (such as the Friend Landing Experience Microsite)
• An external URL that you host

In the Advanced settings, you can edit the UTM parameters that are automatically included in the URL.

Embed the Advocate Stats Dashboard Directly onto a Page

To show an advocate stats dashboard on a page after the user is logged in, such as the My Account page, verify the user and tell Extole who they are.

Complete these two steps:

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

To embed a sharing experience on a dedicated referral page or account page, use the same structure as a marketing tag and set the zone to 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

These steps are not required for most retail experiences, but they may apply to your program.

Creating your own Advocate Code or Link

Extole automatically creates a unique code for every advocate who joins the program. If you want to create your own customer codes, take these steps:

1. Create an API access token in My Extole Security Center.
2. Identify the advocate by creating or updating their person profile with POST /v5/persons or PUT /v5/persons/{person_id}.
3. Check whether the advocate already has a share code with GET /v5/persons/{person_id}/shareables.
4. Create a share code with POST /v5/persons/{person_id}/shareables.

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 email segment, separate from the normal marketing opt-out list, making this step optional. Each email sent to an advocate or friend includes an unsubscribe link, managed by Extole, that opts 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 create your branded domain at Extole and notify your CSM, Extole automatically procures a certificate from Let's Encrypt for your domain.

Verify Advocate Codes

When a potential customer becomes a member of your business, they may go directly to your site and enter an advocate code they received from a friend instead of clicking a referral link.

A valid advocate code tells Extole to capture the signup and run quality rules for the friend reward.

If you want your implementation to give customers immediate feedback when they apply a code, call Extole from the code capture field to check whether the code is a valid referral code.

Implement the code below only if you want to tell the user whether the code is valid before they sign up, similar to a coupon code button on a cart page.

// SCENARIO: A person submitted an advocate code. Verify it is valid, then 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);
    });
}