Send Onsite User Data to Sailthru Using Segment

Use Segment JavaScript calls on your site to add users in Sailthru, update their user profile data and list memberships, and send purchase data or custom events to Sailthru.

The integration translates Segment Identity, Track, Page and Ecommerce Cart/Purchase calls to Sailthru API User, Event and Purchase calls. As Segment captures these events on your website, they are automatically retransmitted to your Sailthru account.

Getting Started

Request a new application-specific API key and secret from your Project Manager or Customer Success representative for use exclusively with Segment.

Your Project Manager or Customer Success Manager will enable Segment keys for use with Purchase, User and Event methods  and provide them to you. We recommend you discuss your strategy for using Segment with your Sailthru team to ensure the optimal deployment. 

Once you have your API key and secret, log in to your Segment account and click Sources, then Javascript.

Add a new integration from the Integrations panel and select Sailthru.

 

This will open up the Sailthru configuration screen. Complete the form fields to add your API key and secret.

segment-settings

In addition to the required settings, you will have the option to configure a default optout status to assign when a user opts out of email and a default list name for adding users. Regardless, you will be able to specify different values for either of these options with each call.

To Track pageviews using Segment’s page call you will need to add your Customer Id. You can find this under your API & Postback settings page in my.sailthru.com.

Optout

The default Optout Status is applied to all users who you add/update via Segment if a specific optout status is not sent in the call. It is usually best to leave this set to “none” so that when you add each user in segment, The default status for the optout value is none or you can select all, basic or blast.

  • all: Opts the user out of all emails (campaigns & transactionals). This is the default status when a subscriber marks your email as spam from within an email client.
  • basic: This opt-out setup allows for certain communications (see some acceptable examples in the next bullet) to always send to a user – despite their status.
  • blast: Opts the user out of all campaign emails. The user will still receive all transactional (1:1) emails.
  • none: Optout(none) is a way of revalidating users back from being any type of optout. This would only be used if an end user has previously opted out and would like to opt back in to be a valid user.

You can read more about Optout Levels here.

Adding Users to a List

To configure a default list name, Segment exposes a setting to configure this in the UI. You can also explicitly set your own defaultListName through the integration option on identify.

Supported Segment Calls

Sailthru supports identify and track events in the Segment integration. For e-commerce events, Segment currently only supports a completed purchase. .

Identify

The Identify call can be used to update user data in Sailthru, add a user to a Sailthru list, or register a user’s opt-out.

The Identify call in Segment will pass that user’s information to Sailthru with a userId that will be stored in Sailthru as the user’s extid key. If that extid already exists, it will be used to identify the user to update in Sailthru.

Any Segment “traits” that are passed (for example, first_name) will be transformed to custom profile fields (vars) in Sailthru, and can be viewed on the My Sailthru user lookup or used in Audience Builder for segmenting or reporting.

To add/update a user profile in Sailthru, use the Identify call. For example:

analytics.identify("123456789",{
   "first_name": "Joanna",
   "Last_name" : "Smith",
   "email": "jsmith@example.com"
   },{
   Sailthru:{
     defaultListName: "Master List"
   }
 });

The Sailthru parameter defaultListName determines the list to add the user. If it is not included, the default list is used that you specified in the Segment UI when configuring this integration. For example, the following call would create a user and add them to your default list:

analytics.identify("123456789",{"first_name": "Joanna"});

You can configure an optout_email value in the Segment UI, or pass in a value through the integrations object with one of the Sailthru expected values:

analytics.identify("123456789",{
   "first_name": "Joanna",
   "Last_name" : "Smith",
   "email": "jsmith@example.com"},
   {
      Sailthru:{optoutValue: "basic"}
   }
);

To ensure that you pass a usable email address to Sailthru, the trait “email” will be added as the “email” key for the user’s profile, as opposed to a custom field (var) named email.

Note: If you send an identify call without a traits.email and only a userId, the user will not have an email key and will not be accessible through the My Sailthru User Lookup. The user profile will only be accessible to look up via the User API, using theextid.

Track

When you track an event using Segment’s track it will send the event to Sailthru as a custom event. This event can be used as an entry point to Lifecycle Optimizer. Navigate to Communications > Lifecycle Optimizer in your Sailthru dashboard to create a new Flow.

Configure a custom event that will start the flow (due to its matching event name) and will trigger a follow-up action to the event.

LO flow from event

For instance, in the above example notice that the Registered event will add the user who trigger the event to a list.

Purchases

Segment can track purchases using the e-commerce tracking API. To send a completed purchase to Sailthru you can track the event with the name Order Completed to send the products you’ve listed to Sailthru’s purchase API. This event will track the purchase on the user profile under purchase history:

You can also view any purchases using the Purchase Log which is available under the Analytics menu.

Email address is the primary identifier for purchases. If an extid is passed then Segment will make a GET request to retrieve the user’s email based on their userId, which is their extid in Sailthru. This requires that the user has an email address as a key on their profile.  If the user does not exist in Sailthru, the Segment event will throw an error.

If the user exists, the purchase will be added to their profile. Be sure to call identify with an email passed in the traits object prior to the Order Completed event to ensure that the email address exists.

If you are sending events using one of Segment’s server-side libraries you can also send the email value in your track calls under context.traits.email.

Once Order Completed is triggered, Segment will pass in incomplete: 0 to signify that the order is now complete. Segment will map the following Sailthru required fields from the v2 Order Completed Spec:

 

Sailthru Spec Segment Spec
title products.$.name
qty products.$.quantity
price products.$.price
id products.$.product_id
url context.page.url

As Sailthru uses the url field to identify each product, Segment will pull this value out from the context.page.url.

Example call:

analytics.track('Order Completed', {
    checkout_id: 'fksdjfsdjfisjf9sdfjsd9f',
    order_id: '50314b8e9bcf000000000000',
    affiliation: 'Google Store',
    total: 30,
    revenue: 25,
    shipping: 3,
    tax: 2,
    discount: 2.5,
    coupon: 'hasbros',
    currency: 'USD',
    email: 'user@example.com',
    products: [{
            product_id: '507f1f77bcf86cd799439011',
            sku: '45790-32',
            name: 'Monopoly: 3rd Edition',
            price: 19,
            quantity: 1,
            category: 'Games'
        },
        {
            product_id: '505bd76785ebb509fc183733',
            sku: '46493-32',
            name: 'Uno Card Game',
            price: 3,
            quantity: 2,
            category: 'Games'
        }
    ]
});

Page

The page call can be used to track pageviews in Sailthru. To enable this functionality you must configure your Segment setup with your Sailthru Customer Id, which can be found on your API settings page in Sailthru.

When you make a  page call using Segment  this will be translated to a Sailthru pageview endpoint and you will see the calls populate in the Sailthru Realtime Dashboard.

The context.page.url is also a required field for all page calls, so be sure this is present on each call.

Segment will map the Segment userId to the Sailthru horizonId, which uniquely identifies a known Sailthru user profile.

The page call in Segment assumes that the Sailthru Content API has been enabled and interests are tracked using stored tags. To build interests profiles please ensure that you have pages tagged using the Sailthru Content API.

 

analytics.page("Home",
"properties" : {"userId" :"<value of sailthru_hid_cookie>"}
);

FAQ

Rate limits

All calls are subject to rate limits.

  • For identify events, we hit the /user endpoint, which allows 300 requests/second.
  • All others allow 40 requests/second.
  • Limits can be raised on a case-by-case basis in order to support valid business practices. Reach out to your Sailthru account representative with any questions or requests.

Nested Traits and Property Handling

Sailthru does not accept nested custom traits or properties through Segment, so by default Segment will flatten any custom nested properties. For example, in this code from the debugger, you will see the nested properties in the “input” converted to a single level of Sailthru vars in the “output”.

{
   "input": {
      "type": "track",
      "userId": "14092348",
      "event": "Played Game",
      "timestamp": "2017",
      "properties": {
         "levels": [
            1,
            2,
            3
         ],
         "arcade": {
            "blips and chitz": {
               "planet": "Parblesnops"
            },
            "galaxy": {
               "coordinates": "1232.4832"
            },
            "games": [
               "Roy: A life well lived",
               "Whack a mole"
            ]
         }
      }
   },
   "output": {
      "id": "14092348",
      "key": "extid",
      "event": "Played Game",
      "vars": {
         "levels_0": 1,
         "levels_1": 2,
         "levels_2": 3,
         "arcade_blips and chitz_planet": "Parblesnops",
         "arcade_galaxy_coordinates": "1232.4832",
         "arcade_games_0": "Roy: A life well lived",
         "arcade_games_1": "Whack a mole"
      },
      "format": "json",
      "api_key": "3c6e0b8a9c15224a8228b9a98ca1531d",
      "shared_secret": "5ebe2294ecd0e0f08eab7690d2a6ee69",
      "sig": "3311842a74c4736836a29eefbc1ea464"
   }
}

Replays

Note that Sailthru does not support historical replay.

Top