SaaSquatch Help Center

squatch.js - Advanced Use Cases

Examples of advanced use cases that the squatch.js V2 library supports.

Just getting started?

If you are just getting started, we recommend you take a look at our squatch.js Quickstart Guide.

Reference Existing User Data

It is possible to reference information about the identified user: 

// when squatch.js is ready to use
squatch.ready(function() {

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

    var initObj = {
      user: {                          
        id: 'abc_123',    
        accountId: 'abc_123',  
        email: 'john@example.com', 
        firstName: 'John',
        lastName: 'Doe'
      },
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM'
  };

  squatch.api().upsert(initObj).then(function(response) {

    //set the referral participants user object to the variable "user"
    user = response.user;

  }).catch(function(err){
    console.log(err);
  });
});

In this example you can reference all the values within the user object, such as referral code, share links from the variable user.

Instances

The squatch.js library supports running as instances, which allows for a wide range of configurations.

These can include:

  • Multiple widgets (of the same or different type) on the same page
  • Multiple users on the same page
  • Multiple tenants on the same page

Example with Multiple Widgets

Using instances of squatch.js enables you to display multiple widgets for the same user on the same page:

// when squatch.js is ready to use
squatch.ready(function() {
  var TenantWidgets = new squatch.Widgets({
    tenantAlias: "test_a5z3ezgicojry"
  });

  var user = {                               
    id: 'abc_123',                      
    accountId: 'abc_123',
    email: 'john@example.com',
    firstName: 'John',
    lastName: 'Doe'
  }
  var jwt =  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM'

  TenantWidgets.upsertUser({
    user: user,
    widgetType: "REFERRER_WIDGET",
    engagementMedium: "POPUP",    
        jwt: jwt
  }).then(function(response) {
    response.widget.open();

  });

  TenantWidgets.upsertUser({
    user: user,
    widgetType: "REFERRER_WIDGET",
    engagementMedium: "EMBED",    
        jwt: jwt
  }).then(function(response) {
    response.widget.open();

  });

});
  
// when squatch.js is ready to use
squatch.ready(function() {
  var TenantWidgets = new squatch.Widgets({
    tenantAlias: "test_a5z3ezgicojry"
  });

  var user = {                               
    id: 'abc_123',                      
    accountId: 'abc_123',
    email: 'john@example.com',
    firstName: 'John',
    lastName: 'Doe'
  }
  var jwt =  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM'

  TenantWidgets.upsertUser({
    user: user,
    widgetType: "p/program-name/w/referrerWidget",
    engagementMedium: "POPUP",    
        jwt: jwt
  }).then(function(response) {
    response.widget.open();

  });

  TenantWidgets.upsertUser({
    user: user,
    widgetType: "p/program-name/w/referrerWidget",
    engagementMedium: "EMBED",    
        jwt: jwt
  }).then(function(response) {
    response.widget.open();

  });

});

Example with multiple users:

Using instances of squatch.js enables you to display widgets for multiple users on the same page:

// when squatch.js is ready to use
squatch.ready(function() {

  var testTenantWidgets = new squatch.Widgets({
    tenantAlias: "test_a5z3ezgicojry"
  });

  var initObj1 = {
    user: {                               
      id: 'abc_123',                      
      accountId: 'abc_123',
      email: 'john@example.com',
      firstName: 'John',
          lastName: 'Doe'
    },
    widgetType: "REFERRER_WIDGET",
    engagementMedium: "EMBED",    
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM'
  };

  var initObj2 = {
    user: {                               
      id: 'abc_124',                      
      accountId: 'abc_124',
      email: 'jane@example.com',
      firstName: 'Jane',
          lastname: 'Doe'
    },
    widgetType: "REFERRER_WIDGET",
    engagementMedium: "EMBED",    
        jwt: 'eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyNCIsImFjY291bnRJZCI6ImFiY18xMjQiLCJlbWFpbCI6ImphbmVAZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKYW5lIiwibGFzdE5hbWUiOiJEb2UifX0.Fa67gpCQO3DJLUGyu6WJUgGohvXrwH7ddbsPjpZUpB0'
  };

  testTenantWidgets.upsertUser(initObj1).then(function(response){});

  testTenantWidgets.upsertUser(initObj2).then(function(response){});
});

// when squatch.js is ready to use
squatch.ready(function() {

  var testTenantWidgets = new squatch.Widgets({
    tenantAlias: "test_a5z3ezgicojry"
  });

  var initObj1 = {
    user: {                               
      id: 'abc_123',                      
      accountId: 'abc_123', 
      email: 'john@example.com',
      firstName: 'John',
          lastName: 'Doe'
    },
    widgetType: "p/program-name/w/referrerWidget",
    engagementMedium: "EMBED",    
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifX0.EZAUeRp3QHEM7rkDrF-eU_-MHIv1nJlUuNGSD5eWUHM'
  };

  var initObj2 = {
    user: {                               
      id: 'abc_124',                      
      accountId: 'abc_124',
      email: 'jane@example.com',
      firstName: 'Jane',
          lastname: 'Doe'
    },
    widgetType: "p/program-name/w/referrerWidget",
    engagementMedium: "EMBED",    
        jwt: 'eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyNCIsImFjY291bnRJZCI6ImFiY18xMjQiLCJlbWFpbCI6ImphbmVAZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKYW5lIiwibGFzdE5hbWUiOiJEb2UifX0.Fa67gpCQO3DJLUGyu6WJUgGohvXrwH7ddbsPjpZUpB0'
  };

  testTenantWidgets.upsertUser(initObj1).then(function(response){});

  testTenantWidgets.upsertUser(initObj2).then(function(response){});
});

Example with multiple programs:

// when squatch.js is ready to use
squatch.ready(function() {
  var firstTenantWidgets = new squatch.Widgets({
    tenantAlias: "arr6gcal3vwp6"
  });

  var secondTenantWidgets = new squatch.Widgets({
    tenantAlias: "test_a5z3ezgicojry"
  });

  var initObj1 = {
    user: {                               
        id: 'abc_123',                      
        accountId: 'abc_123',       
        firstName: 'John',
    },
    widgetType: "REFERRER_WIDGET",
    engagementMedium: "POPUP",    
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJmaXJzdE5hbWUiOiJKb2huIn19.bvp_8G6Yj968_hDWkarIjZW10Ap_Nw-8eiuHPIZG32A'
  };

  var initObj2 = {
    user: {                               
        id: 'abc_124',                      
        accountId: 'abc_124',       
        firstName: 'Jane',
    },
    widgetType: "REFERRER_WIDGET",
    engagementMedium: "EMBED",    
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyNCIsImFjY291bnRJZCI6ImFiY18xMjQiLCJmaXJzdE5hbWUiOiJKYW5lIn19.L_rLNtmzut78sCHHn3ZRjpLrtEMgfqkOpQPXLsvQY0g'
  };

  firstTenantWidgets.upsertUser(initObj1).then(function(response1) {
    response1.widget.open();
  }).catch(function(error){console.log(error)});


  secondTenantWidgets.upsertUser(initObj2).then(function(response2) {
    response2.widget.open();
  }).catch(function(error){console.log(error)});

});

// when squatch.js is ready to use
squatch.ready(function() {
  var firstTenantWidgets = new squatch.Widgets({
    tenantAlias: "arr6gcal3vwp6"
  });

  var secondTenantWidgets = new squatch.Widgets({
    tenantAlias: "test_a5z3ezgicojry"
  });

  var initObj1 = {
    user: {                               
        id: 'abc_123',                      
        accountId: 'abc_123',       
        firstName: 'John',
    },
    widgetType: "p/program-name/w/referrerWidget",
    engagementMedium: "POPUP",    
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJmaXJzdE5hbWUiOiJKb2huIn19.bvp_8G6Yj968_hDWkarIjZW10Ap_Nw-8eiuHPIZG32A'
  };

  var initObj2 = {
    user: {                               
        id: 'abc_124',                      
        accountId: 'abc_124',       
        firstName: 'Jane',
    },
    widgetType: "p/program-name/w/referrerWidget",
    engagementMedium: "EMBED",    
        jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyNCIsImFjY291bnRJZCI6ImFiY18xMjQiLCJmaXJzdE5hbWUiOiJKYW5lIn19.L_rLNtmzut78sCHHn3ZRjpLrtEMgfqkOpQPXLsvQY0g'
  };

  firstTenantWidgets.upsertUser(initObj1).then(function(response1) {
    response1.widget.open();
  }).catch(function(error){console.log(error)});


  secondTenantWidgets.upsertUser(initObj2).then(function(response2) {
    response2.widget.open();
  }).catch(function(error){console.log(error)});

});

Widget Open

You can open the Referral Widget using the widget.open() function. The following example will open the widget in a modal as soon as the referral widget is available:

testTenantWidgets.upsertUser(initObj).then(function(response) {
  response.widget.open();
});

Widget Close

Closing the widget can be done through the widget.close() function. The example below will open the widget as soon as it's available and close it after a 5 second delay:


testTenantWidgets.upsertUser(initObj).then(function(response) {
  response.widget.open();

  setTimeout(function() {
      response.widget.close()
    }, 5000);

});

Sending User Events with squatch.js

Just like the SaaSquatch REST API, squatch.js can be used to send User Events to the SaaSquatch system.

The following is an example of using squatch.js to send a purchase event to SaaSquatch for the user abc_123:

squatch.ready(function(){

  squatch.init({
    tenantAlias: 'test_a5z3ezgicojry'
  });

  //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                
        }]
      }
    }]
  };

  var jwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UiLCJsb2NhbGUiOiJlbl9VUyJ9LCJleHAiOjE1NzE3ODMzMzB9.8MQ3hdg-WFL07phqELtn6CPh4nH13Df4fTps0kKpzVo';

  squatch.events().track(eventObj, {jwt}).then(function(response) {

  }).catch(function(error){
    console.log(error);
  })
});

Authentication

By default, the SaaSquatch system 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 (i.e. includes the id and accountId as well as at least one additional user value).

The requirement for including a JWT in the request can be disabled from the Install page in the Settings section of the SaaSquatch portal by changing the "Track User Event" option to disabled. When not including a JWT in the request, include an an empty JSON object instead ({}).

WARNING: However, 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 particular user will be able to send authorized events.

squatch.js and NPM

The SaaSquatch squatch.js library is available as a package that can be installed through NPM. Installing squatch.js in this way avoids having to reload the library again each time a page is loaded.

Follow these steps to get started using squatch.js through NPM:

1. Install squatch.js

Install squatch.js through NPM using the following command:

$ npm install @saasquatch/squatch-js

2. Include the library in your app

Once installed, squatch.js should be included in your app so that it is available on ever page. Use one of the follwing methods to include squatch.js where applicable:

import * as squatch from "@saasquatch/squatch-js";

var squatch = require("@saasquatch/squatch-js");

3. Use squatch.js

Once installed, and included on each page, you can call squatch.js methods as you otherwise would.

Learn more about loading the squatch.js tracking script and widget in our Quickstart Guide.

Need assistance?

Are you looking for any advanced functionality that isn't listed in the use cases above? Please don't hesitate to reach out to our friendly support team who can assist you further.