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, 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, 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 and static 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, 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.

Event streaming

You can use Airship as an event streaming destination with every sync type except Push Notification and Static Lists. Push Notification would message its whole segment once per event, and Static Lists can only replace the whole list.

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. Hightouch converts timestamp values to that format in UTC. It converts date-only values, such as 2024-03-15, only for the predefined birthdate and account_creation attributes. For custom date attributes, cast date columns to timestamps in your model.

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.

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.

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.