Segment

Segment is a Customer Data Platform (CDP) 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 email registration, message triggering, audience targeting, and analytics (Airship as a destination).

Segment integration requirements

• Accounts
  1. Segment
  2. Airship
     • Messaging
     • Real-Time Data Streaming — Required for source/outbound integration only
• Airship project
  • Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. must be enabled for your project.

Source integration

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

Configuring the Segment source integration

To configure the integration, 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 Airship.

In Segment:

1. Go to Catalog.
2. Find the Airship source and select Add Source.
3. Add a name and optional labels for your source integration, then select Add Source.
4. Copy the Write Key. You will use this token when enabling your Segment integration in Airship.

In Airship:

1. Go to Settings.
2. Under Project Configuration, select Manage for Real-Time Data Streaming.
3. Under Real-Time Data Streaming, select Segment.
4. Follow the onscreen instructions to configure the integration.

   You have the option to include anonymous data. Enable this 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.

   By default, custom events that are sent from Segment to Airship are excluded from being sent back to Segment. If you would prefer to receive these events, contact Airship Support .

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.

Destination integration

This Segment destination integration uses the Segment Actions framework  to map Segment events of all types to Airship Custom Events, Attributes, and Tags. It can also be used to register email addresses as well as associate them with Named Users.

There are predefined mappings for the Segment Actions Set Attributes, Custom Events, and Register and Associate. The Named User defaults to userId. You can customize these mappings and also manually map the Manage Tags actions.

Configuring the Segment destination integration

In Airship:

1. Go to Settings.
2. Under Project Configuration, select Manage for Partner Integrations.
3. Select Segment.
4. Select Configure for the destination integration and follow the onscreen instructions to:
   • Create Tag GroupAn array of tags that you can associate with both channels and named users., AttributesMetadata used for audience segmentation and personalization. They extend the concept of Tags by adding comparison operators and values to determine whether or not to target a user, helping you better evaluate your audience., and an authentication token. Segment uses the token to communicate with your project in Airship.
   • Configure Airship as a destination in Segment. You must select the Airship Actions integration, not the Airship integration.

Custom Events

The default trigger for the Custom Events Action is the Track event type. This, like the rest of the mappings, is configurable in Segment to suit your requirements.

Airship Custom Events must have an Audience (Named User), an Occurred Time, and a Name. These default to userId, timestamp, and event. Feel free to modify, but note that they must exist and be valid. Custom Events can also (optionally) have properties, and these default to items in the properties object.

{
  "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"
}

{
  "occurred": "2019-07-09T19:24:15",
  "user": {
    "named_user_id": "sKQR2ORpaw"
  },
  "body": {
    "name": "install attributed",
    "interaction_type": "cdp",
    "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"],
      "source": "Segment"
    }
  }
}

Manage Tags

For the Manage Tags Action, you must manually map Segment event objects to Airship tags. When mapping, the tag names default to traits.airship_tags. Change these to whatever is relevant, noting that values must be boolean.

The integration uses the segment-integration Airship tag group, which is created automatically when you configure the integration in the Airship project settings. You can use a different tag group that better fits your use case, but the examples on this page refer to segment-integration.

This integration supports boolean properties only. Airship adds or removes its key as a tag in the segment-integration tag group depending on the boolean value. Airship adds tags for properties that are true and removes tags for properties that are false.

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

{
  "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"]
    }
  },
  "type": "TAG_CHANGE"
}

Set Attributes

The default trigger for the Set Attributes Action is the Identify event type, but you can change it in Segment.

The integration maps Segment reserved traits  to Airship predefined attributes:

The following example identify call assigns attributes to the Named User jane. In this example, age maps to a predefined Airship attribute. The integration assumes that there is an attribute defined in Airship with the ID favorite_color.

{
   "type": "identify",
   "traits": {
      "age": 30,
      "favorite_color": "purple"
   },
   "userId": "jane"
}

For traits in the identify call that do not map to a predefined or customer-defined Airship attribute, you must create and enable the attribute in the Airship dashboard. Go to Audience » Attributes in your project. See About attributes for details.

Register and Associate

The default trigger for the Register and Associate Action is the Track event type with an Email Address Registered event, but you can change it in Segment.

The main requirement for registering an email address is simply an email address. This, and most of the other channel objects default to the properties object. The only exception is suppression_state which defaults to context.suppression_state. If a userId (or alternatively mapped) value is present, the email address will be registered and associated with the Named User ID in the same trigger. If new_email is present, it will replace the old email address.

All the other email registration properties are optional, mostly involving opt-in state for various email features.

{
	"type": "track",
	"properties": {
	  "email": "floofy@kittens.org",
	  "commercial_opted_out": "2023-08-30T22:19:03.944Z",
	  "transactional_opted_in": "2023-08-30T22:19:03.944Z",
    "click_tracking_opted_in": "2023-08-30T22:19:03.944Z",
    "open_tracking_opted_in": "2023-08-30T22:19:03.944Z"
	},
	"userId": "6319ffd6-f486-4258-9e96-f256fe7c712f",
	"event": "Email Address Registered"
}

This call will result in the registration of the email address floofy@kittens.org, it’s association with the Named User 6319ffd6-f486-4258-9e96-f256fe7c712f, and its opting-in to Commercial and Transaction emails as well as Click Tracking and Open Tracking.

Troubleshooting your Segment integration

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

400 Bad Request

The call is either missing traits or traits are empty, resulting in no Airship API calls to set tags or attributes.

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.