squatch.js Quickstart

🔗 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

});

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.

Note: Rendering a widget that is flagged to "Automatically pop up on referral" does not require any extra code for squatch.js, and is default behavior from the loader script given above.

🔗 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:

• Classic
• Growth Automation

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',
  referable: 'false'
},
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);
  }); 
});

🔗 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):

• Autofill Code
• Autofill Cookie

    ```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];
    });
  });
  ```

    ```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 cookie 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("referralCookieField");

    // 4. Make the request to retrieve the dropped cookie value
    //  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. Set the value of your element to be the returned cookie
      element.value = response.encodedCookie;
    });
  });
  ```

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.