Skip to main content
"The Altruistic Referral" + Your Web App

Everything you need to have your "Altruistic Referral" campaign up and running in your web app.

Fivos Stergiannis avatar
Written by Fivos Stergiannis
Updated over a week ago

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

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 the identify method, including the details of the newly created user.

If you wish to use an API call for identifying the user, take a look at the Registration method of our Web API.

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.

GDPR consent

If you want to capture GDPR consent as well, add the consents property in the user object. The Consent ID can be found in the Settings Page of the app, where the GDPR consents are added:

Step 4: Tracking conversions

Now, when a user makes a conversion, you should track it to Viral Loops using the Track Conversion method.

Or, via an API call if you want to track the conversion from the server-side.

❗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. Retrieve the available pending rewards by using the Get Pending Rewards method as it's described in the API documentation.

Getting participant data

If you also want to get the referrer's details apart from the reward use the Get Participant data method to fetch information about your participants. The response will get you the referrer's details as well!

Marking rewards as redeemed

After your web app has fulfilled the reward, use the Redeem Reward to mark the specific reward as redeemed. That way you won't provide them twice by mistake.


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.

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?