Airship

Send user data to Airship for mobile marketing and push notification campaigns. Sync named user attributes and tags from your warehouse to Airship’s named users.

Prerequisites

• An Airship account with a project configured
• An Airship app key and master secret, or a bearer token with appropriate permissions
• Knowledge of which Airship cloud site your project uses (US or EU)

Permissions

To sync data to Airship, your credentials need the following permissions:

• Named Users: Read and write access to named users and their attributes
• Tags: Read and write access to tag groups

Authentication

Airship supports two authentication methods.

App Key & Master Secret (Basic Auth)

1. Log in to the Airship dashboard
2. Navigate to Settings > APIs & Integrations
3. Copy your App Key and Master Secret
4. In Zeotap, select App Key & Master Secret as the authentication method
5. Paste the app key and master secret into the corresponding fields

Bearer Token

1. Log in to the Airship dashboard
2. Navigate to Settings > APIs & Integrations > Tokens
3. Create a new token with the required permissions
4. Copy the generated bearer token
5. In Zeotap, select Bearer Token as the authentication method
6. Paste the token into the Access Token field

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Named Users (Attributes)

named_user_id, first_name, last_name, email, phone, city, region, country, zipcode, birthdate, loyalty_tier

Tags

named_user_id, tags

How It Works

Named User Attributes

When syncing named user attributes, Zeotap sends individual attribute update requests to the Airship API for each named user:

1. Each row in your model is mapped to a named user identified by named_user_id
2. All mapped fields (except named_user_id) are sent as attribute set operations
3. Requests are sent to POST /api/named_users/{named_user_id} with an attributes array
4. In mirror mode, rows marked as removed are sent to the uninstall endpoint in batches of 100

Tags

When syncing tags, Zeotap batches tag operations for up to 1,000 named users per request:

1. Tags are extracted from the tags field — comma-separated strings are split into individual tags
2. Add operations use POST /api/named_users/tags with the add action
3. Remove operations use the same endpoint with the remove action
4. In mirror mode, removed rows trigger tag removal while other rows trigger tag addition

Error Handling

• Failed requests are retried up to 3 times with exponential backoff
• HTTP 429 (rate limit) responses are retried automatically with the server-specified delay
• Per-row errors are tracked and reported in sync run results

Rate Limits

Airship does not publish hard rate limits for their API. However, the following best practices apply:

• Tag operations support up to 1,000 named users per request
• Named user uninstall supports up to 100 named users per request
• Zeotap automatically handles HTTP 429 responses with retry and backoff
• If you experience timeouts, consider reducing your sync batch size

Best Practices

• Use meaningful tag groups: Create specific tag groups in Airship for different data sources rather than using the default device group
• Keep tags under 128 characters: Airship enforces a 128-character limit on tag names
• Limit tags per named user: Airship recommends no more than 1,000 tags per named user
• Named User IDs: Keep named user IDs under 128 characters with no leading or trailing whitespace
• Choose the right cloud site: Ensure you select the cloud site (US or EU) that matches your Airship project

Troubleshooting

Authentication failed: invalid credentials

Verify your app key and master secret (or bearer token) are correct. In Airship, navigate to Settings > APIs & Integrations and confirm the credentials. Ensure the master secret has not been rotated since you configured the destination.

Named user not found

Airship creates named users automatically when you set attributes or tags. If you see “not found” errors during connection testing, this is expected — the test uses a dummy named user ID to verify credentials.

Tags not appearing in Airship

Ensure the tag group specified in your target settings exists in Airship. Navigate to Settings > Tags in the Airship dashboard to verify. Tags are case-sensitive — check that your tag values match exactly.

Cloud site mismatch

If API calls return unexpected errors, verify your cloud site setting. US projects use go.urbanairship.com and EU projects use go.airship.eu. Using the wrong site returns authentication errors even with valid credentials.

Rate limiting (HTTP 429)

Zeotap automatically retries rate-limited requests with exponential backoff. If you see persistent rate limit errors, reduce the frequency of your sync schedule or contact Airship support to discuss your API usage limits.

Attribute updates not reflecting immediately

Airship processes attribute and tag updates asynchronously. Even after a successful API response, changes may take a few moments to appear in the Airship dashboard or be available for audience targeting.

Comma-separated tags not splitting correctly

When using the Tags object type, the tags field accepts comma-separated values that are automatically split into individual tags. Ensure there are no unintended commas in your tag values. If you need tags that contain commas, use a JSON array format instead.