Overview

Segment is a Customer Data Platform (CDP) that allows businesses to collect, unify, and route their customer data to different platforms for marketing, analytics, and other purposes. It gathers data from various touchpoints, such as websites, mobile apps, and servers, and centralizes it into a single location. This centralized data can then be sent downstream to other tools and services in the client's marketing and operational stack.

The platform supports event tracking, user identification, and user traits, making it easier for businesses to build a comprehensive view of their customers' interactions and behaviours. Visit the Segment 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 Segment 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 for setup of various components in Segment and AIR.

Segment Source Connection Setup

This is a one time setup for outbound events from AIR to Segment

1. Under Connections --> Sources --> Click Add Source

2. Under Categories --> Server --> click HTTP API

3. Click Add Source

4. Give it a meaningful name and click Add Source

📘

Write Key

The above will produce a unique Write Key value that you can copy and provide to Eagle Eye to set up your outbound connector to Segment

AIR Connection Setup

This is a one time setup for inbound and outbound flow of data between AIR and Segment

📘

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

• Auth token - The client to come up with a secret key a.k.a. Auth token for the inbound connector from Segment to AIR.  This value can be any string for e.g. ILoveEagleEyeInboundKey111, however the following special characters should be avoided: &, #, ?. This key is used for authentication and is passed within the header for inbound API requests from Segment to to AIR by EE connect.

📘

Inbound Connector URL

Once connector setup in AIR is complete, Eagle Eye to provide a Segment inbound connector URL with a unique connector ID that will be required for setting up a destination in Segment

Outbound Connector

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

• Auth token - The client to come up with a secret key a.k.a. Auth token for the outbound connector from AIR to Segment.  This value can be any string for e.g. ILoveEagleEyeOutboundKey222, however the following special characters should be avoided: &, #, ?. This key is used for authentication and is passed within the header for outbound API requests from AIR to Segment by EE connect.
• writeKey - Found in Segment Dashboard under Connections --> Sources --> a source for EE AIR --> settings --> API keys
• currency - 3 character alphanumeric currency for e.g. USD
• identityType - an identifier for looking up the consumer in both AIR and Segment for e.g. CARD

Segment Destination Connection Setup

Once connectors are configured within AIR you can go ahead and set up an Engage destination in Segment.

📘

Destination from Engage Space

Ensure the destination to be created in Segment is via the Engage space. This is because Audiences in Segment reside within Engage and it is via an Audience that rewards in AIR can be issued

1. Go to Engage --> Engage settings --> Click Add destination within your selected Segment space

2. Search for Eagle Eye destination and select it

3. Click Add destination

4. Verify that the correct Engage space is selected and then click Confirm Source

5. Enter in the Inbound Connector URL and Auth Token (External Key) configured in AIR, give the destination a meaningful name for e.g. "AIR UAT Destination", enable the destination and save changes

6. Refresh the page and go back into the destination you just created under Connections --> Destinations --> Click your new destination
7. Click the Mappings tab and click New Mappings

8. Select Trigger Behavioural Action

9. Scroll down to the Map Fields section and enter a desired wallet transaction reference and click Save

📘

Wallet Transaction Reference

It is recommended to use Segment's messageId which will be unique for each message generated by Segment to air. Text fields can be added as prefix or suffix to make the wallet transaction more meaningful and easy to recognize in AIR amongst wallet transactions from other sources.

Do not change the User Identity Value and Behavioural Action Trigger Reference fields as these will be automatically populated for a user within an audience.

10. Enable the mapping you just created

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 rewards in AIR via Social and Behavioural Actions.

Segment Audience Setup

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

Once you have set up Social Behavioural Action Triggers in AIR, you can now configure Segment to tigger a reward in AIR.

1. Ensure you are in the correct Engage Space
2. Go to Engage --> Audiences --> Click New Audience

3. Select Profiles audience --> click Next

4. Select criteria for your audience where all users who Performed an Event

5. Select a custom AIR event from the dropdown list and add any additional properties and filtering as desired. Refer to the Events section within the Data Model for a full list of supported events out of AIR

6. Select the AIR destination you set up earlier

7. Plug in your Social Behavioural Action Trigger reference from AIR, enable track, disable Identity, select Default Setup and click Save

📘

Identity vs Track

Only enable Track events for sending an API call to AIR. Select Identity and Track will issue two triggers to AIR and result in undesirable behaviour.

8. Click Next
9. Give in a meaningful Audience name for e.g. "New Loyalty Joiner" and click Create Audience
10. Now you are ready to start making API calls from AIR and confirm rewards being issued in AIR when audience criteria is met!

Data Model

Traits

Traits are attributes that are stored within a user profile in Segment. The following table details the traits that are populated and maintained by the Segment integration.

Multi-scheme POINTS accounts

• Identify calls include loyalty_points_accounts in traits whenever the connector sends POINTS snapshot data (full profile).
  • Track calls for purchases, refunds, spend, programme join, scheme create, service trigger, and similar do not put loyalty_points_accounts on the primary business event’s properties or context.traits.
    • When snapshots exist, the connector also sends a dedicated track EE Loyalty Points Accounts Updated with properties.loyalty_points_accounts (see below).

Events

The table below shows the mapping of Eagle Eye AIR events to Segment Events. Where the inbound AIR event includes POINTS wallet account snapshots, the integration may emit EE Loyalty Points Accounts Updated in the same batch as the mapped event(s), in addition to any identify that updates traits.

EE Loyalty Points Accounts Updated

Emitted when the inbound AIR event includes POINTS wallet account snapshot rows. Use this event (or identify traits) for multi-scheme balances; primary commerce or loyalty track payloads do not duplicate this array.

Properties

The connector sends context.traits as an empty object on this track (multi-scheme data lives in properties.loyalty_points_accounts and on identify).

EE Loyalty Program Joined

Traits (identify / profile)

These fields are sent on identify when the connector updates the Segment profile. loyalty_points_accounts appears here when POINTS snapshots exist; it is not repeated on the EE Loyalty Program Joined track’s properties or context.traits when EE Loyalty Points Accounts Updated is emitted for the same AIR event.

Properties

The EE Loyalty Program Joined track may include context.traits with loyalty_member, points, and tier fields aligned to the identify call; it does not include loyalty_points_accounts on that track when the dedicated EE Loyalty Points Accounts Updated event is also sent.

EE Loyalty Tier Membership Created

Properties

EE Loyalty Tier Membership Moved

Payload identical to EE Loyalty Tier Membership Created

EE Loyalty Tier Membership Credited

Payload identical to EE Loyalty Tier Membership Created

EE Loyalty Tier Membership Debited

Payload identical to EE Loyalty Tier Membership Created

EE Loyalty Tier Membership Adjusted

Payload identical to EE Loyalty Tier Membership Created

EE Loyalty Coupon Redeemed

Properties

EE Loyalty Purchase

EE Loyalty Order Fulfilment Initiated

EE Loyalty Order Fulfilment In Progress

EE Loyalty Order Fulfilment Completed

EE Loyalty Purchase Refunded

EE Loyalty Points Spent

EE Loyalty Points Spend Voided

EE Loyalty Subscription Joined

EE Loyalty Subscription Cancelled

EE Loyalty Reward Triggered

The context.traits on this track carry points and tier fields from the connector but not loyalty_points_accounts; multi-scheme balances use identify and EE Loyalty Points Accounts Updated when snapshots exist.

EE Loyalty Scheme Account Created

This track has no event properties. Multi-scheme POINTS snapshots are delivered via identify traits (loyalty_points_accounts) and, when present, EE Loyalty Points Accounts Updated; the scheme-created track carries only context.traits for legacy points/tier fields (not loyalty_points_accounts on that track).

EE Loyalty Campaign Account Created

Per-account POINTS balances are not on this track’s properties or context.traits when EE Loyalty Points Accounts Updated is emitted for the same payload.

EE Loyalty Continuity Account Created

EE Loyalty Quest Account Created

EE Loyalty Stamp Card Account Created

EE Loyalty Continuity Account Progressed

EE Loyalty Continuity Account Redeemed

EE Loyalty Quest Objective Redeemed

EE Loyalty Quest Account Redeemed

EE Loyalty Stamp Card Progressed

EE Loyalty Stamp Card Redeemed

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_July14c"
        }
    ],
    "accounts": {
        "campaign": [
            {
                "campaignTag": "frequencydriver",
                "state": "LOADED"
            }
        ],
        "scheme": [
            {
                "status": "ACTIVE",
                "schemeId": {{schemeId}},
                "state": "LOADED"
            }
        ]
    }
}

{
    "walletId": "242563299",
    "friendlyName": null,
    "status": "ACTIVE",
    "type": "CONSUMER",
    "state": "DEFAULT",
    "meta": [],
    "dateCreated": "2025-07-14T16:50:54+00:00",
    "lastUpdated": "2025-07-14T16:50:54+00:00",
    "relationships": {
        "parent": [],
        "child": [],
        "associate": [],
        "donor": []
    },
    "identities": [
        {
            "identityId": "194682251",
            "walletId": "242563299",
            "type": "CUSTOMER_ID",
            "friendlyName": null,
            "value": "1111111111111111_July14c",
            "safeValue": null,
            "secret": null,
            "dates": {
                "start": "2025-07-14T16:50:54+00:00",
                "end": null
            },
            "meta": [],
            "state": "EARNBURN",
            "status": "ACTIVE",
            "dateCreated": "2025-07-14T16:50:54+00:00",
            "lastUpdated": "2025-07-14T16:50:54+00:00",
            "mobileWallet": "https://sb.uk.mypass.is/identity/177556/242563299/194682251/a65deb82bef2644fb7f3d634f5794b53b4288fbd2127788279272a7967480166"
        }
    ],
    "accounts": {
        "campaign": {
            "total": 1,
            "results": [
                {
                    "errorCode": "NF",
                    "errorMessage": "Campaign not found"
                }
            ],
            "successful": {
                "total": 0,
                "results": []
            },
            "failed": {
                "total": 1,
                "results": [
                    {
                        "errorCode": "NF",
                        "errorMessage": "Campaign not found"
                    }
                ]
            }
        },
        "scheme": {
            "successful": {
                "results": [
                    {
                        "accountId": "4475151659",
                        "walletId": "242563299",
                        "campaignId": "100380258",
                        "type": "POINTS",
                        "clientType": "RETAILPOINTS",
                        "status": "ACTIVE",
                        "state": "LOADED",
                        "dates": {
                            "start": "2025-07-14T16:50:54+00:00",
                            "end": "2038-01-19T03:14:07+00:00"
                        },
                        "meta": [],
                        "dateCreated": "2025-07-14T16:50:54+00:00",
                        "lastUpdated": "2025-07-14T16:50:54+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/4475151659/ddab549dd761cc7"
                    }
                ],
                "total": 1
            },
            "failed": {
                "results": [],
                "total": 0
            },
            "total": 1,
            "results": [
                {
                    "accountId": "4475151659",
                    "walletId": "242563299",
                    "campaignId": "100380258",
                    "type": "POINTS",
                    "clientType": "RETAILPOINTS",
                    "status": "ACTIVE",
                    "state": "LOADED",
                    "dates": {
                        "start": "2025-07-14T16:50:54+00:00",
                        "end": "2038-01-19T03:14:07+00:00"
                    },
                    "meta": [],
                    "dateCreated": "2025-07-14T16:50:54+00:00",
                    "lastUpdated": "2025-07-14T16:50:54+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/4475151659/ddab549dd761cc7"
                }
            ]
        }
    },
    "consumer": {
        "consumerId": "49880404",
        "walletId": "242563299",
        "friendlyName": "Sample Consumer Wallet",
        "type": "INDIVIDUAL",
        "state": "DEFAULT",
        "status": "ACTIVE",
        "data": [],
        "meta": {
            "meta1": "Sample meta value 1",
            "meta2": "Sample meta value 2"
        },
        "dateCreated": "2025-07-14T16:50:54+00:00",
        "lastUpdated": "2025-07-14T16:50:54+00:00"
    }
}

User is created in Segment within the specified Audience

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

{
  "external_ids": [
    {
      "collection": "USERS",
      "type": "user_id",
      "id": "1111111111111111_July14c",
      "encoding": "none"
    }
  ],
  "context": {
    "library": {
      "name": "@segment/analytics-node",
      "version": "2.2.1"
    },
    "traits": {
      "loyalty_member": true,
      "points_balance": 0,
      "tier_balances_points": 0,
      "tier_balances_reset_date": "2025-07-14T23:59:59.000Z",
      "tier_balances_spend": 0,
      "tier_balances_transactions": 0,
      "tier_id": "97"
    }
  },
  "type": "track",
  "source_id": "aFnwKkyEJYYC3tgzVgrZrc",
  "message_id": "006f3f25-b34a-4ab2-8c7b-3fd5cd93b50f-2",
  "timestamp": "2025-07-14T16:50:55.013Z",
  "received_at": "2025-07-14T16:50:58.606Z",
  "sent_at": "2025-07-14T16:50:58.261Z",
  "properties": {
    "tier_balances_spend": 0,
    "coupons": [],
    "tier_balances_transactions": 0,
    "points_balance": 0,
    "tier_balances_points": 0,
    "tier_id": "97",
    "tier_balances_reset_date": "2025-07-14T23:59:59.000Z"
  },
  "event": "EE Loyalty Program Joined",
  "related": {
    "USERS": [
      "use_XzYyCeqY8ZczslGAtym2zsFR3jb"
    ]
  },
  "metadata": {
    "jsRuntime": "node",
    "nodeVersion": "v22.16.0"
  }
}

Segment triggers an inbound call to issue reward in AIR

Upon receipt of custom event ee_loyalty_program_joined event from AIR, Segment destination to EE Connect issues a welcome coupon via Social Behavioural Actions using a specific Action Reference in AIR.

Social Behavioural Action triggered in AIR

Coupon issued in AIR

Outbound Trigger event is sent from AIR to Segment

Once the reward is issued an event is reflected back into the user profile

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.