Squatch.js Scripts
This page has a list of the key squatch.js scripts you may need for your implementation. These are general scripts meant for reference purposes. Add your tenant- and program-specific information to ensure they function as intended. To generate your personalized code snippets, sign in to the Admin Portal and go to Settings > Install.
Tip: 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.
đź”— Environment setup
Adding your SaaSquatch tenant alias and JWT to the head in your window allows for easier integration of our widget, event tracking, registration and autofill scripts into individual pages. The squatchToken JWT added here will be used for user upsert when a widget loads.
<script>
window.squatchTenant = 'test_aut32av0b11uc'
window.squatchToken = “o5b236b23632/b326b236236.nb236236326”
// Below used for overriding default config values
window.squatchConfig = {
domain: "<domain>",
npmCdn: "<npmCdn>",
debug: <trueOrFalse>
}
</script>
đź”— Loader script
This async loader script must be included on your referred user landing page in order to create a first-party cookie. If you are placing this in HTML, be sure to wrap it in script tags.
!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);
đź”— Widget scripts
We recommend consulting the Settings > Install page in the Admin Portal to generate a personalized script for your implementation. The general examples provided below are for informational purposes only.
đź”— Widget styles
Squatch.js supports two widget styles: embedded and popup.
Embedded widgets show up directly within your web page or app.
Pop-up widgets are displayed in a modal window. When you use the squatch-popup element, any HTML within the children of the element will serve as a CTA for opening the popup.
đź”— Display a verified access widget
Verified access widgets provide a robust, in-app experience for your referral or loyalty participants. To protect your participants’ personal information, we recommend displaying this widget only to those who have signed in to your product.
JWTs are required for verified access widgets.
Embedded widget
<squatch-embed widget=”w/referral”><div>Loading...</div></squatch-embed>
Popup widget
đź”— Display an instant access widget
Instant access widgets give your participants a simple way to engage with your referral program–without signing into your product or service. They’re available for clients using the current version of the SaaSquatch platform (post-2019).
JWTs are not required for instant access widgets.
Embedded widget
<squatch-embed widget=”w/referral”><div>Loading...</div></squatch-embed>
Popup widget
// Click to open
<squatch-popup widget=”widget-type”><button>Click me to show widget</button></squatch-popup>
Auto popup widget
In addition to the standard embedded and popup widget styles, instant access widgets allow for an automatic pop-up widget to appear whenever the page is loaded. Participants don’t need to interact with your page to trigger a widget load.
đź”— Track user event script
You can use squatch.js to send user events directly to SaaSquatch.
By default, SaaSquatch requires a user object payload JWT to be included with the request when sending a user event. This JWT's payload should be in the format as outlined for the Write Token, including the id and accountId as well as at least one additional user value.
squatch.ready(function(){
//object containing the event object
var eventObj = {
"userId": "abc_123",
"accountId": "abc_123",
"events": [{
"key": "purchase",
"fields":{
"checkout_id": "123456",
"order_id": "234567",
"total": 100,
"revenue": 40,
"tax": 15,
"currency": "USD",
"products": [ {
"product_id": "p_name",
"name": "Product Name",
"price": 85,
"quantity": 1
}]
}
}]
};
// If window.squatchToken is not set, pass in a jwt with .track(eventObj, { jwt })
squatch.events().track(eventObj).then(function(response) {
}).catch(function(error){
console.log(error);
})
});
đź”— Authentication
The requirement for including a JWT in the request can be removed by disabling the Track User Event option on the Settings > Security page. If you choose not to include a JWT, then you can use an empty JSON object instead ({}).
WARNING: Including a JWT is important for fraud prevention and security. We highly recommend including a JWT with an expiry as outlined in the example above, as otherwise anyone with access to the JWT for that participant will be able to send authorized events
đź”— Register participants script
Use the squatch.api method to add or update a user in your referral program without displaying a widget. For example, this method can be used to create a user in SaaSquatch when someone fills out a registration form.
Note that if you added a JWT during the environment setup, then you don’t need to include one with this script too. If there is an existing token on window.squatchToken, then all requests will use that as the default.
squatch.ready(function(){
//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);
});
});
đź”— Autofill script
The squatch.js library can be used to pick up a referral code from the first party cookie generated by the loader script. The library can also use a CSS selector to pick up the cookie itself, if one is present in the referred participant’s browser.
Using the code or cookie to prefill a signup form field can reduce the chance of the referral not being attributed or the referred user not receiving their reward. Autofill can be used during registration and with our integrations such as HubSpot, Stripe and Recurly.
If you want to learn more about using autofill for multiple referral programs, then check out our autofill guide.
js // 1. When squatch.js is ready, run the following function. squatch.ready(function() {
// 2. 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");
// 3. 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) {
// 4. 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];
});
});
đź”— Learn more
đź”— Error codes
We maintain an Issue Code List with details and specific troubleshooting tips for any error codes that you may receive. If you try out the troubleshooting steps and are still experiencing problems, then don’t hesitate to reach out to our Support team for assistance.
đź”— Additional documentation
- Advanced Use Cases: Go beyond the basic scripts and learn how to reference existing user data, render a widget without requiring user information, and more.
- Signed Requests: Learn how to require a JWT or an API key when sending data to SaaSquatch.
- Tracking Cookies: Learn more about squatch.js and first-party cookies.
- Issue Code List: Find details and troubleshooting steps about error codes you encounter.
- squatch.js Reference: Full list of methods available.