> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/developer-tools/javascript-sdk.md). # JavaScript SDK Use the JavaScript SDK to interact with your GrowSurf program and participant data. {% hint style="info" %} **Using AI?** Follow [Build with AI](https://docs.growsurf.com/build-with-ai). {% endhint %} ## Getting Started ### Step 1: Make sure the GrowSurf Universal Code is installed Any webpage with the [GrowSurf Universal Code](/getting-started.md#step-1-install-the-growsurf-universal-code-onto-your-site) installed can use the JavaScript SDK. You can test this by entering [`growsurf.open()`](/developer-tools/javascript-sdk/api-reference.md#open-growsurf-window) in your browser's Developer Console. The SDK acts on the program whose ID is in your GrowSurf Universal Code. [Click here for image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfU8ACBJhil-h8kFAU6%2F-LfU8CXlMq8GdEnHEwxt%2FScreen%20Shot%20on%202019-05-22%20at%2018%3A43%3A17.png?alt=media\&token=3778b13a-db9b-43d3-bce0-eef707391e8a). {% hint style="warning" %} **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](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfU8FwcsZe9b-yjChHs%2F-LfU8rnazUxtZgHvmI4x%2FScreen%20Shot%20on%202019-05-22%20at%2018%3A47%3A27.png?alt=media\&token=d82bbd8e-bff3-471d-af16-3d9edc45facb). * We recommend creating two different programs for development and production environments. [Learn more here](https://support.growsurf.com/article/262-how-can-i-test-in-a-sandbox-or-development-environment). {% endhint %} ## **`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` ```javascript // 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: ```javascript // 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 ```javascript // 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=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 program as a participant, skipping the signup process and seeing their unique link immediately. {% hint style="info" %} **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. {% endhint %} ### 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 |


\&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 |


\&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** * [View Tutorials](/developer-tools/javascript-sdk/tutorials.md) * [View Embeddable Elements](/developer-tools/embeddable-elements.md) * [View Single Page Applications](/developer-tools/javascript-sdk/single-page-applications.md) * [View API Reference](/developer-tools/javascript-sdk/api-reference.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.growsurf.com/developer-tools/javascript-sdk.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.