SaaSquatch Help Center

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

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

createCookieUser

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

Parameters

  • config Optional object Config details

    • config.widgetType The type of widget to be displayed.

      • REFERRER_WIDGET string Widget content that lets people make referrals
      • CONVERSION_WIDGET string Widget content that shows that someone has been referred
        Examples
        engagementMedium: "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
        widgetType: "POPUP"
        

Example Request

var initObj = {
  engagementMedium: 'EMBED',
  widgetType: 'REFERRER_WIDGET'
};

squatch.widgets().createCookieUser(initObj).then(function(response) {
}).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.

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

        Examples

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

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

        Examples

        engagementMedium: "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

        widgetType: "POPUP"
        
    • config.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'  
  },
  engagementMedium: 'EMBED',
  widgetType: 'REFERRER_WIDGET',
  jwt: 'eyJhbGciOiJIUzI1Ni.eyJ1c2VyhbWUiOiJEb2UifX0.m0Rh17-wISTLyM_NRZsGFhmNu4'
};

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.

      • REFERRER_WIDGET string Widget content that lets people make referrals
      • CONVERSION_WIDGET string Widget content that shows that someone has been referred
        Examples
        engagementMedium: "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
        widgetType: "POPUP"
        
    • config.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'       
  },
  engagementMedium: 'EMBED',
  widgetType: 'REFERRER_WIDGET',
  jwt: 'eyJhbGciOiJIUzI1Ni.eyJ1c2VyhbWUiOiJEb2UifX0.m0Rh17-wISTLyM_NRZsGFhmNu4'
};

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.

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

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

cookieUser

Creates/upserts an anonymous user.

Parameters

  • params.widgetType The type of widget to be displayed.

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

    Examples

    engagementMedium: "REFERRER_WIDGET"
    
    • config.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

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

Returns

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

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

      Examples

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

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

    Examples

    engagementMedium: "REFERRER_WIDGET"
    
  • config.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

    widgetType: "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: 'eyJhbGciOiJIUzI1Ni.eyJ1c2VyhbWUiOiJEb2UifX0.m0Rh17-wISTLyM_NRZsGFhmNu4'
};

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.

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

    Examples

    engagementMedium: "REFERRER_WIDGET"
    
  • config.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

    widgetType: "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'       
  },
  engagementMedium: 'EMBED',
  widgetType: 'REFERRER_WIDGET',
  jwt: 'eyJhbGciOiJIUzI1Ni.eyJ1c2VyhbWUiOiJEb2UifX0.m0Rh17-wISTLyM_NRZsGFhmNu4'
};

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

Other Methods

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

});