squatch.js Version 1 Reference
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
tenantalias | 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
|
referral_code | Optional |
The referral code of the person that referred this
|
user_referral_code | Optional |
The referral code used for sharing by this user.
|
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. |
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
|
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 achecksum
for Signed Requests.
Example
<script type="text/javascript">
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>
Troubleshooting
Having trouble making a successful Squatch JS init call? When loading the Referral Widget in EMBED
or POPUP
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 NOCONTENT
mode, you can open your browser's console to retrieve this error code.

In the screenshot above, look for the error code in the right bottom corner and reference this code in our issue code list to diagnose why the Squatch JS init call failed. If you are still experiencing problems, please don't hesitate to contact our Support team.
autofill
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.
_sqh.push(['autofill', jQuerySelector]);
_sqh.push(['autofill', callbackFn]);
Parameters
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).
jQuerySelector | Any jQuery selector string |
---|---|
callbackFn |
A callback function that will be called asynchronously once the coupon code is ready. The callback accepts one parameter, code -- the coupon code of the person that referred the current user
|
Example
<script type="text/javascript">
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
You can programatically open the referral program widget on any page of your application where Referral SaaSquatch javascript has been initialized.
Example
<script type="text/javascript">
_sqh.push('open');
</script>
Pre-Opened Widget
The referral program widget can be pre-opened on any page of your application where Referral SaaSquatch javascript has been initialized. To do this, add the paramter, "squatch_open" to the URL.
Example
http://example.com/?squatch_open
close
You can programatically close the referral program widget on any page of your application where Referral SaaSquatch javascript has been initialized.
Example
<script type="text/javascript">
_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.
_sqh.push(['subscribe', String eventName, function([payload]) {
/ code to execute after event is published from the widget /
]);
Parameters
eventName |
The name of the event you are subscribing to |
---|---|
fn |
A callback function with an optional argument |
Example
_sqh.push(['subscribe', 'changeUrl', function(payload) { window.location = payload.url; }]);