Airship

Build better campaigns on Airship with up-to-date customer data from your data warehouse

View Airship's documentation.

Airship is a customer engagement platform for push notifications, in-app messages, email, and SMS. Hightouch syncs named users, channels, tags, subscription lists, static lists, attribute lists, and custom events from your warehouse to Airship, and sends pushes to Airship segments and named users. Marketers can then target and personalize Airship messages with warehouse data.

Supported syncing

For more information about sync modes, refer to the sync modes docs.

Connect to Airship

Select the Cloud Site that hosts your Airship project: North America or Europe. See Airship's servers docs for the URL each region uses.

Then authenticate with Basic Authentication or Bearer Authentication. Every sync type works with either method except Custom Events, which requires Bearer Authentication with the App key.

Testing the connection checks access to named users, subscription lists, and pushes, plus custom events when a bearer destination has an App key. It doesn't check static lists, attribute lists, templates, or tag groups.

Basic Authentication

Enter these fields:

• APP Key: the app key that identifies your Airship project.
• Secret: your project's master secret. Don't use the app secret. Airship limits the app secret to the endpoints its SDK needs, so pushes, static lists, and attribute lists fail with it.

In Airship, select the dropdown menu next to your project name, then select Project Details to find both values. Viewing the master secret requires the Owner or Administrator role. See Airship's Basic Auth docs.

If a tag group has Allow these tags to be set only from your server enabled, Airship requires the master secret to change its tags. Use Basic Authentication for syncs that write to those tag groups.

Bearer Authentication

Create a token in Airship: select the dropdown menu next to your project name, then Settings. Under Project settings, select Tokens > Create token, enter a name, and select an access role. Airship shows the token only once, so copy it before you close the dialog.

Pick a role that covers every sync type the destination uses. Airship describes the roles in its API security docs, and its API authorization reference shows which endpoints accept bearer tokens.

• Audience Modification grants read and write access to Airship's audience endpoints, and Airship lists sending custom events as its typical use. Use it for Named Users, Channels, Subscription Lists, Tags, Static Lists, Attribute Lists, and Custom Events.
• All Access grants full access to the project. Use it for Push Notification and Templated Push, which send messages instead of changing audience data.

Then enter these fields:

• Access Token: the token you created.
• App key: the project's app key, which Airship shows alongside the token. Only Custom Events syncs need it, because Airship's custom events API requires the app key in every request. The token and app key must belong to the same project.

Sync configuration

Named Users

Select the Object sync type, then the Named Users object, to set tags and attributes on named users. Use Upsert when Hightouch should create named users that don't exist yet. Use Update when Hightouch should only change existing named users. In Update mode, Hightouch looks up each named user first and rejects rows Airship doesn't have.

Record matching

Match rows to named users on Named User ID. Airship named user IDs are case-sensitive, up to 128 characters, and can't have leading or trailing whitespace. See Airship's named users docs.

Field mappings

Map columns in three places:

• Associate, in the field mappings: links channels or email addresses to the named user in the same request. Map a column that holds an array of objects, each with either email_address, or channel_id and optionally device_type. If a channel already belongs to another named user, Airship moves it to this one.
• Attribute mappings: the dropdown lists Airship's default and predefined attributes. For a custom attribute, type its attribute ID, not its name. Except for default attributes, define every attribute in your Airship project first.
• Tag mappings: on the right side of each tags mapping, enter the Group Key of an existing, active tag group. Each mapping replaces the tags in that group. See Behavior and limitations.

Channels

Select the Object sync type, then the Channels object, to set tags and attributes on individual channels, such as a single app install or email address. Channels support Update only, because Airship creates channels when devices and addresses register.

Prefer Named Users when you target people across devices. Airship applies a named user's tags to every channel associated with that named user, but channel tags stay on their channel.

Record matching

Match rows on Channel ID, the UUID Airship assigns to each channel. Hightouch updates channels by ID without looking them up first.

Field mappings

Map Device type for every row, from a column or as a static value. Accepted values are ios, android, amazon, web, email, and open. Case doesn't matter. Hightouch rejects rows with a missing or different device type. SMS channels aren't supported, because Airship's channel attributes API addresses them by phone number instead of channel ID.

Attributes and tags map the same way as for named users. Hightouch sends a row's tags and then its attributes in separate requests. If Airship skips a tag group, Hightouch rejects the row and doesn't send its attributes.

Send push notifications

Use Push Notification to send a message to an Airship segment whenever a row is added to your model. Every push goes to the whole segment, not to a recipient in the row. To message individual named users, use Templated Push.

Configure the push:

• Segment ID: select an Airship segment or enter its ID.
• Device type: select one of iOS, Android, Email, or SMS.
• Title and body: both support Liquid, so they can include values from the row that triggered the push. The email subject, HTML body, and plain text body support Liquid too, as do the content title and body of an iOS media attachment.
• Device-specific fields: an optional media attachment for iOS, extra key/value mappings for Android, or an expiry in seconds for SMS.
• Message type, for email: select Commercial for promotional email and Transactional for messages such as receipts and account updates. Commercial email only reaches opted-in addresses and must contain an unsubscribe link. See Airship's commercial vs. transactional docs.

Hightouch sends nothing on the initial sync run or on a full resync, so the rows already in your model don't each trigger a push.

Subscription Lists

Use Subscription Lists to subscribe named users to Airship subscription lists when they enter your model and unsubscribe them when they leave. Match rows on Named User ID.

Select one or more existing lists, or map a column that contains the list IDs. If your credentials aren't allowed to list subscription lists, none appear in the dropdown, so map a column instead.

Field mappings

Airship requires Scopes, the channel types the subscription applies to. Map an array or a comma-separated string of app, web, email, and sms. See Airship's scoped named user operations docs.

Send templated pushes

Use Templated Push to send an Airship app content template to each named user who enters your model. Each new row sends one push to that named user's devices. Rows that change or leave the model send nothing. Match rows on Named User ID.

Configure the push:

• Device types: select any combination of iOS, Android, and Amazon (Fire OS). The default is iOS and Android. Web, email, and SMS need other template types, so they aren't available.
• Template: with Basic Authentication, select an app content template or enter its ID. With Bearer Authentication, enter the template ID, because Airship doesn't let bearer tokens list templates. To send different templates per row, map a column of template IDs.
• Personalization: each mapped column becomes a global attribute that the template reads by name. To send a set of values in one mapping, map an object column to Global attributes. Names must start with a letter and can't start with ua_.

To find a template's ID in Airship, go to Content > Templates, open the template's menu, and select Copy ID to clipboard. See Airship's content templates docs to create one.

The form also has optional campaign categories and delivery settings. See Airship's push object docs for what each does.

Configure initial pushes

By default, the initial sync run and a full resync send no pushes, so named users already in your model don't each get one. Select No, send a push for every row only if every named user in the model should get the push on the first run.

Tags

Use Tags to keep one Airship tag in step with model membership. Named users get the tag when they enter your model and lose it when they leave. Hightouch doesn't change other tags, including others in the same tag group. Match rows on Named User ID. Airship ignores named user IDs it doesn't have.

Configure the tag:

• Tag group: enter the Group Key of an active tag group, not its display name. Create tag groups in Airship under Audience > Tags > Tag Groups. Airship reserves keys that start with ua_.
• Tag: enter the tag that members of the model should have, up to 128 characters. Tags are case-sensitive. Airship creates the tag the first time Hightouch sets it.

Each sync manages one tag. To manage more than one tag, create a sync for each. See Airship's tags docs for tag group setup and limits.

Static Lists

Use Static Lists to replace an Airship static list with the named users in your model on every sync run. Airship's dashboard calls static lists uploaded lists. Named users who leave your model drop off the list on the next run. Match rows on Named User ID.

Select Use an existing static list and select or enter its name. If your credentials aren't allowed to list static lists, none appear in the dropdown, so type the name instead.

Or select Create a new static list, and Hightouch creates it on the first sync run. Leave the name blank to use your model's name. Hightouch replaces characters other than letters, numbers, ., _, ~, and - with underscores and shortens the name to 64 characters.

Custom Events

Use Custom Events to send actions such as purchases to Airship, where they can trigger Automations and Sequences and personalize messages. Each row added to your model sends one event. Changed and removed rows send nothing.

Record matching

Match each event to a Named User ID, which attributes it across every channel of the named user, or to a Channel ID, which attributes it to one channel. Each channel ID must be a UUID. When you match on Channel ID, you can map each channel's device type. If you leave it blank, Airship determines the device type from the channel ID.

Field mappings

• Event name: select a column or enter a static value. Airship rejects event names with uppercase characters, so Hightouch converts names to lowercase before sending. Names can be up to 255 characters.
• Event fields: Hightouch rejects rows whose Value isn't a number or whose Session ID isn't a UUID. Set Unique ID when event properties trigger or personalize a Sequence, so Airship doesn't drop the messages as duplicate sends.
• Properties: map columns to property names, or map an object column to Event properties. Individually mapped columns override keys of the same name in the object. See Airship's custom event personalization docs.
• Timestamp: optionally map a column with each event's time. If you leave it blank, or a row's timestamp is empty, Airship uses the time it receives the event. Airship only accepts events from the past 90 days and rejects future timestamps.

Configure the event backfill

By default, the initial sync run and a full resync send every row in your model as an event. A backfill can trigger Airship automations for every named user or channel in the model. Select Yes, skip the backfill to send only rows added after the initial run.

Attribute Lists

Use Attribute Lists to set Text, Number, and Date attributes on the named users in your model by uploading the model to an Airship attribute list. Each sync run uploads every row, not only rows that changed, and Airship sets the attributes in the background. Match rows on Named User ID.

Hightouch sends nothing for named users who leave your model, so they keep their attributes. To set attributes only on rows that change, use Named Users instead.

Select Use an existing attribute list and select or enter its name. Airship only lets Hightouch upload to lists whose names start with ua_attributes_. A list appears in the dropdown only after its first upload, and none appear if your credentials aren't allowed to list attribute lists. In either case, type the name instead.

Or select Create a new attribute list, and Hightouch creates it on the first sync run. Leave the name blank to use your model's name. Enter the name without the ua_attributes_ prefix, because Hightouch adds the prefix Airship requires. Hightouch also replaces characters other than letters, numbers, ., _, ~, and - with underscores, and shortens the full name to 64 characters. If Airship already has a list with that name, the sync run fails, so select that list as an existing list or enter a different name.

What an empty cell does depends on the list's name. Hightouch sends null and empty values as empty cells, and Airship leaves those attributes unchanged. In a snapshot list, whose name starts with ua_attributes_snapshot_, Airship removes them instead. To clear attributes with empty values, select an existing snapshot list, or create a new list whose name starts with snapshot_.

Field mappings

Map up to 100 columns to Text, Number, or Date attributes. Create each attribute in your Airship project first, including predefined attributes. After you create an attribute, wait at least 10 minutes before a sync run sets it, because Airship needs that time to process a new attribute. The dropdown lists Airship's predefined attributes. For a custom attribute, type its attribute ID.

Airship has no Boolean attribute type, so map boolean columns only to Text attributes. Hightouch writes them as true and false. Text attribute values can be up to 255 characters, and Hightouch doesn't check their length before uploading. Attribute lists can't set JSON attributes, so Hightouch leaves out rows with an object or array value.

Hightouch converts any value in YYYY-MM-DD form, or an ISO 8601 timestamp with a time zone, to YYYY-MM-DDTHH:MM:SS in UTC. It converts these values for every attribute, including Text attributes. A date-only value such as 2024-03-15 becomes midnight UTC. Hightouch sends dates in other formats unchanged, and Airship fails Date attribute values it can't parse while processing the upload.

Event streaming

You can use Airship as an event streaming destination with every sync type except Push Notification, Static Lists, and Attribute Lists. Push Notification would message its whole segment once per event, and Static Lists and Attribute Lists only upload a whole model at a time.

Hightouch handles each streamed event like a row added to a model:

• Tags only adds the tag, and Subscription Lists only subscribes. Streaming never removes a tag or unsubscribes a named user.
• Templated Push sends a push for every matching event. The initial sync run setting has no effect.
• Custom Events still requires Bearer Authentication with the App key.

Tips and troubleshooting

Behavior and limitations

Tag mappings replace each mapped tag group. Named Users and Channels syncs set the full list of tags in every mapped tag group, so Airship removes tags in that group that aren't in the row. Tag groups you don't map stay as they are. To add or remove one tag without touching the rest of its group, use the Tags sync type.

Empty cells don't clear values. In Named Users and Channels syncs, an empty tag cell leaves its tag group unchanged, and an empty attribute cell leaves the attribute unchanged. These syncs can't clear a tag group or remove an attribute.

Airship can apply part of a row. When Airship skips a tag group or attribute, it still applies the rest of the request. For example, it skips a tag group that doesn't exist or an attribute that isn't defined in the project. Hightouch then rejects the row with Airship's warning, such as Airship did not apply tags: The following tag groups do not exist: loyalty. The row's other tags and attributes may already be in Airship.

Date attributes need a time. Airship parses date attributes as YYYY-MM-DDTHH:MM:SS, and Hightouch converts timestamp values to that format in UTC. In Named Users and Channels syncs, it converts date-only values, such as 2024-03-15, only for the predefined birthdate and account_creation attributes. For custom date attributes in those syncs, cast date columns to timestamps in your model. Attribute Lists syncs convert date-only values for every attribute.

Changing a Tags sync's tag doesn't move existing members. If you change the tag or tag group, named users who already have the old tag keep it, and later removals take off the new tag. To switch tags, create a new sync and remove the old tag in Airship.

Static list uploads process in the background. A sync run succeeds once Airship accepts the upload. Airship keeps sending to the previous version of the list until the new version finishes processing. Hightouch doesn't report processing failures, so check the list's status in Airship as described in Validate your setup.

An empty model doesn't empty a static list. If no row in your model has a usable named user ID, the run fails instead of emptying the list. Hightouch leaves rows without a usable named user ID out of the upload and doesn't report them as rejected. A static list can hold up to 10 million named users.

Attribute list uploads process in the background. A sync run succeeds once Airship accepts the upload, and Airship then sets the attributes. Hightouch doesn't report values Airship fails to set while processing, so check the upload's status in Airship as described in Validate your setup. If a mapped attribute doesn't exist in the project, Airship rejects the whole upload, and every run fails until you create the attribute and wait at least 10 minutes, or remove the mapping. If a run starts while Airship is still processing the list's previous upload, Airship refuses the new upload. Hightouch retries for about five minutes and then fails the run, so space runs far enough apart for Airship to finish processing.

Attribute list syncs leave out rows they can't upload. Hightouch leaves out rows without a usable named user ID, or with a date Hightouch can't parse, an object, or an array. The run counts those rows as synced and doesn't report them as rejected. If your model has rows but Hightouch can't upload any of them, the run fails. An empty model uploads nothing, so it changes no attributes, even in a snapshot list. Airship accepts up to 10 million rows in an attribute list. Hightouch doesn't check that limit before uploading, so split a larger model across syncs that each upload to their own list.

One invalid item doesn't fail a whole batch. Airship rejects a whole Templated Push, Tags, or Custom Events request when one item is invalid. Hightouch splits the batch to isolate the invalid row and rejects only that row with Airship's error.

Validate your setup

• Named users and channels: in Airship, go to Audience > Contact Management and look up a named user ID or channel ID. The details show tag groups and attributes, and a named user's message history lists the messages Airship sent them in the last 30 days. See Airship's contact management docs.
• Static lists: go to Audience > Lists > Uploaded. A new upload shows Processing until Airship finishes it, then Ready or Failed. See Airship's uploaded lists docs.
• Attribute lists: go to Audience > Attributes > Upload History to see each upload's status. For an upload that shows Processed with errors, download the error file to see which named users failed and why. Then look up a named user from your model in Audience > Contact Management and check its attributes. See Airship's upload history docs.

Common errors

To date, our customers haven't experienced any errors while using this destination. If you run into any issues, please don't hesitate to reach out. We're here to help.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.