# How can we help?

## Overview

Cordial seamlessly connects to [mParticle](https://www.mparticle.com/), empowering you to get the most out of your data. With our bi-directional integration, you can easily stream all of your data in and out of Cordial in real time.

Cordial streams mParticle real-time event and contact data related to sending, receiving, and engaging with messages across channels. Cordial’s event data includes supporting metadata and contact identifiers to help mParticle create a more holistic view of your customer.

- You can [learn how to send data from mParticle to Cordial here](https://support.cordial.com/hc/en-us/articles/9136941752717).

## Enable and authenticate Cordial as a source

You can enable the mParticle integration by following the steps below.

1. Once you've created Cordial as a source in your mParticle account, copy the mParticle **Key** and **Secret**.

2. Log in to Cordial and navigate to **Integrations > Partners**.

3. Locate the mParticle card and select **Enable**.

4. In the **Outbound Feed Settings** panel, paste in the **Key** and **Secret** from your mParticle source project.

## Configure feed type

On the mParticle partner card, click **Edit** in the **Outbound Feed Settings** pane to set the desired feed type. Cordial can send events to mParticle via three different feeds:

- iOS: Predefined list of events generated by iOS SDK
- Android: Predefined list of events generated by Android SDK
- Unbound: Events not listed in iOS or Android feeds

If iOS or Android feeds are not available, their events are sent to the Unbound feed.

All data sent to an mParticle feed must be marked as either `development` or `production`. Set this to `true` in your test and QA environments.

## Configure allowed and blocked events

Click **Edit** in the **Outbound Event Settings** pane to block or allow specific data events for each channel, and according to custom events. By default, _Block all events_ is set for each case.

In order to prevent recursion, any event records marked as having mParticle as their origin source will automatically be blocked from being sent back to mParticle.

## Configure contact data

Click **Edit** in the **Identifier Mapping** pane to configure the contact data Cordial attaches to each event. A contact’s Cordial identifier is automatically sent as a partner identity with each event.

## Outbound attribute handling

Outbound attribute handling allows you to specify which Cordial attributes to pass to mParticle as contact attributes with each event. Available attributes are: string, date, number, and boolean.

For SMS and Email channels, two fields are available: `address` and `ss`, which is short for `subscribeStatus`. For example: `channels.channelName.address`, `channels.channelName.ss`.

Following mParticle’s recommended pattern, the attributes are prefixed with `cordial_` when sent to mParticle. For example: `cordial_cid`, `cordial_firstname`.

## Available event data

As events fire in Cordial, they're sent directly to mParticle. Each of the events below (along with all supporting metadata and contact identifiers) are included with the integration.

### Email channel events

| Cordial  | mParticle  |
| --- | --- |
| message-sent | Message sent |
| open          | Email opened |
| click         | Email link clicked |
| optout        | Unsubscribed |
| bounce        | Email bounced |
| crdl_subscribeStatusChange | Change in contact's subscription status |

### Mobile channel events

| Cordial  | mParticle  |
| --- | --- |
| crdl_app_install | Application installed |
| crdl_app_open   | Application opened |
| message-sent    | Message sent |
| crdl_app_close   | Application closed |
| crdl_notification_tap | Push notification tapped |
| crdl_deep_link_open | Deep link opened |
| crdl_{channelKey}_send_failure | Error received when trying to send to the device |
| crdl_notification_delivered_in_foreground | A push notification has been delivered while the app was in the foreground. |
| crdl_notification_delivered_in_background | A push notification has been delivered while the app is in the background. |
| crdl_device_notifications_optout | Push notifications for the app were disabled automatically. |
| crdl_device_notifications_uninstalled | The application was uninstalled from a device. |
| crdl_in_app_message_auto_dismiss | The in-app message was dismissed automatically. |
| crdl_in_app_message_shown | The in-app message was displayed. |
| crdl_in_app_message_manual_dismiss | The in-app message was closed by the user. |
| crdl_inbox_read | The in-app message was read by the user. |
| crdl_notification_dismissed | A notification was dismissed by the user. |
| crdl_notification_tap | A notification was tapped by the user. |

### Podium events

| **Event** | **mParticle** |
| --- | --- |
| crdl-pdm-actn-expired | The orchestration session has expired. |
| crdl-pdm-actn-failed | The action associated with the orchestration failed. |
| crdl-pdm-actn-filtered | Contact action has been filtered from the orchestration. |
| crdl-pdm-actn-ignored  | The action associated with the orchestration was ignored. |
| crdl_merged_contacts | Two contact records were merged into a single record along with respective events and orders. |
| crdl-pdm-actn-success | The action associated with the orchestration was a success. |
| crdl-pdm-goal-met-organic | An orchestration [goal](https://support.cordial.com/hc/en-us/articles/360015822851#setGoal) was met. |
| crdl-pdm-triggered | An orchestration was [triggered](https://support.cordial.com/hc/en-us/articles/360015822851#defineTrigger). |

### SMS channel events

| Cordial  | mParticle  |
| --- | --- |
| message_sent | Message sent |
| click          | Click |
| optout         | Optout |
| crdl_phone_deactivation | Phone number was deactivated by the mobile carrier. |
| crdl_sms_delivered | SMS message was delivered by Cordial. |
| crdl_sms_failed | SMS message failed to deliver. |

### REST channel events

| Cordial  | mParticle  |
| --- | --- |
| message_sent | Message sent |
| crdl_{channelKey}_send_failure | Error received when trying to send to the device |

### Custom events

| Cordial | mParticle |
| --- | --- |
| <as named in Cordial> | <as named in Cordial> |

## Data example

Below is an example of a Cordial click event as passed to mParticle.

```json
{
   "source_request_id":"99126-62b54bdc190dd2169946da15",
   "events":[
      {
         "data":{
            "custom_event_type":"other",
            "event_name":"message-sent",
            "custom_flags":{
            },
            "timestamp_unixtime_ms":"1656048620838",
            "event_id":"2229080450085888785",
            "source_message_id":null,
            "session_start_unixtime_ms":"0",
            "event_start_unixtime_ms":"0",
            "custom_attributes":{
               "cID":"62b44d91196272462701e54f",
               "action":"message-sent",
               "chnl":"email",
               "chnl-type":"email",
               "_id":"62b54bdc190dd2169946da15",
               "bmID":"99126:62b44daf08d94e4e3313897a:ot",
               "mcID":"99126:62b44daf08d94e4e3313897a:ot:62b44d91196272462701e54f:1",
               "sp.stp":"mailgun",
               "sp.ed":"gmail.com",
               "sp.mTags.0":"batch_scheduled_CTZ530776796",
               "sp.tpIPpool":"shared2",
               "name":"batch_scheduled_CTZ530776796",
               "subject":"batch_scheduled_CTZ530776796"
            },
            "is_goal_defined":false,
            "lifetime_value_change":0,
            "lifetime_value_attribute_name":null,
            "data_connection_type":null,
            "event_num":0,
            "view_controller":null,
            "is_main_thread":null,
            "canonical_name":null,
            "event_system_notification_info":null
         },
         "event_type":"custom_event"
      }
   ],
   "device_info":{
      "brand":null,
      "product":null,
      "device":null,
      "android_uuid":null,
      "device_manufacturer":null,
      "platform":"Unknown",
      "os_version":null,
      "device_model":null,
      "screen_height":0,
      "screen_width":0,
      "screen_dpi":0,
      "device_country":null,
      "locale_language":null,
      "locale_country":null,
      "network_country":null,
      "network_carrier":null,
      "network_code":null,
      "network_mobile_country_code":null,
      "timezone_offset":null,
      "build_identifier":null,
      "http_header_user_agent":null,
      "ios_advertising_id":"00000000-0000-0000-0000-000000000000",
      "push_token":null,
      "cpu_architecture":null,
      "is_tablet":null,
      "push_notification_sound_enabled":null,
      "push_notification_vibrate_enabled":null,
      "radio_access_technology":null,
      "supports_telephony":null,
      "has_nfc":null,
      "bluetooth_enabled":null,
      "bluetooth_version":null,
      "ios_idfv":"00000000-0000-0000-0000-000000000000",
      "android_advertising_id":"00000000-0000-0000-0000-000000000000",
      "build_version_release":null,
      "limit_ad_tracking":null,
      "amp_id":null,
      "is_dst":false,
      "roku_advertising_id":"00000000-0000-0000-0000-000000000000",
      "roku_publisher_id":null,
      "microsoft_advertising_id":null,
      "microsoft_publisher_id":null,
      "fire_advertising_id":"00000000-0000-0000-0000-000000000000"
   },
   "application_info":{
      "application_name":null,
      "application_version":null,
      "application_build_number":null,
      "install_referrer":null,
      "package":null,
      "os":"OutOfBand",
      "apple_search_ads_attributes":null
   },
   "user_attributes":{
      "cordial_cID":"62b44d91196272462701e54f"
   },
   "deleted_user_attributes":null,
   "user_identities":{
      "customer_id":"62b44d91196272462701e54f"
   },
   "environment":"development",
   "ip":"",
   "integration_attributes":null,
   "source_info":{
      "channel":"partner",
      "partner":"Cordial",
      "replay_request_id":null,
      "replay_job_id":null,
      "is_historical":false
   },
   "mp_deviceid":"00000000-0000-4000-8000-0000000022fa",
   "attribution_info":null,
   "timestamp_unixtime_ms":1656048620838,
   "batch_id":"-7297337031652824529",
   "mpid":"-4865041417284204612",
   "sdk_version":null,
   "context":{
      "location":{
         "latitude":0,
         "longitude":0,
         "accuracy":0,
         "country_code":null,
         "region_code":null,
         "postal_code":null,
         "dma_code":0,
         "location_source":"unknown",
         "city_name":null
      }
   }
}
```