Squatch.js Advanced Use Cases

Squatch.js, our JavaScript SDK, has all the functionality required to incorporate a SaaSquatch program into your website or web app. Below are some advanced use cases that you may run into when implementing squatch.js. For a list of key scripts that apply to most or all implementations, check out our Scripts doc doc.

🔗 Multi-program support

The squatch.js library provides multi-program support by allowing you to include multiple widgets on the same page. Here’s an example:

<script>
    // Setup configuration
</script>

<squatch-embed widget="w/referral-widget"></squatch-embed>
<squatch-popup widget="w/popup-widget"></squatch-embed>

🔗 Display translated widgets

Before you begin: To display a translated widget, you must first upload translated content to the Admin Portal.

Translated widget content can be displayed to participants in two ways:

By including a locale attribute with the squatch.js web component
By including a locale value on a participant’s user object

For the best participant experience, we recommend including a locale attribute with the web component. This locale allows you to serve content to the participant according to their browser language. It temporarily overrides any locale value on the user object.

If a locale value exists on both the user object and in the web component, then the value used in the web component determines which version of the content your participants see.

Example:

<squatch-embed locale="fr_FR" widget="w/myWidget"></squatch-embed>

Reduce load times for participants by preloading an embedded widget in the background.

You can pass a parent container or a query selector to squatch.js, giving you more control on where and how your widget is loaded within your app. When you pass squatch.js a container or query selector, the embedded widget is shown via a calling method instead of being displayed when loaded. For example, the widget can be loaded and then shown or hidden as a participant navigates your app, instead of re-rendering.

The widget returned from your call to squatch.js has .open() and .close() methods to show or hide itself. Calling .open() reveals the widget and can trigger a background refresh. Calling .close() hides the widget.

The following example applies to popup and embedded widgets with a container or custom query selector. The code opens the widget as soon as it is available:

const initObj = {
    ...
    engagementMedium: "EMBED",
    container: "#customcontainer"
}  

squatch.widgets().upsertUser(initObj).then(function(response) {

      response.widget.open();

  });

The example below opens the widget as soon as it's available and closes it after a 5 second delay:

const initObj = {
    ...
    engagementMedium: "EMBED",
    container: "#customcontainer"
}  

squatch.widgets().upsertUser(initObj).then(function(response) {

response.widget.open();

setTimeout(function() {

    response.widget.close()

  }, 5000);

});

🔗 Legacy object-based squatch.js

squatch.js supports uploading user data by using a user object within the widget and tracking scripts. This user object can be sent along with a signed JWT for a fully secure implementation. Information about our current widget and tracking scripts can be found in our Scripts doc.

Example of legacy object-based script to register participants

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'
      }
    },
    jwt: "SIGNED_JWT_HERE"
  };

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

Example of legacy object-based script to render 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: 'john@example.com',                
  firstName: 'John',       
  lastName: 'Doe',
  locale: 'en_US'
},
engagementMedium: 'EMBED',
widgetType: 'p/referral-program/w/referrerWidget',
jwt: 'SIGNED_JWT_HERE'
  };

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

🔗 Additional documentation

squatch.js Scripts: See general examples of the most important scripts you’ll need when implementing a SaaSquatch program.
Advanced Use Cases: Go beyond the basic scripts and learn how to reference existing user data, render a widget without requiring user information, and more.
Signed Requests: Learn how to require a JWT or an API key when sending data to SaaSquatch.
Tracking Cookies: Learn more about squatch.js and first-party cookies.
Issue Code List: Find details and troubleshooting steps about error codes you encounter.
squatch.js Reference: Full list of methods available.

🔗 Multi-program support

🔗 Display translated widgets

🔗 Preload an embedded widget

🔗 Legacy object-based squatch.js

🔗 Additional documentation