Segment Legacy Destination Integration

Segment is a Customer Data Platform (CDP) that lets you combine data across applications and platforms. Ingest external events from Segment with named users in Airship for message triggering, audience targeting, and analytics.

Segment integration requirements

• Accounts
  1. Segment
  2. Airship — Must include messaging
• Airship project
  • Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. must be enabled for your project.

Configuring the Segment integration

In Airship:

1. Next to your project name, select the dropdown menu (), then Settings.
2. Under Project settings, select Partner Integrations.
3. Select Segment.
4. Select Configure for the destination integration and follow the onscreen instructions to:
   • Create a 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 integration, not the Airship Actions integration.

Using Segment calls to pass values to Airship

The Segment destination  integration uses the Segment track, identify, and group methods to pass values into Airship.

Segment track calls will come into Airship as custom events, and identify calls will come into Airship as either a tag or an attribute depending on the data type of the trait. Boolean traits are added as tags, and non-boolean traits are added as attributes, provided that the attribute is recognized by Airship.

Segment group calls are similar to identify calls: they contain a set of traits that the integration uses to set an Airship tag and attributes on the named user.

Custom events

Airship captures track events from Segment using our 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.
• The track event’s event key maps to the custom event name in Airship.

You can use the name value to differentiate between different track events 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"
}

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

Tags

Airship assigns tags to Named UsersA customer-provided identifier used for mapping multiple devices and channels to a specific individual. based on incoming identify or group events from Segment. You must create a segment-integration tag group to receive these tags. See how to add the tag group in the next section.

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.

{
  "userId": "jane",
  "type": "identify",
  "timestamp": "2019-06-12T22:21:33Z",
  "traits": {
    "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"]
    },
    "current": {
      "segment-integration": ["order-completed-last-60-days"]
    }
  },
  "type": "TAG_CHANGE"
}

{
  "audience": {
    "named_user_id": ["test-user-69w86c"]
  },
  "add": {
    "segment-integration-group": ["hiring", "startup"]
  },
  "remove": {
    "segment-integration-group": ["has-remote-employees"]
  }
}

Attributes for the identify calls

Attributes are set for identify calls without boolean-valued traits.

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.

Attributes for the group calls

Attributes are set for group calls without boolean-values traits. You need to create correct attribute identifiers in Airship first in order to successfully set the attributes on the named user.

The integration maps the Segment reserved group trait name to the Airship predefined attribute company:

The names of all other attributes begin with airship_segment_group_ followed by the segment trait, such as airship_segment_group_industry. Traits that contain nested objects are flattened using underscores: airship_segment_group_address_city represents the address segment trait which includes city.

{
  "messageId": "test-message-0ruqfd",
  "timestamp": "2021-03-26T22:32:43.944Z",
  "type": "group",
  "email": "test@example.org",
  "projectId": "YbPbo7GvTo",
  "traits": {
    "name": "Initech",
    "industry": "Technology",
    "employees": 329,
    "address": {
      "city": "Portland",
      "state": "OR"
    }
  },
  "groupId": "test-group-58qicr",
  "userId": "test-user-69w86c"
}

{
  "audience": {
    "named_user_id": "test-user-69w86c"
  },
  "attributes": [
    {
      "action": "set",
      "key": "company",
      "value": "Initech",
      "timestamp": "2021-03-26T22:32:43"
    },
    {
      "action": "set",
      "key": "airship_segment_group_industry",
      "value": "Technology",
      "timestamp": "2021-03-26T22:32:43"
    },
    {
      "action": "set",
      "key": "airship_segment_group_employees",
      "value": 329,
      "timestamp": "2021-03-26T22:32:43"
    },
    {
      "action": "set",
      "key": "airship_segment_group_address_city",
      "value": "Portland",
      "timestamp": "2021-03-26T22:32:43"
    },
    {
      "action": "set",
      "key": "airship_segment_group_address_state",
      "value": "OR",
      "timestamp": "2021-03-26T22:32:43"
    }
  ]
}

Troubleshooting your Segment integration

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

400 Identify call has no traits. Cannot set tags or attributes

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

501Unsupported 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.