Introduction:
After this guide, you’ll be able to:
Install the Viral Loops campaign to your website through GTM
Add users to your Viral Loops Campaign through your existing forms and signup flows
Trigger successful referrals (conversions) through any GTM trigger
Use the Viral Loops widgets in your site
This guide is relevant to you if you want to create a flow like this:
Important note:
As of November 23, 2023, Viral Loops does not have an explicit Google Tag Manager Integration. This is a stable workaround using our Google Analytics 4 integration. We’re working on a more native solution.
Important note 2:
You might not need all of the steps for your set-up. For example, you might want to trigger another tag when someone participates in your referral program.
Prerequisites
A. Viral Loops installation with GTM: Sending data to Viral Loops
Installing your Viral Loops campaign snippet (Required)
Participation of new customers/users to Viral Loops
Conversion and closing the Viral Loop
B. Getting Viral Loops data and events to GTM
Activate the Viral Loops Google Analytics 4 integration
Check that the Google Tag Manager receives Viral Loops data
Create the Google Tag Manager Triggers
Use the Viral Loops triggers in your tags
Prerequisites
You have already set up Google Tag Manager on your website
You have a basic understanding of how the dataLayer works. Find out more about it here or ask ChatGPT.
You have already created a Viral Loops Milestone campaign.
If you’re using Google Analytics 4, you have set it up through GTM and NOT directly on your website.
A. Viral Loops installation with GTM: Sending data to Viral Loops
The steps below are about sending data to Viral Loops if you already use Google Tag Manager to manage other apps and install tags.
If you only care about creating GTM Triggers from Viral Loops events, skip this section and move to section B.
Only step 0 is required. Then you can do all or any of the rest of the steps, depending on how much of the flow you want managed by Google Tag Manager.
1. Installing your Viral Loops campaign snippet (Required)
Create a global variable for the Viral Loops campaign ID — which we’ll use through the guide to verify that you’re the campaign owner.
Go to GTM > Variables > User-Defined Variables > New, and name it Viral Loops Campaign ID.
For Variable Type, choose “Constant”.
Set the value to the Campaign ID of your campaign — you can find that at the installation step of your campaign.
Do not forget to save it.
Next, Create a tag.
Go to Tag > New, and create a tag for the Viral Loops snippet. From the Tag Type list, select “Custom HTML” and paste in the script below.
<!-- Start Viral Loops Installation -->
<script id="viral-loops-data" type="application/json">
{ "campaignId": "{{Viral Loops Campaign ID}}" }
</script>
<script id="viral-loops-loader" src="https://app.viral-loops.com/widgetsV2/core/loader.js"></script>
<!-- End Viral Loops Installation -->
You can insert GTM variables into your custom HTML tag by wrapping the variable name with {{variableName}}. This can be helpful for tag reuse in multiple contexts.
For Triggering, select “All Pages” from the default triggers.
Save, and remember to submit the change. This little script simply initiates Viral Loops inside your website to ‘listen’ for the rest of the steps you’ll set up — it does not make any visual differences.
2. Participation of new customers/users to Viral Loops
Participating new customers is about enrolling new contacts of yours to the referral program to give them a referral code and the ability to earn rewards for referring their friends.
If that person comes through a referral link, we need to identify who their referrer is. If they come on their own, we do not do that — but we still want them to get their own referral link. The tag we set in this step covers both cases.
When the participation happens ( the GTM trigger ) depends on your business goals. For example, you can participate someone in the referral program when they signup through a form, when their status changes in a third-party tool, or any other trigger you have inside Google Tag Manager.
It’s required that whatever your trigger is, it can send an “email” variable to Viral Loops so a unique referral code can be generated.
For this guide, we’ll do it with a form submission in this demo website.
We have already set up a Form Submission trigger for this signup form and also created the corresponding Data Layer variable that contains the name (optional) and the email (required)
Go to GTM > Tags > New and create a new Tag named “Viral Loops Ristration”.
For the Tag Type, select custom HTML and paste in the code bellow. It’s important you modify it to pass the required user email, the required Campaign ID, and any other additional data.
<script>
(function() {
var campaignId = "{{Viral Loops Campaign ID}}",
user = {
firstname: "{{Signup form name}}",
email: "{{Signup Form Email}}",
referrer: (function() {
var match = location.search.match(/referralCode=([^&]*)/);
return match ? { referralCode: match[1] } : {};
})()
};
if (window.ViralLoops && ViralLoops.getCampaign) {
ViralLoops.getCampaign(campaignId)
.then(function(campaign) { return campaign.identify(user); })
.then(function(response) { console.log('[Viral Loops] Participant identified'); })
.catch(function(error) { console.error("[Viral Loops] Participation error", error); });
} else {
console.error('ViralLoops not defined.');
}
})();
</script>
You can insert GTM variables into your custom HTML tag by wrapping the variable name with {{variableName}}.
3. Conversion and closing the Viral Loop
Now it’s time to set up what makes a successful referral. In other words, what actions will close the referral loop.
For this guide, we assume you want to count a successful referral when someone performs a specific action like a purchase — not when they just sign up.
In other words, a customer will not get a reward unless the friends they invited also become a customer.
To do that, edit your Viral Loops campaign and click “I’ll do it myself” in the Installation step.
There, scroll a little, and select “A referral is complete when referred friends sign up and then make a conversion (API tracked).”
Now, create we need to create GTM Tag to “tell” Viral Loops that someone converted and to attribute a referral to the person who invited them.
Go to GTM > Tags > New and create a new Tag named “Viral Loops Conversion”
For the Tag Type, select custom HTML and paste in the code bellow. It’s important you modify it to parse the required Campaign ID variable.
<script>
(function() {
var campaignId = '{{Viral Loops Campaign ID}}';
// Uncomment and set the variable in GTM to use a custom referral code.
// var customReferralCode = 'GTM VARIALBE';
function sendConversion(referralCode) {
fetch('https://app.viral-loops.com/api/v3/campaign/participant/convert', {
method: 'POST',
headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({ user: { referralCode: referralCode }, publicToken: campaignId })
}).then(function(response) { return response.json(); }).then(console.log).catch(console.error);
}
(function checkReferralCode() {
var referralCode = typeof customReferralCode !== 'undefined' ? customReferralCode :
window.ViralLoops && window.ViralLoops.campaigns.get(campaignId) ? window.ViralLoops.campaigns.get(campaignId).core.userData.referralCode : null;
referralCode ? sendConversion(referralCode) : setTimeout(checkReferralCode, 1000);
})();
})();
</script>
You can insert GTM variables into your custom HTML tag by wrapping the variable name with {{variableName}}.
For the trigger select anything that makes sense for your business and tracking flow.
For this guide we want to trigger conversions when the customer reaches a the page:
domain.com/thank-you-for-your-purchase
Important Things to Know
Out of the box, this code assumes the conversion does not happen in a different domain or subdomain than that of where the registration happened like so:
domain.com -> Registration
domain.com/thank-you-for-your-purchase -> Conversion
If your conversion happens in something like:
sub.domain.com
seconddomain.com
You need to a more advanced flow to manually pass the user’s identifier (referralcode) yourself across your domains.
B. Getting Viral Loops data and events to GTM
The steps below regard how you can create GTM Triggers and Variables with data from Viral Loops.
Popular use case scenarios:
Send a FB Pixel tag when a Viral Loops referral or participation happens
Send Viral Loops data to Google Analytics 4
1. Activate the Viral Loops Google Analytics 4 integration
Go to your Viral Loops campaign > Edit > Integrations > Google Analytics 4
Skip the measurement ID and enable the integration. Once done, you can go back to the Viral Loops dashboard.
2. Check that the Google Tag Manager receives Viral Loops data
Go to your GTM Account > Workspace > Preview
Fill in the url of the page where you host the Viral Loops form to start the debugger.
Go on and participate to your campaign. Then try to copy the sharing URL.
Go back to the Google Tag Manager debugger window. You should see two Viral Loops API calls for every action you took.
3. Create the Google Tag Manager Triggers
These need to contain the exact Event names Viral Loops send to the dataLayer.
Example:
4. Use the Viral Loops triggers in your tags
Here is what an example event should look like:
And... that's all 😎 If you need any further help, please email us at support@viral-loops.com or just send us a message from the support bubble on the right-bottom corner of your account!