diff --git a/src/connections/spec/common.md b/src/connections/spec/common.md index 953e511b48..5365133287 100644 --- a/src/connections/spec/common.md +++ b/src/connections/spec/common.md @@ -120,52 +120,59 @@ Beyond this common structure, each API call adds a few specialized top-level fie Context is a dictionary of extra information that provides useful context about a datapoint, for example the user's `ip` address or `locale`. Context is a complete and explicit specification, so properties outside the spec are ignored. You should **only use** Context fields for their intended meaning. - {% include content/spec-table-header.md %} + + + + + - + - - + - + - + - + - + @@ -181,7 +188,8 @@ Context is a dictionary of extra information that provides useful context about @@ -197,21 +205,22 @@ Context is a dictionary of extra information that provides useful context about - + + 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. + + 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). @@ -309,52 +318,59 @@ Every API call has four timestamps, `originalTimestamp`, `timestamp`, `sentAt` a
**Field****Type****Description**
`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."

+ + This is usually used to flag an `.identify()` call to just update the traits but not "last seen."
`app` `app` Object dictionary of information about the current application, containing `name`, `version` and `build`. -

This is collected automatically from our mobile libraries when possible.

+ + This is collected automatically from our mobile libraries when possible.
`campaign` ObjectDictionary 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.

+ 		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.
`device` ObjectDictionary of information about the device, containing `id`, `manufacturer`, `model`, `name`, `type` and `version`Dictionary of information about the device, containing `id`, `manufacturer`, `model`, `name`, `type` and `version`.
`ip` StringCurrent user's IP addressCurrent user's IP address.
`library` ObjectDictionary of information about the library making the requests to the API, containing `name` and `version`Dictionary of information about the library making the requests to the API, containing `name` and `version`.
`locale` StringLocale string for the current user, for example `en-US`Locale string for the current user, for example `en-US`.
`location` ObjectDictionary of information about the user's current location, containing `city`, `country`, `latitude`, `longitude`, `region` and `speed`Dictionary of information about the user's current location, containing `city`, `country`, `latitude`, `longitude`, `region` and `speed`.
`network``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.

+ + Automatically collected by Analytics.js.
`timezone` StringTimezones are sent as tzdata strings to add user timezone information which might be stripped from the timestamp -

Ex: `America/New_York`

+ 		Timezones are sent as tzdata strings to add user timezone information which might be stripped from the timestamp, for example `America/New_York`
`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).
`userAgent`
originalTimestamp -

Time on the client device when call was invoked

-

**OR**

-

`timestamp` value manually passed in through server-side libraries

+ 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

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

Time on client device when call was sent

-

**OR**

-

`sentAt` value manually passed in

+ Time on client device when call was sent + + **OR** + + `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

+ 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
receivedAt time on Segment server clock when call was received -

Used by Segment to calculate `timestamp`

-

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

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

Calculated by Segment to correct client-device clock skew using the following formula:

-

`receivedAt` - (`sentAt` - `originalTimestamp`)

+ Calculated by Segment to correct client-device clock skew using the following formula: + + `receivedAt` - (`sentAt` - `originalTimestamp`) 		-

Used by Segment to send to downstream destinations

-

Used for historical replays

-

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

+ Used by Segment to send to downstream destinations, and used for historical replays. + + **Note:** Recommended timestamp for analysis when chronology does matter.
-### `originalTimestamp` +### originalTimestamp The `originalTimestamp` tells you when call was invoked on the client device or the value of `timestamp` that you manually passed in. @@ -368,7 +384,7 @@ The `sentAt` timestamp specifies the clock time for the client's device when the **Note:** The `sentAt` timestamp is not useful for any analysis since it's tainted by user's clock skew. -### `receivedAt` +### receivedAt The `receivedAt` timestamp is added to incoming messages as soon as they hit our API. It's used in combination with `sentAt` to correct clock skew, and also to aid with debugging libraries and systems that deliver events in batches. @@ -376,7 +392,7 @@ The `receivedAt` timestamp is most important as the sort key in our Warehouses p **Note:** Chronological order of events is not ensured with `receivedAt`. -### `timestamp` +### timestamp The `timestamp` timestamp specifies when the datapoint occurred, corrected for client-device clock skew. This is the timestamp that is passed to downstream destinations and used for historical replays. It is important to use this timestamp for importing historical data to the API.