Segment

Segment is a Customer Data Infrastructure (CDI) that lets you combine data across applications and platforms. Send Airship events to Segment for profile enrichment and event triggering (Airship as a source), and ingest external events from Segment with named users in Airship for message triggering, audience targeting, and analytics (Airship as a destination).

You can use the Source and Destination integrations together or separately.

Segment Integration Requirements

To get started, you must have accounts with both Segment and Airship. Your Airship account must include messaging.

  • Source integration: Your Airship account must include Real-Time Data Streaming.
  • Destination integration: No additional requirements.
 Note

Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. is not a requirement but is strongly recommended for mapping users across Segment and Airship. See: Associating Channels with Named Users.

Set up a Segment Source Integration

To properly feed events into, and associate events with, Segment profiles, you must map named_user_id to Segment profile userId properties.

The Segment Source integration sends Airship events to Segment. First, you will add Airship to Segment as a source and retrieve your Write Key. Then you will create a Real-Time Data Stream integration for Segment in the Airship dashboard.

  1. Log in to your Segment workspace.

  2. Go to the Catalog.

  3. Find the Airship source and click Connect.

  4. Copy the Write Key. You will use this token when enabling your Segment integration in Airship.

Now you are ready to create the Segment Source integration in the Airship dashboard.

  1. In your messaging project, go to Settings » Real Time Data Streaming.

  2. Under Real-Time Data Streaming, click Segment.

  3. Provide a Name and Description for the integration.

  4. Enter the Segment Write Key that you copied when adding Airship as a source in Segment.

  5. (Optional) Select Include Anonymous Data if you want to send events that are not attributed to a named user to Segment. This can increase the number of customer profiles and the cost of using Segment.

  6. Select the event types that you want to send to Segment.
    • Opens
    • Closes
    • Custom Events
    • Screen Viewed
    • Location
    • Region
    • Sends
    • Control
    • Tag Changes
    • First Opens
    • First Opt-In
    • Uninstalls
    • Message Center Read, Delivery, and Delete Events
    • In-App Message Expiration, Resolution, and Display Events
    • Web Notification Session
    • Web Notification Click
    • Email Subscription
    • SMS Mobile-Originated
  7. Click Activate.

It may take several minutes to begin populating events in Segment. You can open the Airship source in Segment and use the Debugger option to see incoming data and confirm that your integration is working properly.

Segment Destination Integration

The Segment server-side Destination integration passes track events and identify attributes into Airship as custom events and tags.

Segment track events come into Airship as custom events that you can use to trigger and personalize automationsA set of conditions that your audience must meet before they receive a message. and journeysA series of messages that is initiated by a single automation trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine the continuation of the series. .

You can take advantage of Segment identify events to assign tags to named users.

Airship ConceptSegment Concept
Custom EventsEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom events can trigger automation and journeys. You can code them into your app or website, or send them to Airship from an external source using the custom event API. Custom events contain properties that you can use to personalize messages.Track
TagsMetadata that can be associated with a channel or a named user for targeting. Tags are generally descriptive terms indicating user preferences or other categorizations, e.g., wine_enthusiast or weather_alerts_los_angeles. Tags are case-sensitive.Identify

Custom Events from Segment

Airship captures track events from Segment using the Custom Events API. You can use the properties in these incoming events to trigger and personalize messages for your audience.

The track event’s properties object maps to an Airship custom event’s body.properties object. However, Airship only captures strings, numbers, and booleans. Objects and arrays will not appear in the custom event properties in Airship.

The track event’s event key maps to the custom event name in Airhsip. You can use the name value to differentiate between different track events from segment.

Example track event from Segment

{
  "receivedAt": "2019-07-09T19:24:15Z",
  "messageId": "6dJnUw1OKG",
  "type": "track",
  "properties": {
    "provider": "Branch",
    "campaign": {
      "source": "AdWords",
      "name": "Campaign Name",
      "content": "Organic Content Title",
      "ad_creative": "Red Hello World Ad",
      "ad_group": "Red Ones"
    },
    "categories": ["test-campaign"]
  },
  "event": "Install Attributed",
  "userId": "sKQR2ORpaw",
  "timestamp": "2019-07-09T19:24:15Z"
}

Example Custom Event in Airship

{
  "occurred": "2019-07-09T19:24:15",
  "user": {
    "named_user_id": "sKQR2ORpaw"
  },
  "body": {
    "properties": {
      "source": "Segment",
      "provider": "Branch"
    },
    "name": "install attributed",
    "interaction_type": "cdp"
  }
}

Personalize Messages Using Custom Events from Segment

You can use Airship HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. to personalize messages in automation rules or journeys based on incoming events from Segment. This provides a mechanism to message your users automatically, at the right time, and target users with relevant information that increases engagement.

Example Custom Event

{
  "occurred": "2019-07-09T19:24:15",
  "user": {
    "named_user_id": "sKQR2ORpaw"
  },
  "body": {
    "properties": {
      "source": "Segment",
      "provider": "Branch",
      "name": "Cool Person",
      "likes": "baseball"
    },
    "name": "changed_preferences",
    "interaction_type": "cdp"
  }
}

Example Personalized Message Text

Hi {{name}}!

Are you ready for {{#eq likes "baseball"}}opening day?
{{ else }}the next big sporting event?{{/eq}}

Tags from Segment

Airship assigns tags to named usersA customer-provided identifier used for mapping multiple devices and channels to a specific individual. based on incoming identify events from Segment. You must create a segment-integration tag group to receive these tags.

This integration supports boolean traits only. Airship adds or removes the trait key as a tag in the segment-integration group depending on the boolean value; we add tags for traits that are true and remove tags for traits that are false.

 Note

Airship returns a 400 BAD REQUEST if any traits in the identify event are non-boolean.

Example Segment Identify Event

{
  "userId": "jane",
  "type": "identify",
  "timestamp": "2019-06-12T22:21:33Z",
  "traits": {
    "new-customer": false,
    "order-completed-last-60-days": true
  }
}

Example Airship Tag Change

{
  "id": "00000170-cff9-7e5e-6a5a-21814f6b3a37",
  "offset": "1000031868729",
  "occurred": "2019-06-12T22:21:33Z",
  "processed": "2019-06-12T22:21:33Z",
  "device": {
    "named_user_id": "jane"
  },
  "body": {
    "add": {
      "segment-integration": ["order-completed-last-60-days"]
    },
    "remove": {
      "segment-integration": ["new-customer"]
    },
    "current": {
      "segment-integration": ["order-completed-last-60-days"]
    }
  },
  "type": "TAG_CHANGE"
}

Create Your Segment Tag Group

To assign tags to Airship uses using identify events from Segment, you must set up an Airship tag group called segment-integration to capture Segment tags.

See also: Manage Tag Groups.

  1. Go to Settings » APIs & Integrations » Tag Groups.

  2. Click Create Tag Group and configure the fields.

    • Name: This name appears elsewhere in the dashboard, so choose something easily understandable and that describes the associated database, e.g., “Segment Integrations”
    • Description: The description should supplement the name, giving additional information about the tag group, if necessary. Be descriptive enough that anyone in your company would understand its source and purpose.
    • Group Key: Enter segment-integration. This permanent, unique ID is the text you will use when referring to your tag group in the API.
       Warning

      Do not enable the Allow these tags to be set only from your server setting. Enabling this setting prevents Segment from setting tags in Airship.

  3. Click Save.

Create an Airship Access Token for Segment

You must provide Segment a token with the All Access role so that it can communicate with your Airship project.

  1. In Airship, go to Settings » APIs & Integrations » Tokens.

  2. Click Create Token.

  3. Enter a token Name. This is just a friendly name to help you recognize your tokens in Airship.

  4. Select the All Access role.

  5. Click Create Token.

  6. Copy the values for App Key and Access Token, then click Got it to close the window.

Set Up Airship as an Event Destination in Segment

When you add Airship as a destination, Segment adds tags to your named users in the segment-integration tag group and attributes custom events to named users.

  1. Log in to your Segment workspace.

  2. Go to the Catalog.

  3. Find the Airship destination and click Configure Airship.

  4. In the Select Source dialog, select a source and click Confirm Source.

  5. Enter the App Key and Access Token that you copied when setting up the Real-Time Data Streaming integration in Airship.

    • API Key: This is your Airship access token.
    • App Key: This is your Airship app key.
  6. Click Save.

Troubleshooting your Segment Integration

Airship returns errors based on the events received as a part of this integration.

  • 400 Traits do not meet requirements to set tags: Airship supports boolean traits only. Airship rejects requests if any traits are not boolean.

  • 400 Properties may not contain more than 20 elements: Airshp custom events support up to 20 properties. Airship rejects track events with more than 20 properties.

  • 501 Unsupported call type: this integration supports only track and identify events from Segment. Airship reports any other event type as an error.

If you don’t see events in Airship, and you don’t see errors in Segment, make sure that your userId values in Segment exist as named users in Airship. Airship returns 200 OK when attributing events to named users, even if the named_user_id does not exist in Airship.