From 2d26e279d83efcf57c8c900e48eaea67bd1ca12f Mon Sep 17 00:00:00 2001 From: pwseg Date: Wed, 5 Mar 2025 17:58:45 -0600 Subject: [PATCH 01/15] init --- src/engage/event-mapping-configuration.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 src/engage/event-mapping-configuration.md diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md new file mode 100644 index 0000000000..182593aa8e --- /dev/null +++ b/src/engage/event-mapping-configuration.md @@ -0,0 +1,5 @@ +--- +title: Engage Event Mapping +plan: engage-foundations +--- + From 7d43769fe6d78a338e9a1407d6360a85c5a36dc4 Mon Sep 17 00:00:00 2001 From: pwseg Date: Wed, 5 Mar 2025 21:11:19 -0600 Subject: [PATCH 02/15] overview section --- src/engage/event-mapping-configuration.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index 182593aa8e..0018baf12b 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -3,3 +3,17 @@ title: Engage Event Mapping plan: engage-foundations --- +This guide helps you configure mappings for Engage events in Actions Destinations. + + +## Overview + +Engage Mappings let you transform and send user data to downstream destinations. When Engage events get sent to destinations, they may need to be formatted or adjusted to match the destination’s expected data structure. Without mapping, critical user information like audience membership or enriched traits may not sync correctly. + +This guide explains how to configure mappings for Engage events in Actions Destinations, including: + +- The differences between Identify and Track events. +- How to extract and map data from Engage event payloads. +- A step-by-step walkthrough of mapping configurations. +- Advanced features like Trait Enrichment to pass additional profile data. + From d777a989f3e1ab2e0d17373ca5937b0dad5c1b06 Mon Sep 17 00:00:00 2001 From: pwseg Date: Wed, 5 Mar 2025 21:22:57 -0600 Subject: [PATCH 03/15] add Identify section --- src/engage/event-mapping-configuration.md | 37 ++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index 0018baf12b..ad8431be95 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -12,8 +12,43 @@ Engage Mappings let you transform and send user data to downstream destinations. This guide explains how to configure mappings for Engage events in Actions Destinations, including: -- The differences between Identify and Track events. +- The differences between [Identify](/docs/connections/spec/identify/) and [Track](/docs/connections/spec/track/) events. - How to extract and map data from Engage event payloads. - A step-by-step walkthrough of mapping configurations. - Advanced features like Trait Enrichment to pass additional profile data. +## What are Engage events? + +Engage events let you sync audience membership data to your destinations. When a user enters or exits an audience in Engage, Segment generates events that you can use to trigger actions in your connected tools. + +Engage generates Identify and Track events. These events carry critical information including: + +- User identifiers (like `userId` and `anonymousId`) +- Audience membership status +- Other user traits if you've enabled enrichment + +Each event type has a specific structure that determines how you configure your mappings. + +### Identify events: updating user traits + +Identify events are mostly used to update user profiles in external systems, like a CRM or marketing automation platform. Identify events send all user details in the `traits` object. The audience key appears in the object as a boolean that indicates whether the user is in the audience (`true`) or not (`false`), like in this example Identify payload: + +```json +{ + "anonymousId": "anon-test-1", + "traits": { + "email": "user-testing-1@gmail.com", + "your_audience_key": true + }, + "type": "identify", + "userId": "user-testing-1" +} +``` + +Since Identify events are designed to update profile data, they are commonly mapped to destinations that rely on persistent user records, such as customer databases, email platforms, and loyalty systems. + + + + + + From dcc669027f136b9f221272edd28a161d79387177 Mon Sep 17 00:00:00 2001 From: pwseg Date: Wed, 5 Mar 2025 21:28:47 -0600 Subject: [PATCH 04/15] more Track info --- src/engage/event-mapping-configuration.md | 26 +++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index ad8431be95..7d51860e8e 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -47,6 +47,32 @@ Identify events are mostly used to update user profiles in external systems, lik Since Identify events are designed to update profile data, they are commonly mapped to destinations that rely on persistent user records, such as customer databases, email platforms, and loyalty systems. +### Track events: logging user actions + +Track events, on the other hand, capture user actions and behaviors. These events are event-driven rather than profile-based, which makes them ideal for tracking audience membership changes or user activities. + +Here's an example of a Track event payload: + +```json +{ + "anonymousId": "anon-test-1", + "context": { + "traits": { + "email": "user-testing-1@gmail.com" + } + }, + "event": "Audience Entered", + "properties": { + "audience_key": "your_audience_key", + "your_audience_key": true + }, + "type": "track", + "userId": "user-testing-1" +} +``` + + + From 5d64915247ce1de7926638ec0c6d1f3b73635fe9 Mon Sep 17 00:00:00 2001 From: pwseg Date: Sun, 23 Mar 2025 16:58:53 -0500 Subject: [PATCH 05/15] some rewording --- src/engage/event-mapping-configuration.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index 7d51860e8e..77c4abab40 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -5,33 +5,36 @@ plan: engage-foundations This guide helps you configure mappings for Engage events in Actions Destinations. - ## Overview -Engage Mappings let you transform and send user data to downstream destinations. When Engage events get sent to destinations, they may need to be formatted or adjusted to match the destination’s expected data structure. Without mapping, critical user information like audience membership or enriched traits may not sync correctly. +Engage Mappings let you transform and send user data to downstream destinations. Engage events sent to destinations may need to be formatted or adjusted, though, to match the destination’s expected data structure. Without mapping, critical user information like audience membership or enriched traits may not sync correctly. This guide explains how to configure mappings for Engage events in Actions Destinations, including: - The differences between [Identify](/docs/connections/spec/identify/) and [Track](/docs/connections/spec/track/) events. - How to extract and map data from Engage event payloads. - A step-by-step walkthrough of mapping configurations. -- Advanced features like Trait Enrichment to pass additional profile data. +- Advanced features like Trait Enrichment that you can use to pass additional profile data. ## What are Engage events? -Engage events let you sync audience membership data to your destinations. When a user enters or exits an audience in Engage, Segment generates events that you can use to trigger actions in your connected tools. +Segment generates events whenever a user enters or exits an Engage audience. You can then use these Engage events to sync audience membership to your connected destinations. -Engage generates Identify and Track events. These events carry critical information including: +Engage events carry critical information, including: - User identifiers (like `userId` and `anonymousId`) - Audience membership status -- Other user traits if you've enabled enrichment +- Other user traits, if you've enabled enrichment + +### Engage event types and structure + +Engage generates two types of events: Identify and Track. -Each event type has a specific structure that determines how you configure your mappings. +Each event serves a different purpose and has a specific structure that determines how you configure your mappings. -### Identify events: updating user traits +#### Identify events: updating user traits -Identify events are mostly used to update user profiles in external systems, like a CRM or marketing automation platform. Identify events send all user details in the `traits` object. The audience key appears in the object as a boolean that indicates whether the user is in the audience (`true`) or not (`false`), like in this example Identify payload: +Identify events update user profiles with audience membership status. Identify events send all user details in the `traits` object. The audience key appears in the object as a boolean that indicates whether the user is in the audience (`true`) or not (`false`), like in this example Identify payload: ```json { From 2c46cb23cfaf7a14933d02519772dd65346e7e81 Mon Sep 17 00:00:00 2001 From: pwseg Date: Sun, 23 Mar 2025 17:59:24 -0500 Subject: [PATCH 06/15] reword Identify event for clarity --- src/engage/event-mapping-configuration.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index 77c4abab40..c5bdea6c78 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -28,13 +28,15 @@ Engage events carry critical information, including: ### Engage event types and structure -Engage generates two types of events: Identify and Track. +Engage generates two event types: Identify and Track. Each event serves a different purpose and has a specific structure that determines how you configure your mappings. #### Identify events: updating user traits -Identify events update user profiles with audience membership status. Identify events send all user details in the `traits` object. The audience key appears in the object as a boolean that indicates whether the user is in the audience (`true`) or not (`false`), like in this example Identify payload: +Identify events in Engage update user profiles with audience membership status. Identify events send all user details in the `traits` object. + +The audience key appears in the object as a boolean that indicates whether the user is in the audience (`true`) or not (`false`), like in this payload: ```json { From 6925eccb01d7b16c60ccbf8f1b70fca69990ae4a Mon Sep 17 00:00:00 2001 From: pwseg Date: Sun, 23 Mar 2025 20:03:18 -0500 Subject: [PATCH 07/15] explain why event types matter --- src/engage/event-mapping-configuration.md | 34 +++++++++++++++++++++-- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index c5bdea6c78..30807720dc 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -16,7 +16,15 @@ This guide explains how to configure mappings for Engage events in Actions Desti - A step-by-step walkthrough of mapping configurations. - Advanced features like Trait Enrichment that you can use to pass additional profile data. -## What are Engage events? +## Understanding Engage events + +Before you create a mapping, you need to understand how Segment structures Engage events. Where the data lives in each even affects how you map it. + +Engage sends two types of events: Identify and Track. These two event types use different parts of the event payload to store user data. If you're mapping an email address, an audience membership, or a trait like `first_name`, you need to know where to look for that value in each event type. + +If you map from the wrong part of the payload, your data might not reach the destination at all, or it might show up incorrectly. + +This section breaks down the difference between Identify and Track events, shows you what each payload looks like, and explains where to find data you'll typically want to map so you can configure mappings correctly and avoid pitfalls. Segment generates events whenever a user enters or exits an Engage audience. You can then use these Engage events to sync audience membership to your connected destinations. @@ -26,6 +34,20 @@ Engage events carry critical information, including: - Audience membership status - Other user traits, if you've enabled enrichment +## Key Engage event fields + +The following properties appear in Engage event payloads: + +| Field | Type | Description | +| ---------------- | ------ | ----------------------------------------------------------------- | +| `userId` | String | The unique identifier for a known user. | +| `anonymousId` | String | The identifier for anonymous users before they log in. | +| `traits` | Object | Stores user attributes (like `email` and audience status). | +| `context.traits` | Object | In Track events, this object stores user attributes like `email`. | +| `properties` | Object | Stores event-related data, including audience membership. | + +Understanding these fields will help you correctly set up mappings and send Engage data to external destinations. + ### Engage event types and structure Engage generates two event types: Identify and Track. @@ -50,11 +72,16 @@ The audience key appears in the object as a boolean that indicates whether the u } ``` -Since Identify events are designed to update profile data, they are commonly mapped to destinations that rely on persistent user records, such as customer databases, email platforms, and loyalty systems. +In this example: + +- `email` is included in the `traits` object. +- The `your_audience_key` field indicates that the user is part of a specific audience. If the `value` is `false`, it means the user exited the audience. + +Because Identify events update profile data, they are commonly mapped to destinations that rely on persistent user records, like customer databases, email platforms, and loyalty systems. ### Track events: logging user actions -Track events, on the other hand, capture user actions and behaviors. These events are event-driven rather than profile-based, which makes them ideal for tracking audience membership changes or user activities. +Track events, on the other hand, capture user actions and behaviors. These events are event-driven rather than profile-based, which makes them ideal for tracking audience membership changes or user activities. ### Engage event types and structure -Engage generates two event types: Identify and Track. +Engage uses two event types to deliver data to downstream destinations: -Each event serves a different purpose and has a specific structure that determines how you configure your mappings. +- **Identify** events, which send or update user traits like email, name, or audience membership status. +- **Track** events, which capture actions or user behaviors, like when a user enters or exits an audience. #### Identify events: updating user traits From a19406bce8d4090e0ca52d08c13c07abc0868535 Mon Sep 17 00:00:00 2001 From: pwseg Date: Tue, 25 Mar 2025 19:21:16 -0500 Subject: [PATCH 09/15] explain difference between track and identify --- src/engage/event-mapping-configuration.md | 71 +++++++++++++++++------ 1 file changed, 52 insertions(+), 19 deletions(-) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index e986e6072c..5894ae6a5b 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -3,20 +3,20 @@ title: Engage Event Mapping plan: engage-foundations --- -This guide helps you configure mappings for Engage events in Actions Destinations. +This guide explains how to configure mappings for Engage events in Actions Destinations, ## Overview Engage Mappings let you transform and send user data to downstream destinations. Engage events sent to destinations may need to be formatted or adjusted, though, to match the destination’s expected data structure. Without mapping, critical user information like audience membership or enriched traits may not sync correctly. -This guide explains how to configure mappings for Engage events in Actions Destinations, including: +including: - The differences between [Identify](/docs/connections/spec/identify/) and [Track](/docs/connections/spec/track/) events. - How to extract and map data from Engage event payloads. - A step-by-step walkthrough of mapping configurations. - Advanced features like Trait Enrichment that you can use to pass additional profile data. -## Understanding Engage events +## About Engage events Before you create a mapping, you need to understand how Segment structures Engage events. Where the data lives in each event affects how you map it. @@ -53,59 +53,92 @@ Engage uses two event types to deliver data to downstream destinations: - **Identify** events, which send or update user traits like email, name, or audience membership status. - **Track** events, which capture actions or user behaviors, like when a user enters or exits an audience. +These events structure data differently, which directly affects how you should configure mappings. + #### Identify events: updating user traits -Identify events in Engage update user profiles with audience membership status. Identify events send all user details in the `traits` object. +Identify events represent who the user is. These events usually update or enrich profiles in destinations like CRMs and email tools. + +Key characteristics: + +- Identify events store user details in the `traits` object. +- Audience membership (for example, `browse_abandoners = true`) is also included in `traits`. +- Attributes like `email`, `first_name`, and any enriched traits all appear alongside audience flags. -The audience key appears in the object as a boolean that indicates whether the user is in the audience (`true`) or not (`false`), like in this payload: +Here's an example of an Engage Identify event payload: ```json { "anonymousId": "anon-test-1", "traits": { - "email": "user-testing-1@gmail.com", - "your_audience_key": true + "email": "user@example.com", + "browse_abandoners": true, + "first_name": "Jane", + "last_name": "Doe" }, "type": "identify", - "userId": "user-testing-1" + "userId": "user-123" } ``` -In this example: +In this example, a user just entered the `browse_abandoners` audience. If the value for the audience were `false`, it would mean the user just **exited** the audience. -- `email` is included in the `traits` object. -- The `your_audience_key` field indicates that the user is part of a specific audience. If the `value` is `false`, it means the user exited the audience. - -Because Identify events update profile data, they are commonly mapped to destinations that rely on persistent user records, like customer databases, email platforms, and loyalty systems. + ### Track events: logging user actions -Track events, on the other hand, capture user actions and behaviors. These events are event-driven rather than profile-based, which makes them ideal for tracking audience membership changes or user activities. + +## Configure mappings From 70220b5692d4b62208c6a7a55b95d945dca97ed3 Mon Sep 17 00:00:00 2001 From: pwseg Date: Tue, 25 Mar 2025 21:26:05 -0500 Subject: [PATCH 11/15] add setup section --- src/engage/event-mapping-configuration.md | 24 +++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index 7a04e8b7cf..e4c3088312 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -144,6 +144,30 @@ The following table summarizes the differences between Identify and Track events ## Configure mappings +To send Engage event data to a destination, you’ll need to configure a mapping. Mappings define how Segment fields, like `traits.email` or `properties.browse_abandoners` are passed to the destination's API endpoint. + +When you add a mapping, you’ll choose the event type (Identify or Track) and then define which fields to send and where to send them. The structure of the event payload depends on the type of event, which is why mapping an Identify event differs from mapping a Track event. + +The following sections walk through each event type and show how to configure a mapping using example payloads. + +### Map an Identify event + +Since Identify events send data in the `traits` object, you'll use `traits` in your mappings, like in this example: + +```json +{ + "type": "identify", + "userId": "user-123", + "anonymousId": "anon-test-1", + "traits": { + "email": "user@example.com", + "browse_abandoners": true, + "first_name": "Jane", + "last_name": "Doe" + } +} +``` + From 66b1123daeeb00780e6c9cadfd7dd5cb7995e0ed Mon Sep 17 00:00:00 2001 From: pwseg Date: Wed, 26 Mar 2025 11:55:28 -0500 Subject: [PATCH 12/15] more changes --- src/engage/event-mapping-configuration.md | 77 ++++++++++++++++++++++- 1 file changed, 75 insertions(+), 2 deletions(-) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index e4c3088312..0ce49673e4 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -144,13 +144,32 @@ The following table summarizes the differences between Identify and Track events ## Configure mappings -To send Engage event data to a destination, you’ll need to configure a mapping. Mappings define how Segment fields, like `traits.email` or `properties.browse_abandoners` are passed to the destination's API endpoint. +To send Engage event data to a destination, you’ll need to configure a mapping. Mappings define Segment passes fields like `traits.email` or `properties.browse_abandoners` to the destination's API endpoint. When you add a mapping, you’ll choose the event type (Identify or Track) and then define which fields to send and where to send them. The structure of the event payload depends on the type of event, which is why mapping an Identify event differs from mapping a Track event. The following sections walk through each event type and show how to configure a mapping using example payloads. -### Map an Identify event +Before you begin, make sure you've done the following: + +- Created an audience in Engage +- Connected an Actions destination +- Confirmed whether the destination expects Identify or Track events +- Located your audience key (you'll use it to configure the trigger) + +### Create a mapping + +To create a mapping, follow these steps: + +1. In your Segment workspace, go to **Connections > Destinations**. +2. Select the destination where you want to send Engage data. +3. On the destination overview page, click **Mappings > + New mapping**. +4. Choose the event type you want to use: Identify or Track. + +After you select the event type, you'll configure a trigger to determine when the mapping fires (based on audience entry or exit), and then map the fields to the destination's expected format. + + +Map an Identify event Since Identify events send data in the `traits` object, you'll use `traits` in your mappings, like in this example: @@ -168,6 +187,60 @@ Since Identify events send data in the `traits` object, you'll use `traits` in y } ``` +Here’s how you might configure your mapping for this Identify event: + +| Segment field | Destination field | Details | +| -------------------------- | ----------------- | --------------------------------- | +| `traits.email` | `email_address` | User’s email | +| `traits.browse_abandoners` | `audience_status` | True if user entered the audience | +| `traits.first_name` | `first_name` | User’s first name | +| `traits.last_name` | `last_name` | User’s last name | + +| Step | Who | What happens | +| ---- | -------- | ------------------------------------------------------------------------------ | +| 1 | Enginer | Creates string key and wires it into the UI (like `settings.saveButton.label`) | +| 2 | Engineer | Seeds initial content into the CMS during feature development | +| 3 | Designer | Logs into the CMS and updates the content post-launch | +| 4 | Console | Loads content from the CMS at build time or runtime depending on use case | + + + + + + +### Map a Track event + +Track events send data in the `properties` object, like in this example: + +```json +{ + "type": "track", + "event": "Audience Entered", + "userId": "user-123", + "anonymousId": "anon-test-1", + "context": { + "traits": { + "email": "user@example.com" + } + }, + "properties": { + "audience_key": "browse_abandoners", + "browse_abandoners": true, + "first_name": "Jane", + "last_name": "Doe" + } +} +``` + +This event logs the moment the user entered the `browse_abandoners` audience. Audience status and [enriched traits](#) show up in `properties`, while email is stored in `context.traits`. +Here’s how you might configure your mapping for this Track event: +| Segment field | Destination field | Details | +| ------------------------------ | ----------------- | --------------------------------- | +| `context.traits.email` | `email_address` | User’s email | +| `properties.browse_abandoners` | `audience_status` | True if user entered the audience | +| `properties.first_name` | `first_name` | User’s first name | +| `properties.last_name` | `last_name` | User’s last name | + - -### Map a Track event +#### Map a Track event Track events send data in the `properties` object, like in this example: @@ -231,7 +245,6 @@ Track events send data in the `properties` object, like in this example: } } ``` - This event logs the moment the user entered the `browse_abandoners` audience. Audience status and [enriched traits](#) show up in `properties`, while email is stored in `context.traits`. Here’s how you might configure your mapping for this Track event: @@ -243,4 +256,19 @@ Here’s how you might configure your mapping for this Track event: | `properties.first_name` | `first_name` | User’s first name | | `properties.last_name` | `last_name` | User’s last name | - - ### Track events: logging user actions Track events, on the other hand, represent something the user did. These events capture user actions and log events and behaviors. @@ -144,7 +142,7 @@ The following table summarizes the differences between Identify and Track events ## Configure mappings -To send Engage event data to a destination, you’ll need to configure a mapping. Mappings define Segment passes fields like `traits.email` or `properties.browse_abandoners` to the destination's API endpoint. +To send Engage event data to a destination, you’ll need to configure a mapping. A mapping defines how Segment passes fields from Engage events (like `traits.email` or `properties.browse_abandoners`) to the format your destination expects. When you add a mapping, you’ll choose the event type (Identify or Track) and then define which fields to send and where to send them. The structure of the event payload depends on the type of event, which is why mapping an Identify event differs from mapping a Track event. @@ -271,4 +269,62 @@ Trait Enrichment lets you pull Segment profile traits into mappings when syncing To enable trait enrichment: 1. From your Segment workspace, go to **Engage > Audiences**. -2. \ No newline at end of file +2. Choose an audience, then select a destination from the audience overview tab. +3. In the destination side panel, click **Traits and identifiers**. +4. Add identifiers and/or traits, then click **Save**. + +Enriched Identify events include traits in the `traits` object, and enriched Track events include traits in the `properties` object, like in these examples: + +{% codeexample %} +{% codeexampletab Enriched Identify event payload%} +```json +{ + "anonymousId": "anon-test-1", + "traits": { + "email": "user-testing-1@gmail.com", + "browse_abandoners": true, + "enriched_trait_1": "value_1", + "enriched_trait_2": "value_2" + }, + "type": "identify", + "userId": "user-testing-1" +} +``` +{% endcodeexampletab %} + +{% codeexampletab Enriched Track event payload %} +```json +{ + "anonymousId": "anon-test-1", + "context": { + "traits": { + "email": "user-testing-1@gmailx.com" + } + }, + "event": "Audience Entered", + "properties": { + "browse_abandoners": true, + "enriched_trait_1": "enriched_trait_value_1", + "enriched_trait_2": "enriched_trait_value_2" + }, + "type": "track", + "userId": "user-testing-1" +} + +``` +{% endcodeexampletab %} +{% endcodeexample %} + +## Troubleshooting + +#### Why can't I find the email in my Track event properties? + +For Track events, `email` is located in context.traits.email, not in the `properties` object. Make sure to map `context.traits.email` to your destination's email field. + +#### How do I know whether to use an Identify or Track event? + +The event type you use depends on your destination. Some destinations work better with Identify events for updating user profiles, while others prefer Track events to trigger actions. Read the destination's documentation to learn more about what event types will work best for your use case. + +#### My destination fields aren't being populated correctly. What should I check? + +Verify that you're mapping from the correct location in the event. For Identify events, look in the `traits` object. For Track events, most fields are in the `properties` object, except for `email`, which is in `context.traits`. \ No newline at end of file From 78774ff4694b473a4ad74e4055664b4f7bd32136 Mon Sep 17 00:00:00 2001 From: pwseg Date: Fri, 28 Mar 2025 00:06:52 -0500 Subject: [PATCH 15/15] some more rearranging [netlify-build] --- src/engage/event-mapping-configuration.md | 82 ++++++++++------------- 1 file changed, 35 insertions(+), 47 deletions(-) diff --git a/src/engage/event-mapping-configuration.md b/src/engage/event-mapping-configuration.md index f4b374ae89..25c80e6070 100644 --- a/src/engage/event-mapping-configuration.md +++ b/src/engage/event-mapping-configuration.md @@ -3,36 +3,26 @@ title: Engage Event Mapping plan: engage-foundations --- -This guide explains how to configure mappings for Engage events in Actions Destinations, +This guide explains how to configure mappings for Engage events in [Actions Destinations](/docs/connections/destinations/actions/). ## Overview -Engage Mappings let you transform and send user data to downstream destinations. Engage events sent to destinations may need to be formatted or adjusted, though, to match the destination’s expected data structure. Without mapping, critical user information like audience membership or enriched traits may not sync correctly. +Engage mappings let you transform and send user data to downstream destinations. Engage events sent to destinations may need to be formatted or adjusted, though, to match the destination’s expected data structure. Without mapping, critical user information like audience membership or enriched traits may not sync correctly. This guide covers: - The differences between [Identify](/docs/connections/spec/identify/) and [Track](/docs/connections/spec/track/) events. - How to extract and map data from Engage event payloads. - A step-by-step walkthrough of mapping configurations. -- Advanced features like Trait Enrichment that you can use to pass additional profile data. +- Advanced features like trait enrichment that you can use to pass additional profile data. ## About Engage events Before you create a mapping, you need to understand how Segment structures Engage events. Where the data lives in each event affects how you map it. -Engage sends two types of events: Identify and Track. These two event types use different parts of the event payload to store user data. If you're mapping an email address, an audience membership, or a trait like `first_name`, you need to know where to look for that value in each event type. +This section lists the important Engage event fields, breaks down the difference between Identify and Track events, shows you what each payload looks like, and explains where to find data you'll typically want to map so you can configure mappings correctly and avoid pitfalls. -If you map from the wrong part of the payload, your data might not reach the destination at all, or it might show up incorrectly. - -This section breaks down the difference between Identify and Track events, shows you what each payload looks like, and explains where to find data you'll typically want to map so you can configure mappings correctly and avoid pitfalls. - - +Understanding these fields will help you correctly set up mappings and send Engage data to external destinations. ### Engage event types and structure @@ -55,6 +45,27 @@ Engage uses two event types to deliver data to downstream destinations: These events structure data differently, which directly affects how you should configure mappings. +### Understanding the difference between Identify and Track in Engage + +Engage sends both Identify and Track events when a user enters or exits an audience. While these events can contain similar information, they serve different purposes. + +Identify events answer the question, "Who is this user right now?" They update the user’s profile with traits like email, name, and audience membership. For example: “Jane’s email is `jane@example.com`. She’s in the `browse_abandoners` audience. Her first name is `jane`.” + +Track events capture a specific moment in time, like when a user joins or leaves an audience. For example: “Jane just entered the `browse_abandoners` audience.” + +Engage sends both types of events because different destinations rely on different types of data. Identify events are used to keep user profiles up to date, whereas Track events are useful for triggering time-sensitive actions based on audience entry or exit. + +For example, you might use an Identify event to sync the current list of users in an audience to your CRM. But if you want an ad platform to show an ad the moment someone enters an audience, you'd use a Track event. + +The following table summarizes the differences between Identify and Track events in Engage: + +| Attribute | Identify | Track | +| ---------------------- | ----------------------------------------- | ----------------------------------------------------- | +| What it describes | The user’s current traits and attributes | A specific moment or action (like audience entry) | +| When to use it | To update a user profile in a destination | To trigger an action based on something that happened | +| Audience data location | `traits` | `properties` | +| Email location | `traits.email` | `context.traits.email` | + #### Identify events: updating user traits Identify events represent who the user is. These events usually update or enrich profiles in destinations like CRMs and email tools. @@ -83,7 +94,7 @@ Here's an example of an Engage Identify event payload: In this example, a user just entered the `browse_abandoners` audience. If the value for the audience were `false`, it would mean the user just **exited** the audience. -### Track events: logging user actions +#### Track events: logging user actions Track events, on the other hand, represent something the user did. These events capture user actions and log events and behaviors. @@ -117,28 +128,7 @@ Here's an example of an Engage Track event payload: In this example, a user just entered the `browse_abandoners` audience. The audience flag and traits are nested in `properties`, and the email address is in `context.traits.email`. -### Understanding the difference between Identify and Track in Engage - -Engage sends both Identify and Track events when a user enters or exits an audience. While these events can contain similar information, these events serve different purposes. - -Identify events answer the question, "Who is this user right now?" They update the user’s profile with traits like email, name, and audience membership. For example: “Jane’s email is `jane@example.com`. She’s in the `browse_abandoners` audience. Her first name is `jane`.” - -Track events capture a specific moment in time, like when a user joins or leaves an audience. For example: “Jane just entered the `browse_abandoners` audience.” - -Engage sends both types of events because different destinations rely on different types of data. Identify events are used to keep user profiles up to date, whereas Track events are useful for triggering time-sensitive actions based on audience entry or exit. - -For example, you might use an Identify event to sync the current list of users in an audience to your CRM. But if you want an ad platform to show an ad the moment someone enters an audience, you'd use a Track event. - -The following table summarizes the differences between Identify and Track events in Engage: - -| Attribute | Identify | Track | -| ---------------------- | ----------------------------------------- | ----------------------------------------------------- | -| What it describes | The user’s current traits and attributes | A specific moment or action (like audience entry) | -| When to use it | To update a user profile in a destination | To trigger an action based on something that happened | -| Audience data location | `traits` | `properties` | -| Email location | `traits.email` | `context.traits.email` | - - +Now that you understand the different purposes each event type serves, you're ready to configure a mapping. ## Configure mappings @@ -150,8 +140,8 @@ The following sections walk through each event type and show how to configure a Before you begin, make sure you've done the following: -- Created an audience in Engage -- Connected an Actions destination +- Created [an audience in Engage](/docs/engage/audiences/) +- Connected an [Actions destination](/docs/connections/destinations/actions/#available-actions-based-destinations) - Confirmed whether the destination expects Identify or Track events - Located your audience key (you'll use it to configure the trigger) @@ -160,7 +150,7 @@ Before you begin, make sure you've done the following: To create a mapping, follow these steps: 1. In your Segment workspace, go to **Connections > Destinations**. -2. Select the destination where you want to send Engage data. +2. Select the (Actions) destination you want to send Engage data to. 3. On the destination overview page, click **Mappings > + New mapping**. 4. Choose the event type you want to use: Identify or Track. @@ -170,8 +160,6 @@ After you select the event type, you'll configure a trigger to determine when th Before mapping fields, you’ll define a trigger that determines when the mapping executes. For Engage events, triggers typically use the audience key's boolean value. -So to trigger the mapping when a user enters or exits an audience, you'd use the audience key and its boolean value: - When a user enters the audience, configure the trigger like this: - Trigger type: `Event Trait` @@ -190,7 +178,7 @@ This tells Segment to execute the mapping only when the value of the audience ke The fields you map depend on whether you selected Identify or Track. -#### Map an Identify event +#### 3a. Map an Identify event Since Identify events send data in the `traits` object, you'll use `traits` in your mappings, like in this example: @@ -220,7 +208,7 @@ Here’s how you might configure your mapping for this Identify event: -#### Map a Track event +#### 3b. Map a Track event Track events send data in the `properties` object, like in this example: @@ -264,7 +252,7 @@ Once you've decided whether to map a Track or Identify event, finish by followin ## Trait enrichment -Trait Enrichment lets you pull Segment profile traits into mappings when syncing audiences or journeys to destinations and [Destination functions](/docs/connections/functions/destination-functions/). +Trait enrichment lets you pull Segment profile traits into mappings when syncing audiences or journeys to destinations and [Destination functions](/docs/connections/functions/destination-functions/). To enable trait enrichment: