# mParticle
Map mobile engagement events to your customer data warehouse.
[mParticle](https://www.mparticle.com/) is a mobile data platform that aggregates data from your app, website, and other sources.
## mParticle Integration Types
There are three ways you can integrate with mParticle:
1. By integrating your **app** with the mParticle co-SDK — *Use mParticle to segment and target your Airship App audience.*
1. Via the Server-to-Server (S2S) integration for your **website** — *Send web events to Airship and use them to trigger messages and personalize message content.*
1. By sending [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) events from Airship to mParticle
## mParticle Integration Requirements
* **Accounts**
1. mParticle
1. Airship
* Messaging
* [Real-Time Data Streaming](https://www.airship.com/docs/reference/feature-packages/#data) — *Required for outbound integration only*
* **Airship project**
* The Airship SDK must use the same user identity as the mParticle SDK.
## App Integration
Use the App integration and set tags on your app audience from mParticle.
```mermaid
sequenceDiagram
participant a as User
participant b as mParticle
participant c as Airship
a->>b: Performs action recorded as event
b->>c: Sets tag on user in Airship
c->>a: Send message to user
```
### Configuring the App Integration
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](https://docs.mparticle.com/integrations/airship/event/#embedded-kit-integration) document to install the kit.
> **Note:** Location events are not automatically tracked in the co-SDK integration. See: [Gimbal integration](https://www.airship.com/docs/integrations/gimbal/) and [Radar integration](https://www.airship.com/docs/integrations/radar/).
>
> The co-SDK issues a custom event for each item in the array of the standard mParticle event.
### Troubleshooting
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.
### Mapping Attributes
[Airship predefined
attributes](https://www.airship.com/docs/reference/data-collection/attributes/#predefined-attributes)
are mapped to [mParticle reserved user attributes](https://docs.mparticle.com/developers/server/json-reference/#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:
```json
{"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 |
| 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](https://www.airship.com/docs/developer/rest-api/ua/schemas/channels/#channellistingobject) 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.
## Web Integration
The Server to Server (S2S) integration sends mParticle events captured from your website to Airship using the [Custom Events API](https://www.airship.com/docs/developer/rest-api/ua/operations/custom-events/#addcustomevents). You can trigger automations, in-app automations, and sequences using incoming [Custom Events](https://www.airship.com/docs/reference/glossary/#custom_event) from mParticle. You can even [personalize messages](https://www.airship.com/docs/guides/personalization/about/) in automations or sequences using values from these events.
```mermaid
sequenceDiagram
participant a as User
participant b as mParticle
participant c as Airship
a->>b: Performs action recorded as event
b->>c: Sends custom event
c->>a: Automatically sends message based on event
```
Custom events are associated with [Named Users](https://www.airship.com/docs/reference/glossary/#named_user). 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.
### Configuring the Web Integration
You must have an [access level of Owner, Admin or Full Access](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels) to configure the integration.
In Airship:
1. Next to your project name, select the dropdown menu (
), then **Settings**.
1. Under **Project settings**, select **Partner Integrations**.
1. Select **mParticle**.
1. Select **Configure** for the inbound integration and follow the onscreen instructions to:
* Create [Custom Events](https://www.airship.com/docs/reference/glossary/#custom_event) `purchased`, `added_to_cart`, `browsed`, and `starred_item`.
* Configure Airship in mParticle.
Next, get your Airship project's [App Key](https://www.airship.com/docs/reference/glossary/#app_key), which you will use to configure the integration in mParticle:
1. Next to your project name, select the dropdown menu (
), then **Project Details**.
1. Copy your App Key.
In mParticle:
1. Create an Output Configuration for Airship:
1. Select **Directory**, then **Airship**.
1. Select **Add Airship to Setup**.
1. For **Integration Type**, select **Output Event**, then select **Add to Setup**.
1. Select the **Airship** output configuration group.
1. Enter a Configuration Name, your Airship App Key, and select your domain.
1. Select **App Key is for Web**, then **Save**.
1. Connect inputs to the output configuration you created in the previous step:
1. Go to **Connections**, then **Connect**.
1. Select the Input for the connection definition.
1. Select **Connect Output**.
1. Select the **Airship** Output Configuration that you created in previous steps.
1. Paste the bearer token that you created in earlier steps into the **Token** field.
1. Select the **Named User ID Type** that you want to map to your named users in Airship.
1. Select **Add Connection**.
### Mapping mParticle Events and Airship Events
[mParticle commerce events](https://docs.mparticle.com/developers/sdk/web/commerce-tracking/) 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` |
> **Note:** 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 Sequences Using mParticle Events {#personalize}
You can use Airship [Handlebars](https://www.airship.com/docs/reference/glossary/#handlebars) to personalize messages in automation rules or sequences 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}}`.
```json
{
"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.
```text
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!
```
## Real-Time Data Streaming Integration
Take advantage of events recorded by Airship in your mParticle customer data aggregate.
```mermaid
sequenceDiagram
participant a as User
participant b as Airship
participant c as mParticle
b->>a: Sends a message
a->>b: App open event resulting from message
b->>c: Sends event to mParticle CDP
```
> **Important:** Only events that have at least one device ID (IDFV/AAID) or user identity ([Named User ID](https://www.airship.com/docs/reference/glossary/#named_user)) are sent to mParticle.
### Configuring the RTDS Integration
This integration maps Airship App and Web channels to mParticle platforms. First you will create a feed for each Airship channel in mParticle, then you will configure RTDS for each feed and specify which events to send to mParticle.
* iOS, Android, and Web have direct matches in mParticle, so you will select each when creating feeds.
* Email and SMS do not have direct matches in mParticle, so you will not select a platform when creating the feed. These events are instead sent as *Unbound* data to mParticle.
You can also opt to send **all** Airship data as unbound traffic. In this case, do not select a platform when creating an mParticle feed.
---
In mParticle, repeat these steps to create feeds for iOS, Android, Web, and/or Unbound channels:
1. Go to **Directory** to view the available integrations.
1. Hover over the Airship tile and select **Setup**.
1. Go to **Setup**, then **Inputs**.
1. Select the plus icon ().
1. Enter a unique configuration name.
1. Select a platform or leave unselected for an Unbound feed.
1. Select **Save**.
1. Copy the **Server to Server Key** and **Secret** for use in the next steps in Airship.
1. Select **Close**.
In Airship, complete these steps for each feed you created in mParticle:
1. Next to your project name, select the dropdown menu (
), then **Settings**.
1. Under **Project settings**, select **Real-Time Data Streaming**.
1. Under **Real-Time Data Streaming**, select **mParticle**.
1. Follow the onscreen instructions to configure the integration.
* Be sure to enter the correct mParticle Server to Server Key and Secret for the platform you select.
* The default User Identity Type is Customer ID, but you can also select Other, which is a field in mParticle's `user_identities` object.
### Mapping Events
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 Event
`custom_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 |