mParticle

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:
     • Messaging
     • Real-Time Data Streaming
• 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.

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.

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

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

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 a Team Access level of Owner, Admin or Full Access to configure the integration. You must also have your Airship project’s app key and master secret to configure the integration. Go to Settings and copy the app key and master secret before configuring the integration.

In Airship:

1. Go to Settings » Project Configuration and click Manage for Partner Integrations.
2. Select mParticle.
3. Click Configure for the inbound integration and follow the onscreen instructions to:
   • Create 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, 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. purchased, added_to_cart, browsed, and starred_item.
   • Configure Airship in mParticle.

— OG

In Airship:

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

In mParticle:

1. Create an Output Configuration for Airship.
   1. 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.
2. 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.

Mapping mParticle Events and Airship Events

mParticle commerce events  are mapped to Airship events as follows:

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.

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 click Setup.
3. Go to Setup » Inputs.
4. Click  .
5. Enter a unique configuration name.
6. Select a platform or leave unselected for an Unbound feed.
7. Click Save.
8. Copy the Server to Server Key and Secret for use in the next steps in Airship.
9. Click Close.

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

1. Go to Settings » Project Configuration and click Manage for Real-Time Data Streaming.
2. Under Real-Time Data Streaming, select mParticle. Previously configured integrations are listed under Enabled Integrations.
3. Follow the onscreen instructions to configure the integration.
   • Make 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 may 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}