Segment Subscription

	Source / Stream	Destination / Subscription
Segment Integration Documentation	Tech Reference	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.

4. Copy your Segment API Key

5. Login to your Segment account

6. Under Destinations select "Add Destination".

7. On the Catalog page, search for "SaaSquatch" and select the "SaaSquatch v2" result.

8. Select Javascript as the data source and click Next

9. Enter a name for the destination (eg. SaaSquatch) and click Save

10. On the side bar, click on Connections > Destinations and select your newly created Destination from the list

11. Under Connection Settings click API Key

12. Edit the API key field and paste in the API key that you copied from the SaaSquatch Integrations page, then click Save

🔗 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 the referral code is included in areferredByCodes trait as an array recorded in Segment.
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 Completed 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 or first_name in Segment is mapped to firstName in SaaSquatch
  • lastName or last_name 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 userId and accountId

• 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.

• Track calls with a timestamp more than 180 days in the past or more than 90 days in the future will be discarded.

• 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.

• Segment messageId is used as the idempotencyKey in the track event API call to SaaSquatch. This results in at most once processing of the event by SaaSquatch regardless of any potential retries made by Segment. If you set a custom messageId that is an invalid idempotency key, it will be ignored and the event will be logged without idempotency. For more details, read our event idempotency developer's guide

These standard Segment Spec events are mapped:

• Order Completed in Segment maps to the purchase in SaaSquatch, although this mapping can be prevented if needed

• 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, Group, Screen, and Alias 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.

🔗 General Settings

These settings are applied to all events.

🔗 Invalid Segments Strategy

Segment operations on SaaSquatch users can be set using our Identify Segments Transformer or our Track User Upsert Transformer, although they only contain alpha-numeric characters. This setting allows you to choose how segments operations that do not meet this requirement are handled. You can choose 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.

2. 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.

3. 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.

🔗 Identify Call Settings

These settings are applied to all Segment Identify events.

🔗 Ignore Identify Events

This setting allows you to have control over if users are or are not upserted when SaaSquatch receives your Identify events. By default, Identify events will cause user upserts but by enabling this option, they will be ignored.

🔗 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.

🔗 Track Call Settings

These settings are applied to all Segment Track events.

🔗 Prevent Order Completed Event Remapping

By default, the key of Order Completed events from Segment will be remapped to SaaSquatch purchase events. You may want to disable this behavior if you are sending Order Completed events with non-standard fields, as they might not be valid purchase events.

🔗 Track User Upsert Strategy

This setting allows you to control in which situations users should be upserted from Track events. The default is that they will be created if they do not exist, but you can choose from three handling strategies.

1. Never upsert: do not perform any user upsert. If the user exists, the event will be logged, if not the event will fail.
2. Upsert if no user: only upsert the user if they do not already exist.
3. Always upsert: always perform a user upsert prior to logging the event.

Using the visual editor, you can build conditions to specify when to do each of the three strategies mentioned above. This condition is an JSONata expression, and is evaluated using the Track event itself so any field that might be in the Track event can be used to customize this behaviour.

For example if you created the following JSONata condition with the editor, event = "Order Completed" ? "ALWAYS" : "MISSING_USER", it would configure it such that users are always upserted when Order Completed Track events are received and only upserted if the user doesn't exist in all other cases.

🔗 Track User Upsert Transformer

In the case where a Track event causes a user upsert, the track user upsert transformer allows you to transform properties from your Track events into fields on the user upsert.

This transformer is a JSONata expression which returns the object to include in the user upsert. Supported fields for the user upsert mirror that of our Open User Upsert API method.

Since this JSONata expression is evaluated using the Track event, any field that might be in the Track event can be used to customize this behaviour. For example, if your Track event contains a property called plan, you could upsert it to a custom field on the user with the expression { "customFields": { "plan": properties.plan } }