diff --git a/src/connections/spec/common.md b/src/connections/spec/common.md index 5365133287..bd8dcc3dfa 100644 --- a/src/connections/spec/common.md +++ b/src/connections/spec/common.md @@ -4,7 +4,7 @@ title: 'Spec: Common Fields' In the Segment [Spec](/docs/connections/spec/) all the [API calls](/docs/connections/spec#api-calls) have a common structure, and a few common fields. -However, not all destinations accept all fields included in the Spec. Not sure which fields an destination accepts? Refer to the destination's documentation page, or check out the [open-source destination code on Github](https://github.com/segment-integrations). +However, not all destinations accept all fields included in the Spec. Not sure which fields a destination accepts? Refer to the destination's documentation page, or check out the [open-source destination code on Github](https://github.com/segment-integrations). ## Structure Every API call has the same core structure and fields. These fields describe user identity, timestamping and mechanical aides like API version. @@ -129,7 +129,7 @@ Context is a dictionary of extra information that provides useful context about `active` Boolean Whether a user is active - +

This is usually used to flag an `.identify()` call to just update the traits but not "last seen." @@ -137,7 +137,7 @@ Context is a dictionary of extra information that provides useful context about `app` Object dictionary of information about the current application, containing `name`, `version` and `build`. - +

This is collected automatically from our mobile libraries when possible. @@ -145,7 +145,7 @@ Context is a dictionary of extra information that provides useful context about `campaign` Object Dictionary of information about the campaign that resulted in the API call, containing `name`, `source`, `medium`, `term` and `content`. - +

This maps directly to the common UTM campaign parameters. @@ -187,9 +187,7 @@ Context is a dictionary of extra information that provides useful context about `page` Object - Dictionary of information about the current page in the browser, containing `hash`, `path`, `referrer`, `search`, `title` and `url` - - Automatically collected by Analytics.js. + Dictionary of information about the current page in the browser, containing `hash`, `path`, `referrer`, `search`, `title` and `url`. This is automatically collected by Analytics.js. @@ -212,14 +210,14 @@ Context is a dictionary of extra information that provides useful context about `groupId` String Group / Account ID. - +

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. `traits` Object Dictionary of `traits` of the current user - +

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). @@ -307,63 +305,59 @@ Every API call has four timestamps, `originalTimestamp`, `timestamp`, `sentAt` a ### Timestamp Overview --- - + +

+ **Note:** `originalTimestamp` is not useful for analysis since it's not always trustworthy as it can be easily adjusted and affected by clock skew. - + - + - + @@ -377,7 +371,7 @@ The `originalTimestamp` tells you when call was invoked on the client device or **Note:** The `originalTimestamp` timestamp is not useful for any analysis since it's not always trustworthy as it can be easily adjusted and affected by clock skew. -### `sentAt` +### sentAt The `sentAt` timestamp specifies the clock time for the client's device when the network request was made to the Segment API. For libraries and systems that send batched requests, there can be a long gap between a datapoint's `timestamp` and `sentAt`. Combined with `receivedAt`, we can use `sentAt` to correct the original `timestamp` in situations where a user's device clock cannot be trusted (mobile phones and browsers). The `sentAt` and `receivedAt` timestamps are assumed to occur at the same time (maximum a few hundred milliseconds), and therefore the difference is the user's device clock skew, which can be applied back to correct the `timestamp`.
**Timestamp** **Calculated** **Description**
originalTimestamp`originalTimestamp` Time on the client device when call was invoked - +
**OR** - +
The `timestamp` value manually passed in through server-side libraries.
Used by Segment to calculate `timestamp`. - - **Note:** `originalTimestamp` is not useful for analysis since it's not always trustworthy as it can be easily adjusted and affected by clock skew. -
sentAt`sentAt` Time on client device when call was sent - +
**OR** - - `sentAt` value manually passed in. +
+ `sentAt` value manually passed in.
Used by Segment to calculate `timestamp`. - - **Note:** `sentAt` is not useful for analysis since it's not always trustworthy as it can be easily adjusted and affected by clock skew

+

+ **Note:** `sentAt` is not useful for analysis since it's not always trustworthy as it can be easily adjusted and affected by clock skew.
receivedAt`receivedAt` time on Segment server clock when call was received Used by Segment to calculate `timestamp`, and used as sort key in Warehouses. - +

**Note:** For max query speed, `receivedAt` is the recommended timestamp for analysis when chronology does not matter as chronology is not ensured.
timestamp`timestamp` Calculated by Segment to correct client-device clock skew using the following formula: - +
`receivedAt` - (`sentAt` - `originalTimestamp`)
Used by Segment to send to downstream destinations, and used for historical replays. - +

**Note:** Recommended timestamp for analysis when chronology does matter.