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 user-level events in real time to your backend or third-party systems using the Data Streaming API. events from Airship to mParticle

mParticle Integration Requirements

• Accounts
  1. mParticle
  2. Airship
     • Messaging
     • Real-Time Data Streaming — Required for outbound integration only
• 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, including Sequences and Scenes. 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 an access level of Owner, Admin or Full Access to configure the integration.

In Airship:

1. Next to your project name, select the dropdown menu (), then Settings.
2. Under Project settings, select Partner Integrations.
3. Select mParticle.
4. Select 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, including Sequences and Scenes. 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.

Next, get your Airship project’s App KeyThe unique identifier for your Airship project. It is used to authenticate the application for API calls., which you will use to configure the integration in mParticle:

1. Next to your project name, select the dropdown menu (), then Project Details.
2. Copy your App Key.

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:

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 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. Next to your project name, select the dropdown menu (), then Settings.
2. Under Project settings, select 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}