Milestone installation guide

This is a guide about what you can do with your Viral Loops campaign and how to use it for your business.

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

So you’ve created your campaign. Now what? 

This is a guide about what you can do with your Viral Loops campaign and how to use it for your business.

Your campaign needs the following:

  1. A way for participants to join the campaign.

  2. A way for participants to share their unique link and invite friends.

  3. A way for participants to see how many friends they have referred and which milestones they have reached (optional).

Let’s see how you can accomplish all three using the Viral Loops widgets and custom integration options.

Before you begin…

Make sure you have added the Viral Loops campaign javascript snippet in all the following pages:

  • The campaign page which is the page where referral links redirect people. You set this in the Info step of the campaign wizard.

  • In any page where you are going to add a Viral Loops widget (such as the Form Widget). 

  • In any page where you are going to run the “campaign.identify()” javascript call to integrate Viral Loops with your custom form. More on that later.

You can find the campaign javascript snippet in the Installation step of the Campaign Wizard, after selecting "I'll do it myself".

This snippet has two functions:

Firstly, it will identify if someone that arrived on your page was referred there. When this person joins the campaign, it will automatically include the referral code of their referrer in the submission.

Secondly, it provides all the necessary functions for the Viral Loops widgets to work so don’t forget to add it in any page where you have added widgets.

Joining the campaign

The Form Widget

The first and easiest option for getting your visitors to join your campaign is the Form Widget. You can customize it in the Widgets step of the Campaign Wizard. The Form Widget is available on campaigns created with the Milestone Referral, Refer a Friend and Online to Offline templates.

It has two states: the Form State and the Sharing State.

The Form State is the default state, what appears to visitors that have not yet joined the campaign. It displays a form (naturally!) through which they will provide their name (optional or required — up to you) and email address (always required!) and join the campaign.

As soon as the form is submitted, the widget turns into the Sharing State which displays all the available sharing options for the participant.

Where should I put it?

There are a few ways you can use the Form Widget. Here are some examples.

Scenario #1

If the main action you want your users to take on your website is to give you their email, add the Form Widget front and center in your landing page. Capture that lead! 

Then, you might want to redirect participants to a different URL. You can do this so that you have the opportunity to explain your referral campaign in more detail (writing details that you were not willing to put on your landing page) such as, for example, the rewards offered.

That’s also the setup that Harry’s did in their infamous pre-launch campaign.

You can set the Form Widget to redirect by choosing that option when editing the Form State of the widget, in the Widgets step of the Campaign Wizard.

Scenario #2

Another option would be to give your referral program its own place on your website. For example, it could be a dedicated page, eg.

Visitors to that page will be able to see the Form Widget and participate to the referral campaign. In the same page you can also include other available widgets such as the Rewards Widgets (of the Refer a Friend template) or the Milestone Widget (of the Milestone Referral).

If you have a web app, you can have the referral campaign in the “Account” or “Profile” section of logged-in users. Read below for integrating the campaign with your existing sign-up (and log-in) form so that your users don’t have to fill-in their details on the Form Widget but are identified automagically and see the sharing options directly.

An existing (custom) form

Another option for getting your visitors to join the referral campaign would be to use an existing form on your website. This is the best option for custom built websites and web apps.

This solution works on campaigns created with the Milestone Referral, Refer a Friend and Online to Offline templates.

For web apps, this is how you can connect your sign-up (and log-in) form with the Viral Loops campaign so that you can track referred sign-ups.

Your form needs to be “connected” to the campaign so that when someone submits the form they are also added to the campaign. 

For this to work, add the Viral Loops campaign javascript snippet in the page and when the form is submitted run the identify method of our Javascript API.


If you are using Landingi for your landing page then you can use your own custom form. Check out this article to find out how: How to use a Landingi native form for your Viral Loops campaign

The benefit of the custom form is that you can keep using the existing form on your website and start using Viral Loops without changing anything user facing. The drawback is that the integration with the custom form is much harder than simply using the Form Widget and is not supported on most major landing page platforms.

Sharing the link

Bear in mind that even if you skip using the Form Widget to capture participations for your campaign, you will still need to add it somewhere else on your website as it’s the only widget through which participants can get their unique link and invite others. More on that later.

Participation via the URL

There are some platforms where you can’t have the previous option for your custom form but, when the custom form is submitted, the form values (parameters) can be appended on the URL. 

In those cases, make sure the form has the following two hidden fields:

  • autoDetect=1 (the default value should be 1)

  • referralCode (with no default value)

In the form settings, make sure to select to “Post form data to a URL” under the form submission options. The wording might differ from one CMS to the other but you will be able to find this setting under the form submission (or form confirmation) options in most platforms.

The redirect URL of the form should be some page where you have added the Form Widget. When visitors submit the custom form on the first page, they get redirected to the page with the widget with a URL that will look like this: 

This causes the Form Widget to automatically identify the visitor (since their email is a parameter on the URL) and submit them to Viral Loops. The Form Widget will automatically display the Sharing State the moment the visitor is redirected to that page.

Don’t forget that the Viral Loops campaign javascript snippet needs to be installed in both pages.

Where does this work?

Unbounce supports this option. Check out this article to see how it would work on the Refer a Friend template (read the section “Joining with a custom form in Unbounce”).

Coming from an email

Let’s say you want to notify your existing mailing list about your new referral program and you will send them an email about it. But you don’t want them to have to fill-in their details on the Form Widget.

You can include a button (or link) in that message so that when they click it they will get to your website with a URL just like before:

You need to make sure to include the parameter autoDetect=1 and to replace the name (optional) and email (required) with the relevant merge tags in your marketing automation platform.

Just like before, when they click that link and get to the page with the Form Widget, they will automatically see the Sharing State to invite their friends. 

Read more on how to use the URL params.

Server-side submission

If you want to register the new subscribers from the server-side, you can use the

Registration method of our Web API.

Inviting friends & seeing your progress 

As shown, there are several ways someone can join your campaign. However, there is only one way they can invite their friends: the Form Widget.

Regardless of which option you choose, the Form Widget needs to be installed on your website so that participants can invite their friends. 

You can use the options described earlier, such as the custom form integration or the automatic participation via the URL, to make the Form Widget show the Sharing State automatically. If you don’t, that’s still OK and the visitor can just enter their email once more to get their unique link and invite their friends.

It is up to you to choose where to add the Form Widget so that the participants can invite their friends. However, make sure it's somewhere where it's easy to get found and used. 

Lastly, a common practice is to add on that same page other campaign widgets as well, such as the Milestone Widget that participants can use to see the milestones they have reached and rewards they have won. 

Did this article help you? Let us know! 😊

Did this answer your question?