mParticle
AIRSHIP MAINTAINED INTEGRATION
This integration is maintained by Airship. Please contact Airship for support.Map mobile engagement events to your customer data warehouse.
mParticle is a mobile data platform that aggregates data from your app, website, and other sources.
mParticle Integration Types
There are three avenues through which you can integrate with mParticle:
- Via the Server-to-Server (S2S) integration for your website
- By integrating your app with the mParticle co-SDK
- By sending Real-Time Data StreamingA service that delivers engagement events in real time via the Data Streaming API or an Airship partner integration. events from Airship back to mParticle
Use the mParticle S2S integration to send web events to Airship. You can trigger automations, in-app automations, and journeys using incoming custom events from mParticle. You can even personalize messages in automations or journeys using values from events.
Use the App integration and set tags on your app audience from mParticle. Use mParticle to segment and target your Airship App audience.
Send Airship events back to mParticle. Take advantage of events recorded by Airship in your mParticle customer data aggregate.
Integrating Your App with mParticle
To integrate your app with mParticle, you must add mParticle’s Airship Kit to your app’s dependencies. The kit acts as a bridge between the mParticle and Airship SDKs, and it exposes the full range of Airship features to mParticle.
Follow mParticle’s Airship Kit Integration document to install the kit.
Location events are not automatically tracked in the co-SDK integration. See: Gimbal integration and Radar integration.
The co-SDK issues a custom event for each item in the array of the standard mParticle event.
Mapping mParticle Events and User Attributes
Most Airship events are mapped to mParticle’s Custom Event where:
event_type = custom_event
custom_event_type = other
event_name = {Airship event type}
Airship Event | mParticle Event |
---|---|
ATTRIBUTE_OPERATION | Set as User Attributes |
CLOSE | Custom Event |
CONTROL | Custom Event |
CUSTOM | Custom Event |
FIRST_OPEN | Custom Event |
FIRST_OPT_IN | Custom Event |
IN_APP_BUTTON_TAP | Custom Event |
IN_APP_EXPERIENCES | Custom Event |
IN_APP_FROM_DISPLAY | Custom Event |
IN_APP_FROM_RESULT | Custom Event |
IN_APP_MESSAGE_DISPLAY | Custom Event |
IN_APP_MESSAGE_EXPIRATION | Custom Event |
IN_APP_MESSAGE_RESOLUTION | Custom Event |
IN_APP_PAGE_SWIPE | Custom Event |
IN_APP_PAGE_VIEW | Custom Event |
IN_APP_PAGER_COMPLETED | Custom Event |
IN_APP_PAGER_SUMMARY | Custom Event |
LOCATION | Custom Eventcustom_event_type = location |
MOBILE_ORIGINATED | Custom Event |
OPEN | Custom Event |
REGION | Custom Event |
RICH_DELETE | Custom Event |
RICH_DELIVERY | Custom Event |
RICH_READ | Custom Event |
SCREEN_VIEWED | Screen View |
SEND | Custom Event |
SEND_ABORTED | Custom Event |
SEND_REJECTED | Custom Event |
SHORT_LINK_CLICK | Custom Event |
SUBSCRIPTION | Custom Event |
TAG_CHANGE | Set as User Attributes |
UNINSTALL | Uninstall |
WEB_CLICK | Custom Event |
WEB_SESSION | Custom Event |
Airship predefined
attributes
are mapped to mParticle reserved user attributes.
If this mapping is not possible, the event properties are flattened and added to
the custom_attributes
object.
Airship Attribute | mParticle Attribute |
---|---|
age | $age |
gender | $gender |
country | $country |
region (State or province) | $state |
first_name | $firstname |
last_name | $last_name |
mobile_phone | $mobile |
Airship tags are grouped: mParticle creates a user attribute list for each tag group. The
key is prefixed with Airship
. For example, a tag group loyalty which contains tags
silver_member
and special_offers
is mapped as follows:
{"Airship loyalty" : ["silver_member", "special_offers"]}
Airship Property | mParticle Property | Description |
---|---|---|
occurred | timestamp_unixtime_ms | Event timestamp |
com.urbanairship.vendor | ios_idfv | IDFV |
com.urbanairship.aaid | android_advertising_id | Android Advertising ID |
com.urbanairship.limited_ad_tracking_enabled | limit_ad_tracking | Indicates if the user has enabled limit ad tracking |
device_model | device_model | The device model |
device_os | os_version | The device operating system |
carrier | network_carrier | The carrier of the device |
locale_language_code | locale_language | Current language device is set to |
locale_country_code | locale_country | Current locale device is set to |
locale_timezone | timezone_offset | The device’s timezone offset setting in hours relative to UTC. |
web_user_agent_string | http_header_user_agent | HTTP User Agent |
app_package_name | package | A unique identifier for the app name |
app_version | application_version | The version of the app |
named_user_id | customer_id | Customer ID |
channel | airship_channel_id | Partner ID |
Your app integration maps user attributes from mParticle to Airship tags in the device
tag group. If a user attribute does not contain a value, the attribute key is mapped directly to an Airship tag. If the user attribute contains a value, Airship sets the tag as key-value
.
For example, an mParticle user attribute in the format "a_custom_property": "some_value"
would map to a a_custom_property-some_value
tag in Airship.
Sending mParticle Events Using the Server to Server Integration
The Server to Server (S2S) integration sends mParticle events captured from your website to Airship using the Custom Events API. Custom events are associated with named usersA customer-provided identifier used for mapping multiple devices and channels to a specific individual.
; you can map named users to a hashed email address, an mParticle customer_id
, or Other
(a field in mParticle’s user_identities
object).
The S2S integration uses the name of the event as the key in the properties of the event, containing an array of objects that you can iterate over — a list of products, promotions, or impressions.
To send Airship events back into mParticle, see Sending Airship RTDS Events to mParticle.
In the Airship dashboard, go to Settings and copy your App Key.
Create a bearer token with the All Access role.
- Go to Settings » Project Configuration and click Manage for Tokens.
- Click Create Token.
- Enter a token Name. This is just a friendly name to help you recognize your tokens in Airship.
- Select the Role you want to grant for this token. For additional information, see Airship API Security.
- Audience Modification: Grants read and write permission to audience APIs, including channels, named users, segments, lists, etc. Use this permission for users sending custom events into Airship.
- All Access: Grants full access to your Airship project, except Acoustic integrations. You should use this permission when creating a token for an inbound message handling webhook.
- Click Create Token.
- Copy the values, then click Got it to close the window.
Go to mParticle and create an Output Configuration for Airship.
In mParticle, select Directory and then click Airship.
Click Add Airship to Setup.
Select the Output Event Integration Type and click Add to Setup.
Select the Airship output configuration group to configure an output event configuration.
Enter a Configuration Name, your Airship App Key, and select your Domain.
Select App Key is for Web and click Save.
Connect inputs to the output configuration you created in the previous step.
Go to Connections » Connect.
Select the Input for the connection definition.
Click Connect Output.
Select the Airship Output Configuration that you created in previous steps.
Paste the bearer token that you created in earlier steps into the Token field.
Select the Named User ID Type that you want to map to your named users in Airship.
Click Add Connection.
mParticle commerce events are mapped to Airship events as follows:
mParticle parent object | mParticle Event | Airship Mapped Name | Array of Objects (S2S integration only) |
---|---|---|---|
product_action | purchase | purchased | purchased.products |
product_action | add_to_cart | added_to_cart | added_to_cart.products |
product_action | add_to_wishlist | starred_item | starred_item.products |
product_action | remove_from_wishlist | remove_from_wishlist | remove_from_wishlist.products |
product_action | remove_from_cart | remove_from_cart | remove_from_cart.products |
product_action | checkout | checkout | checkout.products |
product_action | refund | refund | refund.products |
product_action | checkout_option | checkout_option | checkout_option.products |
product_action | view_detail | view_detail | view_detail.products |
promotion_action | unknown | unknown | unknown.promotions |
promotion_action | view | view | view.promotions |
promotion_action | click | browsed | browsed.promotions |
product_impressions | impression | impression.impressions |
To use mParticle’s lifetime value feature, you must specify an event name for Airship. Usually, these are purchase events or other events you’d like to attribute to the lifetime value of the customer.
Personalizing Messages and Journeys Using mParticle Events
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 journeys based on incoming mParticle events.
The mParticle event name
generally contains an array of objects relevant to the event. For example, in the event below, the array of products
appears in the added_to_cart
key in the added_to_cart
event.
Use object and array notation to access these properties. For example, using the incoming mParticle custom event below, you iterate over the array of products
using {{#each added_to_cart.products}}
.
{
"occurred": "2020-02-27T09:41:54",
"user": {
"named_user_id": "hugh.manbeing"
},
"body": {
"value": 119.95,
"name": "added_to_cart",
"properties": {
"id": "c420c8f2-5b81-4236-a07e-176cec0e4327",
"source_id": "daba03c3-cc27-4395-b38f-deb9d44a0855",
"session_id": "-310836276167998200",
"coupon_code": "Example transaction coupon code",
"transaction_id": "example-transaction-id",
"tax_amount": 5.0,
"shipping_amount": 5.0,
"action": "added_to_cart",
"added_to_cart": {
"products": [
{
"id": "example-sku",
"name": "t-shirt",
"brand": "Nike",
"category": "Athletics",
"position": 0,
"price": 19.99,
"quantity": 4,
"totalAmount": 79.96
},
{
"id": "example-sku-2",
"name": "jacket",
"brand": "Columbia",
"category": "Outdoors",
"position": 0,
"price": 29.99,
"quantity": 1,
"totalAmount": 29.99
}
]
},
"source": "mParticle"
}
}
}
For example, you might create a template using #each
to iterate over the products
array in the example event above and let your audience know about the products that are still in their cart.
You added the following items to your cart!
{{#each added_to_cart.products}}
{{quantity}}x {{name}} @ ${{price}} = {{totalAmount}}
{{/each}}
Use coupon code {{coupon_code}} to save now!
Sending Airship RTDS Events to mParticle
Start by configuring the Airship integration on the mParticle dashboard:
- Click Directory.
- From the available integrations, find the Airship tile. Hover over the Airship tile and click the Setup button that appears.
The Airship integration supports the feeds: iOS, Android, Web, and Unbound. If you want to capture data for multiple platforms, you must configure one instance of the feed for each platform in mParticle.
- In the dialog window, click Go to Setup » Input Feed.
- Expand Airship and click .
- Enter a unique name in the Configuration Name field.
- Select the appropriate option from the list in the Platform field: iOS, Android, or Web. For the Unbound feed, leave this field unselected.
- Click Save to complete your setup.
For each created input, mParticle provides a Server to Server Key and Secret. Copy these credentials for Airship setup, making sure to note which feed each pair of credentials is for. For each platform that you want to set up, complete the following steps:
- In Airship, open your project, then go to Settings » Project Configuration and click Manage for Real-Time Data Streaming.
- Click mParticle and enter a name and description.
- Choose an mParticle environment.
- Configure platforms with Server to Server Keys and Secrets copied from mParticle.
- In the User Identity Type field, select Customer ID. You may also select Other (a field in mParticle’s
user_identities
object). - Select the event types that you want to send to mParticle.
- Click Activate to complete the configuration.
- This integration maps Airship channels to mParticle platforms. For example, you set iOS in the Airship RTDS configuration page to map to iOS on the mParticle platform. iOS, Android, and Web have direct matches on the mParticle’s side. Airship email and SMS data are sent as Unbound data to mParticle. Another option is to configure all Airship data to be sent as unbound traffic. In this case, you will not select a platform in the mParticle configuration.
- Only events that have at least one device ID (IDFV/AAID) or user identity (Named User IDA customer-provided identifier used for mapping multiple devices and channels to a specific individual. ) are sent to mParticle.
Troubleshooting mParticle Setup
- What do I do if I already have the Airship SDK in my app and want to add mParticle’s SDK?
- To send events from mParticle to Airship, do one of the following:
Reinstall the kit through mParticle for a SDK update and to map the events.
Map mParticle events to Airship-specific events, such as tags, custom events, etc.
- How do I update the Airship SDK when it was originally installed via the mParticle SDK?
- You can specify a newer Airship SDK cocoapod for iOS or define a newer gradle dependency for Android. Both cocoapods and gradle resolve to the newest dependency listed. For example, the kit could define 7.0.0, but if the app wants 7.2.0, the kit will be forced to use 7.2.0.
Categories