GrowSurf Docs
GrowSurf Docs
API Reference
System Status
Contact Support
GrowSurf Docs
GrowSurf Docs
Welcome
Getting Started for Web
API Guidelines
API Response Codes
🔧 Integrate
JavaScript Web API
Tutorials
Embeddable Elements
Single Page Applications
API Reference
REST API
🎁 Automate Rewards
Webhooks
Zapier
Integromat
Tango Card
⚙️ Additional Integrations
Mailchimp
HubSpot
Slack
Powered by GitBook

Tutorials

How to implement the GrowSurf JavaScript Web API in common use-case scenarios.

Table of contents

Scenario

​Example 1: Trigger a referral on custom event (e.g, on purchase or upgrade)​

​Example 2: Open the GrowSurf window on button click​

​Example 3: Display a participant's unique share link and referral count inline on a webpage​

​Example 4: Redirect to another URL after a successful participant signup​

​Example 5: Add a personalized message to your Share URL for a warm welcome​

Example 1: Trigger a referral on custom event (e.g, on purchase or upgrade)

​Step 1: Make sure the GrowSurf Universal Code is installed​

Step 2: Add the participant

Important Note: If your campaign is configured to add participants automatically through a form on your website (see image), skip this step.

First, in the code where you capture the new person's email, add them to your GrowSurf campaign as a participant with growsurf.addParticipant(). Let's say you have a signup function called signUpFree(), here's what that looks like:

your-script.js
// In this example, a new person is just signing up for a free account
const signUpFree = (userEmail) => {
    // ...code that registers a new user...
    // Then add the new user as a participant in your GrowSurf campaign:
    if (window.growsurf) {
        growsurf.addParticipant(userEmail);
    }
};

Behind the scenes, the GrowSurf Universal Code will associate the referrer (if they exist) with the new participant. At any future date within the referral credit window, if this new participant triggers a referral, GrowSurf will provide credit to the referrer.

Step 3: Trigger the referral

Then, in the code where the action takes place, trigger the referral with growsurf.triggerReferral(). Let's say you have a function called upgradeToPaidPlan(), here's what that looks like:

your-script.js
// In this example, the user upgrades to a paid plan
const upgradeToPaidPlan = (userEmail) => {
    // ...code that upgrades the user...
    // Then trigger this action as a referral trigger:
    if (window.growsurf) {
        growsurf.triggerReferral(userEmail);
    }
};

Important Note: Make sure your campaign's referral trigger is set to Custom Event (see image). If the referral trigger is set to Signup Event, triggering referrals will not work since referral credit has already been provided.

Remember to set up reward fulfillment automation

Make sure you have Webhooks or Zapier set up so that rewards automatically get fulfilled to the participant once they reach a reward goal.

Example 2: Open GrowSurf window on button click

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.

​Step 1: Make sure the GrowSurf Universal Code is installed​

Step 2: Add code

Use Embeddable Elements
Use JavaScript Web API
Use Embeddable Elements

Add the Embedded Button anywhere in your HTML

Just paste <div data-grsf-block-button></div> anywhere in your HTML, and clicking the element will open up the GrowSurf window. 

index.html
<!-- Here's the simplest solution: -->
<div data-grsf-block-button></div>
​
<!-- Here's a customized solution: -->
<div data-grsf-block-button
 data-grsf-button-style="{'background-color': '#117a8b', 'font-family': 'Arial', 'color': '#FFFFFF', 'border-radius': '6px' }"
 data-grsf-button-text="Join My Referral Program">
</div>
Use JavaScript Web API

Add onclick="growsurf.open()" to any HTML element

Just add onclick="growsurf.open()" to any HTML element, and clicking it will open up the GrowSurf window. 

index.html
<!-- Works on any HTML element. Here's a <div> example: -->
<div onclick="growsurf.open()">Refer Friends</div>
​
<!-- Here's a <button> example: -->
<button onclick="growsurf.open()">Refer Friends</button>

Example 3: Display a participant's unique share link and referral count inline on a webpage

​Step 1: Make sure the GrowSurf Universal Code is installed​

Step 2: Add code

Use Embeddable Elements
Use JavaScript Web API
Use Embeddable Elements

Add the Embedded Form anywhere in your HTML

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 via automatic form detection, via the GrowSurf form, or via JavaScript Web API). 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.

index.html
<!-- Providing just this code will make the GrowSurf form appear: -->
<div data-grsf-block-form></div>
​
<!-- Add a `data-grsf-email` attribute to authenticate the participant: -->
<div data-grsf-block-form
 data-grsf-email="gavin@hooli.com">
</div>
​
<!-- You can also completely customize the Embedded Form, shown in this example -->
<div data-grsf-block-form
 data-grsf-email="gavin@hooli.com"
 data-grsf-button-style="{'background-color': '#5890E7', 'color': '#fcfcfc', 'font-family': 'Sans', 'font-size': '12px'}"
 data-grsf-email-button-style="{'background-color': '#5890E7', 'color': '#fcfcfc', 'font-family': 'Arial', 'font-size': '12px'}"
 data-grsf-email-button-text="Share"
 data-grsf-twitter-button-style="{'background-color': '#5890E7', 'font-family': 'Arial', 'font-size': '12px'}"
 data-grsf-twitter-button-text="Share"
 data-grsf-facebook-button-style="{'background-color': '#5890E7', 'font-family': 'Courier New', 'font-size': '12px'}"
 data-grsf-facebook-button-text="Share"
 data-grsf-pinterest-button-style="{'background-color': '#5890E7', 'letter-spacing': '1.2', 'font-size': '12px'}"
 data-grsf-pinterest-button-text="Pin It"
 data-grsf-share-instructions="Share this unique link with your friends">
</div>
Use JavaScript Web API

Call growsurf.getParticipantByEmail()

Fetch a participant's information using growsurf.getParticipantByEmail().

Here's an example of retrieving the participant data, then updating the #share-url and #referral-count HTML elements to show their unique referral link and referral count.

index.html
<!DOCTYPE html>
<html>
<head>
	<title>Your Referral Stats</title>
	<!-- The GrowSurf Universal Code -->
	<script type="text/javascript">
		(function(g,r,s,f){g.growsurf={};g.grsfSettings={campaignId:"REPLACE_ME_WITH_YOUR_CAMPAIGN_ID",version:"2.0.0"};s=r.getElementsByTagName("head")[0];f=r.createElement("script");f.async=1;f.src="https://growsurf.com/growsurf.js"+"?v="+g.grsfSettings.version;f.setAttribute("grsf-campaign", g.grsfSettings.campaignId);!g.grsfInit?s.appendChild(f):"";})(window,document);
	</script>
</head>
<body>
	<input id="share-url" type="text" disabled>
	<div id="referral-count"></div>
	
	<script>
    // Listen and wait for Growsurf to initialize
    window.addEventListener('grsfReady', () => {
        const participantEmail = 'sarah@website.com'; // replace with your user's email
        // Get the GrowSurf participant's information
		growsurf.getParticipantByEmail(participantEmail).then(participant => {
			document.getElementById("share-url").value = participant.shareUrl;
			document.getElementById("referral-count").innerHTML = participant.referralCount;			
		});
    });	
	</script>
</body>
</html>

Example 4: Redirect to another URL after a successful participant signup

This is for when you want to redirect to another webpage after a participant successfully signs up for your referral campaign.

​Step 1: Make sure the GrowSurf Universal Code is installed​

Step 2: Add code

Use Embeddable Elements
Use JavaScript Web API
Use Embeddable Elements

If you are using the Embedded Form, you can add the following HTML attribute: data-grsf-redirect-url.

Remember to replace https://replaceme.com with your redirect URL.

<div data-grsf-block-form
 data-grsf-redirect-url="https://replaceme.com">
</div>
Use JavaScript Web API

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 GrowSurf Universal Code. Remember to replace https://replaceme.com at line 7 with your redirect URL.

<script>
// Listen and wait for the Growsurf Universal Code to initialize
window.addEventListener('grsfReady', () => {
  console.log('GrowSurf is Ready!');
  // Your redirect code goes here....
  growsurf.subscribe('signup', (participant) => {
    window.location.replace("http://replaceme.com");
  });
});
</script>

Please note: 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.

Example 5: Add a personalized message to your Share URL for a warm welcome

When a new visitor lands on your site from using their friend's unique link, you can personalize a message for them with growsurf.getReferrerId() and growsurf.getParticipantById(). 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".

​Step 1: Make sure the GrowSurf Universal Code is installed​

Step 2: Add code

index.html
index.html
<html>
	<body>
		<h1 id="header">Pet puppies on-demand</h1>
	</body>
	<script>
		window.addEventListener('grsfReady', () => {
			const referrerId = growsurf.getReferrerId();	
			if (referrerId) {
				growsurf.getParticipantById(referrerId).then(participant => {
					if (participant) {
						const { firstName, lastName } = participant;
						const newHeader = `${firstName && lastName ? firstName + ' ' + lastName.charAt(0) + '. invited you to pet puppies on-demand' : 'Pet puppies on-demand'}`;
						const headerEl = document.getElementById('header');
						headerEl.innerHTML = newHeader;
					}
				});
			}
		});
	</script>
</html>
🔧 Integrate - Previous
JavaScript Web API
Next
Embeddable Elements
Last updated 2 months ago
Contents
Table of contents
Example 1: Trigger a referral on custom event (e.g, on purchase or upgrade)
Step 1: Make sure the GrowSurf Universal Code is installed
Step 2: Add the participant
Step 3: Trigger the referral
Example 2: Open GrowSurf window on button click
Step 1: Make sure the GrowSurf Universal Code is installed
Step 2: Add code
Example 3: Display a participant's unique share link and referral count inline on a webpage
Step 1: Make sure the GrowSurf Universal Code is installed
Step 2: Add code
Example 4: Redirect to another URL after a successful participant signup
Step 1: Make sure the GrowSurf Universal Code is installed
Step 2: Add code
Example 5: Add a personalized message to your Share URL for a warm welcome
Step 1: Make sure the GrowSurf Universal Code is installed
Step 2: Add code