Skip to content

Commit 674e65b

Browse files
cmastrcmastr
authored
Merge pull request #5982 from segmentio/lizkane222-patch-16
Update track.md - Track Spec added context.traits and actions destina…
2 parents f6c2dca + 665eef8 commit 674e65b

File tree

1 file changed

+79
-1
lines changed

1 file changed

+79
-1
lines changed

‎src/connections/spec/track.md

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ Here's a complete example of a Track call:
7878

7979
### Create your own Track call
8080

81-
Use the following interactive code pen to see what your Track calls would look like with user-provided information:
81+
Use the following interactive code pen to see what your Track calls look like with user-provided information:
8282

8383
{% include components/codepens/track-spec.html %}
8484

@@ -114,3 +114,81 @@ The following are all of the reserved properties Segment has standardized that a
114114
| `value` | Number | An abstract "value" to associate with an event. This is typically used in situations where the event doesn't generate real-dollar revenue, but has an intrinsic value to a marketing team, like newsletter signups. |
115115

116116
**Note:** You might be used to some destinations recognizing special properties differently. For example, Mixpanel has a special `track_charges` method for accepting revenue. Luckily, you don't have to worry about those inconsistencies. Just pass along `revenue`. **Segment will handle all of the destination-specific conversions for you automatically.** Same goes for the rest of the reserved properties.
117+
118+
## Sending Traits in a Track Call - Destination Actions
119+
All events have the ability to include additional event data in the `context` object. There may be instances when your team may want to include user traits or group traits in a Track event, such as having a single event trigger multiple events in an Actions destination. Since user Traits are not standard fields for a Track event, in order to do this, you'll need to explicitely pass the user's traits into the event payload's `context.traits` object.
120+
_For instructions on how to pass fields to the context object for a specific library, please see the related library's Source documentation._
121+
122+
Segment's Actions destinations allows your team to build individual actions that are triggered based on a set of configured conditions. By adding the user's latest traits to the Track event's `context.traits` object, its possible to build two separate Actions to be triggered by this single event. For example, if your team would like to send an Identify event anytime the specific Track event "Button Clicked" is triggered, simply add the available traits into the Track event's payload, then build a destination Actions for the Track event : `Event Name is Button Clicked`, and a destination Action for the Identify event : `All of the following conditions are true: Event Name is Button Clicked, Event Context traits exists`, and then both Actions will have access to reference the `context.traits` fields within its mappings.
123+
124+
For more information on the context object, please see the [Spec: Common Fields](https://segment.com/docs/connections/spec/common/#context) documentation.
125+
126+
<table>
127+
{% include content/spec-table-header.md %}
128+
{% include content/spec-field-context.md %}
129+
</table>
130+
131+
If the [Example Payload](https://segment.com/docs/connections/spec/track/#example) shared above is modified as the event `Button Clicked` with `"username": "testing-123"` in the `context.traits` object, then the event's payload would be :
132+
```
133+
{
134+
"anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
135+
"context": {
136+
"library": {
137+
"name": "analytics.js",
138+
"version": "2.11.1"
139+
},
140+
"page": {
141+
"path": "/academy/",
142+
"referrer": "",
143+
"search": "",
144+
"title": "Analytics Academy",
145+
"url": "https://segment.com/academy/"
146+
},
147+
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36",
148+
"ip": "108.0.78.21",
149+
"traits": {
150+
"username": "testing-123"
151+
}
152+
},
153+
"event": "Button Clicked",
154+
"integrations": {},
155+
"messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
156+
"properties": {
157+
"title": "Intro to Analytics"
158+
},
159+
"receivedAt": "2015-12-12T19:11:01.266Z",
160+
"sentAt": "2015-12-12T19:11:01.169Z",
161+
"timestamp": "2015-12-12T19:11:01.249Z",
162+
"type": "track",
163+
"userId": "AiUGstSDIg",
164+
"originalTimestamp": "2015-12-12T19:11:01.152Z"
165+
}
166+
```
167+
168+
Here's what that Identify Action would look like :
169+
![Identify Action - Triggered by Button Clicked Track event with context traits](https://github.com/segmentio/segment-docs/assets/68755692/552d418d-abdd-4ec5-9253-da931f22f164)
170+
171+
## Context
172+
173+
Context is a dictionary of extra information that provides useful context about a datapoint, for example the user's `ip` address or `locale`. You should **only use** Context fields for their intended meaning.
174+
175+
| Field | Type | Description |
176+
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
177+
| `active` | Boolean | Whether a user is active. <br><br> This is usually used to flag an `.identify()` call to just update the traits but not "last seen." |
178+
| `app` | Object | dictionary of information about the current application, containing `name`, `version`, and `build`. <br><br> This is collected automatically from the mobile libraries when possible. |
179+
| `campaign` | Object | Dictionary of information about the campaign that resulted in the API call, containing `name`, `source`, `medium`, `term`, `content`, and any other custom UTM parameter. <br><br> This maps directly to the common UTM campaign parameters. |
180+
| `device` | Object | Dictionary of information about the device, containing `id`, `advertisingId`, `manufacturer`, `model`, `name`, `type`, and `version`. |
181+
| `ip` | String | Current user's IP address. |
182+
| `library` | Object | Dictionary of information about the library making the requests to the API, containing `name` and `version`. |
183+
| `locale` | String | Locale string for the current user, for example `en-US`. |
184+
| `network` | Object | Dictionary of information about the current network connection, containing `bluetooth`, `carrier`, `cellular`, and `wifi`. If the `context.network.cellular` and `context.network.wifi` fields are empty, then the user is offline. |
185+
| `os` | Object | Dictionary of information about the operating system, containing `name` and `version`. |
186+
| `page` | Object | Dictionary of information about the current page in the browser, containing `path`, `referrer`, `search`, `title` and `url`. This is automatically collected by [Analytics.js](/docs/connections/sources/catalog/libraries/website/javascript/#context--traits). |
187+
| `referrer` | Object | Dictionary of information about the way the user was referred to the website or app, containing `type`, `name`, `url`, and `link`. |
188+
| `screen` | Object | Dictionary of information about the device's screen, containing `density`, `height`, and `width`. |
189+
| `timezone` | String | Timezones are sent as tzdata strings to add user timezone information which might be stripped from the timestamp, for example `America/New_York`. |
190+
| `groupId` | String | Group / Account ID. <br><br> This is useful in B2B use cases where you need to attribute your non-group calls to a company or account. It is relied on by several Customer Success and CRM tools. |
191+
| `traits` | Object | Dictionary of `traits` of the current user. <br><br> This is useful in cases where you need to `track` an event, but also associate information from a previous Identify call. You should fill this object the same way you would fill traits in an [identify call](/docs/connections/spec/identify/#traits). |
192+
| `userAgent` | String | User agent of the device making the request. |
193+
| `userAgentData` | Object | The user agent data of the device making the request. This always contains `brands`, `mobile`, `platform`, and may contain `bitness`, `model`, `platformVersion`,`uaFullVersion`, `fullVersionList`, `wow64`, if [requested](/docs/connections/sources/catalog/libraries/website/javascript/#client-hints) and available. <br><br> This populates if the [Client Hints API](https://developer.mozilla.org/en-US/docs/Web/API/User-Agent_Client_Hints_API){:target="_blank"} is available on the browser. <br><br> This may contain more information than is available in the `userAgent` in some cases. |
194+
| `channel` | String | where the request originated from: server, browser or mobile

0 commit comments

Comments
 (0)