squatch.js Quickstart
How to integrate squatch.js V2 javascript to register users, track referral cookies, and place the Referral Widget into your web product.
🔗 1. Include squatch.js loader script in your website
Include squatch.js on your referred user landing page (or all your webpages) To allow tracking and other functionality.
!function(a,b){a("squatch","https://fast.ssqt.io/squatch-js@2",b)}(function(a,b,c){var d,e,f;c["_"+a]={},c[a]={},c[a].ready=function(b){c["_" + a].ready = c["_" + a].ready || [];c["_" + a].ready.push(b);},e=document.createElement("script"),e.async=1,e.src=b,f=document.getElementsByTagName("script")[0],f.parentNode.insertBefore(e,f)},this);
Note: This is an async loader script from our CDN. If you are placing this in HTML, be sure to wrap in script
tags.
🔗 squatch.js & 1st party cookies
The above loader script must be included on your referred user landing page (the page that a new user arrives at after clicking a share link) in order to allow it to create a 1st party cookie.
Learn more about 1st party cookies at our overview here.
🔗 2. Using squatch.js
As squatch.js will load asynchronously, we wait for squatch.js to be ready before using it:
// when squatch.js is ready to use
window.squatch.ready(function(){
//place squatch.js functionality here
});
paymentProviderId
. This parameter should be included in the user object being passed into the squatch.js method only when you wish to set the value.
🔗 Tracking script
Use the squatch.api
method to update/register a user in your referral program without displaying a widget:
squatch.ready(function(){
//configure squatch.js for the tenant you are using
squatch.init({
tenantAlias: 'test_abzxg88g30tn2'
});
//object containing the init parameters for squatch.js
var initObj = {
//the object for the user you want to upsert
user: {
id: 'abc_123',
accountId: 'abc_123',
email: 'dave@example.com',
firstName: 'Dave',
lastName: 'Doe',
locale: 'en_US'
customFields: {
companyName: 'Dave Inc.',
phoneNumber: '(555) 340-0505'
}
}
};
squatch.api().upsertUser(initObj).then(function(response) {
user = response.user;
}).catch(function(error){
console.log(error);
});
});
🔗 Referrer Widget
This implies you have user information and can generate a JWT. If you just want to load a widget and do not need a user upsert on widget load, see Rendering widgets without user information
Use the squatch.widgets
method to update/register a user in your referral program and load an embedded Referrer Widget for a Referrer:
🔗 Popup Widget
To load a widget in a modal window, also known as popup mode, you will need to:
- Set
engagementMedium: "POPUP"
- Include an HTML element with the attribute
class="squatchpop"
.
These example triggers below display a popup widget when the element is clicked:
Button
<button class="squatchpop">Referral Discount</button>
Link
<a href="#" class="squatchpop">Invite a Friend</a>
Div
<div class="btn" class="squatchpop">Love our service? Share the wealth!</div>
Note: To use a custom trigger element, pass a query selector string in the trigger
field in your initObj
. See our squatchJS reference for more information.
🔗 Embedded Widget
To load the a widget in embedded mode you will need to:
- set
engagementMedium: "EMBED"
- include an HTML element with the attribute
class="squatchembed"
where you want the widget to be displayed:
<div class="squatchembed"></div>
Note: Use the container
field in the initObj
to use a custom element as your widget container. See our squatchJS reference and advanced use cases for more information.
🔗
🔗 3. Autofill the Referral Code
The squatch.js library can be used to pickup a referral code from the cookie or just the cookie its self if present in the Referred User's browser, for example using a CSS Selector (my_selector
):
```js
// 1. When squatch.js is ready, run the following function.
squatch.ready(function() {
// 2. Configure squatch.js for the tenant you are using.
squatch.init({
tenantAlias: 'test_abzxg88g30tn2',
});
// 3. Retrieve the element you want to auto-fill the referral code into from the DOM.
// The are many methods to do this but some of the most common include:
// getElementbyId - Retrieve the element by using its id https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById
// getElementByClassName - Retrieve the element by using its className https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByClassName
// getElementByTag - Retrive the element by using its tag https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByTagName
const element = document.getElementById("referralCodeField");
// 4. Make the request to retrieve referral information from the dropped cookie
// Cookies are dropped after a user clicks on a sharelink
// This cookie includes important referral information such as the referrer's referral code
// To read more on our referral cookies see https://docs.saasquatch.com/developer/squatchjs/cookies/
squatch.api().squatchReferralCookie().then(function(response) {
// 5. Retrieve a specific programs referral code from the response and set it on your element
// The response returns referral codes within an object called "codes"
// This object is key value pair where the key is the program id and the value is the referral code
// Example:
// {
// "program-1": "REFERRALCODE1",
// "program-2": "REFERRALCODE2"
// }
// Use your program id to access and apply the correct referral code to your element
element.value = response.codes["program-id];
});
});
```
Using this to prefill a signup form field can reduce the chance of the referral not being attributed or the referred user not receiving their reward. This can be used during registration and with our integrations such as HubSpot, Stripe and Recurly.
🔗 Troubleshooting
Having trouble making a successful Squatch JS init call? When loading the Referral Widget in EMBED
or POPUP
mode, it can return a screen showing that the Referral Program is temporarily unavailable. Please see an example of this screen below:
In the screenshot above, look for the error code in the right bottom corner and reference this code in our issue code list to diagnose why the widget load failed.
🔗 Test Tenant
We strongly recommend you use your Test Tenant while implementing. One of the many added benefits are helpful logs and error messages that will be displayed in your browser's console.
If you are still experiencing problems, please don't hesitate to contact our Support team.
🔗 Additional Resources
More information about Version 2 of our squatch.js library can be found in the library Reference, or in our squatch.js Advanced Use Cases guide which contains more examples.
Learn more about The SaaSquatch Referral Program Loop in our Success Center.