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.

init

The init function is the core of Squatch.js. This function lets you identify your users, show them referral widgets, generate referral links and codes, automatically attribute referrals, track conversions and more all from one place. The first time that a user is identified to Squatch.js with this method, it will be created in Referral SaaSquatch and can later be looked up via the API.

You must always call init before you can use any part of squatch.js

_sqh.push(['init', parameterObject]);

Parameters

tenant_alias Required Identifies which account to connect to. This is a super important parameter. For your app, you will get two tenant aliases -- one for test mode and one for live mode. Test mode alias are prefixed with test_, for example test_abhoihnqwet
account_id Required for Widget We use this ID to link a group of users together. See Shared vs Solo Accounts to see what you should use here.
payment_provider_id Required for Widget The payment_provider_id is either the Stripe Customer ID, the Recurly Account ID, the Braintree Account ID or the Zuora Account ID. Can be null for free trials or freemium accounts. You must use Signed Requests to set payment_provider_id to null. This field is not required for API-only integrations.
account_status Optional

The status of the account identified by account_id.

referral_code Optional

The referral code of the person that referred this account_id (i.e. if Bob referred you, this value would be BOB)

  • Defaults to the first referral cookie value detected for FREE or TRIAL accounts.
  • Stores the value that is looked up with Coupon Autofill
  • If someone uses a referral code during checkout, set that value here.
  • Automatically calculated from integrations that use payment_provider_id
  • Will not update a value inside of a payment provider. Do not use when payment_provider_id exists.
  • Can also be set using the REST API or Mobile Widget.
user_referral_code Optional

The referral code used for sharing by this user.

  • Used to set a custom code for the new user.
  • Defaults to the first 15 alphanumeric characters of the user's first and last names.
  • Limited to 15 characters. Restricted to ASCII character codes 48-57, 65-90, and 97-122.
user_id Required for Widget A user ID from your system (must be unique for every user). We use this to uniquely track users, and lets us handle accounts that are shared between users.
email Required for Widget The e-mail address of the user. We use this to contact someone when they have a successful referral.
first_name Required for Widget The user's first name
last_name Optional The user's last name
user_image Optional Defaults to Gravatar or, if unavailable, the user's initials. If you provide a absolute profile image URL the minimum image size is 80px x 80px. Requires Signed Requests.
jwt Optional A JSON Web Token (JWT) that is used to validate that data originated from your servers. For details, see the Signed Requests documentation. A signed request can use EITHER jwt or checksum but not both.
checksum Optional A HMAC-SHA2 checksum that is used to validate that data originated from your servers. For details, see the Signed Requests documentation. A signed request can use EITHER jwt or checksum but not both.
fb_share_image † OptionalDeprecated Defaults to no image for Facebook referrals. If you provide an absolute URL an image it will be used when a referral is made on Facebook. Minimum image size is 114px tall or 155px wide. Not signed in the checksum.
locale † Optional The user's locale, used for Internationalization. The locale must be of the format 'language_COUNTRY` where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore. Examples: en or en_US or zh_CN
mode † Optional

Sets the mode the widget is operating in on the page it's being loaded on. Valid options are POPUP (default), EMBED and NOCONTENT. Not signed in the checksum.

  • Popup mode (POPUP) requires an element with class="squatchpop" applied to trigger the popup to show or can be shown with the open method
  • Embed mode (EMBED) requires a div with id="squatchembed" to control where the widget is embedded
  • No content mode (NOCONTENT) allows user tracking and does not load any widget

Required for Widget

The parameters with the label Required for Widget are not required when all you're doing on the page is coupon autofill, but they are required to show users their referral program widget as a popup or embedded in your page. Without these paramaters, your "refer-a-friend" buttons won't work and your widget will show a RS0XX issue code.

not included in checksum

These fields should not be included when generating a checksum for Signed Requests.
</div>


<hr/>

<h4>Example</h4>
<pre><code class="lang-html">&lt;script type="text/javascript"&gt;

var _sqh = _sqh || [];

// Push user details for a user who is logged in to your system _sqh.push(['init', { tenant_alias: 'test_bpinhag9yagag', account_id: 'abc', payment_provider_id: 'cus_1234', user_id: '5678', email: 'bob@example.com', first_name: 'Bob', last_name: 'Testerson', user_image: 'http://myapp.example.com/img/user_5678.jpg' }]);

// Include squatch.js (function(){function l(){var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src=location.protocol+"//d2rcp9ak152ke1.cloudfront.net/assets/javascripts/squatch.min.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(s,t)}if(window.attachEvent){window.attachEvent("onload",l)}else{window.addEventListener("load",l,false)}})(); </script>

<h4>Troubleshooting</h4>
<p>Having trouble making a successful Squatch JS init call? When loading the Referral Widget in <code>EMBED</code> or <code>POPUP</code> mode, it can return a screen showing that the Referral Program is temporarily unavailable. Please see an example of this screen below. If you are running Squatch JS init in <code>NOCONTENT</code> mode, you can open your browser's console to retrieve this error code.</p>
<img src="/assets/images/squatchjs_error_code.jpg" alt="Example of the Squatch JS error screen" />
<br /><br />
<p>In the screenshot above, look for the <b>error code</b> in the <b>right bottom corner</b> and reference this code in our <a href="/squatchjs/issue/">issue code list</a> to diagnose why the Squatch JS init call failed. If you are still experiencing problems, please don't hesitate to <a href="mailto:support@saasquat.ch" target="_BLANK">contact our Support team</a>.</p>
<h2 id="autofill" class="js-apidocs-methodname">autofill</h2>

<p>Use autofill on your payment page to connect a referral's coupon code to your payment form. Coupon code input elements can be hidden elements.</p>
<pre><code class="lang-js">_sqh.push(['autofill', jQuerySelector]);

_sqh.push(['autofill', callbackFn]);

<h4>Parameters</h4>
<p>Autofill accepts either a jQuery selector of an input element to autofill, or a callback function. If you want to use both, call autofill multiple times (like in the example below).</p>
<div>
    <table class="table table-hover">
      <tr>
        <th>jQuerySelector</th>
        <td>
            Any jQuery selector string
        </td>
      </tr>
      <tr>
        <th>callbackFn</th>
        <td>
            A callback function that will be called asynchronously once the coupon code is ready. The callback accepts one parameter, <code>code</code> -- the coupon code of the person that referred the current user
        </td>
      </tr>
  </table>
</div>

<hr />

<h4>Example</h4>
<pre><code class="lang-html">&lt;script type="text/javascript"&gt;

var _sqh = _sqh || [];

// squatch.js must be initialized to call autofill, but user information is not required _sqh.push(['init', { tenant_alias: 'test_bpinhag9yagag' }]);

// Example 1 -- use a callback function var autofillCb = function(code){ window.alert('The coupon code of the person that referred you is: ' + code); };

_sqh.push(['autofill', autofillCb]);

// Example 2 -- use a jQuery selector _sqh.push(['autofill', '#my_coupon']);

// Include squatch.js (function(){function l(){var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src=location.protocol+"//d2rcp9ak152ke1.cloudfront.net/assets/javascripts/squatch.min.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(s,t)}if(window.attachEvent){window.attachEvent("onload",l)}else{window.addEventListener("load",l,false)}})(); </script>

<input type="text" name="Coupon" id="my_coupon" value="" /> <!-- This input box will get autofilled -->

open

<p>You can programatically open the referral program widget on any page of your application where Referral SaaSquatch javascript has been <a href="#init">initialized</a>.</p>
<h4>Example</h4>
    <pre><code class="lang-html">&lt;script type="text/javascript"&gt;
_sqh.push('open');

</script>

<h3>Pre-Opened Widget</h3>
<p>The referral program widget can be pre-opened on any page of your application where Referral SaaSquatch javascript has been <a href="#init">initialized</a>. To do this, add the paramter, "squatch_open" to the URL.</p>
<h4>Example</h4>
<pre> http://example.com/?squatch_open</code></pre>

close

<p>You can programatically open the referral program widget on any page of your application where Referral SaaSquatch javascript has been <a href="#init">initialized</a>.</p>
<h4>Example</h4>
    <pre><code class="lang-html">&lt;script type="text/javascript"&gt;
_sqh.push('close');

</script>

subscribe

Subscribes the provided callback to the given event; any time an event of the provided name (eventName) is published via the widget, this subscribe call will be triggered.

<pre><code class="lang-js">_sqh.push(['subscribe', String eventName, function([payload]) {

/* code to execute after event is published from the widget */ ]);

<h4>Parameters</h4>
<div>
    <table class="table table-hover">
      <tr>
        <th>eventName</th>
        <td>
            <p>The name of the event you are subscribing to</p>
      </td>
      </tr>
      <tr>
        <th>fn</th>
        <td>
            <p>A callback function with an optional argument <code>payload</code>. The 'payload' argument will only be set if provided in the Widget JS publish call, otherwise it will be undefined.</p>
      </td>
      </tr>
  </table>
</div>

<h4>Example</h4>
<pre><code class="lang-js">_sqh.push(['subscribe', 'changeUrl', function(payload) { window.location = payload.url; }]);</code></pre>

getReward REMOVED

<div class="bs-callout bs-callout-danger">
  <h4>Removed</h4>
  Only worked with older accounts and the PCT_DISCOUNT reward. Prefer to use the more flexible <a href="#subscribe">subscribe</a> method.
</div>

<div class="js-docs-collapse" style="display:none;">

<p>Looks up the referral reward for the currently logged in user. (this is the user identified in ‘init’)</p>
<pre><code class="lang-js">_sqh.push(['getReward', function(reward){ ... }]);</code></pre>

<h4>Parameters</h4>
<div>
    <table class="table table-hover">
      <tr>
        <th>fn</th>
        <td>
            <p>A callback function with a single argument <code>reward</code> with the following fields</p>

            <table class="table table-hover">
              <tr>
                <th>details</th>
                <td>
                    <p>An object of reward details</p>
                    <table class="table table-hover">
                      <tr>
                        <th>discountPercentage</th>
                        <td>
                            <p>The total discount percentage both from referring and being referred</p>
                        </td>
                      </tr>
                      <tr>
                        <th>referrerDiscountPercent</th>
                        <td>
                            <p>Earned from referring friends</p>
                        </td>
                      </tr>
                      <tr>
                        <th>referredDiscountPercent</th>
                        <td>
                            <p>Earned by being referred by friends</p>
                        </td>
                      </tr>
                    </table>
                </td>
              </tr>
              <tr>
                <th>type</th>
                <td>
                    <p>The reward type</p>
                </td>
              </tr>
            </table>
      </td>
      </tr>
  </table>
</div>

<hr />

<h4>Example</h4>
<pre><code class="lang-html">&lt;script type="text/javascript"&gt;

var _sqh = _sqh || [];

// Push user details for a user who is logged in to your system _sqh.push(['init', { tenant_alias: 'test_bpinhag9yagag', account_id: 'abc', payment_provider_id: 'cus_1234', user_id: '5678', email: 'bob@example.com', first_name: 'Bob', last_name: 'Testerson' }]);

_sqh.push(['getReward', function(reward){ // Gets the current user's (e.g. Bob Testerson) reward // e.g. show this on the My Account page to show the current user's info }]);

// Include squatch.js (function(){function l(){var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src=location.protocol+"//d2rcp9ak152ke1.cloudfront.net/assets/javascripts/squatch.min.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(s,t)}if(window.attachEvent){window.attachEvent("onload",l)}else{window.addEventListener("load",l,false)}})(); </script>

getRewardBalance REMOVED

<div class="bs-callout bs-callout-danger">
  <h4>Removed</h4>
  Only worked with older accounts. Prefer to use the more flexible <a href="#subscribe">subscribe</a> method.
</div>

<div class="js-docs-collapse" style="display:none;">

<p>Looks up the Reward Balance reward for the currently logged in user. (this is the user identified in ‘init’)</p>
<pre><code class="lang-js">_sqh.push(['getRewardBalance', function(rewardBalance){ ... }]);</code></pre>

<h4>Parameters</h4>
<div>
    <table class="table table-hover">
      <tr>
        <th>fn</th>
        <td>
            <p>A callback function with a single argument <code>rewardBalance</code>. Returns the same <a href="/api/methods/#list_balances">Reward Balance object
            as the REST API</a></p>
      </td>
      </tr>
  </table>
</div>

<hr />

<h4>Example</h4>
<pre><code class="lang-html">&lt;script type="text/javascript"&gt;

var _sqh = _sqh || [];

// Push user details for a user who is logged in to your system _sqh.push(['init', { tenant_alias: 'test_bpinhag9yagag', account_id: 'abc', payment_provider_id: 'cus_1234', user_id: '5678', email: 'bob@example.com', first_name: 'Bob', last_name: 'Testerson' }]);

_sqh.push(['getRewardBalance', function(rewardBalance){ // Gets the current user's (e.g. Bob Testerson) reward balance // e.g. show this on the My Account page to show the current user's info console.log(rewardBalance.0.totalAssignedCredit); }]);

// Include squatch.js (function(){function l(){var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src=location.protocol+"//d2rcp9ak152ke1.cloudfront.net/assets/javascripts/squatch.min.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(s,t)}if(window.attachEvent){window.attachEvent("onload",l)}else{window.addEventListener("load",l,false)}})(); </script>

</div>
In this Article: