JavaScript Web API
Use the JavaScript Web API to interact with your GrowSurf campaign and participant data.
Getting Started
Step 1: Make sure the GrowSurf Universal Code is installed
When you have the GrowSurf Universal Code installed on a webpage, that webpage has access to the JavaScript Web API, and you are ready for development. You can test this by entering growsurf.open()
in your browser's Developer Console.
The unique campaign ID from your GrowSurf Universal Code is the campaign that is the target. 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 Campaign Editor. Click here for image.We recommend creating two different campaigns for development and production environments. Learn more here.
grsfReady
Event Listener
grsfReady
Event ListenerThe 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 Web API functions work.
Example of using grsfReady
grsfReady
In some cases, the GrowSurf Universal script may already be available and the grsfReady
event may have already fired. This depends on how long it takes your scripts to load and can happen for various other reasons.
If your grsfReady
callback isn't being invoked on thegrsfReady
event we recommend you check to see if the growsurf
script is already available before adding the event listener callback with a conditional like this...
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
URL Parameters
On any webpage where you have GrowSurf installed (including the GrowSurf-hosted referral 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=bob@loblaw.com
, 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 campaign 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 (i.e., when a person shows high intent to share, they land on your referral portal, and only then are they added to your GrowSurf campaign).
Setting
grsf_first_name
andgrsf_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=bob@loblaw.com
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=bob@loblaw.com
&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=bob@loblaw.com
&grsf_first_name=Bob
&grsf_last_name=Loblaw
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
Last updated