mParticle

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.

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.

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 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 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"]}

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

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:

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.

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.