Overview

mParticle is a Customer Data Platform (CDP) that centralizes customer data from multiple sources, enabling businesses to gather, analyze, and leverage this data to create targeted audience segments. This platform facilitates the aggregation of customer behaviour data, allowing users to define specific audience criteria and dynamically update audiences as new data comes in. The data collected through mParticle can be sent to downstream platforms via outbound plugins, ensuring that businesses can effectively execute personalized marketing strategies.

Visit the mParticle website to learn more.

To learn more out Eagle Eye Connect as a whole please visit: https://developer.eagleeye.com/docs/ee-connect

To learn about the supported CDP/MAP use cases for this connector, please visit: https://developer.eagleeye.com/docs/eagle-eye-connect-cdp-map

📘

Are you a mParticle client interested in using Eagle Eye AIR?

Please reach out to our Partnerships team at [email protected] to get you started!

Configuration

This is the recommended order of configuration.

mParticle Connection Setup

This is a one-time setup to get events flowing form AIR to mParticle.

For receiving events form AIR

1. Go to Data Platform --> Setup --> Connections

2. Add a Custom Feed input and give it a meaningful name for e.g. "Eagle Eye Loyalty - Node"

3. 

   Copy the Server to Server Key ,Server to Server Secret and API Endpoint and share with Eagle Eye for connector setup

4. From the Input Protection Level dropdown, select Create & Update Profiles and click Save

For Issuing Rewards in AIR

This is a one-time setup to enable mParticle to make API calls to Eagle Eye Connect for issuing rewards in AIR.

1. Go to Data Platform --> Setup --> Outputs

2. Click the Audiences tab

3. Click Add Audience Output and select the Eagle Eye tile. Alternatively you can click the 'Add Audience Output' button and select Eagle Eye from the dropdown list.

   

4. Select your desired environment. Note: UK Cluster, US 02 Cluster and AU 01 Cluster are production environments.

   

5. Give it a name for e.g. "Issue Reward in AIR"

6. For AIR external Key provide the secret key a.k.a. Auth token for your inbound connector from mParticle to AIR that was pre-established with Eagle Eye

7. For AIR Connector ID provide the inbound connector ID received from Eagle Eye

8. Click Save

AIR Connection Setup

This is a one-time setup to get Eagle Eye connectors up and running between AIR and mParticle.

Config Service for EE Connect

📘

Config Service via AIR Dashboard

Currently the set up of connectors is possible via API with the help of EE. This feature will be available for clients to self-serve via the AIR dashboard in the near future.

When a new connector is requested, the following will also be done under the hood:

• The service will also configure unique API credentials for EE connect to use for mParticle.
• Event notifications enriched with identity information from AIR to EE Connect will also be done automatically.

The client to provide information listed below to Eagle Eye for inbound and outbound connector setup:

Inbound Connector

The following information is required for inbound connector setup for mParticle:

• Auth token - The client to generate and specify a unique key for security that is passed within the header for inbound API requests from mParticle to EE Connect. API calls without this information will be rejected.
• mparticleIdentityType for e.g. "other"

Outbound Connector

The following information is required for outbound connector setup for mParticle:

• Auth token - The client to generate and specify a unique key for security that is passed within the header for outbound events from AIR. API calls without this information will be rejected.
• apiEndpoint - URL for your instance of mParticle for e.g. https://s2s.mparticle.com/
• serverToServerKey - Can be set up under Data Platform --> Setup --> Inputs --> Feeds --> Custom Feed for Eagle Eye AIR in mParticle Dashboard
• serverToServerSecret - Can be set up under Data Platform --> Setup --> Inputs --> Feeds --> Custom Feed for Eagle Eye AIR in mParticle Dashboard
• mparticleIdentityType for e.g. "other"
• mparticleWalletIdType for e.g "customerid"
• currency - 3 character alphanumeric currency for e.g. USD
• identityType - an identifier for looking up the consumer in both AIR and mParticle for e.g. CARD

AIR Social Behavioural Action Trigger Setup

Social Behavioural Action Triggers can be set up in AIR for various use cases with a unique Action Reference. This unlocks the capability of issuing coupons or points as rewards.

mParticle Audience Setup

Audiences can be set up to trigger an API call to EE Connect to issue rewards in AIR via Social and Behavioural Actions or outputs to other platforms for various purposes including communications to a consumer. There can be various triggers for e.g.

• when a custom EE event is received from AIR
• when events are received from other platforms
• when audiences are created based on the various search criteria

📘

Audience Criteria Selection

Select Eventsfor all AIR custom events excluding purchases for e.g. join and leave loyalty program. Event names will only show up in this list once they flow from AIR to your mParticle instance for any user.

Select Ecommercefor all purchase events from AIR for e.g. Settle, Fulfil.

In this example points are issued to a consumer for joining the loyalty program. To create an audience listens for an AIR event and issues an SBA reward, follow these steps:

1. Go to Segmentation --> Audiences

2. Click New Audience and select your Eagle Eye AIR Connection and click Create

3. 

   click Add Criteria and choose Events from the dropdown list

4. 

   Select your Eagle Eye AIR connection and click Done

5. 

   Select User Preference from the dropdown list and click Done

6. 

   click All for a drop down list of custom events from AIR. Find the list of support events in the data model section. Note: Event names will only show up in this list once they flow from AIR to mParticle.

   

7. You can add further filtering by attributes within the event if required.

8. Give the Audience a name and click Save

9. Click + Connect Output

10. Select Eagle Eye button and select the Eagle Eye AIR output under Select Configuration

    

11. Plug in the Action reference for your desired AIR SBA Trigger, click the toggle to activate and click Add Connection

    

12. Your Audience is ready!

Usage

All inbound and outbound use cases described in EE Connect for CDP and MAP are supported in mParticle. Refer to the Data Model for mParticle for custom attributes and events that are available for use in mParticle.

Data Model

User Profiles

The following custom attributes will be set on a user profile by the mParticle integration:

An example of the custom attributes is shown below:

{
  "loyalty_member": "true",
  "points_balance": "123",
  "tier_id": "177",
  "tier_balances_points": "200",
  "tier_balances_spend": "100",
  "tier_balances_transactions": "1",
  "tier_balances_reset_date": "2035-01-01T00:00:00.000Z"
}

Note that all values are stored as strings.

Events

Commerce Events

Commerce - Purchase

Sent to mParticle on receipt of POSCONNECT.WALLET.SETTLE or POSCONNECT.WALLET.FULFIL. There are three different type of POSCONNECT.WALLET.FULFIL event - "initial", "middle" and "final". As the content of these events differs slightly, the content of the resulting mParticle Commerce Purchase events also differs. Each is described below.

POSCONNECT.WALLET.SETTLE

Sent when a transaction is settled via the "Wallet Settle" POS Connect API.

Commerce Attributes

Event Attributes

User Attributes

POSCONNECT.WALLET.FULFIL (initial)

First event sent as an E-commerce transaction has items fulfilled.

Commerce Attributes

Event Attributes

User Attributes

POSCONNECT.WALLET.FULFIL (middle)

Intermediate event sent as items are fulfilled.

Commerce Attributes

Event Attributes

User Attributes

POSCONNECT.WALLET.FULFIL (final)

Final event sent as items are fulfilled.

Commerce Attributes

Event Attributes

User Attributes

Commerce - Refund

Sent to mParticle on receipt of POSCONNECT.WALLET.REFUND.

Commerce Attributes

Event Attributes

User Attributes

Custom Events

ee_loyalty_program_joined

Sent to mParticle on receipt of SERVICE.WALLET.ACCOUNTS.CREATE or SERVICE.WALLET.CREATE. Note that optional attributes will be included if the data is available - this will normally be the case when a SERVICE.WALLET.ACCOUNTS.CREATE triggers the event, but not when it is triggered by SERVICE.WALLET.CREATE.

Event Attributes

Stringified Coupon Lists

For each atomic operation where:

objectType = "walletAccountTransactionEntity",
operationType = "CREATE",
objectValue.account.type = "ECOUPON"

an entry containing the following attributes will be created in a coupon list:

The resulting list will be stringified, for example:

[{"account_id":"4093853179","campaign_id":"100641542","type":"ECOUPON","client_type":"OFFER","status":"ACTIVE","state":"LOADED","date_start":"2025-01-29T20:23:00+00:00","date_end":"2025-12-31T23:59:00+00:00"},{"account_id":"4093853180","campaign_id":"100641543","type":"ECOUPON","client_type":"OFFER","status":"ACTIVE","state":"LOADED","date_start":"2025-01-29T20:23:00+00:00","date_end":"2025-12-31T23:59:00+00:00"}]

ee_loyalty_program_left

Sent to mParticle on receipt of SERVICE.WALLET.DELETE.

Event Attributes

None

Note: receipt of this event will delete all user attributes related to EagleEye Loyalty from the user profile.

ee_loyalty_tier_membership_create

Sent to mParticle on receipt of TIER.MEMBERSHIP.CREATE.

Event Attributes

ee_loyalty_tier_membership_credit

Sent to mParticle on receipt of TIER.MEMBERSHIP.CREDIT.

Event Attributes

ee_loyalty_tier_membership_debit

Sent to mParticle on receipt of TIER.MEMBERSHIP.DEBIT.

Event Attributes

ee_loyalty_tier_membership_move

Sent to mParticle on receipt of TIER.MEMBERSHIP.MOVE.

Event Attributes

ee_loyalty_tier_membership_adjust

Sent to mParticle on receipt of TIER.MEMBERSHIP.ADJUST.

Event Attributes

ee_loyalty_posconnect_wallet_fulfil

Sent to mParticle on receipt of POSCONNECT.WALLET.REFUND.

Event Attributes

Stringified Coupon Lists

For each atomic operation where:

objectType = "walletAccountTransactionEntity",
operationType = "UPDATE",
objectValue.account.type = "ECOUPON"
objectValue.event = "REDEEM"

an entry containing the following attributes will be created in a coupon list:

The resulting list will be stringified, for example:

[{"account_id":"4093853179","campaign_id":"100641542","value":700},{"account_id":"4093853180","campaign_id":"100641543","value":200}]

Stringified Product Lists

For each purchased products found in the atomic operations within the event, an entry containing the following attributes will be created in a product list:

The resulting list will be stringified, for example:

[{"description":"Coffee","count":1,"itemCost":1000,"totalCost":1000},{"description":"Oranges","count":1,"itemCost":1000,"totalCost":1000}]

ee_loyalty_posconnect_wallet_refund

Sent to mParticle on receipt of POSCONNECT.WALLET.REFUND.

Event Attributes

Stringified list of coupons unredeemed

For each unredeemed coupon, an entry with the following attributes will be added to the list:

The resulting list will be stringified, for example:

[{"account_id":"4093853356","campaign_id":"100792525","value":700}]

Stringified list of products returned

For each returned product, an entry with the following attributes will be added to the list:

The resulting list will be stringified, for example:

[{"count":2,"description":"Lemonade","itemCost":1000,"totalCost":2000},{"count":1,"description":"Coffee","itemCost":1000,"totalCost":1000}]

ee_loyalty_posconnect_wallet_spend

Sent to mParticle on receipt of POSCONNECT.WALLET.SPEND.

Event Attributes

ee_loyalty_posconnect_wallet_spend_void

Sent to mParticle on receipt of POSCONNECT.WALLET.SPEND.VOID.

Event Attributes

ee_loyalty_service_trigger

Sent to mParticle on receipt of SERVICE.TRIGGER.

Event Attributes

ee_loyalty_subscription_cancelled

Sent to mParticle on receipt of WALLET.ACCOUNT.UPDATE.

Event Attributes

ee_loyalty_subscription_joined

Sent to mParticle on receipt of WALLET.ACCOUNT.CREATE.PLAN.

Event Attributes

Stringified Entitlements Lists

For each entitlement found in the atomic operations within the event, an entry containing the following attributes will be created in an entitlements list:

The resulting list will be stringified, for example:

[{"account_id":"4093853179","campaign_id":"100641542","value":700},{"account_id":"4093853180","campaign_id":"100641543","value":200}]

ee_loyalty_wallet_account_create_campaign

One of these events is sent to mParticle for each walletAccountTransactionEntity that is received in a WALLET.ACCOUNT.CREATE.CAMPAIGN.

Event Attributes

ee_loyalty_wallet_account_create_scheme

Sent to mParticle on receipt of WALLET.ACCOUNT.CREATE.SCHEME.

Event Attributes

None

ee_loyalty_coupon_redeemed

Sent to mParticle on receipt of any event containing a walletAccountTransactionEntity with objectValue.value equal to REDEEM (i.e. coupon redemption).

Event Attributes

Sample Journey: A Consumer Joins Loyalty Program

A wallet is created in AIR

API call Services Wallet Account Create is made and all wallet objects are created by one request.

{
    "state": "DEFAULT",
    "status": "ACTIVE",
    "type": "CONSUMER",
    "consumer": {
        "friendlyName": "Sample Consumer Wallet",
        "type": "INDIVIDUAL",
        "status": "ACTIVE",
        "meta": {
            "meta1": "Sample meta value 1",
            "meta2": "Sample meta value 2"
        }
    },
    "identities": [
        {
            "state": "EARNBURN",
            "status": "ACTIVE",
            "type": "CUSTOMER_ID",
            "value": "1111111111111111_May17d"
        },
        {
            "state": "EARNBURN",
            "status": "ACTIVE",
            "type": "CARD",
            "value": "2222222222222222_May17d"
        },
        {
            "state": "EARNBURN",
            "status": "ACTIVE",
            "type": "MOBILE",
            "value": "+1(416)-111-1111_May17d"
        }
    ],
    "accounts": {
        "campaign": [
            {
                "campaignTag": "initialoffer",
                "state": "LOADED"
            }
        ],
        "scheme": [
            {
                "status": "ACTIVE",
                "schemeId": {{schemeId}},
                "state": "LOADED"
            }
        ]
    }
}

{
    "walletId": "219153391",
    "friendlyName": null,
    "status": "ACTIVE",
    "type": "CONSUMER",
    "state": "DEFAULT",
    "meta": [],
    "dateCreated": "2025-05-17T13:51:37+00:00",
    "lastUpdated": "2025-05-17T13:51:37+00:00",
    "relationships": {
        "parent": [],
        "child": [],
        "associate": [],
        "donor": []
    },
    "identities": [
        {
            "identityId": "190325876",
            "walletId": "219153391",
            "type": "CUSTOMER_ID",
            "friendlyName": null,
            "value": "1111111111111111_May17d",
            "safeValue": null,
            "secret": null,
            "dates": {
                "start": "2025-05-17T13:51:37+00:00",
                "end": null
            },
            "meta": [],
            "state": "EARNBURN",
            "status": "ACTIVE",
            "dateCreated": "2025-05-17T13:51:37+00:00",
            "lastUpdated": "2025-05-17T13:51:37+00:00",
            "mobileWallet": "https://sb.uk.mypass.is/identity/202323/219153391/190325876/82170f51b92a962cfe2856e93789c352ec30ac9cf83a1c2e5bbbcda249ee7eb8"
        },
        {
            "identityId": "190325877",
            "walletId": "219153391",
            "type": "CARD",
            "friendlyName": null,
            "value": "2222222222222222_May17d",
            "safeValue": null,
            "secret": null,
            "dates": {
                "start": "2025-05-17T13:51:37+00:00",
                "end": null
            },
            "meta": [],
            "state": "EARNBURN",
            "status": "ACTIVE",
            "dateCreated": "2025-05-17T13:51:37+00:00",
            "lastUpdated": "2025-05-17T13:51:37+00:00",
            "mobileWallet": "https://sb.uk.mypass.is/identity/202323/219153391/190325877/f29a3d9b78b6803e771f6dc16c30c6aa0fc9ab41ac3776c5434eec67a3cfcfc0"
        },
        {
            "identityId": "190325878",
            "walletId": "219153391",
            "type": "MOBILE",
            "friendlyName": null,
            "value": "+1(416)-111-1111_May17d",
            "safeValue": null,
            "secret": null,
            "dates": {
                "start": "2025-05-17T13:51:37+00:00",
                "end": null
            },
            "meta": [],
            "state": "EARNBURN",
            "status": "ACTIVE",
            "dateCreated": "2025-05-17T13:51:37+00:00",
            "lastUpdated": "2025-05-17T13:51:37+00:00",
            "mobileWallet": "https://sb.uk.mypass.is/identity/202323/219153391/190325878/cc1d7c5441fde3d3911c7e37ac905f7e705cfe485fbba846d276dbd16d5afce0"
        }
    ],
    "accounts": {
        "campaign": {
            "total": 3,
            "results": [
                {
                    "accountId": "4306837532",
                    "walletId": "219153391",
                    "campaignId": "101042199",
                    "type": "ECOUPON",
                    "clientType": "OFFER",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-05-17T13:51:37+00:00",
                        "end": "2026-03-01T23:59:00+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-05-17T13:51:37+00:00",
                    "lastUpdated": "2025-05-17T13:51:37+00:00",
                    "overrides": [],
                    "balances": {
                        "available": 0,
                        "refundable": 0
                    },
                    "relationships": [],
                    "mobileWallet": "https://sb.uk.mypass.is/a/4306837532/0adbe535232832b"
                },
                {
                    "accountId": "4306837533",
                    "walletId": "219153391",
                    "campaignId": "101042203",
                    "type": "ECOUPON",
                    "clientType": null,
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-05-17T13:51:37+00:00",
                        "end": "2026-12-31T23:59:00+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-05-17T13:51:37+00:00",
                    "lastUpdated": "2025-05-17T13:51:37+00:00",
                    "overrides": [],
                    "balances": {
                        "available": 0,
                        "refundable": 0
                    },
                    "relationships": [],
                    "mobileWallet": "https://sb.uk.mypass.is/a/4306837533/5de1140b9f1cd66"
                },
                {
                    "accountId": "4306837534",
                    "walletId": "219153391",
                    "campaignId": "101042204",
                    "type": "ECOUPON",
                    "clientType": "OFFER",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-05-17T13:51:37+00:00",
                        "end": "2026-03-01T23:59:00+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-05-17T13:51:37+00:00",
                    "lastUpdated": "2025-05-17T13:51:37+00:00",
                    "overrides": [],
                    "balances": {
                        "available": 0,
                        "refundable": 0
                    },
                    "relationships": [],
                    "mobileWallet": "https://sb.uk.mypass.is/a/4306837534/271748c57494ad5"
                }
            ],
            "successful": {
                "total": 3,
                "results": [
                    {
                        "accountId": "4306837532",
                        "walletId": "219153391",
                        "campaignId": "101042199",
                        "type": "ECOUPON",
                        "clientType": "OFFER",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-05-17T13:51:37+00:00",
                            "end": "2026-03-01T23:59:00+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-05-17T13:51:37+00:00",
                        "lastUpdated": "2025-05-17T13:51:37+00:00",
                        "overrides": [],
                        "balances": {
                            "available": 0,
                            "refundable": 0
                        },
                        "relationships": [],
                        "mobileWallet": "https://sb.uk.mypass.is/a/4306837532/0adbe535232832b"
                    },
                    {
                        "accountId": "4306837533",
                        "walletId": "219153391",
                        "campaignId": "101042203",
                        "type": "ECOUPON",
                        "clientType": null,
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-05-17T13:51:37+00:00",
                            "end": "2026-12-31T23:59:00+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-05-17T13:51:37+00:00",
                        "lastUpdated": "2025-05-17T13:51:37+00:00",
                        "overrides": [],
                        "balances": {
                            "available": 0,
                            "refundable": 0
                        },
                        "relationships": [],
                        "mobileWallet": "https://sb.uk.mypass.is/a/4306837533/5de1140b9f1cd66"
                    },
                    {
                        "accountId": "4306837534",
                        "walletId": "219153391",
                        "campaignId": "101042204",
                        "type": "ECOUPON",
                        "clientType": "OFFER",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-05-17T13:51:37+00:00",
                            "end": "2026-03-01T23:59:00+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-05-17T13:51:37+00:00",
                        "lastUpdated": "2025-05-17T13:51:37+00:00",
                        "overrides": [],
                        "balances": {
                            "available": 0,
                            "refundable": 0
                        },
                        "relationships": [],
                        "mobileWallet": "https://sb.uk.mypass.is/a/4306837534/271748c57494ad5"
                    }
                ]
            },
            "failed": {
                "total": 0,
                "results": []
            }
        },
        "scheme": {
            "successful": {
                "results": [
                    {
                        "accountId": "4306837535",
                        "walletId": "219153391",
                        "campaignId": "100910378",
                        "type": "POINTS",
                        "clientType": "RETAILPOINTS",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-05-17T13:51:37+00:00",
                            "end": "2038-01-19T03:14:07+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-05-17T13:51:37+00:00",
                        "lastUpdated": "2025-05-17T13:51:37+00:00",
                        "overrides": [],
                        "balances": {
                            "current": 0,
                            "usable": 0,
                            "locked": 0,
                            "lifetime": 0,
                            "lifetimeSpend": 0,
                            "lifetimeSpendValue": 0,
                            "pending": 0
                        },
                        "relationships": [],
                        "mobileWallet": "https://sb.uk.mypass.is/a/4306837535/a0a5ae5e3057569"
                    }
                ],
                "total": 1
            },
            "failed": {
                "results": [],
                "total": 0
            },
            "total": 1,
            "results": [
                {
                    "accountId": "4306837535",
                    "walletId": "219153391",
                    "campaignId": "100910378",
                    "type": "POINTS",
                    "clientType": "RETAILPOINTS",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-05-17T13:51:37+00:00",
                        "end": "2038-01-19T03:14:07+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-05-17T13:51:37+00:00",
                    "lastUpdated": "2025-05-17T13:51:37+00:00",
                    "overrides": [],
                    "balances": {
                        "current": 0,
                        "usable": 0,
                        "locked": 0,
                        "lifetime": 0,
                        "lifetimeSpend": 0,
                        "lifetimeSpendValue": 0,
                        "pending": 0
                    },
                    "relationships": [],
                    "mobileWallet": "https://sb.uk.mypass.is/a/4306837535/a0a5ae5e3057569"
                }
            ]
        }
    },
    "consumer": {
        "consumerId": "48493887",
        "walletId": "219153391",
        "friendlyName": "Sample Consumer Wallet",
        "type": "INDIVIDUAL",
        "state": "DEFAULT",
        "status": "ACTIVE",
        "data": [],
        "meta": {
            "meta1": "Sample meta value 1",
            "meta2": "Sample meta value 2"
        },
        "dateCreated": "2025-05-17T13:51:37+00:00",
        "lastUpdated": "2025-05-17T13:51:37+00:00"
    }
}

A custom event is received in mParticle

User is created in mParticle

Note: if the user already exists in mParticle from other source systems, then mParticle will automatically enhance an existing user profile instead of creating a new one as long as the user ID matches.

mParticle triggers an inbound call to issue reward in AIR

Upon receipt of custom event ee_loyalty_program_joined event from AIR, the user was added to a webhook variant campaign which invoked an API call to EE Connect to issue 5000 welcome bonus points via the Social Behavioural Actions using a specific Action Reference in AIR.

Social Behavioural Action triggered in AIR

Points awarded in AIR

Outbound Trigger event is sent from AIR to mParticle

User's points balance increases in mParticle

Technical Information

The code for Eagle Eye Foundation Connector is written in TypeScript and is open sourced in GIT here.

Technical documentation can be found in GIT here.

📘

GIT Access

We are in the process of open sourcing the code in GIT. The above links will become available for use very shortly.