JavaScript SDK

Use the JavaScript SDK to interact with your GrowSurf program and participant data.

Using AI? Follow Build with AI.

Getting Started

Step 1: Make sure the GrowSurf Universal Code is installed

Any webpage with the GrowSurf Universal Code installed can use the JavaScript SDK. You can test this by entering growsurf.open() in your browser's Developer Console.

The SDK acts on the program whose ID is in your GrowSurf Universal Code. Click here for image.

Testing in development?

• If you are testing on a development URL (e.g., http://localhost:3000), you will need to whitelist that URL in the Installation step of the Program Editor. Click here for image.

• We recommend creating two different programs for development and production environments. Learn more here.

grsfReady Event Listener

The GrowSurf Universal Code loads asynchronously. Therefore, if you intend to execute any growsurf functions on page load, you must wait until the library has completely loaded.

When loaded successfully, the GrowSurf Universal Code will dispatch a grsfReady event, notifying any event listeners that it is ready for use. Only then will any GrowSurf JavaScript SDK functions work.

Example of using grsfReady

// Listen and wait for the Growsurf Universal Code to initialize
window.addEventListener('grsfReady', () => {
  console.log('GrowSurf is Ready!');
  // Your code goes here...
});

Depending on script load order, grsfReady may fire before your code adds its listener. If your callback never runs, check for window.growsurf first:

// Check to see if GrowSurf is available
if(!window.growsurf) {
  // Listen and wait for the Growsurf Universal Code to initialize
  window.addEventListener('grsfReady', () => {
    console.log('GrowSurf is Ready!');
    // Your code goes here...
  });
} else {
  console.log('GrowSurf is Already Available');
  // Your code goes here...
}

If you are executing growsurf functions not on page load, we recommend you wrap them in a conditional like this...

Example of using a conditional

// Check if the GrowSurf Universal Code is present
if (window.growsurf) {
    // Then, open the GrowSurf window
    growsurf.open();
}

URL Parameters

On any webpage where you have GrowSurf installed (including the GrowSurf-hosted referral or affiliate portal), you can use the grsf_email URL parameter to ensure that when someone lands on the page, they see their unique referral link right away instead of a signup form.

For example, when an existing participant lands on https://grow.surf/abc123?grsf_email=[e-mail], they can instantly access their unique referral link without needing to log in. Conversely, if it's a non-existing participant, they will be added to your program as a participant, skipping the signup process and seeing their unique link immediately.

Other tips:

• Using grsf_email is also useful for adding new participants on the fly (e.g., add people only when they open your referral or affiliate portal).

• Setting grsf_first_name and grsf_last_name will also set the participant's first name and last name, respectively, if the participant was newly added.

List of URL Parameters

URL Parameter	Description	Example URL
grsf_email	Set this value if you want to automatically add a new participant, or return an existing participant	https://grow.surf/abc123/grsf_email=[e-mail]
grsf_first_name	(Only applies if grsf_email is set) Set this value if you want to add a new participant with a first name	https://grow.surf/abc123?grsf_email=[e-mail] &grsf_first_name=Bob
grsf_last_name	(Only applies if grsf_email is set) Set this value if you want to add a new participant with a last name	https://grow.surf/abc123?grsf_email=[e-mail] &grsf_first_name=Bob &grsf_last_name=Loblaw
grsf_lang	(Business plan or higher) Shows your program in this language, such as es or pt-BR, if the program has it turned on in Options > Languages. The language option in window.grsfConfig takes priority. On GrowSurf-hosted portals, lang also works. Learn more	https://yoursite.com?grsf_lang=es
grsf	(Read-Only) This value represents the referrer's unique GrowSurf ID. You never have to worry about setting this value, as it gets automatically generated in participant's unique referral links.	https://yoursite.com?grsf=z7o8au

Next Steps

• View Tutorials

• View Embeddable Elements

• View Single Page Applications

• View API Reference