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'.

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();
});

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

});

squatch.js Reference

Methods

ready

autofill

submitEmail

Widgets

constructor

upsertUser

render

WidgetApi

constructor

upsertUser

render

squatchReferralCookie

Static Instance

init

api

widgets

Methods for Pop-up Widgets

Widget Open

Widget Close