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:

  1. Via the Server-to-Server (S2S) integration for your website
  2. By integrating your app with the mParticle co-SDK
  3. 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.

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

Use the App integration and set tags on your app audience from mParticle. Use mParticle to segment and target your Airship App audience.

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

Send Airship events back to mParticle. Take advantage of events recorded by Airship in your mParticle customer data aggregate.

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

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.

 Note

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 EventmParticle Event
ATTRIBUTE_OPERATIONSet as User Attributes
CLOSECustom Event
CONTROLCustom Event
CUSTOMCustom Event
FIRST_OPENCustom Event
FIRST_OPT_INCustom Event
IN_APP_MESSAGE_DISPLAYCustom Event
IN_APP_MESSAGE_EXPIRATIONCustom Event
IN_APP_MESSAGE_RESOLUTIONCustom Event
LOCATIONCustom Event
custom_event_type = location
MOBILE_ORIGINATEDCustom Event
OPENCustom Event
REGIONCustom Event
RICH_DELETECustom Event
RICH_DELIVERYCustom Event
RICH_READCustom Event
SCREEN_VIEWEDScreen View
SENDCustom Event
SEND_REJECTEDCustom Event
SHORT_LINK_CLICKCustom Event
SUBSCRIPTIONCustom Event
TAG_CHANGESet as User Attributes
UNINSTALLUninstall
WEB_CLICKCustom Event
WEB_SESSIONCustom 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 AttributemParticle 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 PropertymParticle PropertyDescription
occurredtimestamp_unixtime_msEvent timestamp
com.urbanairship.vendorios_idfvIDFV
com.urbanairship.aaidandroid_advertising_idAndroid Advertising ID
com.urbanairship.limited_ad_tracking_enabledlimit_ad_trackingIndicates if the user has enabled limit ad tracking
device_modeldevice_modelThe device model
device_osos_versionThe device operating system
carriernetwork_carrierThe carrier of the device
locale_language_codelocale_languageCurrent language device is set to
locale_country_codelocale_countryCurrent locale device is set to
locale_timezonetimezone_offsetThe device’s timezone offset setting in hours relative to UTC.
web_user_agent_stringhttp_header_user_agentHTTP User Agent
app_package_namepackageA unique identifier for the app name
app_versionapplication_versionThe version of the app
named_user_idcustomer_idCustomer ID
channelairship_channel_idPartner 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).

 Note

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.

  1. In the Airship dashboard, go to Settings and copy your App Key.

  2. Create a bearer token with the All Access role.
    1. Go to Settings » Project Configuration and click Manage for Tokens.
    2. Click Create Token.
    3. Enter a token Name. This is just a friendly name to help you recognize your tokens in Airship.
    4. 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.
    5. Click Create Token.
    6. Copy the values, then click Got it to close the window.
  3. Go to mParticle and create an Output Configuration for Airship.

    1. In mParticle, select Directory and then click Airship.

    2. Click Add Airship to Setup.

    3. Select the Output Event Integration Type and click Add to Setup.

    4. Select the Airship output configuration group to configure an output event configuration.

    5. Enter a Configuration Name, your Airship App Key, and select your Domain.

    6. Select App Key is for Web and click Save.

  4. Connect inputs to the output configuration you created in the previous step.

    1. Go to Connections » Connect.

    2. Select the Input for the connection definition.

    3. Click Connect Output.

    4. Select the Airship Output Configuration that you created in previous steps.

    5. Paste the bearer token that you created in earlier steps into the Token field.

    6. Select the Named User ID Type that you want to map to your named users in Airship.

    7. Click Add Connection.

mParticle commerce events are mapped to Airship events as follows:

mParticle parent objectmParticle EventAirship Mapped NameArray of Objects (S2S integration only)
product_actionpurchasepurchasedpurchased.products
product_actionadd_to_cartadded_to_cartadded_to_cart.products
product_actionadd_to_wishliststarred_itemstarred_item.products
product_actionremove_from_wishlistremove_from_wishlistremove_from_wishlist.products
product_actionremove_from_cartremove_from_cartremove_from_cart.products
product_actioncheckoutcheckoutcheckout.products
product_actionrefundrefundrefund.products
product_actioncheckout_optioncheckout_optioncheckout_option.products
product_actionview_detailview_detailview_detail.products
promotion_actionunknownunknownunknown.promotions
promotion_actionviewviewview.promotions
promotion_actionclickbrowsedbrowsed.promotions
product_impressionsimpressionimpression.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 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:

  1. Click Directory.
  2. 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.

  1. In the dialog window, click Go to Setup » Input Feed.
  2. Expand Airship and click  .
  3. Enter a unique name in the Configuration Name field.
  4. Select the appropriate option from the list in the Platform field: iOS, Android, or Web. For the Unbound feed, leave this field unselected.
  5. 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:

  1. In Airship, open your project, then go to Settings » Project Configuration and click Manage for Real-Time Data Streaming.
  2. Click mParticle and enter a name and description.
  3. Choose an mParticle environment.
  4. Configure platforms with Server to Server Keys and Secrets copied from mParticle.
  5. In the User Identity Type field, select Customer ID. You may also select Other (a field in mParticle’s user_identities object).
  6. Select the event types that you want to send to mParticle.
  7. Click Activate to complete the configuration.
 Important

  1. 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.
  2. 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.