Note: these instructions are for GrowSurf v1, an older version of the platform.

This tutorial has a complete code example at this GitHub Repo.

So you want to begin growing your user/customer/subscriber list through a referral program, but you don't have the time or resources to build something in-house. Nor do you want to pay for some of the expensive referral software solutions out there.

That’s why we built GrowSurf, free referral software that lets you provide every new signup a unique referral link.

There are simple ways to integrate GrowSurf using an HTML button or HTML form. But if want to save more information than just a name and email, and you also want to save the data to your own database, you will want to use the GrowSurf JavaScript API. With this, you can tailor the power of GrowSurf referral campaigns to your application's needs.

Here are some use-case examples:

  • Validate user input
  • Manipulate user input to your business needs
  • Utilize other 3rd party integrations
  • Control application flow

The possibilities are endless. Okay "Talkie talkie talkie. No more talkie". Fair enough.

Let's look at an example of how to create a new user account for your application and utilize a referral campaign using the GrowSurf JavaScript API (we will presume you have some general HTML & JavaScript know-how for this example).

  • We will be using Firebase to create a new user account, however you could use any data store or API endpoint of your choice to perform a similar task.
  • We will also use Bootstrap for basic styling.

Lets get started!

Create GrowSurf Campaign

If you haven't read the blog post about how to create a campaign, please read the Creating a GrowSurf Campaign Blog Post

Assuming you already have a GrowSurf account, let's create a new referral campaign for our application with the following attributes:

Campaign Create

After publishing the campaign make a note of the referral url under the Share your unique referral code section in the live campaign editor, which looks something like this:

http://myawesomestartup.com?grsf=CONTACT_ID

We'll get to this later.

Sign Up New Users

Lets start by creating a form that allows a new user to register/signup for our application. When a user completes the form, we will validate the email address and password provided by the user. We will complete the sign up by creating a new user in Firebase. Once that new user account is created successfully within Firebase we will pass the form information to our GrowSurf referral campaign.

Sign up Form

<form id="signupForm" class="form-signup">
  <h2 class="form-signin-heading">Sign up</h2>
  
  <!-- name -->
  <label for="name" class="sr-only">Full Name</label>
  <input id="name" name="name" type="text" placeholder="Full Name">      
  
  <!-- email -->
  <label for="email" class="sr-only">Email address</label>
  <input id="email" name="email" type="email" placeholder="Email address">
        
  <!-- password -->
  <label for="password" class="sr-only">Password</label>
  <input id="password" name="password" type="password" placeholder="Password">
        
  <button id="signupBtn" type="button">Sign up</button>
</form> 

Hopefully this code looks somewhat familiar. We are just creating a simple signup form for site visitors to fill out. The form accepts ** name, email, and password** values, all of which will be required.

Notice that the form contains no action or method attributes. The button within the form is of type button and not submit. This is because we will handle the form submission within our JavaScript. Lets take a look at that.

The final product should look something like this
Signup Form

Event Listeners

//Add a click listener to our signup button within the form
document.getElementById('signupBtn').addEventListener('click', onSubmit);
//Add keydown listener for enter key events
document.getElementById('signupForm').addEventListener('keydown',
	function(event){
		//check if event is from the enter/return key
		if(event.keyCode == 13){
			onSubmit(event);
		}
});

Here we attach two types of event listeners to the form. One for a click event on the "Sign Up" button within the form and another for the keydown event which will handle the enter/return key. Both of these listeners invoke the onSubmit function.

onSubmit()

var onSubmit = function(event){
	var name = document.getElementById('name').value;
	var email = document.getElementById('email').value;
	var password = document.getElementById('password').value;
	
	//validate the form before continuing
	if(isValidSignup(name, email, password)){
		
		//signup user using Firebase Auth API
		signupUser(email, password, function(){
			/*
			 * Invoke the growsurf JS SDK to create a new contact 
			 * within our referral campaign
			 */
			addUserToCampaign('re1vv9', name, email);
		});
		
	} else {
		alert('Please complete the form.');
	}
};

If you remember, the onSubmit() function will be invoked anytime the user clicks or hits the enter/key. Within this function we do the following:

  • Validate the user input (isValidSignup())
  • If the input is valid we invoke the signupUser() function which will add the user to the Firebase data store.
  • Once the user is added to Firebase we will then add the user to the Early Access Launch Campaign referral campaign we created earlier (addUserToCampaign()).

The isValidSignup() function does nothing more but check for non empty values in the form so lets skip that and look at signupUser().

signupUser()

var signupUser = function(email, password, cb){
	//signup user using Firebase
	firebase.auth().createUserWithEmailAndPassword(email, password)
	.then(cb)
	.catch(function(error) {
	   //Firebase returned an error
	   alert('Signup Failed!\n\nFirebase says ' + error.message);
	});
};

Using the Firebase Auth API, we create a new user account using the information provided within the form. If the user account is created successfully the callback function cb() is invoked. Otherwise, we display an alert displaying the error message returned by Firebase.

Keep in mind that for explanatory purposes we are using Firebase but any data store or API endpoint of your choice could be called within this function.

Onward!

Lets assume the Firebase user was created successfully and our callback is invoked. "Nice!". Within that callback, we are going to utilize the GrowSurf JavaScript API to add a new contact to our Early Access Referral Campaign using the addUserToCampaign() function.

addUserToCampaign()

var addUserToCampaign = function(campaignId, name, email){
	growsurf.createContact(campaignId, email, name, {}, function(response){
		if(response && response.meta && response.meta.code === 200){
			var contact = response.data.contact;
			var referralUrl = (window.location.href + '?grsf=' + contact.id);
			alert('Thank you ' + name + '\n\n Your referral link is ' + referralUrl);
		} else {
			alert('Failed to add contact to GrowSurf campaign' + campaignId);
		}
	});
};

By invoking the growsurf.createContact() function we are adding the new contact to the GrowSurf referral campaign we created earlier. Lets take a look at the parameters that we passed to this function.

Params

  • campaignId - The campaign id. This can be found within the campaign integration instructions after the campaign has been published. Its at the end of the path within the form action value. If the form action value is growsurf.com/c/re1vv9 then re1vv9 is the campaignId value to pass to the growsurf.createContact() function.

  • name - The name entered within our signup form

  • email - The email entered within our signup form

  • metadata - Any other metadata to associate to the contact information within GrowSurf. This could potentially be the id of a user within your application or anything really. In this example we are providing an empty object {} so we are not passing any metadata.

  • callback - Callback function to invoke after the call to GrowSurf is complete

After the user has been added to the GrowSurf referral campaign, we are displaying a simple alert to the user but feel free to customize this to something more ascetically pleasing for a better user experience.

Hopefully this gives you a better understanding of how you can customize the flow of your application and still utilize the power of GrowSurf referral campaigns.

If something is still not clear or you feel like something is missing please feel free to send an email to [email protected] anytime.

A complete code example from this tutorial can be found the within this GitHub Repo.

Happy Coding!