These instructions are specific to installing "The Altruistic Referral" campaign in a web app. 

Alright! This isn't rocket science but you need to be fairly technical to do it. If you face an issue, do not hesitate to contact us.

Before we begin...

This template was inspired by Airbnb to help you get more purchases, bookings or whatever action is important for your business. It works by rewarding people who refer others to do this action.

(Psst...! If you're looking to incentivize sign-ups then you should go with the "Refer-a-friend" template as it will be more suitable for you 😉)

So, as part of this campaign, your existing customers will be able to share their personal unique link. There will be a pending reward for the invitee, e.g. a discount towards their first order and whenever they complete the "conversion", then a pending reward is created for the referrer, too. 

Here's what you have to do:

  1. Add a bit of Javascript, so that the campaign widgets can be loaded on your platform.

  2. Create the referral dashboard by adding the widgets.

  3. Identify new users and track their conversions.

  4. Check for pending rewards and mark rewards as redeemed.

Please note that this template can be installed only on custom-built pages. WordPress and Woo-Commerce are not supported.

Step 1: A bit of JavaScript

Right before the closing <body> tag in your web app, add the Javascript snippet that you will find in the Installation step of the Campaign Wizard. It should go in your log-in page, your sign up page, on every publicly accessible page and on every page in which you will use any widgets. 

It looks something like this, but be sure to get yours from your Campaign Wizard:

<script>!function(){var a=window.VL=window.VL||{};return a.instances=a.instances||{},a.invoked?void(window.console&&console.error&&console.error("VL snippet loaded twice.")):(a.invoked=!0,void(a.load=function(b,c,d){var e={};e.publicToken=b,e.config=c||{};var f=document.createElement("script");f.type="text/javascript",f.id="vrlps-js",f.async=!0,f.src="https://app.viral-loops.com/client/vl/vl.min.js";var g=document.getElementsByTagName("script")[0];return g.parentNode.insertBefore(f,g),f.onload=function(){a.setup(e),a.instances[b]=e,d&&"function"==typeof d&&d(null,e)},e.identify=e.identify||function(a,b){e.afterLoad={identify:{userData:a,cb:b}}},e.pendingEvents=[],e.track=e.track||function(a,b){e.pendingEvents.push({event:a,cb:b})},e}))}();var campaign = VL.load("YOUR_CAMPAIGN_ID");</script>

If you copy-paste the snippet from this page, make sure to replace YOUR_CAMPAIGN_ID with, well, your campaign ID. You can find that too in the Installation step of the Campaign Wizard.

Step 2: Make your referral dashboard

You want your users to be able to share their unique link, invite their friends and see the status of their invites. You can do that by creating a dashboard inside your web app. You can do that by using the adding these HTML <div>'s inside the page.

For the Sharing Widget, use this:
<div data-vl-widget="sharingWidget"></div>

For the Reward Stats Widget, use this:
<div data-vl-widget="rewardStats"></div>

Step 3: Identifying new users

Right after someone signs up for your app, or just gives you their details, run this JavaScript function, including the details of the newly created user. We've included some example data below.

campaign.identify({
  "firstname": "Michael",
  "lastname": "Bolton",
  "email": "michael@initech.com",
  "createdAt": 1472217120 //Creation date of your user in UNIX timestamp format. Leave empty for new users.
}, function(err, details) {
  campaign.widgets.load();
});


If you wish, you can use an API call for identifying the user: 


Method: POST
Endpoint: https://app.viral-loops.com/api/v2/events
Headers: "Content-Type": "application/json"

//INPUT:
{
    "params": {
        "event": "registration",
        "user": {
            "firstname": "",
            "lastname": "",
            "email": ""
        },
        "referrer": {
            //at least one of these two is necessary if there is a referrer
            "referralCode": "",
            "email": ""
        },
        "refSource": "" //referral channel if available, valid values are email/facebook/twitter/redit/copy
    },
    "apiToken": "s3cretApiT0cken" //replace with the API token of your campaign
}

//OUTPUT
{
  "referralCode": "abc123", eventId: "abc345"
}


Please note: This step is important because it "ties" the invitee with their referrer. You see, when someone visits your website by following a referral URL, as soon as you know their email address you should track that to Viral Loops so that, when they become customers, Viral Loops will know that the conversion can be attributed to their referrer.

If you want to capture GDPR consent as well, use the following:

{

    "apiToken":"MY_TOKEN",

    "params":{

        "event":"registration",

        "user":{

            "firstname": "the user's firstname",

            "lastname": "the user's lastname",

            "email":"the user's email",

            "extraData": { "internalID": "1234" },

            "consents": {

              "2": true // 2 is the ID of the consent.

            }

        },

        "referrer":{

            "referralCode": "the referrer's referralCode (if available)"

        },

        "refSource": "the refSource (if available)"

    }

}

GDPR consents can be added and enabled in the Settings page of the app. The consent ID is displayed here:

Step 4: Tracking conversions

Now, when a user makes a conversion, you should track it to Viral Loops, as follows:

campaign.track("conversion", function(err, data) {
  console.log(err, data);
});

Or, via an API call:

POST https://app.viral-loops.com/api/v2/events
Content-type: “application/json”

Example request:

{
"apiToken": "MySecretT0ken"
"params": {
    "event": "conversion",
    "user": {
        "email": "the email of the user who made the payment"
    }
}
}

The successful response is: processing
 


❗Important note: When a participant invites someone to your app, they will get rewarded after their friend completes your conversion event. This means, that the referrer-referral connection (the number of referrals they have) will be updated on your Dashboard after the conversion. The invitee, will also get their reward after they make a conversion.❗

Step 5: Rewarding

When someone is invited to your platform, a pending reward is created for them. When they convert, a pending reward is created for their referrer.

A pending reward is basically a note in Viral Loops that means that they should get X reward. At any moment, you should be checking Viral Loops for these rewards and provide them.

Use this API call to check for pending rewards:

method	: GET
endpoint: https://app.viral-loops.com/api/v2/pending_rewards
headers: "Content-Type: application/json"

Example request:

https://app.viral-loops.com/api/v2/pending_rewards?apiToken=MySecretToken&user={"email":"zisis@viral-loops.com"}&filter={"limit":10,"skip":25}
  • Replace MySecretToken with your API Token. Find it in the Installation step of your Campaign Wizard.

  • The filter object is optional. It can be used for pagination using limit (default=25, max=25) and skip (default=0).

  • The user object is optional. If provided, only rewards for that specific user will be returned (pagination rules apply here as well). The user object needs the email or referralCode of the user.

Here's an example response to a request without filters:

{
  "pending": [
    {
     "user": {
"firstname": "Zisis",
"lastname": "",
"email": "zisis@viral-loops.com",
"referralCode": "SkuVQmS9W",
"referralCountTotal": 1,
"risk": 0
      },
      "rewards": [
        {
            "id": "reward_NGU0NzA5OTNiOGU1MDJiODM1ZWM",
            "metadata": {
                "reward": {
                    "user": {
                        "email": "zisis@viral-loops.com",
                        "firstname": "Zisis",
                        "lastname": ""
                    },
                    "details": {
                        "rewardName": "Megabytes",
                        "rewardAmount": 500,
                        "rewardType": "programmatic"
                    }
                }
            }
        }
      ]
    },
    ...
  ]
}


👉🏻 If you also wan to get the referrer's details apart from the reward, use this GET call for the invitee:

https://app.viral-loops.com/api/v2/participant_data{
"apiToken": "<API_TOKEN>",
"params": {
"participants": [{
"email": "<invitee_email>"
}]
}
}


The response will get you the referrer's details as well!

Marking rewards as redeemed

Use this API call to mark rewards as redeemed so you don't provide them twice by mistake.

HTTP

method: POST
endpoint: https://app.viral-loops.com/api/v2/rewarded

Example request:

JSON

{
  "rewardId": "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg",
  "user": {
    "email": "dimitris@viral-loops.com"
  },
  "apiToken": "MySecretToken"
}

You can either mark a specific reward as redeemed or all of a user's rewards as redeemed.

  • Provide a rewardId to mark a single reward as redeemed.

  • Provide a user object to mark all of their rewards as redeemed. The user object needs the email or referralCode of the user.

Example response:

JSON

{
  "redeemed": {
    "total": 1,
    "rewards": [
      "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg"
    ]
  }
}

Inviting

You can use this API call to track how many times a participant has invited others. It increases the share counter for the relevant channel.

POST https://app.viral-loops.com/api/v1/social_action

A header Content-Type: application/json is needed.

Request Parameters

{
  "referralCode": "JFI876FDD",
  "postType": "email",
  "apiToken": "MY_TOKEN"
}

Successful response

{
    "status": "ok"
}
  • referralCode: the referralCode of the user doing the invite

  • postType: the channel the invite has been made through. Valid values are facebook, twitter, reddit, email

  • apiToken: The campaign's secret apiToken. Available in the installation step of the campaign wizard.

That's all!

🛒Are you an E-commerce merchant? Check out our blog for 3 ways to introduce your Referral Program to your ecommerce customers.

Do you need more help? Let us know! 





Did this answer your question?