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: the Server-to-Server (S2S) integration for your website, integrate your app with the mParticle co-SDK, and send 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 into 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.

Mapping mParticle Events and Properties to Airship

mParticle events normally contain an array of objects representing products, promotions, or impressions. The Airship Kit integration for apps and the S2S integration for websites both forward mParticle events to Airship as custom events. However, the custom events sent to Airship take a different shape depending on whether they come from the Airship Kit co-SDK or the mParticle S2S integration.

• For your app: The co-SDK issues a custom event for each item in the array of the standard mParticle event.

• For your website: The S2S integration uses the name of the event as a key in the properties of the event, containing an array of objects that you can iterate over — a list of products, promotions, or impressions.

The following eCommerce events are mapped to Airship events:

Integrate 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 User Attributes to Airship Tags

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.

Set Up an mParticle S2S Integration

This integration sends mParticle events captured from your website to Airship using the Custom Events API. Custom events are mapped to named users; 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 Setting Up an Airship-to-mParticle Feed .

1. In the Airship dashboard, go to Settings » API & Integrations and copy your App Key.

2. Create a bearer token with the All Access role.

   1. Go to Settings » APIs & Integrations » 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 IBM UBX 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.

Personalize Messages and Journeys Using mParticle Events

You can use Airship HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. 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 would 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!

Set Up an Airship-to-mParticle Feed

This integration enables Airship to send Real-Time Data Streaming events back into mParticle so you can take advantage of Airship data and events in other mParticle-connected platforms.

1. In mParticle, go to the Directory and click Airship.

2. Click Setup » Input Feed » Configure.

3. Enter a Configuration Name and click Save.

4. Copy the Token. You’ll paste it into Airship in later steps.

5. In Airship, open your project and go to Settings » Real-Time Data Streaming.

6. Under Real-Time Data Streaming, click mParticle.

7. Enter a Name and Description to help you identify the integration.

8. Enter the mParticle Token that you copied when adding Airship to mParticle as an input feed.

9. Select the event types that you want to send to mParticle.

10. Click Activate.

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, either:

• Reinstall the kit through mParticle for a SDK update and to map the events.

• Map mParticle events to Airship-specific events, e.g., 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.