Skip to content

event-mapping-configuration.md

Latest commit

 

History

History
318 lines (230 loc) · 13.7 KB

event-mapping-configuration.md

File metadata and controls

318 lines (230 loc) · 13.7 KB
title Engage Event Mapping
plan engage-foundations

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 covers:

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

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.

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

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.

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 appear together with audience membership information.

Here's an example of an Engage Identify event payload:

{
  "anonymousId": "anon-test-1",
  "traits": {
    "email": "user@example.com",
    "browse_abandoners": true,
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "type": "identify",
  "userId": "user-123"
}

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, on the other hand, represent something the user did. These events capture user actions and log events and behaviors.

Key characteristics:

  • Most event-specific data is stored in the properties object.
  • The user's email isn't in properties; it's nested under context.traits.
  • Audience entry and exit shows as a boolean, where true is an entry and false is an exit.

Here's an example of an Engage Track event payload:

{
  "anonymousId": "anon-test-1",
  "context": {
    "traits": {
      "email": "user@example.com"
    }
  },
  "event": "Audience Entered",
  "properties": {
    "audience_key": "browse_abandoners",
    "browse_abandoners": true,
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "type": "track",
  "userId": "user-123"
}

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.

Now that you understand the different purposes each event type serves, you're ready to configure a mapping.

Configure mappings

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.

The following sections walk through each event type and show how to configure a mapping using example payloads.

Before you begin, make sure you've done the following:

1. Create a mapping

To create a mapping, follow these steps:

  1. In your Segment workspace, go to Connections > Destinations.
  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.

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.

2. Define the event trigger

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.

When a user enters the audience, configure the trigger like this:

  • Trigger type: Event Trait
  • Field: browse_abandoners
  • Condition: is true

When a user exits the audience, set the trigger like this:

  • Trigger type: Event Trait
  • Field: browse_abandoners
  • Condition: is false

This tells Segment to execute the mapping only when the value of the audience key changes in the appropriate direction.

3. Map event fields

The fields you map depend on whether you selected Identify or Track.

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:

{
  "type": "identify",
  "userId": "user-123",
  "anonymousId": "anon-test-1",
  "traits": {
    "email": "user@example.com",
    "browse_abandoners": true,
    "first_name": "Jane",
    "last_name": "Doe"
  }
}

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

3b. Map a Track event

Track events send data in the properties object, like in this example:

{
  "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

Once you've decided whether to map a Track or Identify event, finish by following these steps:

  1. Load a test event or paste the event JSON into the mapping interface.
  2. For each field you want to send:
  • Select the source field from the left panel.
  • Enter the destination field on the right.

Trait enrichment

Trait enrichment lets you pull Segment profile traits into mappings when syncing audiences or journeys to destinations and Destination functions.

To enable trait enrichment:

  1. From your Segment workspace, go to Engage > Audiences.
  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%}

{
  "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 %}

{
 "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.