SaaSquatch Help Center

Simple quickstart guide on how to successfully integrate the squatch.js V2 script to register users, track referral cookies, and place the Referral Widget into your web product.

1. Including squatch.js

Include squatch.js in your webpage by including the library from our CDN using this async loader script:

<script>
!function(a,b){a("squatch","https://d2rcp9ak152ke1.cloudfront.net/assets/javascripts/v2/squatch.min.js",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);
</script>

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

});

Classic only Note: If your referral program makes use of one of our direct payment provider intregrations (such as Stripe or Recurly) you will also need to pass SaaSquatch your users' Recurly Account Code or Stripe Customer ID as the 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:

window.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: 'john@example.com',                
      firstName: 'John',       
      lastName: 'Doe' 
    },
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM'
  };

  squatch.api().upsertUser(initObj).then(function(response) {
    user = response.user;
  }).catch(function(error){
    console.log(error);
  })
});

Referral Widget

Use the squatch.widgets method to update/register a user in your referral program and load an embedded Referral Widget for a Referrer:


window.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: 'john@example.com',
firstName: 'John',
lastName: 'Doe' }, engagementMedium: 'EMBED', widgetType: 'REFERRER_WIDGET', jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM' }; squatch.widgets().upsertUser(initObj).then(function(response) { user = response.user; }).catch(function(error){ console.log(error); }); });

window.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: 'john@example.com',
firstName: 'John',
lastName: 'Doe' }, engagementMedium: 'EMBED', widgetType: 'p/program-name/w/referrerWidget', jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM' }; //update/register a referral participant and display a widget squatch.widgets().upsertUser(initObj).then(function(response) { user = response.user; }).catch(function(error){ console.log(error); }); });

To load the Referral Widget in a modal window, also known as popup mode, you will need to:

  • Set engagementMedium: "POPUP"
  • Include an HTML element with the class="squatchpop".

These example triggers below will display a popup widget:

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>

Embedded Widget

To load the Referral Widget in embedded mode you will need to:

  • set engagementMedium: "EMBED"
  • include an HTML element with the class="squatchembed" where you want the widget to be displayed:

    <div class="squatchembed"></div>
    

3. Autofill the Referral Code

The squatch.js library can be used to pickup a referral code from the cookie if present in the Referred User's browser, for example using a CSS Selector (my_selector):

squatch.ready(function() { 

  //configure squatch.js for the tenant you are using
  squatch.init({
    tenantAlias: 'test_a5z3ezgicojry'
  });

  //autofilling the element with selector my_selector
  squatch.autofill('my_selector');

});

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 is mostly used for our Payment Provider Integrations such as 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:

RS032

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.

Our guides section also offers walkthroughs for setting up a successful referral program, including options for different business models and using a wide range of reward types.