SaaSquatch Help Center

squatch.js is the SaaSquatch javascript SDK and a one-stop shop to integrate the SaaSquatch platform into your website or web app. It can show Program Widgets on any website, track users, generate unique referral short links and referral codes, and more.

Version 2 is the most recent and current version of squatch.js. If you started using SaaSquatch before November 2016, you are probably using Version 1. You can read more about the difference by clicking here.

🔗 Methods

🔗 ready

Squatch.js can't start safely making operations until it's "ready". This function detects that state.

Parameters

  • fn function A callback once Squatch.js is ready.

Examples

squatch.ready(function() {
  console.log("ready!");
  squatch.api().cookieUser();
});

Returns void

🔗 autofill

Autofills a referral code into an element when someone has been referred. Uses WidgetApi.squatchReferralCookie behind the scenes.

Parameters

  • selector string Element class/id

Returns void

Example

squatch.autofill('my_selector');

🔗 submitEmail

Overrides the default function that submits the user email. If you have Security enabled, the email needs to be signed before it's submitted.

Parameters

  • fn function Callback function for the 'submit_email' event.

Examples

squatch.submitEmail(function(target, widget, email) {
  // Sign email and generate jwt token
  var jwt = 'token';
  widget.reload(email, jwt);
});

Returns void

🔗 Widgets

Widgets is a factory for creating widgets. It's possible to build your own widgets using the WidgetApi but most people will prefer to use these easy methods.

🔗 constructor

Initialize a new Widgets instance.

Parameters

  • tenantAlias string The Tenant that you're using.
  • domain string The domain for API. Defaults to https://app.referralsaasquatch.com

Examples

Browser example

var widgets = new squatch.Widgets({tenantAlias:'test_12b5bo1b25125'});

Browserify/Webpack example

var Widgets = require('squatch-js').Widgets;
var widgets = new Widgets({tenantAlias:'test_12b5bo1b25125'});

Babel+Browserify/Webpack example

import {Widgets} from 'squatch-js';
let widgets = new Widgets({tenantAlias:'test_12b5bo1b25125'});

🔗 upsertUser

This function calls the WidgetApi.upsert method, and it renders the widget if it is successful. Otherwise it shows the "error" widget.

Parameters

  • config object Config details

    • config.user Object The user details
      • config.user.id string The user id
      • config.user.accountId string The user account id
      • config.user.referable boolean Indicates if a user is referable or not. Use this in an upsert to indicate a user is no longer eligible to be referred.
        • Note: This flag shouldn't be used as part of the initial user upsert of a referred user as it will override the attribution.
        • Spelling Counts: Make sure that when using this flag you spell it correctly, using a single r. It should always be referable or the system will not pick up the value.
      • config.user.referredByCodes array This array is used to indicate who referred this user for Growth Automation programs.
      • Classic only config.user.referredBy object This object is used to pass in the referral code using the following fields.
        • config.user.referredBy.code string is the field in which the referrer's code is added.
        • config.user.referredBy.isConverted boolean tells the system whether or not the referral should be converted or not.
      • config.user.referralCodes object This is where you can optionally specify the referral codes for your growth automation programs.
      • Classic only config.user.referralCode string This string can be optionally used to specify a referral code in a classic program for the user.
    • config.widgetType The type of widget to be displayed.

      • For Growth Automation Programs:
        • referrerWidget string Widget content that lets people make referrals.
        • conversionWidget string Widget content that shows that someone has been referred.
        • partnerWidget string Widget content that lets partners refer people into a Partner Program.
      • Classic only For Classic Referral Programs:

        • REFERRER_WIDGET string Widget content that lets people make referrals.
        • CONVERSION_WIDGET string Widget content that shows that someone has been referred.

        Examples

        Growth Automation Programs:

        widgetType: "/p/program-name/w/referrerWidget"
        

        Classic only Classic Referral Programs:

        widgetType: "REFERRER_WIDGET"
        
    • config.engagementMedium How the widget is to be displayed.

      • POPUP string Displays the widget as a modal popup. Popups widgets are rendered on top of other elements in a page.
      • EMBED string Displays the widget embedded in the page. An EmbedWidget is displayed inline as part of your page.

        Examples

        engagementMedium: "POPUP"
        
    • config.jwt string the JSON Web Token (JWT) that is used to validate the data (can be disabled)

Example Request

For Growth Automation Platforms

var initObj = {
  user: {                               
    id: 'abc_123',                      
    accountId: 'abc_123',       
    email: 'john@example.com',                
    firstName: 'John',       
    lastName: 'Doe',
    locale: 'en_US',
    referralCodes: {
      program-id1: 'JOHNDOECODE',
      program-id2: 'JOHNDOECODETWO'
    }
    referredByCodes: [
      'JANEDOE'
    ]
  },
  engagementMedium: 'EMBED',
  widgetType: '/p/program-name/w/referrerWidget',
  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UiLCJsb2NhbGUiOiJlbl9VUyIsInJlZmVycmVkQnlDb2RlcyI6WyJKQU5FRE9FIl19fQ.mlBQG0iaZuheMp4W4SmvmIMz7IiGWMpCzBQrABLLJgA'
};

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

Classic only For Classic Referral Platforms

var initObj = {
  user: {       
    id: 'abc_123',
    accountId: 'abc_123',
    email: 'john@example.com',
    firstName: 'John',
    lastName: 'Doe',
    locale: 'en_US',
    referralCode: 'JOHNDOECODE',
    referredBy: {
      code: 'JANEDOE'          
      isConverted: false
     }
  },
  engagementMedium: 'EMBED',
  widgetType: 'REFERRER_WIDGET',
  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMiLCJlbWFpbCI6ImpvaG5AZXhhbXBsZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UiLCJsb2NhbGUiOiJlbl9VUyIsInJlZmVycmVkQnkiOnsiY29kZSI6IkpBTkVET0UiLCJpc0NvbnZlcnRlZCI6ZmFsc2V9fX0.yePfMPei_2VvC-W14KGwJ054QB7BBAJcyquKAjijBdw'
};

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

Returns

Promise json object if true, with a Widget and user details.

  • widget Widget The widget that was created.
  • user User The user that's in the widget.

🔗 render

This function calls the WidgetApi.render method, and it renders the widget if it is successful. Otherwise it shows the "error" widget.

Parameters

  • config object Config details

    • config.user Object The user details

      • config.user.id string The user id
      • config.user.accountId string The user account id

        Examples

        user: {                               
          id: 'abc_125',                      
          accountId: 'abc_125'
        }
        
    • config.widgetType The type of widget to be displayed.

      • For Growth Automation Programs:
        • referrerWidget string Widget content that lets people make referrals.
        • conversionWidget string Widget content that shows that someone has been referred.
        • partnerWidget string Widget content that lets partners refer people into a Partner Program.
      • Classic only For Classic Referral Programs:

        • REFERRER_WIDGET string Widget content that lets people make referrals.
        • CONVERSION_WIDGET string Widget content that shows that someone has been referred.

        Examples

        Growth Automation Programs:

        widgetType: "/p/program-name/w/referrerWidget"
        

        Classic only Classic Referral Programs:

        widgetType: "REFERRER_WIDGET"
        
    • config.engagementMedium How the widget is to be displayed.

      • POPUP string Displays the widget as a modal popup. Popups widgets are rendered on top of other elements in a page.
      • EMBED string Displays the widget embedded in the page. An EmbedWidget is displayed inline as part of your page.

        Examples

        engagementMedium: "POPUP"
        
    • config.jwt string the JSON Web Token (JWT) that is used to validate the data (can be disabled)

Example Request

For Growth Automation Programs:

var initObj = {
  user: {                               
    id: 'abc_123',                      
    accountId: 'abc_123'       
  },
  engagementMedium: 'EMBED',
  widgetType: 'p/program-name/w/referrerWidget',
  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMifX0.Sor56NRtkKqZKLLOy8177bFee5ukiS2-__R1s34KNOE'
};

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

Classic only For Classic Referral Programs:

var initObj = {
  user: {                               
    id: 'abc_123',                      
    accountId: 'abc_123'       
  },
  engagementMedium: 'EMBED',
  widgetType: 'REFERRER_WIDGET',
  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMifX0.Sor56NRtkKqZKLLOy8177bFee5ukiS2-__R1s34KNOE'
};

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

Returns

Promise json object if true, with a Widget and user details.

  • widget Widget The widget that was created.
  • user User The user that's in the widget.

🔗 WidgetApi

The WidgetApi class is a wrapper around the Widget Endpoints of the SaaSquatch REST API.

🔗 constructor

Initialize a new WidgetApi instance.

Parameters

  • tenantAlias string The Tenant that you're using.
  • domain string The domain for API. Defaults to https://app.referralsaasquatch.com

Examples

Browser example

var squatchApi = new squatch.WidgetApi({tenantAlias:'test_12b5bo1b25125'});

Browserify/Webpack example

var WidgetApi = require('squatch-js').WidgetApi;
var squatchApi = new WidgetApi({tenantAlias:'test_12b5bo1b25125'});

Babel+Browserify/Webpack example

import {WidgetApi} from 'squatch-js';
let squatchApi = new WidgetApi({tenantAlias:'test_12b5bo1b25125'});

🔗 upsertUser

Creates/upserts user.

Parameters

  • params.user object The user details

    • params.user.id string The user id
    • params.user.accountId string The user account id
    • params.user.referable boolean Indicates if a user is referable or not. Use this in an upsert to indicate a user is no longer eligible to be referred.
      • Note: This flag shouldn't be used as part of the initial user upsert of a referred user as it will override the attribution.
      • Spelling Counts: Make sure that when using this flag you spell it correctly, using a single r. It should always be referable or the system will not pick up the value.
    • params.user.referredByCodes array This array is used to indicate who referred this user for Growth Automation programs.
    • Classic Only params.user.referredBy object This object is used to pass in the referral code using the following fields.
      • params.user.referredBy.code string is the field in which the referrer's code is added.
      • params.user.referredBy.isConverted boolean tells the system whether or not the referral should be converted or not.
    • params.user.referralCodes object This is where you can optionally specify the referral codes for your growth automation programs.
    • Classic only params.user.referralCode string This string can be optionally used to specify a referral code in a classic program for the user.

      Examples

      For Growth Automation Programs:

        user: {                               
          id: 'abc_125',                      
          accountId: 'abc_125',       
          email: 'john@example.com',                
          firstName: 'John',       
          lastName: 'Doe',         
          locale: 'en_US',
          referralCodes: {
            program-id1: 'JOHNDOECODE'
          }
          referredByCodes: [
            "JANEDOE"
          ]
        }
      

      Classic only For Classic Referral Programs:

        user: {                               
          id: 'abc_125',                      
          accountId: 'abc_125',       
          email: 'john@example.com',                
          firstName: 'John',       
          lastName: 'Doe',         
          locale: 'en_US',
          referralCode: 'JOHNDOECODE',
          referredBy: {
            isConverted: true
          }
        }
      
  • params.widgetType The type of widget to be displayed.

    • For Growth Automation Programs:
      • referrerWidget string Widget content that lets people make referrals.
      • conversionWidget string Widget content that shows that someone has been referred.
      • partnerWidget string Widget content that lets partners refer people into a Partner Program.
    • For Classic Referral Programs:

      • REFERRER_WIDGET string Widget content that lets people make referrals.
      • CONVERSION_WIDGET string Widget content that shows that someone has been referred.

      Examples

      Growth Automation Programs:

       widgetType: "/p/program-name/w/partnerWidget"
      

      Classic only Classic Referral Programs:

       widgetType: "REFERRER_WIDGET"
      
  • params.engagementMedium How to display the widget.

    • POPUP string Displays the widget as a modal popup. Popups widgets are rendered on top of other elements in a page.
    • EMBED string Displays the widget embedded in the page. An EmbedWidget is displayed inline as part of your page.

    Examples

    engagementMedium: "POPUP"
    
  • params.jwt string the JSON Web Token (JWT) that is used to validate the data (can be disabled)

Example Request

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().upsertUser(initObj).then(function(response) {
  user = response.user;
}).catch(function(error){
  console.log(error);
});

Returns

Promise string if true, with the widget template, jsOptions and user details.

🔗 render

Render an HTML template of the widget

Parameters

  • params.user object The user details

    • params.user.id string The user id
    • params.user.accountId string The user account id

      Examples

      user: {                               
        id: 'abc_125',                      
        accountId: 'abc_125'
      }
      
  • params.widgetType The type of widget to be displayed.

    • For Growth Automation Programs:
      • referrerWidget string Widget content that lets people make referrals.
      • conversionWidget string Widget content that shows that someone has been referred.
      • partnerWidget string Widget content that lets partners refer people into a Partner Program.
    • Classic only For Classic Referral Programs:

      • REFERRER_WIDGET string Widget content that lets people make referrals.
      • CONVERSION_WIDGET string Widget content that shows that someone has been referred.

      Examples

      Growth Automation Programs:

       widgetType: "/p/program-name/w/referrerWidget"
      

      Classic only Classic Referral Programs:

       widgetType: "REFERRER_WIDGET"
      
  • params.engagementMedium How to display the widget.

    • POPUP string Displays the widget as a modal popup. Popups widgets are rendered on top of other elements in a page.
    • EMBED string Displays the widget embedded in the page. An EmbedWidget is displayed inline as part of your page.

    Examples

    engagementMedium: "POPUP"
    
    • params.jwt string the JSON Web Token (JWT) that is used to validate the data (can be disabled)

Example Request

For Growth Automation Programs:

var initObj = {
  user: {                               
    id: 'abc_123',                      
    accountId: 'abc_123'       
  },
  engagementMedium: 'EMBED',
  widgetType: 'p/program-name/w/referrerWidget',
  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMifX0.Sor56NRtkKqZKLLOy8177bFee5ukiS2-__R1s34KNOE'
};

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

Classic only For Classic Referral Programs:

var initObj = {
  user: {                               
    id: 'abc_123',                      
    accountId: 'abc_123'       
  },
  engagementMedium: 'EMBED',
  widgetType: 'REFERRER_WIDGET',
  jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiYWJjXzEyMyIsImFjY291bnRJZCI6ImFiY18xMjMifX0.Sor56NRtkKqZKLLOy8177bFee5ukiS2-__R1s34KNOE'
};

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

Returns

Promise template html if true.

🔗 squatchReferralCookie

Looks up the referral code of the current user, if there is any.

Returns Promise json code referral code if true.

🔗 Static Instance

🔗 init

Initializes the static squatch global. This sets up:

  • squatch.api() a static instance of the WidgetApi
  • squatch.widgets() a static instance of Widgets

Properties

  • tenantAlias string The Tenant that you're using.
  • domain string The domain for API. Defaults to https://app.referralsaasquatch.com

Examples

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

Returns void

🔗 api

A static instance of the WidgetApi created when you call init. Read the WidgetApi docs.

Returns WidgetApi static instance

🔗 widgets

A static instance of the Widgets created when you call init. Read the Widgets docs.

Returns Widgets static instance



🔗 Methods for Pop-up Widgets

The following functions can be added to control when and how your widget pop-up works. This only works when you use engagementMedium: 'POPUP'.

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

});