Merge pull request #5458 from segmentio/lizkane222-patch-29

Update using-engage-data.md Additional info on engage events

Author: rchinn1

src/engage/using-engage-data.md

@@ -61,56 +61,98 @@ User-list destinations can have individual limits on how often Segment can sync
 
 The payloads sent from your Engage space to your destinations will be different depending on if you configured the destination to receive identify or track calls, and whether the payload is coming from a computed trait or audience. As a reminder, identify calls usually update a trait on a user profile or table, whereas track calls send a point-in-time event that can be used as a campaign trigger or a detailed record of when a user's audience membership or computed trait value was calculated.
 
+To view the events generated by an Engage Space's audience or computed traits, navigate to **Unify settings > Debugger** and view the list of sources that are configured to generate events per [each destination instance](/docs/engage/warehouses/#why-are-there-multiple-schemas-prefixed-with-engage_-in-my-warehouse-when-i-only-have-one-space:~:text=Segment%20currently%20can,schemas%20than%20spaces.). Each source will only generate events to connected destinations. From the source's Debugger tab, you'll find the most recent events generated by that source per the connected destinations' audiences and computed traits. 
+
+In the full json body of an audience, computed trait, or journey, you'll find specific details under the `context.personas` object. These fields can be useful when building out [Destination Filters](/docs/connections/destinations/destination-filters/), [Actions destination mappings](/docs/connections/destinations/actions/#set-up-a-destination-action), and [Functions](/docs/connections/functions/).
+
+The integrations object in the payload displays as `{"All" : false,}` and only lists some destinations. This is due to the fact that each source has multiple destinations connected while each audience/trait may only have a subset of destinations connected to it. See [Filtering with the Integrations Object](/docs/guides/filtering-data/#filtering-with-the-integrations-object) for more information. The integrations object routing specific events to its specified destinations is also why a destination's [Delivery Overview](/docs/connections/delivery-overview/) tab will show a large number of events under the [Filtered at destination](/docs/connections/delivery-overview/#:~:text=Filtered%20at%20destination%3A%20Events,will%20be%20filtered%20out.) box, as that destination will only receive the events intended to be sent to it by audiences, traits, or journeys that are connected to that specific destination.
+
 ### Computed Trait generated events
 
-`Identify` events generated by a computed trait have the trait name set to the computed trait value:
+`Identify` events generated by a Computed Trait have the trait name set to the Computed Trait value:
 
 ```js
 {
+  "context": {
+    "personas": {
+      "computation_class": "trait", // the type of computation
+      "computation_id": "tra_###", // the trait's id found in the URL
+      "computation_key": "aud_###", // the configured trait key that appears on user profile
+      "namespace": "spa_###", // the Engage Space's ID
+      "space_id": "spa_###" // the Engage Space's ID
+    }
+  },
   "type": "identify",
-  "userId": u123,
+  "userId": "u123",
   "traits": {
      "total_revenue_180_days": 450.00
   }
 }
 ```
 
-`Track` events generated by a computed trait have a key for the trait name, and a key for the computed trait value. The default event name is `Trait Computed`, but you can change it.
+`Track` events generated by a Computed Trait have a key for the trait name, and a key for the Computed Trait value. The default event name is `Trait Computed`, but you can change it.
 
 ```js
 {
+  "context": {
+    "personas": {
+      "computation_class": "trait", // the type of computation
+      "computation_id": "tra_###", // the trait's id found in the URL
+      "computation_key": "aud_###", // the configured trait key that appears on user profile
+      "namespace": "spa_###", // the Engage Space's ID
+      "space_id": "spa_###" // the Engage Space's ID
+    }
+  },
   "type": "track",
   "event": "Trait Computed",
-  "userId": u123,
+  "userId": "u123",
   "properties": {
      "trait_key": "total_revenue_180_days",
      "total_revenue_180_days": 450.00
   }
 }
 ```
 
-Engage only sends events to the destination if the computed trait value has changed for the user. Engage doesn't send a payload for every user in your trait every time the trait computes.
+Engage only sends events to the destination if the Computed Trait value has changed for the user. Engage doesn't send a payload for every user in your trait every time the trait computes.
 
 ### Audience generated events
 
-`Identify` events generated by an audience have the audience key set to `true` or `false` based on whether the user is entering or exiting the audience:
+`Identify` events generated by an Audience have the Audience key set to `true` or `false` based on whether the user is entering or exiting the audience:
 
 ```js
 {
+  "context": {
+    "personas": {
+      "computation_class": "audience", // the type of computation
+      "computation_id": "aud_###", // the audience's id found in the URL
+      "computation_key": "aud_###", // the configured audience key that appears on user profile
+      "namespace": "spa_###", // the Engage Space's ID
+      "space_id": "spa_###" // the Engage Space's ID
+    }
+  },
   "type": "identify",
-  "userId": u123,
+  "userId": "u123",
   "traits": {
      "first_time_shopper": true // false when a user exits the audience
   }
 }
 ```
 
-`Track` events generated by an audience have a key for the audience name, and a key for the audience value:
+`Track` events generated by an Audience have a key for the Audience name, and for the Audience value:
 
 ```js
 {
+  "context": {
+    "personas": {
+      "computation_class": "audience", // the type of computation
+      "computation_id": "aud_###", // the audience's id found in the URL
+      "computation_key": "aud_###", // the configured audience key that appears on user profile
+      "namespace": "spa_###", // the Engage Space's ID
+      "space_id": "spa_###" // the Engage Space's ID
+    }
+  },
   "type": "track",
-  "userId": u123,
+  "userId": "u123",
   "event": "Audience Entered", // "Audience Exited" when a user exits an audience
   "properties": {
      "audience_key": "first_time_shopper",
@@ -119,6 +161,51 @@ Engage only sends events to the destination if the computed trait value has chan
 }
 ```
 
+### Journey generated events
+_See [this doc](https://segment.com/docs/engage/journeys/send-data/#what-do-i-send-to-destinations) for more information on Journeys events._
+`Track` events generated by a journey have a key for the journey name "audience_key", and a key for the journey value:
+
+```js
+{
+  "context": {
+    "personas": {
+      "computation_class": "audience", // the type of computation
+      "computation_id": "aud_###", // the audience's id found in the URL
+      "computation_key": "j_o_###", // the configured journey key that appears on user profile
+      "namespace": "spa_###", // the Engage Space's ID
+      "space_id": "spa_###" // the Engage Space's ID
+    }
+  },
+  "type": "track",
+  "userId": "u123",
+  "event": "Audience Entered", // "Audience Exited" when a user exits an audience
+  "properties": {
+     "audience_key": "j_o_###",
+     "recent_buyer": true // false when a user exits the journey
+  }
+}
+```
+
+`Identify` events generated by a Journey have the Journey key set to `true` or `false` based on whether the user is entering or exiting the Journey:
+
+```js
+{
+  "context": {
+    "personas": {
+      "computation_class": "audience", // the type of computation
+      "computation_id": "aud_###", // the audience's id found in the URL
+      "computation_key": "j_o_###", // the configured journey key that appears on user profile
+      "namespace": "spa_###", // the Engage Space's ID
+      "space_id": "spa_###" // the Engage Space's ID
+    }
+  },
+  "type": "identify",
+  "userId": "u123",
+  "traits": {
+     "recent_buyer": true // false when a user exits the journey
+  }
+}
+```
 
 
 ## Additional identifiers