SaaSquatch Help Center

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.

Note: 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 sharelink) 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

});

Classic only Note: If your referral program makes use of one of our direct payment provider integrations (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:

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

Use the squatch.widgets method to update/register a user in your referral program and load an embedded Referrer 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', locale: 'en_US' }, engagementMedium: 'EMBED', widgetType: 'REFERRER_WIDGET' }; 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', locale: 'en_US' }, engagementMedium: 'EMBED', widgetType: 'p/referral-program/w/referrerWidget' }; //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 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 if present in the Referred User's browser, for example using a CSS Selector (my_selector):

squatch.ready(function() {

  var element = document.getElementById('my_coupon');

  squatch.init({
    tenantAlias: "test_abzxg88g30tn2"
  });

  squatch.api().squatchReferralCookie().then(function(response) {
    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 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.