Tutorials

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

Table of contents

Scenario
Example 1: Trigger a referral on qualifying action (e.g, on conversion, 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 6: Only add a participant if they were referred
Example 7: Hide the GrowSurf embedded form until a GrowSurf participant is detected
Example 8: Add internationalization support for the GrowSurf embedded form and embedded invite
Example 9: Update pre-populated share and email invite messages to capitalize on a customer "aha moment"

Example 1: Trigger a referral on qualifying action (e.g, on conversion, 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 referred friend's email address, 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 Sign Up + Qualifying Action (see image). If the referral trigger is set to Sign Up, 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

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

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="[e-mail]">
</div>

<!-- You can also completely customize the Embedded Form, shown in this example -->
<div data-grsf-block-form
 data-grsf-email="[e-mail]"
 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 = '[e-mail]'; // 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

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

<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 lastNameAsString = (lastName).toString();
						const newHeader = `${firstName && lastName ? firstName + ' ' + lastNameAsString.charAt(0) + '. invited you to pet puppies on-demand' : 'Pet puppies on-demand'}`;
						const headerEl = document.getElementById('header');
						headerEl.innerHTML = newHeader;
					}
				});
			}
		});
	</script>
</html>

Example 6: Only add a participant if they were referred

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 growsurf.getReferrerId() and growsurf.addParticipant() to do this.

Here we are only adding the participant but if you wish to trigger a referral replace the growsurf.addParticipant()method with growsurf.triggerReferral() in the example below. The example code also assumes that you have setup 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 here is an example.

Step 1: Make sure the GrowSurf Universal Code is installed

Step 2: Add code

This code is just an example and will not work on all sites. It simply demonstrates a few key components which are listed below.

index.html

<html>
	<body>
		<h1 id="header">Pet puppies on-demand</h1>
		<!-- Example form only, this must be replaced with your actual form -->
		<form id="form">
  		<label>Email: <input name="email" type="text"></label>
  		<button type="submit">Submit form</button>
		</form>
	</body>
	<script>
	// Listen for the GrowSurf Ready Event
	window.addEventListener('grsfReady', () => {
		// Add our a listener to the example form to listen for submissions
		const form = document.getElementById('form');
		form.addEventListener('submit', onFormSubmit);
	});
	
	// Callback function that is invoked when a new visitor has just submitted a form on your website
	const onFormSubmit = (event) => {
	    // Get the value of the email - Update this depending on your form
	    const userEmail = event.target.email.value;
	    // Check to see if the submitter was referred
	    if (window.growsurf && !!window.growsurf.getReferrerId()) {
	        // Only Add the participant if they were referrered
	        window.growsurf.addParticipant(userEmail);
	    }
	    event.preventDefault();
	};
	</script>
</html>

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 GrowSurf script is ready. 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 getReferrerId() 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 addParticipant() 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.

Example 7: Hide the GrowSurf embedded form until a GrowSurf participant is detected

Let's say you are using the GrowSurf embedded form 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.

Step 1: Make sure the GrowSurf Universal Code is installed

Step 2: Add code

HTML

<div data-grsf-block-form
  data-grsf-email="[e-mail]"
  class="hide-until-grsf-auth"></div>

CSS

.show-after-grsf-auth { display: initial }
.hide-until-grsf-auth { display: none }

JS (jQuery)

// Check if a participant is logged-in, and display auth views based on if there is a participant
function showGrsf() {
	var participantAuth = growsurf.getParticipantId();
	if (participantAuth) {
    $('.hide-until-grsf-auth').addClass('show-after-grsf-auth');
	} else {
		// Subscribe to a 'GrowSurf signup' event listener
		growsurf.subscribe('signup', function(participant) {
		  $('.hide-until-grsf-auth').addClass('show-after-grsf-auth');
		});
	}
}

// See if GrowSurf is available
if(!window.growsurf) {
  // Listen and wait for the Growsurf Universal Code to initialize
  window.addEventListener('grsfReady', function() {
  	showGrsf();
  });
} else {
  showGrsf();
}

Example 8: Add internationalization support for the GrowSurf embedded form and embedded invite

In this example, we'll walk through how to use GrowSurf embeddable elements to support multiple languages on your website. We will use the Embedded Form and Embedded Invite elements and customize data attributes to display text in English and Spanish.

Step 1: Make sure the GrowSurf Universal Code is installed

Step 2: Add code

Embedded Form

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" (see image). Custom fields are supported via kebab-case (see example usage of phone-number at lines 6 and 7 in the code snippets below).

In English:

<div data-grsf-block-form
 data-grsf-field-first-name-label="First name"
 data-grsf-field-first-name-placeholder="First name"
 data-grsf-field-first-name-label="Last name"
 data-grsf-field-first-name-placeholder="Last name" 
 data-grsf-field-phone-number-label="Phone number"
 data-grsf-field-phone-number-placeholder="Phone number"
 data-grsf-share-instructions="Share this unique link with your friends"
 data-grsf-copy-link-button-text="Copy Link"
 data-grsf-email-button-text="Share"
 data-grsf-email-button-message="I just saved $X,XXX by using this service! {{shareUrl}}"
 data-grsf-email-button-subject="Check this out friend"
 data-grsf-facebook-button-text="Share"
 data-grsf-facebook-button-message="I just saved $X,XXX by using this service! {{shareUrl}}"
 data-grsf-twitter-button-text="Share"
 data-grsf-twitter-button-message="I just saved $X,XXX by using this service! {{shareUrl}}">
</div>

In Spanish:

<div data-grsf-block-form
 data-grsf-field-first-name-label="Primer nombre"
 data-grsf-field-first-name-placeholder="Primer nombre"
 data-grsf-field-first-name-label="Apellido"
 data-grsf-field-first-name-placeholder="Apellido" 
 data-grsf-field-phone-number-label="Número de teléfono"
 data-grsf-field-phone-number-placeholder="Número de teléfono"
 data-grsf-share-instructions="Comparte este enlace único con tus amigos"
 data-grsf-copy-link-button-text="Copiar link"
 data-grsf-email-button-text="Cuota"
 data-grsf-email-button-message="¡Acabo de ahorrar $X,XXX al usar este servicio! {{shareUrl}}"
 data-grsf-email-button-subject="Mira esto amigo"
 data-grsf-facebook-button-text="Cuota"
 data-grsf-facebook-button-message="¡Acabo de ahorrar $X,XXX al usar este servicio! {{shareUrl}}"
 data-grsf-twitter-button-text="Cuota"
 data-grsf-twitter-button-message="¡Acabo de ahorrar $X,XXX al usar este servicio! {{shareUrl}}">
</div>

Embedded Invite

These examples only use google as the enabled address book. If you have other address books enabled, make sure to account for them.

In English:

<div data-grsf-block-invite
 data-grsf-input-placeholder-text="Enter email addresses here"
 data-grsf-preview-link-text="Preview your message"
 data-grsf-preview-subject-label="Email Subject"
 data-grsf-preview-subject-placeholder="Check this out friend"
 data-grsf-preview-subject="Check this out friend"
 data-grsf-preview-message-label="Email Message"
 data-grsf-preview-message-placeholder="I just saved $X,XXX by using this service! {{shareUrl}}"
 data-grsf-preview-message="I just saved $X,XXX by using this service! {{shareUrl}}" 
 data-grsf-submit-button-text="Send Invites"
 data-grsf-google-button-text="Import Google Contacts"
 data-grsf-contact-picker-search-text="Search"
 data-grsf-contact-picker-suggestions-text="Suggestions"
 data-grsf-contact-picker-results-text="Results"
 data-grsf-contact-picker-load-more-button-text="Load More">
</div>

In Spanish:

<div data-grsf-block-invite
 data-grsf-input-placeholder-text="Ingrese las direcciones de correo electrónico aquí"
 data-grsf-preview-link-text="Vista previa de su mensaje"
 data-grsf-preview-subject-label="Asunto del email"
 data-grsf-preview-subject-placeholder="Mira esto amigo"
 data-grsf-preview-subject="Mira esto amigo"
 data-grsf-preview-message-label="Mensaje de correo electrónico"
 data-grsf-preview-message-placeholder="¡Acabo de ahorrar $X,XXX al usar este servicio! {{shareUrl}}"
 data-grsf-preview-message="¡Acabo de ahorrar $X,XXX al usar este servicio! {{shareUrl}}" 
 data-grsf-submit-button-text="Enviar invitaciones"
 data-grsf-google-button-text="Importar contactos de Google"
 data-grsf-contact-picker-search-text="Buscar"
 data-grsf-contact-picker-suggestions-text="Sugerencias"
 data-grsf-contact-picker-results-text="Resultados"
 data-grsf-contact-picker-load-more-button-text="Carga más">
</div>

Example 9: Update pre-populated share and email invite messages to capitalize on a customer "aha moment"

If your product has an "aha moment", this is a great time to ask for referrals. On your webpage or web app, display the GrowSurf embedded form and GrowSurf embedded invite elements to provoke the participant to share.

In this example, we will use two methods growsurf.updateSocialShareMessage() and growsurf.updateEmailInviteMessage() to update pre-populated social share messages so that the default text is more relevant to your user.

Step 1: Make sure the GrowSurf Universal Code is installed

Step 2: Add code

To better illustrate this use-case, consider the following scenarios:

Social media SaaS

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):

<div>
    <h2>💯 Alert!</h2>
    <p>Amazing, you just hit 100 followers this past week.</p>
    <div data-grsf-block-form
         data-grsf-share-instructions="Get your next month on us when you refer a friend"
         data-grsf-copy-link-container-style="{'display': 'none'}"></div>
    <div data-grsf-block-invite></div>
</div>

Add the following JavaScript code:

// Sign up (or log in) your user as a GrowSurf participant
const userEmail = '[e-mail]'; // Replace with the user's email address
growsurf.addParticipant(userEmail);

// Set the initial message and subject line
const message = "I've just gained 100 followers by using this tool! {{shareUrl}}";
const subjectLine = "Check this out!";

// Update the social share messages
growsurf.updateSocialShareMessage('email', message, subjectLine);
growsurf.updateSocialShareMessage('facebook', message);
growsurf.updateSocialShareMessage('twitter', message);
growsurf.updateSocialShareMessage('pinterest', message);
growsurf.updateSocialShareMessage('sms', message);
growsurf.updateSocialShareMessage('whatsapp', message);

// Update the pre-populated email invite message and subject line
growsurf.updateEmailInviteMessage(message, subjectLine);

If you need to call this on immediate page load, wrap the JavaScript code in a grsfReady Event Listener.

Enterprise messaging app

Let's say you're a messaging SaaS (e.g, Slack). You could ask for referrals once a team sends 2,000 messages in a workspace.

Add the following HTML code (e.g, in a popup on your webpage):

<div>
    <h2>Woohoo, you've just sent 2,000 messages!</h2>
    <p>That's 6 days worth of time saved in productivity.</p>
    <div data-grsf-block-form
         data-grsf-share-instructions="Share your victory:"
         data-grsf-copy-link-container-style="{'display': 'none'}"></div>
    <div data-grsf-block-invite></div>
</div>

Add the following JavaScript code:

// Sign up (or log in) your user as a GrowSurf participant
const userEmail = '[e-mail]'; // Replace with the user's email address
growsurf.addParticipant(userEmail);

// Set the initial message and subject line
const message = "We've just sent 2,000 messages using this service and have saved 6 days of productivity. Love this service! {{shareUrl}}";
const subjectLine = "Check this out!";

// Update the social share messages
growsurf.updateSocialShareMessage('email', message, subjectLine);
growsurf.updateSocialShareMessage('facebook', message);
growsurf.updateSocialShareMessage('twitter', message);
growsurf.updateSocialShareMessage('pinterest', message);
growsurf.updateSocialShareMessage('sms', message);
growsurf.updateSocialShareMessage('whatsapp', message);

// Update the pre-populated email invite message and subject line
growsurf.updateEmailInviteMessage(message, subjectLine);

If you need to call this on immediate page load, wrap the JavaScript code in a grsfReady Event Listener.

Food delivery service

Let's say you're a food delivery service company (e.g, Doordash). You could ask for referrals once the user leaves a positive review after a delivery.

Add the following HTML code (e.g, in a popup on your webpage):

<div>
    <h2>Loving Doordash?</h2>
    <div data-grsf-block-form
         data-grsf-share-instructions="Get your next meal on us, up to $20 when you refer a friend."
         data-grsf-copy-link-container-style="{'display': 'none'}"></div>
    <div data-grsf-block-invite></div>
</div>

Add the following JavaScript code:

// Sign up (or log in) your user as a GrowSurf participant
const userEmail = '[e-mail]'; // Replace with the user's email address
growsurf.addParticipant(userEmail);

// Set the initial message and subject line
const message = "I just ordered delicious Wing's spicy noodle soup with DoorDash. 5/5 experience! Get $20 off your first order: {{shareUrl}}";
const subjectLine = "Check this out!";

// Update the social share messages
growsurf.updateSocialShareMessage('email', message, subjectLine);
growsurf.updateSocialShareMessage('facebook', message);
growsurf.updateSocialShareMessage('twitter', message);
growsurf.updateSocialShareMessage('pinterest', message);
growsurf.updateSocialShareMessage('sms', message);
growsurf.updateSocialShareMessage('whatsapp', message);

// Update the pre-populated email invite message and subject line
growsurf.updateEmailInviteMessage(message, subjectLine);

If you need to call this on immediate page load, wrap the JavaScript code in a grsfReady Event Listener.