squatch.js Version 1 Reference
🔗 squatch.js Version 1
Deprecated
**Squatch V1 will no longer be supported:** Please visit our breaking changes page for more details and use Squatch.js V2 as it is the only version that supports all up-to-date use cases. If you are not sure what version you are using, please refer to our article on the squatch.js JavaScript Library to find out.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
|
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.
</div>
<hr/>
<h4>Example</h4>
<pre><code class="lang-html"><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>
<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>
<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"><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
<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"><script type="text/javascript">
_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 close 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"><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.
<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"><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' }]);
_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"><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' }]);
_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>