Tutorials
How to implement the GrowSurf JavaScript SDK in common use-case scenarios.
Last updated
Was this helpful?
How to implement the GrowSurf JavaScript SDK in common use-case scenarios.
Last updated
Was this helpful?
Table of contents
Scenario
Sometimes you want people to access your referral campaign from any webpage. Or perhaps you just want to use buttons that look native to your website's branding instead of using the GrowSurf floating widget button.
Just paste <div data-grsf-block-button></div>
anywhere in your HTML, and clicking the element will open up the GrowSurf window.
Just paste <div data-grsf-block-form></div>
anywhere in your HTML, and the GrowSurf form will appear. If you want your participant to be already logged in and see their stats (instead of the form), you can add an attribute data-grsf-email
to have the value of the participant's email.
Important Note:
If you have participant authentication enabled for your campaign, then the participant's unique share link and social buttons will only display if the participant entered your referral program from their browser (either through automatic form detection, the GrowSurf form, or the JavaScript SDK). This is because a browser cookie will be saved that identifies the participant. Otherwise, the signup form will be shown, and the participant can click the login link to get sent a one-time login email.
This is for when you want to redirect to another webpage after a participant successfully signs up for your referral campaign.
Remember to replace https://replaceme.com
with your redirect URL.
Please note that if the redirect is not working, it is most likely because the form submission is failing. If this is the case, please check your browser console for errors.
This code is for demonstration purposes only. You may need to modify it to work on your website.
In English:
In Spanish:
To better illustrate this use-case, consider the following scenarios:
If you have multiple GrowSurf campaigns and want to use the same landing page and/or signup pages, here's how you can load the right campaign depending on where the traffic is coming from.
For each of your campaigns, navigate to Campaign Editor > 5. Installation and update the Share URL to include a ?growsurf_campaign
parameter.
Grab the campaign ID in the address bar of your browser.
See an example in the image below:
Instead of pasting the GrowSurf Universal Code into the <HEAD>
of your webpage(s), add the following code below. Make sure to update the DEFAULT_GROWSURF_CAMPAIGN_ID
value at line 3 to your own default campaign ID.
In this tutorial, you'll learn how to display referral links to users on your login page. The typical use-case for this is to remind returning users of your referral program and conveniently provide their referral link that they can share.
This tutorial uses React, Firebase Authentication, and the GrowSurf JavaScript SDK.
Inside your App.js
, add the following function and use it in a useEffect
:
Important: Make sure to replace x8yi1l
at line 1 with your own campaign ID.
This ensures GrowSurf loads once when the app starts.
For the purpose of this demo, this is the logic that we'll have when a new user registers:
Create the user in Firebase
Redirect them to the Profile page
This is what the register()
function in the Register.js
file looks like:
In the Profile.js
file, we'll show the user’s email and display a Logout button:
When the user logs out, they’re redirected back to the Login page.
When a user logs in, we'll have the following logic be executed:
Here's what we have in the Login.js
file:
In this tutorial, you'll learn how to display a message like “You came through a referral link!” on your signup page using the GrowSurf JavaScript SDK using the following two methods:
The use-case for this scenario is for verifying to referred visitors that they came through a referral link.
This tutorial uses React, Firebase Authentication, and the GrowSurf JavaScript SDK.
Demo:
From this tutorial, the following can be assumed:
The GrowSurf Universal Code will be dynamically injected in App.js
User authentication is via Firebase Auth and Firebase Realtime Database
growsurf.addParticipant(email)
will be called after user signup to track referrals
The login state is managed using a custom AuthContext.js
Inside your App.js
, add the following function and use it in a useEffect
:
Important: Make sure to replace x8yi1l
at line 1 with your own campaign ID.
This ensures GrowSurf loads once when the app starts.
referralId
and show the referral message on the registration pageThis code does two things:
Shows a referral banner only if a referrer ID is stored. The growsurf.getReferrerId()
method checks if there is a referral cookie stored (which would be present if the visitor initially came from a referral link).
Then render the message inside your JSX:
Important note on applying the $50 discount upfront:
Important Note: If your campaign is configured to add participants automatically through a form on your website (), skip this step.
First, in the code where you capture the referred friend's email address, add them to your GrowSurf campaign as a participant with . Let's say you have a signup function called signUpFree()
, here's what that looks like:
Behind the scenes, the GrowSurf Universal Code will associate the referrer (if they exist) with the new participant. At any future date , if this new participant triggers a referral, GrowSurf will provide credit to the referrer.
Then, in the code where the action takes place, trigger the referral with . Let's say you have a function called upgradeToPaidPlan(), here's what that looks like:
Important Note: Make sure your campaign's referral trigger is set to Sign Up + Qualifying Action (). If the referral trigger is set to Sign Up, triggering referrals will not work since referral credit has already been provided.
Make sure you have or set up so that rewards automatically get fulfilled to the participant once they reach a reward goal.
Just add onclick="
"
to any HTML element, and clicking it will open up the GrowSurf window.
Fetch a participant's information using .
If you are using the , you can add the following HTML attribute: data-grsf-redirect-url
.
If you are using your own form via automatic form detection or JavaScript Web API, then include the following snippet of code within the <HEAD>
of the HTML source code. This should be the same page(s) where you have included the . Remember to replace https://replaceme.com
at line 7 with your redirect URL.
When a new visitor lands on your site using their friend's unique link, you can personalize a message for them with and . In this example, we have a simple page with a h1#header
that will display as "Emily S. invited you to pet puppies on-demand" if a referrer exists, otherwise it will display as "Pet puppies on-demand".
In this example, we will only add a participant if they were referred by another participant within your campaign. We will utilize the GrowSurf functions and to do this.
Here we are only adding the participant but if you wish to trigger a referral replace the method with in the example below. The example code also assumes that you have set up a submit listener on your form which will listen for submission events and invoke the callback function described below. If you are not sure how to add a form submission listener .
A few things to notice here are the window.addEventListener
and the form.addEventListener
snippets of code. The window.addEventListener
listens for the GrowSurf script grsfReady
event which is emitted when the . Once the GrowSurf script is ready we are adding a submit
event listener to our form form.addEventListener
to listen for submission events. You will need to get the form element using document.getElementById
using the id of your form for this to work - this is just an example.
The next piece of code we will look at is the onFormSubmit
function that is called when our form is submitted. The function provided by the GrowSurf JavaScript API is used to determine if the submitter of the form was referred. If this function returns a value we then continue to add the participant using the function. You will need to get the value of theuserEmail
input using the id or name of the input element of your form - this is just an example.
Please note that this example will attempt to add a participant on all form submissions regardless if the form is valid or not. If you wish to perform some validation before adding the participant that will require some extra coding to do so but is out of scope for this example.
Let's say you are using the and passing an email address as a data attribute so that a participant gets created. Because GrowSurf needs to wait for a network request to finish, the signup form may be shown for a few seconds or less. To change this behavior to hide the signup form, you can use the following HTML, CSS, and JS (jQuery) code as an example below.
In this example, we'll walk through how to use GrowSurf embeddable elements to support multiple languages on your website. We will use the and elements, customizing data attributes to display text in both English and Spanish.
These examples only use facebook
and twitter
as the enabled social share buttons. If you have other social share options enabled, make sure to account for them.
These examples also assume that you have a custom signup field called "Phone Number" (). Custom fields are supported via (see example usage of phone-number
at lines 6 and 7 in the code snippets below).
If your product has an "", this is a great time to ask for referrals. On your webpage or web app, display the and elements to provoke the participant to share.
In this example, we will use two methods and to update pre-populated social share messages so that the default text is more relevant to your user.
If you need to call this on immediate page load, wrap the JavaScript code in a .
If you need to call this on immediate page load, wrap the JavaScript code in a .
If you need to call this on immediate page load, wrap the JavaScript code in a .
Demo: To view a working demo and to access the full code, .
The first step is to install the by dynamically injecting it into your React app.
Add the user to GrowSurf using
After a successful Firebase login, check if the user exists in your GrowSurf campaign using .
If the user exists in the campaign, call to log them in as a GrowSurf participant.
After tracking the user login state, we can now conditionally display the (aka the referral link) on the Login page — but only after logout.
to fetch the referrer ID (aka the referral code)
to fetch custom reward metadata (for displaying the 50
in "$50 discount will automatically be applied to your account.")
to add new user signups to your GrowSurf campaign
To view a working demo, and navigate to the signup page.
To access the full code, .
The first step is to install the by dynamically injecting it into your React app.
Now switch to Register.js
. Inside a useEffect
, check if a referral ID is stored by calling .
If there is a referrer ID, then show a banner that says "You came through a referral link! $50 discount will automatically be applied to your account." Get the 50
by fetching the reward amount from your GrowSurf campaign's reward metadata by calling :
Uses growsurf.getCampaign()
to fetch the metadata of your campaign's first reward. Note, you'll need to have .
When a new user signs up, you’re already registering them with Firebase Auth. After that, use to add them to your GrowSurf campaign:
This tutorial does not cover how to apply the $50 discount the new user who just signed up. To view how to apply the actual discount, .
Let's say you're a SaaS company that helps social media users gain more followers. You could ask for referrals once a user gains 100 followers.
Add the following HTML code (e.g, in a popup on your webpage):
Add the following JavaScript code: