Referral SaaSquatch Help Center

The Segment.io integration with Referral SaaSquatch makes it easy to send your existing Segment data to Referral SaaSquatch.

This reference outlines the functionality of the Segment Integration and includes details about the structure of the method, available parameters, limitations, and examples.

How do I use the Segment integration?

Segment customers can use the Segment analytics.js library instead of directly using the squatch.js Referral SaaSquatch javascript library.

Use the analytics.js identify method instead of squatch.js init call to identify, attribute, and convert users in your Referral SaaSquatch Referral program.

To get started with our Segment.io integration checkout our Quickstart guide.

What features are supported with Segment?

Most of the features of the Referral SaaSquatch squatch.js library are available through this Segment Integration. However, there will always be some things that will require you to use squatch.js directly.

Signed Requests

The Segment Integration supports Signed Requests using checksums.

Please be aware of the following differences:

The structure and contents of the checksum being generated is based on that of the equivalent squatch.js call.

  • Ordering of parameters when generating the checksum is based upon squatch.js init parameters names, not the analytics.js parameter names. For example, avatar should still be sorted with "u" for user_image
  • Omit other analytics.js traits from the checksum, such as Google Analytics ids
Referral SaaSquatch REST API

At this time the Segment integration with Referral SaaSuatch is only an abstractions of the squatch.js javascript library.

Identify Method Reference

The Segment analytics.js library identify method is used to connect with your Referral SaaSquatch.

Structure

The Segment analytics.identify method is structured differently than the Referral SaaSquatch squatch.js init call.

Unlike the squatch.js init call, in the analytics.identify method the userId and the tenantAlias are not listed among the regular parameters.

tenantAlias Required Identifies which program tenant to connect to. Your program has two tenant aliases -- one for test mode and one for live mode. Test mode alias are prefixed with test_, for example test_abhoihnqwet

The tenantAlias is set in the SaaSquatch Integration settings in the Segment portal.
userId Required 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.

The userId is used as the analitics.identify userId rather than a trait like the other parameters
Example

The following example highlights the structure of the analytics.identify method with no parameters:

analytics.identify( "userId", {
    /*
    PARAMETERS GO HERE
    */
},{
    integrations: {
        SaaSquatch: {
            checksum: null
        }
    }
});

Parameters

accountId Required We use accountId to link a group of users together. See Shared vs Solo Accounts to see what you should use here.
firstName Required The user's first name
lastName Optional The user's last name
email Optional The e-mail address of the user. We use this to contact the user when someone they referred signs up or pays.
avatar 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.
paymentProviderId Required Unless explicitly setting this field it should be left as 'null'. On payment provider programs this can be set to the Stripe Customer ID, Recurly Account ID, Braintree Account ID, or the Zuora Account ID.
accountStatus Optional

The status of the account identified by accountId.

  • Omit this parameter on Payment Provider Integration programs.
  • The default value is TRIAL.
  • Possible values are TRIAL, FREE, PAID, or CANCELLED
  • Can also be updated using the REST API or Squatch.js.
referralCode Optional

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

  • Do not include when paymentProviderId exists.
  • Automatically filled in the background by Analytics.identify method from browser cookie.
  • If someone uses a referral code during checkout, set that value here.
  • Can also be set using the REST API or Squatch.js.
userReferralCode Optional The referral code to be shared by this userId.
  • Used to set a custom referral code for this userId.
  • 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.
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_US or zh_CN
mode Optional

Sets the mode in which the widget is displayed. 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
  • 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
checksum Optional A HMAC-SHA2 checksum that is used to validate that data originated from your servers. For details, see the Signed Requests documentation.

Example

Below is a comparison of a squatch.js init call vs the equivalent Segment analytics.js identify call.

Referral SaaSquatch - squatch.js Segment - analytics.js
Use squatch.js init Use analytics.js identify
_sqh.push(["init", {
    tenant_alias: "test_aaaexampleaaa",
    user_id: "u1234",
    account_id: "a5678",
    email: "joe.tester@example.com",
    user_image: "http://example.com/avatar/205e460b479e2e",
    first_name: "Joe",
    last_name: "Tester",
    user_referral_code: "JOETESTER",
    mode: "EMBED",
    account_status: "PAID",
    locale: "en_US",
    fb_share_image: "http://www.example.com/logo.png",
    checksum: "arbPDAcedO38Qw/qdJLCqd2tlRQ="
}]);
analytics.identify( "u1234", {
    accountId: "a5678",
    email: "joe.tester@example.com",
    avatar: "http://example.com/avatar/205e460b479e2e",
    firstName: "Joe",
    lastName: "Tester",
    userReferralCode: "JOETESTER",
    mode: "EMBED",
    accountStatus: "PAID",
    locale: "en_US",
    referralImage: "http://www.example.com/logo.png",
    paymentProviderId: 'cus_8rVOAthroptvT6'
},{
    integrations: {
        SaaSquatch: {
            checksum: 'n3VtXg92TVOuzQ+6EMV8FvjY4em5NptCcesDYv+9tegs='
        }
    }
});

Additional Resources

Segment provides support documents about their integration with Referral SaaSquatch.

You can also check out the full source code for the integration on Segment's Github.

A Quickstart guide for our integration with Segment is also available.

Details about squatch.js can be found in our Referral Widget Quickstart as well as in the squatch.js reference.

Looking for something special?

Still couldn't find it?