mParticle

AIRSHIP MAINTAINED INTEGRATION

This integration is maintained by Airship. Please contact Airship for support.

mParticle 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.
  2. 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.
  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 to mParticle

mParticle Integration Requirements

  • Accounts
    1. mParticle
    2. Airship — Must include both:
  • 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.

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

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

Web Integration

The Server to Server (S2S) integration sends mParticle events captured from your website to Airship using the Custom Events API. You can trigger automations, in-app automations, and sequences using incoming Custom EventsEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom events can trigger automation, including Sequences, Scenes, and Surveys. You can code them into your app or website, or send them to Airship from an external source using the custom event API. Custom events contain properties that you can use to personalize messages. from mParticle. You can even personalize messages in automations or sequences using values from these 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

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.

Configuring the Web Integration

You must have an access level of Owner, Admin or Full Access to configure the integration. You must also have your Airship project’s App KeyThe unique identifier for your Airship project. It is used to authenticate the application for API calls. and Master SecretA secret that can be used as the Basic authorization password for any API call. Guard the Master Secret carefully, and never embed it in an application you distribute to users. to configure the integration. You can copy them from Settings in your project.

In Airship:

  1. Go to Settings.
  2. Under Project Configuration, select Manage for Partner Integrations.
  3. Select mParticle.
  4. Select Configure for the inbound integration and follow the onscreen instructions to:

In mParticle:

  1. Create an Output Configuration for Airship:
    1. Select Directory, then Airship.
    2. Select Add Airship to Setup.
    3. For Integration Type, select Output Event, then select Add to Setup.
    4. Select the Airship output configuration group.
    5. Enter a Configuration Name, your Airship App Key, and select your domain.
    6. Select App Key is for Web, then Save.
  2. Connect inputs to the output configuration you created in the previous step:
    1. Go to Connections, then Connect.
    2. Select the Input for the connection definition.
    3. Select 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. Select Add Connection.

Mapping mParticle Events and Airship Events

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 Sequences 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 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}}.

{
  "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!

Real-Time Data Streaming Integration

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
 Important

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.

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.
  2. Hover over the Airship tile and select Setup.
  3. Go to Setup, then Inputs.
  4. Select the plus icon ().
  5. Enter a unique configuration name.
  6. Select a platform or leave unselected for an Unbound feed.
  7. Select Save.
  8. Copy the Server to Server Key and Secret for use in the next steps in Airship.
  9. Select Close.

In Airship, complete these steps for each feed you created in mParticle:

  1. Go to Settings.
  2. Under Project Configuration, select Manage for Real-Time Data Streaming.
  3. Under Real-Time Data Streaming, select mParticle.
  4. 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 EventmParticle Event
ATTRIBUTE_OPERATIONSet as User Attributes
CLOSECustom Event
CONTROLCustom Event
CUSTOMCustom Event
FIRST_OPENCustom Event
FIRST_OPT_INCustom Event
IN_APP_BUTTON_TAPCustom Event
IN_APP_EXPERIENCESCustom Event
IN_APP_FROM_DISPLAYCustom Event
IN_APP_FROM_RESULTCustom Event
IN_APP_MESSAGE_DISPLAYCustom Event
IN_APP_MESSAGE_EXPIRATIONCustom Event
IN_APP_MESSAGE_RESOLUTIONCustom Event
IN_APP_PAGE_SWIPECustom Event
IN_APP_PAGE_VIEWCustom Event
IN_APP_PAGER_COMPLETEDCustom Event
IN_APP_PAGER_SUMMARYCustom 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_ABORTEDCustom Event
SEND_REJECTEDCustom Event
SHORT_LINK_CLICKCustom Event
SUBSCRIPTIONCustom Event
TAG_CHANGESet as User Attributes
UNINSTALLUninstall
WEB_CLICKCustom Event
WEB_SESSIONCustom Event