Segment Subscription

Beta Program - Version 2 of the SaaSquatch for Segment integration is part of our Beta Program. Please contact our Success Team.

	Source / Stream	Destination / Subscription	Web Plugin
Segment Integration Documentation	Tech Reference	Tech Reference	Classic only Quickstart Classic only Tech Reference

🔗 Overview

The Segment destination consumes data sent from Segment to the SaaSquatch APIs for tracking events and upserting users.

Segment	SaaSquatch
Identify	Upsert User
Track	Track User Event

🔗 Installing the Segment Destination

1. Login to the SaaSquatch Portal

2. Go to your Integrations page

3. Enable the Segment integration.

Note: You must have the Segment integration enabled for your tenant by SaaSquatch before the option will show up on this page.

1. Copy your Segment Access Token

2. Login to your Segment account

3. Create a new Webhooks destination.

1. Configure the destination with:
   • Webhook URL: https://segment.integrations.saasquatch.com/segment
   • Header: Authorization: Bearer {{YOURTOKENHERE}}

🔗 Using Segment for Core Topics

Area	Solution
Identification	Identification is handled entirely by this integration. id and accountId are passed through the integration.
Attribution	Attribution can either be done by ensuring that referredByCodes is a trait recorded in Segment, connecting the Branch integration for Mobile or by using Squatch.js for cookie tracking.
Engagement	Engagement can be done by using the referralCode trait in your other marketing tools, by doing a batch export for email, or by using Squatch.js or the Mobile Widget for embedding widgets into your apps.
Conversion	Conversion is typically triggered by either user traits, or tracked events such as order complete through this integration.
Fulfillment	The Segment subscription does not solve fulfillment. Look at using our API, batch fulfillment, one of our 3rd party reward integrations or the Segment source.

🔗 Identify Calls

Segment's identify calls are tracked in SaaSquatch by upserting users.

• Custom Traits in Segment are mapped to Custom Fields in SaaSquatch

• address, birthday, created_at and id traits are ignored, so they are not stored as custom fields on the SaaSquatch user

• These Segment standard fields are mapped to SaaSquatch standard fields

  • avatar in Segment is mapped to imageUrl in SaaSquatch
  • email in Segment is mapped to email in SaaSquatch
  • firstName in Segment is mapped to firstName in SaaSquatch
  • lastName in Segment is mapped to lastName in SaaSquatch
  • name in Segment is mapped/split into firstName and lastName in SaaSquatch
  • userId in Segment is mapped to user_id and account_id

• Certain values are sanitized

  • Non-alphanumeric characters in Segment traits are stripped.
  • Text traits longer than 1024 characters are truncated.
  • Trait names longer than 64 characters are truncated.

• locale in SaaSquatch is set based on locale in the Segment context.

• IP Addresses in SaaSquatch are set based on the ip in the Segment context.

• User Agent tracking in SaaSquatch uses the user_agent in the Segment context.

• Users with a anonymousId but without an userId will be ignored.

🔗 Track Calls

The Segment track calls are mapped to the SaaSquatch APIs for tracking events. Key names will be camelcased, and traits will be stored as event fields.

• When the account_id trait doesn't exist, then the id trait will be used in it's place. See Shared vs Solo Accounts.

• Users with an anonymousId but without a userId will be ignored.

• Certain values are sanitized

  • Text traits longer than 1024 characters are truncated.
  • Trait names longer than 64 characters are truncated.
  • Tracked event names longer than 64 characters are truncated.
  • Non-alphanumeric characters in Segment traits are stripped.
  • Non-alphanumeric characters in Segment event names are stripped.

These standard Segment Spec events are mapped:

• Order Completed in Segment maps to the purchase in SaaSquatch

• Order Refunded in Segment maps to the refund in SaaSquatch

• purchase and refund events in SaaSquatch are modelled based on the Segment spec, so contain all the same fields.

🔗 Page and Group Calls

These calls are not yet implemented in the SaaSquatch subscription destination.

🔗 Configuration Options

When configuring your SaaSquatch Destination for Segment, there are several options you can set in the configuration of the integration on the Integrations page in the SaaSquatch Portal.

🔗 Identify segments transformer

The segments transformer allows you to provide a custom JSONata expression which can transform the body of a Segment Identify call into a list of segment operations which will apply to the user upsert in SaaSquatch.

You may need to segment users in SaaSquatch based on traits provided by Segment. For example, given the following Identify body:

{
  "messageId": "test-message-rxya2",
  "timestamp": "2021-01-12T22:28:04.947Z",
  "type": "identify",
  "email": "test@example.org",
  "projectId": "nczL0it7lw",
  "traits": {
    "trait1": 1,
    "trait2": "test",
    "trait3": true
  },
  "userId": "test-user-524utb"
}

And a segments transformer configured as:

[traits.trait2, "hardcoded"]

When the user is upserted into SaaSquatch it will be in the segment test and the segment hardcoded.

JSONata is a flexible expression language for transforming JSON data - for more information please see the documentation.

🔗 Invalid segments strategy

Segments on SaaSquatch users can only contain alpha-numeric characters. This setting allows you to choose how segments resulting from the segments transformer that do not meet this requirement are handled. You can chosoe from 3 different handling strategies:

1. Discard invalid segments

This option will remove any invalid segment from the segment array before being applied to the user in SaaSquatch.

2. Discard all segments if any are invalid

This option will prevent any segments from being applied to the user in SaaSquatch if any of them are invalid.

3. Sanitize invalid segment names

This option will attempt to "sanitize" any invalid segment names by stripping them of invalid characters.

🔗 Invalid event data strategy

Some data that is supported by Segment is not supported in events by SaaSquatch. An example of such data is a field that contains arrays which themselves contain arrays. In the case of encountering unsupported data you can choose from 3 different handling strategies:

1. Discard the event

If unsupported data is encountered in an event that is to be sent to SaaSquatch, this option will discard the event and will prevent the attempt to log the event in SaaSquatch.

3. Discard invalid event field values

If a field of an event contains unsupported data, this option will discard only that field's data, but otherwise log the event as usual. In JSON terminology, the field's value will be set to null.

5. Stringify invalid event field values

If a field of an event contains unsupported data, this option will replace the field's value with a "stringified" version of the field's value. This way, no data will be lost from the event, however the structure of the inserted event will no longer match the original.