SaaSquatch Help Center

Referral SaaSquatch integrates with Branch Metrics. This technical reference explains the specifics fields, features, API calls and functionality that is used in the integration.

New to Branch? Start Here

This page is a technical reference of the Branch integration. Just getting started for the first time? Check out this article instead: Branch Metrics Getting Started Guide

How it Works

The Referral SaaSquatch integrates with Branch Metrics works as follows:

  • SaaSquatch referral links (e.g. ssqt.co/h126b21) will start redirecting to Branch links
  • Referral SaaSquatch will create branch links dynamically and set values for data, channel, tags and desktop_url
  • Branch deep link data will include details of the referral code, the referrer and reward (See field reference below)
  • Analytics Tags will be added to help you track the performance of different platforms.
    • channel: the referral medium. One of FACEBOOK, TWITTER, EMAIL, DIRECT, REMINDER, UNKNOWN
    • tags: the source of the referral. One of STANDARD, MOBILE, UNKNOWN

By default Referral SaaSquatch will send all link clicks through Branch, but will continue to send redirect desktop traffic to your web/desktop site you configured. This is done by setting the Branch value for desktop_url.

  • desktop_url: the landing page you set in our portal when you created your program. If you set a desktop url for your app in Branch, it will be overwritten.

When Referral SaaSquatch creates links dynamically in branch the resulting link, including analytics tags, redirects and custom metadata produce a deep link like the following example:

{
    "code" : "BRITTANYTEST",
    "$desktop_url" : "http:\/\/landingpage.com\/a\/test_a6whcgrt0vcw3\/widgets\/referral?code=BRITTANYTEST&referralMedium=DIRECT&referralSource=STANDARD",
    "sq_accountId" : "55a43496ebbaff9cf86443d3",
    "sq_amount" : "10",
    "sq_firstName" : "Brittany",
    "sq_id" : "55a43496ebbaf01cebac42cb",
    "sq_imageUrl" : "http:\/\/gravatar.com\/avatar\/77af7eba41d1ccad2bf2c13704637c25?d=mm",
    "sq_lastName" : "Test",
    "sq_referralCode" : "BRITTANYTEST",
    "sq_type" : "PCT_DISCOUNT",
    "sq_unit" : "PERCENT",
    "~channel" : "DIRECT",
    "~tags" : ["STANDARD"],
    "~creation_source" : "API",
    "+is_first_session" : false,
    "+clicked_branch_link" : true
}

Data Fields

When Referral SaaSquatch creates links dynamically in branch, it includes a number of metadata fields in the data field. These includes fields from the User, Referral Code and Reward objects.

sq_id
string

The referrer's user id. This allows you to look up the user in your own system.

sq_accountId
string

The referrer's account id. This allows you to look up group or company info. See Shared vs. Solo accounts

sq_firstName
string

The referrer's first name.

sq_lastName
string

The referrer's last name.

sq_imageUrl
string

The referrer's profile image url. Note that unlike the user's imageUrl that is used other places in Referral SaaSquatch, like via API, in theme context and in Squatch.js, if this field is set to null it won't actually be null. Instead, when it's null it is instead replaced by a gravatar link that's automatically generated based upon a hash for the referrer user's email address for when we do not have an image url for that user. If you want to detect for null images instead you should look for if it's gravatar, or not use this field and look up the value in your user database, or something else.

sq_referralCode
string

The referrer's referral code. This is necessary to attribute the referral.

sq_amount
string

The amount of the referree's reward. This is sort of like the reward fields returned from the lookup referral code API call for explaining a reward but it's different and uses a custom mapping of fields described in the table below to map from this abstract field (that's not available in the API) to other stored or calculated fields for rewards that can be looked up directly via the API, or the fields used in programDetails of theme context or the fields in squatch.js, or other places where rewards are used. Use this convenient mapping table.

  • For rewards of type TIME_CREDIT and CREDIT this field is equal to the reward field called credit
  • For rewards of type PCT_DISCOUNT this field is equal to the reward field called discountPercent
  • For rewards of type FEATURE this field is equal to the reward field called quantity
  • For rewards of type GIFTCODE this field is empty
sq_unit
string

The unit of the referree's reward. For example, in a 10% off referral program this would be PERCENT

sq_type
string

The type of the referree's reward. One of: PCT_DISCOUNT, TIME_CREDIT, FEATURE, CREDIT, GIFTCODE