Overview

Braze is a Marketing Automation Platform that allows marketers to create personalized, real-time marketing campaigns and engage with customers across various digital touch points such as email, SMS, mobile apps, and web. The platform offers features such as customer journey orchestration, cross-channel messaging, real-time data activation, and AI-driven optimizations to help brands build stronger relationships with their customers. Visit the Braze 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 Braze client interested in using Eagle Eye AIR?

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

Configuration

Braze Connection Setup

Create App For receiving events from AIR

1. Go to Settings --> App Settings --> Add App:
2. Give it a name
3. Select Web from the dropdown list
4. Click Add App
5. Copy API key and SDK Endpoint that are generated and share with Eagle Eye for Connector Configuration. These will be the restAPIKey and restEndpoint for EE Connector setup respectively.

Create API Key

1. Go to Settings --> APIs and Identifiers --> API Keys tab

2. Click Create API Key

3. Give it a name

4. Select permissions as follows

   

5. Click Create API Key to save

6. Once created, hit the copy button to save the identifier generated and share with Eagle Eye for connector configuration. This will be the brazeAppId for EE connector setup.

AIR Connection Setup

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 Braze.
• 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 Braze:

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

Outbound Connector

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

• 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.
• brazeAppId - Can be created in Braze under Settings --> APIs and Identifiers --> API Keys
• restAPIKey - Found in Braze under Settings --> App Settings
• restEndpoint - URL for your instance of Braze; region can be confirmed under Settings --> App Settings --> SDK Endpoint however, the full URL including https should be used from Braze.
• currency - 3 character alphanumeric currency for e.g. USD
• identityType - an identifier for looking up the consumer in both AIR and Braze 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 Social and Behavioural Action rewards in AIR.

Braze Campaign Setup

Webhook Variant Campaigns

This will trigger an API call to EE Connect to issue rewards in AIR

Campaigns can be set up in Braze to trigger an API call to EE Connect to issue rewards in AIR. 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

In this example points are issued to a consumer for joining the loyalty program.

Email Variant Campaigns

This example uses Email Variant Campaigns to trigger an an email to the consumer when a custom EE event is received in Braze. Email body can be enhanced by inserting attributes from the custom event to make the message more relevant. Attributes within the custom event can also be used as added criteria for when the email should be sent.

Example: Email based on order fulfilment event from AIR

In this example when an order is placed online and fulfillment of items has begun, an email is sent to a consumer based on Braze receiving the EE Fulfil event.

Note: that additional conditions are added in this example to ensure this message is only sent when it's not the initial or final fulfil event for a given order.

Example: Email based on reward issued in AIR

In this example a campaign is set up to listen to ee_service_trigger event from AIR when a Social Behavioural Action reward is issued for a specific trigger so that a custom message sent to a consumer every time rewards are issued for the chosen trigger.

📘

Campaign ID

Social Behavioural Actions in AIR have unique IDs that are campaign Ids in the back end. This can be used in Braze for campaign Id field to customize messages to a consumer for each trigger.

Custom properties from EE AIR events can be inserted within the email message by using {{event_properties.${ee_attribute}}} where ee_attribute would be the property name within a desired custom event. Refer to the data model for a full list of supported property names.

Usage

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

Braze Data Model

User Profiles

The following custom attributes shall be stored within the user profile:

Example

{
  "ee_loyalty": {
    "points": {
      "current": 123,
    },
    "tier": {
      "tierId": "178",
      "balances": {
        "points": 0,
        "spend": 0,
        "transactions": 0
      }
    },
    "coupons": [{
      "accountId": "123",
      "campaignId": "345",
      "type": "ECOUPON",
      "clientType": "OFFER",
      "status": "USED",
      "dates": {
        "start": "2025-01-01T00:00:00Z",
        "end": "2026-01-01T00:00:00Z"
      }
    }, {
      "accountId": "124",
      "campaignId": "346",
      "type": "ECOUPON",
      "clientType": "ENTITLEMENT",
      "status": "ACTIVE",
      "dates": {
        "start": "2025-01-01T00:00:00Z",
        "end": "2026-01-01T00:00:00Z"
      }
    }],
    "subscriptions": [{
      "accountId": "125",
      "campaignId": "347",
      "status": "ACTIVE",
      "dates": {
        "start": "2025-01-01T00:00:00Z",
        "end": "2026-01-01T00:00:00Z"
      }
    }]
  }
}

Custom Events

The following custom events shall be sent to Braze where relevant:

ee_loyalty_program_joined

Sent to Braze on receipt of SERVICE.WALLET.ACCOUNTS.CREATE or SERVICE.WALLET.CREATE.

Custom Properties

None

ee_loyalty_program_left

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

Custom Properties

None

ee_loyalty_tier_membership_create

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

Custom Properties

ee_loyalty_tier_membership_credit

Custom Properties

ee_loyalty_tier_membership_debit

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

ee_loyalty_tier_membership_move

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

ee_posconnect_wallet_fulfil

Sent to Braze on receipt of POSCONNECT.WALLET.FULFIL.

Custom Properties

⚠️ For “middle” fulfil transactions neither initial nor final will be present.

ee_posconnect_wallet_return

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

Custom Properties

ee_posconnect_wallet_settle

Sent to Braze on receipt of POSCONNECT.WALLET.SETTLE.

Custom Properties

ee_posconnect_wallet_spend

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

Custom Properties

ee_posconnect_wallet_spend_void

Sent to Braze on receipt of POSCONNECT.WALLET.SPEND_VOID.

Custom Properties

ee_service_trigger

Sent to Braze on receipt of SERVICE.TRIGGER.

Custom Properties

ee_subscription_cancelled

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

Custom Properties

ee_subscription_joined

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

Custom Properties

ee_wallet_account_create_campaign

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

Custom Properties

ee_wallet_account_create_scheme

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

Custom Properties

None

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_A16a"
        },
        {
            "state": "EARNBURN",
            "status": "ACTIVE",
            "type": "CARD",
            "value": "2222222222222222_A16a"
        },
        {
            "state": "EARNBURN",
            "status": "ACTIVE",
            "type": "MOBILE",
            "value": "+1(416)-111-1111_Apr16a"
        }
    ],
    "accounts": {
        "campaign": [
            {
                "campaignTag": "initialoffer",
                "state": "LOADED"
            }
        ],
        "scheme": [
            {
                "status": "ACTIVE",
                "schemeId": {{schemeId}},
                "state": "LOADED"
            }
        ]
    }
}

{
    "walletId": "218457111",
    "friendlyName": null,
    "status": "ACTIVE",
    "type": "CONSUMER",
    "state": "DEFAULT",
    "meta": [],
    "dateCreated": "2025-04-16T18:33:41+00:00",
    "lastUpdated": "2025-04-16T18:33:41+00:00",
    "relationships": {
        "parent": [],
        "child": [],
        "associate": [],
        "donor": []
    },
    "identities": [
        {
            "identityId": "189701604",
            "walletId": "218457111",
            "type": "CUSTOMER_ID",
            "friendlyName": null,
            "value": "1111111111111111_A16a",
            "safeValue": null,
            "secret": null,
            "dates": {
                "start": "2025-04-16T18:33:41+00:00",
                "end": null
            },
            "meta": [],
            "state": "EARNBURN",
            "status": "ACTIVE",
            "dateCreated": "2025-04-16T18:33:41+00:00",
            "lastUpdated": "2025-04-16T18:33:41+00:00",
            "mobileWallet": "https://sb.uk.mypass.is/identity/202316/218457111/189701604/f3785e7b49450351494b9f01cffc699d5902159dfa02366a1a29bb71a3ead98d"
        },
        {
            "identityId": "189701605",
            "walletId": "218457111",
            "type": "CARD",
            "friendlyName": null,
            "value": "2222222222222222_A16a",
            "safeValue": null,
            "secret": null,
            "dates": {
                "start": "2025-04-16T18:33:41+00:00",
                "end": null
            },
            "meta": [],
            "state": "EARNBURN",
            "status": "ACTIVE",
            "dateCreated": "2025-04-16T18:33:41+00:00",
            "lastUpdated": "2025-04-16T18:33:41+00:00",
            "mobileWallet": "https://sb.uk.mypass.is/identity/202316/218457111/189701605/7cf188b0aa70456cb07f7aa636fc426688abc38f6cc65c7f89cd75bcf0a992df"
        },
        {
            "identityId": "189701606",
            "walletId": "218457111",
            "type": "MOBILE",
            "friendlyName": null,
            "value": "+1(416)-111-1111_Apr16a",
            "safeValue": null,
            "secret": null,
            "dates": {
                "start": "2025-04-16T18:33:41+00:00",
                "end": null
            },
            "meta": [],
            "state": "EARNBURN",
            "status": "ACTIVE",
            "dateCreated": "2025-04-16T18:33:41+00:00",
            "lastUpdated": "2025-04-16T18:33:41+00:00",
            "mobileWallet": "https://sb.uk.mypass.is/identity/202316/218457111/189701606/4004836c24c24317e3abb1d62c80582156090be05ae6c013cd03495467690814"
        }
    ],
    "accounts": {
        "campaign": {
            "total": 3,
            "results": [
                {
                    "accountId": "4223205212",
                    "walletId": "218457111",
                    "campaignId": "100914505",
                    "type": "ECOUPON",
                    "clientType": "OFFER",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-04-16T18:33:41+00:00",
                        "end": "2026-12-31T23:59:00+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-04-16T18:33:41+00:00",
                    "lastUpdated": "2025-04-16T18:33:41+00:00",
                    "overrides": [],
                    "balances": {
                        "available": 0,
                        "refundable": 0
                    },
                    "relationships": [],
                    "mobileWallet": "https://sb.uk.mypass.is/a/4223205212/318e675c0b34454"
                },
                {
                    "accountId": "4223205213",
                    "walletId": "218457111",
                    "campaignId": "100914507",
                    "type": "ECOUPON",
                    "clientType": "OFFER",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-04-16T18:33:41+00:00",
                        "end": "2026-12-31T23:59:00+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-04-16T18:33:41+00:00",
                    "lastUpdated": "2025-04-16T18:33:41+00:00",
                    "overrides": [],
                    "balances": {
                        "available": 0,
                        "refundable": 0
                    },
                    "relationships": [],
                    "mobileWallet": "https://sb.uk.mypass.is/a/4223205213/785513349940213"
                },
                {
                    "accountId": "4223205214",
                    "walletId": "218457111",
                    "campaignId": "100970330",
                    "type": "ECOUPON",
                    "clientType": "OFFER",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-04-16T18:33:41+00:00",
                        "end": "2026-12-31T23:59:00+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-04-16T18:33:41+00:00",
                    "lastUpdated": "2025-04-16T18:33:41+00:00",
                    "overrides": [],
                    "balances": {
                        "available": 0,
                        "refundable": 0
                    },
                    "relationships": [],
                    "mobileWallet": "https://sb.uk.mypass.is/a/4223205214/f7aaa09092dd828"
                }
            ],
            "successful": {
                "total": 3,
                "results": [
                    {
                        "accountId": "4223205212",
                        "walletId": "218457111",
                        "campaignId": "100914505",
                        "type": "ECOUPON",
                        "clientType": "OFFER",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-04-16T18:33:41+00:00",
                            "end": "2026-12-31T23:59:00+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-04-16T18:33:41+00:00",
                        "lastUpdated": "2025-04-16T18:33:41+00:00",
                        "overrides": [],
                        "balances": {
                            "available": 0,
                            "refundable": 0
                        },
                        "relationships": [],
                        "mobileWallet": "https://sb.uk.mypass.is/a/4223205212/318e675c0b34454"
                    },
                    {
                        "accountId": "4223205213",
                        "walletId": "218457111",
                        "campaignId": "100914507",
                        "type": "ECOUPON",
                        "clientType": "OFFER",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-04-16T18:33:41+00:00",
                            "end": "2026-12-31T23:59:00+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-04-16T18:33:41+00:00",
                        "lastUpdated": "2025-04-16T18:33:41+00:00",
                        "overrides": [],
                        "balances": {
                            "available": 0,
                            "refundable": 0
                        },
                        "relationships": [],
                        "mobileWallet": "https://sb.uk.mypass.is/a/4223205213/785513349940213"
                    },
                    {
                        "accountId": "4223205214",
                        "walletId": "218457111",
                        "campaignId": "100970330",
                        "type": "ECOUPON",
                        "clientType": "OFFER",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-04-16T18:33:41+00:00",
                            "end": "2026-12-31T23:59:00+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-04-16T18:33:41+00:00",
                        "lastUpdated": "2025-04-16T18:33:41+00:00",
                        "overrides": [],
                        "balances": {
                            "available": 0,
                            "refundable": 0
                        },
                        "relationships": [],
                        "mobileWallet": "https://sb.uk.mypass.is/a/4223205214/f7aaa09092dd828"
                    }
                ]
            },
            "failed": {
                "total": 0,
                "results": []
            }
        },
        "scheme": {
            "successful": {
                "results": [
                    {
                        "accountId": "4223205215",
                        "walletId": "218457111",
                        "campaignId": "100910376",
                        "type": "POINTS",
                        "clientType": "RETAILPOINTS",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-04-16T18:33:41+00:00",
                            "end": "2038-01-19T03:14:07+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-04-16T18:33:41+00:00",
                        "lastUpdated": "2025-04-16T18:33:41+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/4223205215/5a2be76f7eb469f"
                    }
                ],
                "total": 1
            },
            "failed": {
                "results": [],
                "total": 0
            },
            "total": 1,
            "results": [
                {
                    "accountId": "4223205215",
                    "walletId": "218457111",
                    "campaignId": "100910376",
                    "type": "POINTS",
                    "clientType": "RETAILPOINTS",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-04-16T18:33:41+00:00",
                        "end": "2038-01-19T03:14:07+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-04-16T18:33:41+00:00",
                    "lastUpdated": "2025-04-16T18:33:41+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/4223205215/5a2be76f7eb469f"
                }
            ]
        }
    },
    "consumer": {
        "consumerId": "48335452",
        "walletId": "218457111",
        "friendlyName": "Sample Consumer Wallet",
        "type": "INDIVIDUAL",
        "state": "DEFAULT",
        "status": "ACTIVE",
        "data": [],
        "meta": {
            "meta1": "Sample meta value 1",
            "meta2": "Sample meta value 2"
        },
        "dateCreated": "2025-04-16T18:33:41+00:00",
        "lastUpdated": "2025-04-16T18:33:41+00:00"
    }
}

User is created in Braze

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

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

User's points balance increases in Braze

Braze triggers an email to the user

Upon receipt of the custom event ee_service_trigger, the email variant campaign was invoked and the user received a congratulatory email with information about the 5000 welcome bonus points.

Technical Information

Deployment Guide

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

Build

Prerequisites

The Braze Connector (integration-braze) depends on the integration-events-common package. integration-events-common is not yet published to npm, so a package tarball must be acquired to allow the dependency to be installed. Instructions for this can be found here: <https://github.com/Eagle-Eye-Solutions/integration-events-common?tab=readme-ov-file#building-the-package>

Creating the container image

Instructions for creating the Braze Connector container image can be found here: <https://github.com/Eagle-Eye-Solutions/integration-braze?tab=readme-ov-file#usage>

Deployment

The Braze Connector should be deployed to GCP Cloud Run. A sample deployment script (using gcloud CLI) is available here:

<https://github.com/Eagle-Eye-Solutions/integration-braze/blob/master/docs/deploy.sh.example>

Additional details can be found in the accompanying document:

<https://github.com/Eagle-Eye-Solutions/integration-braze/blob/master/docs/deployment.md>

Braze Data Mapping

Within integration-braze, after an outbound event is received from AIR and it passes a minimum amount of validation (does it contain request, atomic operations, enrichment data…) the next step is to go through a mapper, before it gets resent into the queue as an event inbound for Braze.

For this purpose, two mappers are available: a flexible-mapper, which right now is just used to set Braze user identifiers from AIR identity values; and the ee-braze-mapper, used to set all of the other request properties for Braze.

The main properties sent to Braze and how they’re handled are the following:

• User attributes: information stored in the user’s profile, including any identifiers and custom properties set by other systems.
  • At least one identifier must be provided, either the ID generated by Braze or one of the profile’s identifiers (external_id, email, …).
  • Only one identity will be taken from the enrichment data’s wallet and set to the proper attribute based on the flexible mapper’s configuration.
  • Any other EE related custom properties are stored in a ee_loyalty object, which includes things like coupons or points.
  • This is handled initally by mapAirOutboundEventToUserAttributes, which then sets this properties based on the outbound event (not all events have the same data available to be added/updated in the profile), mostly using local functions and sometimes by external functions like getAtomicOperationCustomAttributes.
• Custom events: these are event objects very similar to stock/expected Braze events, but they have custom names and properties to suit your needs.
  • Base properties like the inbound event name, timestamp and the user identifier can be extracted from the outbound event. Others like app_id, which is generated when the API key is created in Braze, so it needs to be provided through the Config API.
  • Custom properties vary between events, but pretty much all of them come from the outbound event (currently there’s just once exception, for events based on voided spend transactions). These are mapped initially from mapAirOutboundEventToBrazeCustomEvent and are handled either by getAtomicOperationCustomEvents or by local functions, depending on the event.
  • An exception is the inbound event for Coupon Redeemed, there’s no specific outbound event for it so its custom event is generated from atomic operations.
• Orders or product purchases: object describing individual products/SKUs that where purchased or orders placed. These can be tracked separate from custom events to get metrics like lifetime revenue from a given user.
  • We currently generate these from Settle and Fulfil outbound events.
  • In our case we’ve taken the “order level” approach, setting product_id from the Settle/Fulfil reference and a products property containing the same information we’d place for the Settle/Fulfil custom events.
  • Couple of important points: prices must be set as money and a currency must be set. AIR is currency agnostic so as general rules: we assume (and divide) all values by two fraction digits and take the currency from the Config API.
  • For fulfil: only middle/final fulfil transactions are tracked as purchases. Tracking initial would lead to duplicate revenue from the user and wrong total spend from the order. Custom events do include this data for all scenarios so they can be used for communications if needed.
  • These objects are generated in mapAirOutboundEventToBrazePurchases and the specifics are handled by conditions in getAtomicOperationPurchases.
• Braze partner name/string: a string required for requests made by Braze partners, for tracking/debugging/analytics purposes. Currently set from an environment variable at deployment time.
  • The User-Agent header also gets a similar custom user agent, currently partner-eagleeye/<version from package.json>.

For more information on which data is set as user attributes/custom event properties, see: Braze Data Model