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
-
-
-
| **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.
- |
+
+ **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.
|
@@ -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`.