Event

Airship is a Customer Engagement Platform (CXP) that helps you drive loyalty, engagement, and revenue through channels such as mobile apps, email, and SMS. Airship provides push messaging services, including segmentation and targeting capabilities. To learn more about what you can do with Airship, see Airship’s documentation.

Supported inputs

You can send events data to Airship from the following inputs:

Create an Airship output configuration

Regardless of the input you want to connect to Airship, you must first set up an Airship app and create an Airship output configuration in mParticle.

1. Airship setup

1. Sign in to your Airship account at https://go.urbanairship.com/accounts/login/.
2. Create a new app if necessary, or use an existing app.

3. Navigate to Settings > Project Details to find your Airship App Key and Secret. You’ll use these when creating your output configuration in mParticle in the next section. For a definition Airship keys and secrets, see App Keys & Secrets: Security in Airship’s documentation.

2. Create your Airship output configuration in mParticle

1. Log in to your mParticle account and go to Data Platform > Setup > Outputs.
2. From the Event outputs tab, click Add Event Output, then search for and select Airship.
3. Enter a descriptive name for your Airship output.
4. Enter your Airship App Key and Secret.
5. Select the Domain (for example, US or EU) for where your Airship credentials were issued.
6. If this configuration is only for a Web or Feed input, check App Key is for Web or Feed.
7. Click Save.

The connection setup instructions differ depending on the input you want to use.

• For iOS and Android, see iOS and Android integration setup
• For Web and Feed, see Web and Feed integration setup

iOS and Android integration setup

The integration for iOS and Android uses a client-side kit that was built in partnership with Airship and that provides full support for both mParticle’s and Airship’s features. The kit bundles Airship’s native SDK with the mParticle SDK, allowing you to dynamically enable or disable event forwarding and to manage your configuration and filtering settings from mParticle’s UI.

When correctly installed, the embedded kit makes available the following functionality:

• Initialize the Airship SDK with your Airship key and secret configured via mParticle
• Track metrics for when your users register for, and open, push notifications
• Collect and forward user attributes, tags, and identities
• Collect and forward ecommerce and in-app event data
• Forward Google Play installation events to Airship (Android only)
• Add event and user attribute tags

The source code for each kit can be found at:

• iOS
• Android

To leverage the functionality described above, and to use other mParticle features, you must make calls to the iOS or Android mParticle SDKs. Similarly, you can use Airship’s other features by making direct API calls to the Airship SDK as described in Airship’s documentation.

1. Add the kit to your app

This step will add the mParticle SDK (if not present already), the Airship SDK, along with the Airship kit, which acts as a bridge between the two SDKs. See the iOS and Android examples below, and reference the Apple SDK and Android SDK GitHub pages to learn more about kits.

iOS

If you’re using CocoaPods, add the following to your app’s Podfile:

pod 'mParticle-UrbanAirship', '~> 8'

If you’re using SPM, using the standard Xcode interface to add the following package to your project:

https://github.com/mparticle-integrations/mparticle-apple-integration-urbanairship

Android

Add the following to your app’s build.gradle file:

dependencies {
    compile ('com.mparticle:android-urbanairship-kit:5.+')
}

2. Create an Airship output configuration in mParticle

If you haven’t created an output configuration yet, follow the steps outlined in Create an Airship output configuration before continuing to step 3 below.

3. Connect your Android or iOS input to your new Airship output

1. From mParticle, go to Data Platform > Setup > Connections.
2. Select either iOS or Android.
3. Click Connect Output and select your new Airship output configuration. Click Next.

4. Under Token enter your Airship provided bearer token.

   • You can create and manage tokens in the Airship dashboard by navigating to Settings > Project Configuration > Tokens > Manage.
5. Under Named User ID Type, select the mParticle user identifier you want to forward to Airship.
6. Under Custom Domain Proxy URL, enter a URL that you want to route your Airship SDK traffic through. See Custom Domain Proxy in Airship’s documentation to learn more.
7. Under Event Names that map to User Tags, select an mParticle event name and enter the name of the Airship user tag you want to map it to. Add additional mappings by clicking Add.
8. Under Event Attributes that map to User Tags, select an mParticle event attribute and enter the name of the Airship user tag you want to map it to. Add additional mappings by clicking Add.
9. To forward mParticle user tags to Airship, check Enable Tags.
10. To forward mParticle user attributes (in addition to user tags) to Airship, check Send all user attributes as tags. If left unchecked, only user tags are forwarded. Send all user attributes as tags setting only takes effect if the Enable Tags setting is also checked.

4. Configure push notifications

If the Airship kit is included in your app, mParticle will pass any push notifications from Airship to the kit for display. However, you will need to provide credentials in the Airship dashboard.

See the Airship’s documentation for push notifications for more detail for the various platforms:

• iOS
• Android

Android

For Android push notifications, you will need to provide your Server Key to Airship. See Airship’s Android Push Notifications documentation for more information.

iOS

For iOS push notifications you will need to upload your APNs Push SSL certificate to Airship. See the Airship’s iOS Push Notifications documentation for more information.

iOS 10 Service Extension

If you are integrating with Airship and need to implement a Service Extension for user notifications, please refer to Airship’s Extensions Documentation.

Airship User Tags

Airship uses tags to group users together based on shared interests, preferences, or behaviors. Each user’s channel can be associated with multiple tags, and these tags can be associated with multiple channels. These tags are analogous to mParticle user attributes and tags. If you want to exclude certain attributes from being mapped to Airship tags, you can filter them from being forwarded using data filters.

To forward tags, check Enable Tags when creating your Airship integration configuration. If you check Send all user attributes as tags, your user attributes are also forwarded as tags.

Mapping Events and Event Attributes to Tags

The mParticle kit integration can automatically set Airship tags when particular events and/or event attributes are detected. When enabling and configuring Airship, you may select the events that you’ve sent to mParticle in the past, and customize exactly which tag(s) those events should trigger. In the screenshot below, when an event named “Map View” is fired, mParticle will set the tag “my tag” within the Airship platform and when an event attribute named “Transaction Id” is seen, mParticle will set the tag “transaction”.

Web and Feed integration setup

The server-to-server Airship integration forwards commerce and custom events ingested via the Web SDK or a Feed input, allowing you to dynamically enable or disable event forwarding and to manage your configuration and filtering settings from mParticle’s UI.

The S2S integration will not create users in Airship. When data is sent to Airship without a known Named User you will not see these events or users in your Airship account.

Event Filters in mParticle will show all events supported between kit and S2S integrations. Because the S2S integration sends a subset of these events, only filters set on S2S-supported events will affect the forwarded data.

1. Create your output configuration

If you haven’t created an output configuration yet, follow the steps outlined in Create an Airship output configuration before continuing to step 2 below.

2. Connect your Web or Feed input to your new Airship output

1. From mParticle, go to Data Platform > Setup > Connections.
2. Select your web or feed input.
3. Click Connect Output and select your new Airship output configuration. Click Next.

4. Under Token enter your Airship provided bearer token.

   • You can create and manage tokens in the Airship dashboard by navigating to Settings > Project Configuration > Tokens > Manage.
5. Under Named User ID Type, select the mParticle user identifier you want to forward to Airship.
6. To register an email channel in Airship for named users, check Enable Email Channel Registration. Learn more in Email Channel Registration.
7. If you enabled email channel registration, enter your email channel request mappings.
8. Click Save.

Email Channel Registration

You can automatically register Airship email channels for your users by selecting the Enable Email Channel Registration setting in your Airship Event integration connection settings. These email channels can be used for audience segmentation with mParticle’s Airship audience integration.

After enabling the Email Channel Registration setting, you can select which mParticle user attributes you want to map to each Airship email channel registration field, as described below. Email channels are automatically associated with named user IDs based on the Named User ID Type setting. See Named users in Airship’s documentation for more information.

Supported email channel registration fields

Airship supports several “opt-in” and “opt-out” fields that represent what kind of email channel activity your users have consented to, such as commercial emails and click tracking within those emails.

All of these fields are optional. To map an mParticle user attribute to an Airship field, in addition to selecting the Enable Email Channel Registration setting, use the Email Channel Request Mapping dropdown menu in your connection settings. Any mParticle user attribute you select must be formatted as a date-time value according to Airship’s documentation.

Event Mapping

Mapping of mParticle events to Airship events occurs automatically in both kit and S2S implementations. mParticle eCommerce events are mapped to Airship events as follows:

Configuration Settings

If your Airship configuration uses the same App Key for Mobile and Web, all 3 configuration settings are required. If your Airship configuration is for Web only, enter an App Key, and enable the This App Key is for Web only in my Airship Setup. setting.

Connection Settings