SaaSquatch Help Center

This installation guide has been designed to provide in-depth instructions on how to install your SaaS business's referral program.

The use of step-by-step instructions, relevant examples, and plenty of links to additional resources to help explain concepts and provide information about how to go about the integration as well as tailor this guide to the specifics of your business.

This is a companion document to the SaaS Referral Program Guide Introduction and SaaS Referral Program Guide Outline from our Success Centre. Please make sure you have familiarized yourself with these two documents before moving forward with the installation.

Getting Started

To get started installing your referral program, make sure you have successfully created a Referral SaaSquatch account and project. When you are creating the project, please make sure you choose your Program Reward as either Dollar Credit or Percent Discount, and your Payment System as Other (via SaaSquatch API).

To make use of either the Percent Discount or Dollar Credit rewards simply follow the version of the reward fulfillment steps of this guide which pertain to your reward type (7a and 8a for Dollar Credit, and 7b and 8b for Percent discount).

If you have any questions about information in this install guide, or throughout the process of implementing your referral program, don’t hesitate to contact our support team who will be more than happy to assist you.

Live and Test Tenant Alias: This Install guide includes references to the tenant alias for your program. Make sure to replace {{tenant alias}} with your actual tenant alias found on the install page of your Referral SaaSquatch program portal. Please note that each project includes both a Live and a Test tenant. Please check out our document on best practices for testing.
Signed Requests: Signed Requests are turned on by default with a new project. Places where a JWT is needed in this guide are indicated using {{calculated_JWT}}. Information about generating the JWT’s, and how to turn them off can be found in our docs.

Additional Resources:

  • REST API Reference - Provides detailed information about all the methods found in the Referral SaaSquatch REST API
  • Squatch.js Reference - Provides details about all the functions found in the Referral SaaSquatch squatch.js Javascript Library.
  • Our technical docs also provide additional Guides covering a wide range of use cases which can be helpful for providing further context.

This Install Guide includes the following steps:

1. Squatch JS Tracking Script [Desktop]

2. Squatch Mobile Tracking [Mobile]

3. Referral Widget Script [Desktop]

4. Referral Widget [Mobile]

5. Conversion Script [Desktop]

6. Conversion Script [Mobile]

Reward Fulfillment - Referred User:

Reward Fulfillment - Referrer:

1. Squatch JS Tracking Script [Desktop]

The following script will identify a newly registered user to SaaSquatch. We load this script in the nocontent mode for tracking purposes only, which will not show the referral widget.

Squatch JS will automatically look for a referral cookie and make the referral connection.

<script type="text/javascript">

//Include squatch.js in your webpage
!function(a,b){a("squatch","https://d2rcp9ak152ke1.cloudfront.net/assets/javascripts/v2/squatch.min.js",b)}(function(a,b,c){var d,e,f;c["_"+a]={},c[a]={},c[a].ready=function(b){c["_" + a].ready =  c["_" + a].ready || [];c["_" + a].ready.push(b);},e=document.createElement("script"),e.async=1,e.src=b,f=document.getElementsByTagName("script")[0],f.parentNode.insertBefore(e,f)},this);

squatch.ready(function() {        // when squatch.js is ready to use
  squatch.init({
      tenantAlias: "{{tenant alias}}"        //configure squatch.js for the tenant you are using
    });
    var initObj = {        //object containing the init parameters for squatch.js
    user: {        //the object for the user you want to upsert                              
        id: 'abc_123',      
        accountId: 'abc_123',       
        email: 'john@example.com',               
        firstName: 'John',       
        lastName: 'Doe'
    },
    jwt: '{{calculated_JWT}}'
  };

  //update/register a referral participant without displaying a widget 
  squatch.api().upsertUser(initObj).then(function(response) {
    user = response.user;
  }).catch(function(err){
    console.log(err);
  });
});
</script>

2. Squatch Mobile Tracking [Mobile]

Use this SaaSquatch endpoint to identify referred users inside the Mobile app.

The following is an example to use this endpoint for tracking and conversion purposes:

https://app.referralsaasquatch.com/a/{{tenant_alias}}/widgets/mobilewidget
?jwt={{calculated_JWT}}
&accountId=abc_123
&userId=abc_123
&email=john%40example.com
&firstName=John
&lastName=Doe
&referralCode=JANEDOE
&paymentProviderId=null
&mode=EMPTY

The above example will result in the following url:

https://app.referralsaasquatch.com/a/{{tenat_alias}}/widgets/mobilewidget?jwt={{calculated_JWT}}&accountId=abc_123&userId=abc_123&email=john%40example.com&firstName=John&lastName=Doe&referralCode=JANEDOE&paymentProviderId=null&mode=EMPTY

Please note:

  • Make sure to encode special characters.
  • Don’t include paymentProviderId
  • Use systemId instead of account_id
  • The referral code of the referrer this referred user was referred by can be found inside the Branch integration’s JSON format: "sq_referralCode" : "JANEDOE"
  • If this user was not referred, leave the referralCode field empty.

3. Referral Widget Script [Desktop]

Use the Squatch JS library to identify users and enable them to share their unique sharelink through email, Facebook or Twitter among their network of friends.

<-- Insert this div on the page where the widget is suppose to be placed. -->

<div id="squatchembed"></div>

<-- Insert this javascript right before </body> for improved page load time -->

<script type="text/javascript">
!function(a,b){a("squatch","https://d2rcp9ak152ke1.cloudfront.net/assets/javascripts/v2/squatch.min.js",b)}(function(a,b,c){var d,e,f;c["_"+a]={},c[a]={},c[a].ready=function(b){c["_" + a].ready =  c["_" + a].ready || [];c["_" + a].ready.push(b);},e=document.createElement("script"),e.async=1,e.src=b,f=document.getElementsByTagName("script")[0],f.parentNode.insertBefore(e,f)},this);

// when squatch.js is ready to use
window.squatch.ready(function(){

  //configure squatch.js for the tenant you are using       
  squatch.init({
      tenantAlias: '{{tenant_alias}}'
  });

  //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'  
    },
    engagementMedium: 'EMBED',
    widgetType: 'REFERRER_WIDGET',
        jwt: '{{calculated_JWT}}'
  };

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

4. Referral Widget [Mobile]

Use the Mobile Widget to identify users inside the Mobile app and enable them to share their unique sharelink through email, Facebook or Twitter among their network of friends.

The URL to request the Mobile Widget stores all the parameters. The following is an example to load the Referral Widget for your users.

https://app.referralsaasquatch.com/a/{{tenant alias}}/widgets/mobilewidget
?userId=abc_123
&firstName=John
&lastName=Doe
&accountId=abc_123
&paymentProviderId=null
&email=john%40example.com
&jwt={{calculated_JWT}}

The above example will result in the following url:

https://app.referralsaasquatch.com/a/{{tenant alias}}/widgets/mobilewidget?userId=abc_123&firstName=John&lastName=Doe&accountId=abc_123&paymentProviderId=null&email=john%40example.com&jwt={{calculated_JWT}}

Note: make sure to encode special characters.

5. Conversion Script [Desktop]

Conversion using JavaScript

When a referred user successfully completes their purchase, use the following script to identify this newly registered user to SaaSquatch. We load this script in the nocontent mode for tracking purposes only, which will not show the referral widget.

Squatch JS will automatically look for a referral cookie and make the referral connection.

Adding the account_status = “PAID” parameter will automatically convert the referral.

<-- Insert this javascript right before </body> if possible for improved page load time -->
<script type="text/javascript">

!function(a,b){a("squatch","https://d2rcp9ak152ke1.cloudfront.net/assets/javascripts/v2/squatch.min.js",b)}(function(a,b,c){var d,e,f;c["_"+a]={},c[a]={},c[a].ready=function(b){c["_" + a].ready =  c["_" + a].ready || [];c["_" + a].ready.push(b);},e=document.createElement("script"),e.async=1,e.src=b,f=document.getElementsByTagName("script")[0],f.parentNode.insertBefore(e,f)},this);

squatch.ready(function() {

  squatch.init({
      tenantAlias: "{{tenant_alias}}"
    });

    var initObj = {
    user: {                              
        id: 'abc_123',      
        accountId: 'abc_123',       
        email: 'john@example.com',               
        firstName: 'John',       
        lastName: 'Doe',
        referredBy: {
              isConverted: true
          }
    },
        jwt: '{{calculated_JWT}}'
  };

  squatch.api().upsertUser(initObj).then(function(response) {
    user = response.user;
  }).catch(function(err){
    console.log(err);
  });
});
</script>

Conversion using REST API When the goal post is hit, the referred user completes their order, SaaSquatch needs to be informed of this conversion step so the rewards are created.

This conversion step can be done by using the SaaSquatch REST API to set the account status to PAID by updating the Account.

Type: POST
URL: https://app.referralsaasquatch.com/api/v1/{{tenant alias}}/accountsync

JSON request

{
    "id": "abc_123",
    "subscription": {
"status": "PAID",
"billingIntervalType": "DAY",
"billingIntervalValue": 1,
"value": 1
    }
}

Example response

{
    "id": "abc_123",
    "currency": "USD",
    "subscription": {
        "status": "PAID",
        "value": 1,
        "billingIntervalType": "DAY",
        "billingIntervalValue": 1
    },
    "referral": {
        "code": "JANEDOE"
    }
}

|

Please note:

The following values are required but not used for your program. You can hard code the following values:

"billingIntervalType": "DAY",
"billingIntervalValue": 1,
"value": 1

6. Conversion Script [Mobile]

Use this SaaSquatch endpoint to identify referred users inside the Mobile app and convert the referral after a successful purchase.

The following is an example to use this endpoint for tracking and conversion purposes:

https://app.referralsaasquatch.com/a/{{tenat_alias}}/widgets/mobilewidget
?jwt={{calculated_JWT}}
&accountId=abc_123
&userId=abc_123
&email=john%40example.com
&accountStatus=PAID
&firstName=John
&lastName=Doe
&referralCode=JANEDOE
&paymentProviderId=null
&mode=EMPTY

The above example will result in the following url:

https://app.referralsaasquatch.com/a/{{tenat_alias}}/widgets/mobilewidget?jwt={{calculated_JWT}}&accountId=abc_123&userId=abc_123&email=john%40example.com&accountStatus=PAID&firstName=John&lastName=Doe&referralCode=JANEDOE&paymentProviderId=null&mode=EMPTY

Please note:

  • Make sure to encode special characters.
  • Don’t include paymentProviderId
  • Use systemId instead of account_id
  • The referral code of the referrer this referred user was referred by can be found inside the Branch integration’s JSON format: "sq_referralCode" : "JANEDOE"

7a. Reward Fulfillment - Referred User [Dollar Credit]

During the referred user’s checkout process the referred user should have their reward applied. The following code examples help determine whether or not a user was referred.

[Desktop]

Check for Referral Code cookie with Squatch JS autofill. If there is a Referral Code present, this means the user has been referred.

Squatch JS autofill example The following code snippet will check for a referral code with a simple If / Else statement.

<script type="text/javascript">

!function(a,b){a("squatch","https://d2rcp9ak152ke1.cloudfront.net/assets/javascripts/v2/squatch.min.js",b)}(function(a,b,c){var d,e,f;c["_"+a]={},c[a]={},c[a].ready=function(b){c["_" + a].ready =  c["_" + a].ready || [];c["_" + a].ready.push(b);},e=document.createElement("script"),e.async=1,e.src=b,f=document.getElementsByTagName("script")[0],f.parentNode.insertBefore(e,f)},this);

squatch.ready(function() { 

  var element = document.getElementById('my_coupon');

  squatch.init({
    tenantAlias: "{{tenant_alias}}"
  });

  squatch.api().squatchReferralCookie().then(function(response) {
    element.value = response.code;
  });

});

</script>

[Mobile]

The Referral Code is stored in the Branch integration’s JSON format instead of a cookie on the user’s device:

  "sq_referralCode" : "JANEDOE",

If a referral code is found, this means that this user has been referred and should receive their discount during the checkout process.

Verify the referral code [optional]

The above code only checks to see if there is a referral code present. You can verify the referral code by using the Lookup a Referral Code API call.

Type: GET
URL: https://app.referralsaasquatch.com/api/v1/{{tenant alias}}/code/JANEDOE

Example Response [Valid Referral Code]

{  
   "code":"JANEDOE",
   "dateCreated":1455752646974,
   "referrerName":"Jane Doe",
   "reward":{  
      "credit":1000,
      "unit":"CENTS",
      "type":"CREDIT"
   }
}

Example Response [Invalid Referral Code]

{  
   "message":"Invalid referral code",
   "statusCode":404,
   "apiErrorCode":"REFERRAL_CODE_NOT_FOUND"
}

Reward Fulfillment

If the user was referred, apply a discount coupon during the checkout process so the referred user gets their reward.

7b. Reward Fulfillment - Referred User [Percent Discount]

During the referred user’s checkout process the referred user should have their reward applied. The following code examples help determine whether or not a user was referred.

[Desktop]

Check for Referral Code cookie with Squatch JS autofill. If there is a Referral Code present, this means the user has been referred and should you should apply their discount during the checkout process.

Squatch JS autofill example The following code snippet will check for a referral code with a simple If / Else statement.

<script type="text/javascript">

!function(a,b){a("squatch","https://d2rcp9ak152ke1.cloudfront.net/assets/javascripts/v2/squatch.min.js",b)}(function(a,b,c){var d,e,f;c["_"+a]={},c[a]={},c[a].ready=function(b){c["_" + a].ready =  c["_" + a].ready || [];c["_" + a].ready.push(b);},e=document.createElement("script"),e.async=1,e.src=b,f=document.getElementsByTagName("script")[0],f.parentNode.insertBefore(e,f)},this);

squatch.ready(function() { 

  var element = document.getElementById('my_coupon');

  squatch.init({
    tenantAlias: "{{tenant_alias}}"
  });

  squatch.api().squatchReferralCookie().then(function(response) {
    element.value = response.code;
  });

});

</script>

[Mobile]

The Referral Code is stored in the Branch integration’s JSON format instead of a cookie on the user’s device:

  "sq_referralCode" : "JANEDOE",

If a referral code is found, this means that this user has been referred and you should apply their discount during the checkout process.

Verify the referral code [optional]

The above code only checks to see if there is a referral code present. You can verify the referral code by using the Lookup a Referral Code API call.

Type: GET
URL: https://app.referralsaasquatch.com/api/v1/{{tenant alias}}/code/JANEDOE

Example Response [Valid Referral Code]

{
  "code": "JANEDOE",
  "dateCreated": 1465584764407,
  "referrerName": "Jane Doe ",
  "reward": {
    "discountPercent": 10,
    "monthsDiscountIsValid": 1,
    "type": "PCT_DISCOUNT"
  }
}

Example Response [Invalid Referral Code]

{  
   "message":"Invalid referral code",
   "statusCode":404,
   "apiErrorCode":"REFERRAL_CODE_NOT_FOUND"
}

Reward Fulfillment

If the user was referred, apply a discount coupon during the checkout process so the referred user gets their reward.

8a. Reward Fulfillment - Referrer [Dollar Credit]

Listen for Webhooks

Subscribe a URL as a webhook endpoint to receive webhook events.

Here you can listen for the creation of a reward for the referrer. The reward.created event will notify you whenever a new reward is created.

Lookup the reward

Use the List reward balances API call to lookup the user’s available reward balance based on the rewardId, accountId, and userId in the webhook data.

Type: GET
URL: https://app.referralsaasquatch.com/api/v1/{{tenant_alias}}/reward/balance?accountId=abc_122

Example response

{
    "count": 1000,
    "totalAssignedCredit": 1000,
    "totalRedeemedCredit": 0,
    "unit": "CENTS",
    "type": "CREDIT"
}

This will give you the reward balance by calculating the difference between totalAssignedCredit and totalRedeemedCredit. In this example:

totalAssignedCredit 1000 minus totalRedeemedCredit 0 equals 1000 CENTS available.

Apply the reward

The calculated amount should be added onto the user’s next invoice.

Redeem the reward

Use the Debit a reward balance API call to debit the account’s reward balance. This will update the reward balance and the referral participant’s progress inside the Referral Widget.

Type: POST
URL: https://app.referralsaasquatch.com/api/v1/{{tenant_alias}}/credit/bulkredeem

JSON request

{
    "accountId": "abc_122",
    "unit": "CENTS",
    "amount": 1000
}

Example response

{
   "creditRedeemed": 1000,
   "creditAvailable": 0,
   "unit": "CENTS"
}

8b. Reward Fulfillment - Referrer [Percent Discount]

Listen for Webhooks

Subscribe a URL as a webhook endpoint to receive webhook events.

Here you can listen for the creation of a reward for the referrer. The reward.created event will notify you whenever a new reward is created.

Lookup the reward

Use the List reward balances API call to lookup the user’s available reward balance based on the rewardId, accountId, and userId in the webhook data.

Type: GET
URL: https://app.referralsaasquatch.com/api/v1/{{tenant_alias}}/reward/balance?accountId=abc_122

Example response

{
    "totalDiscountPercent": 10,
    "referrerDiscountPercent": 10,
    "referredDiscountPercent": 0,
    "type": "PCT_DISCOUNT"
}

The total reward discount available to the referrer is then the totalDiscountPercent value.

Apply the reward

The amount should then be applied to the user’s next invoice. Make sure to be aware of the length of the discount set in your Referral SaaSquatch project so that you are aware when the discount will expire.