Web Script

Please begin with the installation and then you can move on to this.

In the installation section, we discussed on how to create Campaign and Referral Links for our AwesomeApp.

With campaign in place, we now wish to capture every visit made to our website through the referral links and track various actions performed by referred users. For this we can make use of the Web-script especially when we are using vanilla JS and HTML.

Step 1: Installation

We need to first install web-script in our website by adding the following script tag in the root html file:

<script src="https://prod-referralapi-script.s3.us-east-2.amazonaws.com/referralapi.min.js"></script> 

Step 2: Initialize Script

Now we are required to initialize the Referral API Class, since Referral-API follows a singleton approach, we are required to initialize it once and use its instance throughout our web-app.

Thus we would initialize it on the root of our project, assuming we a have a root file "main.js", at the top of the file we can initialise the Referral API Script at the top of the file.

const referralAPI = new window.ReferralAPI('your_api_key', 'your_campaign_id')

With this initialization in place, when a user is directed to your website through a referral link, ReferralAPI automatically stores information about the referral link as a cookie. This cookie remains active for 30 days. The presence of this cookie signifies that the current user accessing the website arrived via a referral link.

Everytime a user accesses your website with a referral cookie present, the Referral-API logs an action with the action_type set to 'VISIT.' Therefore, even if a user initially accessed the site via a referral link but signed up on a subsequent visit, potentially without a referral link, they would still be tracked as a successful referral due to the presence of the cookie. You can conveniently monitor these statistics within the analytics tab of a campaign dashboard.

Step 3: Referral Links

In the installation section, we discussed about creating links using Referral-API's API or dashboard interface. However you can create and fetch referral links using our script, eliminating the need for making explicit API calls. We can do this by calling createReferralLink function that the web-script offers.

For our "Summer Referral Bonanza", let us allow one referral link to be associated with every user of ours. Thus before creating a referral link, we are required to check if a referral link exists for our user, for this we can make use of getReferralLinks function.

createReferralLink function takes an optional parameter referrer_id and returns a referral link object.

getReferralLinks function requires referrer_id as argument and retrieves a list of referral links associated with the specified referrer_id for a particular campaign. If no such links exist, the function returns an empty list.

We can implement the following code snippet to generate and retrieve referral links:

const referralAPI = window.ReferralAPI.getInstance();
async function fetchReferralLink() {
    while (!referralAPI.isReady()) {
        // Waits untill referralAPI is ready, always better to wait referral api to be initialized.
        await new Promise(resolve => setTimeout(resolve, 100)); // Wait for 100 milliseconds before checking again
    }

    let link = "";
    // Assuming we have authenticated user's email address handy. For this example we are using email address as referrer id.
    referralAPI.getReferralLinks(referrer_id).then(async (res) => {
        if (res.length == 0) {
            const referralLink = await referralAPI.createReferralLink(referrer_id);
            link = referralLink.referral_link;
        } else {
            link = res[0].referral_link;
        }
        return link;
    }).catch((err) => {
    })

}

Step 4: Tracking Referrals - Referred Users

When users share referral links, there's a possibility that the link may be clicked by existing users of our website. However, the primary goal of our referral program is to expand our user base. Therefore, we aim to differentiate between new users and existing users who arrive on our website through referral links. This distinction allows us to accurately track and attribute new user acquisitions to our referral program, ensuring that our metrics reflect the program's effectiveness in attracting and retaining new users.

ReferralAPI provides functionality to create "Referred User", using createReferredUser function.

The createReferredUser function requires the referred_user_id, an arbitrary string that uniquely identifies a user of your website. It associates a "referred_user_id" with only one referral link belonging to the campaign. This function is responsible for creating a "Referred User" when invoked in the presence of a referral link cookie. It returns Referred User Object in case the referred user gets created otherwise returns null. We can invoke this function when there is successful signup as following:

const referralAPI = window.ReferralAPI.getInstance();

async function signup(email, password) {
       try {
        const response = await fetch('signup', {
            method: 'POST',
            body: JSON.stringify({
                email: email,
                password: password
            }),
            headers: {
                'Content-Type': 'application/json'
            }
        });

        if (response.ok) {
            // Successful SignUp
            
            // Check if referralAPI is ready before tracking referral
            if (referralAPI.isReady()) {
                const referralResponse = await referralAPI.createReferredUser(email);
                // Optionally handle response
            }
        } else {
            // Unsuccessful Signup
        }
    } catch (error) {
       // Handle any error
    }

}

Therefore, any new user who signs up and is directed to the website through a referral link will be categorized as a "Referred User." These users can be viewed under the Referrals tab on the dashboard.

This also solves one part of our problem, that is tracking successful Signups for our “Summer Referral Bonanza”.

Step 5: Tracking Funnels

While we've successfully tracked new sign-ups through our referral program, our focus often extends beyond mere registrations. We're keen to understand the subsequent actions these new users take on our platform, as it enables us to tailor rewards for referrers accordingly. By delving deeper into user behavior post-signup, we can identify valuable engagement metrics such as purchases, subscriptions, or other desired actions.

ReferralAPI offers the createAction function to facilitate tracking and rewarding user actions beyond sign-ups. This function necessitates specifying an action_type as a string, along with metadata - a JSON Object and an optional parameter, referred_user_id.

When utilizing the createAction function without specifying a referred_user_id, it records an action for any user browsing your website while a referral cookie is present. This method treats both existing users and referred users equally, as they are both identified by the presence of the referral cookie. This inclusive approach aids in assessing the overall effectiveness of the referral program, providing insights into user engagement regardless of referral status. Additionally, it enables tracking of actions that may be initiated by unauthenticated users, contributing to a comprehensive understanding of user behavior and program impact.

For example, on AwesomeApp's blog section, users have the option to anonymously like blog posts. By leveraging referral tracking mechanisms, we can monitor the engagement levels of users who arrive through referral links. This includes tracking the number of users who visit our blog section via referral links and the subset of those users who further engage with the content by liking blog posts. This comprehensive approach enables us to assess the effectiveness of our referral program in driving traffic to our blog and fostering user engagement with the content.

Returning to the core objective of any Referral Program, it is essential to effectively track and analyze the actions taken by newly referred users. That is where the referred_user_id field comes in handy.

In the context of AwesomeApp Referral Program, we wish to track every purchase made by the referred user. We can incorporate the following code after successful purchase of any product.

const referralAPI = window.ReferralAPI.getInstance();

async function purchaseProducts(productList) {
    try {
        const response = await fetch('purchase', {
            method: 'POST',
            body: JSON.stringify({
                products : productList
            }),
            headers: {
                'Content-Type': 'application/json'
            }
        });

        if (response.ok) {
            // Successful Purchase
            
            referralAPI.createAction("PURCHASED_PRODUCT", {"productIds" : productList}, email);
        } else {
            // Unsuccessful Purchase
        }
    } catch (error) {
       // Handle any error
    }
}

So, in this scenario, the createAction function is invoked every time any user purchases product(s). However, ReferralAPI only creates actions for those purchases that are done by the "Referred Users".

To achieve this, ReferralAPI checks if the provided referred_user_id (in this case, the user's email, since it serves as the user ID in the campaign design) is present in the Campaign's Referred User section. If the referred_user_id is found, ReferralAPI adds the action and associates it with the referred user. However, if the referred_user_id is not found, ReferralAPI simply ignores the request, as it indicates that the action was not performed by a referred user.

createAction function returns Action Object in case action gets successfully created otherwise returns null.

Please note to create successful action pinning to a referred user, it is not necessary to have a referral cookie, only thing necessary is that provided referred_user_id had already been associated with the camapaign as a "Referred User". However for creating action without pinning it to any user, presence of cookie is important.

In certain scenarios, validating operations like successful purchases of subscriptions through the frontend may not be feasible due to security concerns. In such cases, the validation process is typically handled by our backend or server-side code. As an alternative, actions can be created by directly making a call to the Referral-API's Action API.

Do check out sanbox for better understanding of integration with web-script.

Rewarding Users

This is still under work in progress. In the meantime, you can make use of webhooks to recieve the realtime updates about your referral program enabling you to promptly release rewards to participants.

Please reach out to inquire about a specific rewarding solution.

Next Steps

Checkout out API Reference for detailed guide about each of the methods discussed in this tutorial.