Segment
AIRSHIP MAINTAINED INTEGRATION
This integration is maintained by Airship. Please contact Airship for support.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 message triggering, audience targeting, and analytics (Airship as a destination).
Segment integration requirements
- Accounts
- Segment
- Airship — Must include both:
- Messaging
- Real Time Data Streaming
- 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:
- Go to the Catalog.
- Find the Airship source and click Add Source.
- Add a name and optional labels for your source integration, and once again click Add Source.
- Copy the Write Key. You will use this token when enabling your Segment integration in Airship.
In Airship:
Go to Settings » Project Configuration and click Manage for Real-Time Data Streaming.
Under Real-Time Data Streaming, select Segment. Previously configured integrations are listed under Enabled Integrations.
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
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.
Configuring the Segment destination integration
In Airship:
- Go to Settings » Project Configuration and click Manage for Partner Integrations.
- Select Segment.
- Click Configure for the destination integration and follow the onscreen instructions to:
- Create Tag GroupsAn array of tags that you can associate with both channels and named users. , AttributesMetadata that you can use for audience segmentation. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE. , and an authentication token. Segment uses the token to communicate with your project in Airship.
- Configure Airship as a destination in Segment.
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.
Airship transforms all custom event names to lower case. In the following example, note that the value of
event
appears as Install Attributed for Segment while in Airship it is recorded as install attributed in thename
attribute.Events from Segment are sent as server-side events, which cannot be used to trigger In-App AutomationMessages that are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. .
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": {
"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"
}
}
}
Personalize Messages Using Custom Events from Segment
You can use Airship HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}
, to complex evaluations of personalization data. to personalize messages in automation rules or sequences 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
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
.
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 event
{
"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"
}
Example Segment group
call
{
"messageId": "test-message-0ruqfd",
"timestamp": "2021-03-26T22:32:43.944Z",
"type": "group",
"email": "test@example.org",
"projectId": "YbPbo7GvTo",
"traits": {
"hiring": true,
"startup": true,
"has-remote-employees": false
},
"groupId": "test-group-58qicr",
"userId": "test-user-69w86c"
}
Resulting Airship set tags payload
{
"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:
Segment Trait | Attribute Name | Attribute ID | Attribute Type |
---|---|---|---|
address.city | City | city | Text |
address.country | Country | country | Text |
address.postalCode | Zipcode | zipcode | Number |
address.state | Region | region | Text |
age | Age | age | Number |
birthday | Birthdate | birthdate | Date |
company.name | Company | company | Text |
createdAt | Account Creation | account_creation | Date |
email | Email Address | email | Text |
firstName | First Name | first_name | Text |
gender | Gender | gender | Text |
lastName | Last Name | last_name | Text |
name | Full Name | full_name | Text |
phone | Mobile Phone Number | mobile_phone | Number |
title | Title | title | Text |
username | Username | username | Text |
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 Attributes for more detail.
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:
Segment Trait | Attribute Name | Attribute ID | Attribute Type |
---|---|---|---|
name | Company | company | Text |
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.
The Segment group
call
{
"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"
}
The resulting Airship set attributes payload
{
"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"
}
]
}
Personas
Segment Personas let you to create unified customer profiles in Segment and activate audiences across marketing tools. This integration supports setting attributes with Segment Personas Computed Traits and Personas Audiences .
Create Computed Traits in Segment to set as Attributes
Segment automatically generates a Trait Key
based off the Trait Name
you specify when creating a Computed Trait. In order to successfully set the trait as an attribute make sure the Attribute ID
matches the Trait Key
when you create the attribute in Airship.
Trait Name | Trait Key | Attribute Name | Attribute ID | Attribute Type |
---|---|---|---|---|
Most Viewed Page Category | most_viewed_page_category | Most Viewed Page Category | most_viewed_page_category | Text |
Application Opened Count | application_opened_count | Application Opened Count | application_opened_count | Number |
Segment gives you the option to send computed traits data with the track
and/or identify
methods.
You can select either, but you should not select both as both methods perform the same set attribute action. Selecting both types will result in multiple redundant calls.
Set Audience as an Attribute
To set the Personas Audience as an attribute on a named user, send the event as a track
call.
Segment automatically generates an Audience Key
based off the Audience Name
you specify when creating an Audience. In order to successfully set the Audience as an attribute make sure the Attribute ID
matches the Audience key
when you create the attribute in Airship.
Audience Name | Audience Key | Attribute Name | Attribute ID | Attribute Type |
---|---|---|---|---|
Has Email Address | has_email_address | Has Email Address | has_email_address | Text |
Set Audience as a Tag
To set the Audience as a tag on the named user, send the event as a an identify
call. Requires segment-integration
tag group.
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 integration returns this error when theidentify
call is either missing traits or traits are empty, resulting in no Airship API calls to set tags or attributes.501
Unsupported call type: This integration supports onlytrack
andidentify
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.
Categories