> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/rudderstack-api/api-specification/rudderstack-spec/common-fields.md).

# Common Fields

Detailed technical description of the common fields that define the core event data structure.

The common fields define the core event data structure in RudderStack. These fields also contain vital information about the event and the source platform.

Every RudderStack API call shares the same common fields.

The following table lists all the common fields with their detailed description:

| Name                | Data type | Presence | Description                                                                                                                                                                                   |
| ------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `anonymousId`       | String    | Required | Unique identification for the user. This is the same as the `deviceId`.                                                                                                                       |
| `channel`           | String    | Required | Identifies the source of the event. Permitted values are `mobile`, `web`, `server`.                                                                                                           |
| `context`           | Object    | Required | Contains all the additional user information. The RudderStack SDKs populate this information automatically.                                                                                   |
| `event`             | String    | Optional | Captures the user action that you want to record.                                                                                                                                             |
| `type`              | String    | Required | Captures the type of event. Values can be either `track`, `screen`, `identify`, `page`.                                                                                                       |
| `integrations`      | Object    | Optional | You can specify the destinations for which you want to enable/disable sending events.                                                                                                         |
| `messageId`         | String    | Optional | Unique identification for the event.                                                                                                                                                          |
| `properties`        | Object    | Optional | Passes all the relevant information associated with the event.                                                                                                                                |
| `originalTimestamp` | DateTime  | Required | Records the actual time when the event occurred. Make sure it conforms to the ISO 8601 date format `yyyy-MM-ddTHH:mm:ss.SSSZ`. For e.g., `2022-02-01T19:14:18.381Z`.                          |
| `sentAt`            | DateTime  | Required | Captures the time when the event was sent from the client to RudderStack. Make sure it conforms to the ISO 8601 date format `yyyy-MM-ddTHH:mm:ss.SSSZ`. For e.g., `2022-02-01T19:14:18.381Z`. |

Upon receving the event, RudderStack also sets `receivedAt` - the timestamp when the event is ingested(received). You need not set this field explicitly when sending the events to RudderStack.

## Clock skew considerations

RudderStack considers the time at its end to be absolute and assumes any difference on the client-side. Thus, the client clock skew is relative.

If not specified in the payload explicitly, RudderStack calculates `timestamp` based on `originalTimestamp` and `sentAt` to account for the client clock skew.

As mentioned in the above section:

| Field               | Description                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `originalTimestamp` | Records the actual time when the event occurred at the source.                                                                 |
| `sentAt`            | Captures the time when the event was sent from the client to RudderStack.                                                      |
| `receivedAt`        | The timestamp when the event is received(ingested) by the RudderStack server.                                                  |
| `timestamp`         | Calculated by RudderStack to account for the client clock skew, **IF** the user does not explicitly specify it in the payload. |

`sentAt` > `originalTimestamp` is **always true**. However, `timestamp` can be more or less than the `originalTimestamp`. Refer to the cases below for more details.

### Case 1: `originalTimestamp` < `receivedAt`

The following table demonstrates an example of `originalTimestamp` < `receivedAt`(when the client-side time is less than the time registered by RudderStack):

| originalTimestamp       | sentAt                  | receivedAt              | timestamp = receivedAt - (sentAt - originalTimestamp) |
| ----------------------- | ----------------------- | ----------------------- | ----------------------------------------------------- |
| 2020-04-26 07:00:43.400 | 2020-04-26 07:00:45.124 | 2020-04-26 07:00:45.558 | 2020-04-26 07:00:44.834                               |

In this case, `timestamp` will be **greater** than `originalTimestamp`.

### Case 2: `originalTimestamp` > `receivedAt`

The following table demonstrates an example of `originalTimestamp` > `receivedAt`(when the client-side time is more than the time registered by RudderStack):

| originalTimestamp       | sentAt                  | receivedAt              | timestamp = receivedAt - (sentAt - originalTimestamp) |
| ----------------------- | ----------------------- | ----------------------- | ----------------------------------------------------- |
| 2020-04-26 07:00:45.558 | 2020-04-26 07:00:46.124 | 2020-04-26 07:00:43.400 | 2020-04-26 07:00:43.965                               |

In this case, `timestamp` will be **less** than `originalTimestamp`.

## Contextual fields

The contextual fields give additional useful context about a particular event.

The following table lists all the contextual fields with their detailed description:

| Name        | Data type | Description                                                                                                                                                                                                                                                                                                            |
| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app`       | Object    | Gives detailed information related to your app, like `build`, `name`, `namespace` and `version`.                                                                                                                                                                                                                       |
| `device`    | Object    | Information about the device from which you are capturing the event. It contains `deviceId`, `manufacturer`, `model`, `name` and `type`.                                                                                                                                                                               |
| `library`   | Object    | Details about the RudderStack SDK you are using, like `name` and `version`.                                                                                                                                                                                                                                            |
| `locale`    | String    | Captures the language of the device.                                                                                                                                                                                                                                                                                   |
| `ip`        | String    | The user's IP address.                                                                                                                                                                                                                                                                                                 |
| `network`   | Object    | Contains information about the reachability of the device. Also, it gives you the status of the device's `bluetooth`, `wifi`, `cellular` network and `carrier` name.                                                                                                                                                   |
| `os`        | Object    | Captures the operating system details of the device you are tracking.                                                                                                                                                                                                                                                  |
| `screen`    | Object    | Gives you the screen dimensions of the device, i.e. `height`, `width` and the `density`.                                                                                                                                                                                                                               |
| `timezone`  | String    | Captures the timezone of the user you are tracking.                                                                                                                                                                                                                                                                    |
| `traits`    | Object    | Captures any additional relevant information about the user. RudderStack fills in the `anonymousId` for you. You can also associate the [**traits**](https://rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/identify/#identify-traits) from the previously-made `identify` call from the SDK. |
| `userAgent` | String    | The user agent of the device that you are tracking.                                                                                                                                                                                                                                                                    |
| `campaign`  | Object    | Gives detailed information about campaigns, like `name`, `source`, `medium`, `content` and `term`.                                                                                                                                                                                                                     |

**Not all of the above contextual fields are automatically collected by the RudderStack SDKs.** Refer to the following sections for more information on which SDK automatically populates what contextual fields.

The following sections highlight all the contextual fields that are automatically collected and populated by each of the RudderStack SDKs:

### JavaScript SDK

| Field                      | Automatically Collected? |
| -------------------------- | ------------------------ |
| `app.name`                 | -                        |
| `app.version`              | -                        |
| `app.build`                | -                        |
| `campaign.name`            | Yes                      |
| `campaign.source`          | Yes                      |
| `campaign.medium`          | Yes                      |
| `campaign.term`            | Yes                      |
| `campaign.content`         | Yes                      |
| `device.type`              | -                        |
| `device.advertisingId`     | -                        |
| `device.adTrackingEnabled` | -                        |
| `device.manufacturer`      | -                        |
| `device.model`             | -                        |
| `library.name`             | Yes                      |
| `library.version`          | Yes                      |
| `ip`                       | Yes                      |
| `locale`                   | Yes                      |
| `location.latitude`        | -                        |
| `location.longitude`       | -                        |
| `location.speed`           | -                        |
| `network.bluetooth`        | -                        |
| `network.carrier`          | -                        |
| `network.cellular`         | -                        |
| `network.wifi`             | -                        |
| `os.name`                  | -                        |
| `os.version`               | -                        |
| `page.path`                | Yes                      |
| `page.referrer`            | Yes                      |
| `page.search`              | Yes                      |
| `page.title`               | Yes                      |
| `page.url`                 | Yes                      |
| `screen.density`           | -                        |
| `screen.height`            | -                        |
| `screen.width`             | -                        |
| `traits`                   | -                        |
| `userAgent`                | Yes                      |
| `timezone`                 | -                        |

### Android SDK

| Field                      | Automatically Collected? |
| -------------------------- | ------------------------ |
| `app.name`                 | Yes                      |
| `app.version`              | Yes                      |
| `app.build`                | Yes                      |
| `campaign.name`            | -                        |
| `campaign.source`          | -                        |
| `campaign.medium`          | -                        |
| `campaign.term`            | -                        |
| `campaign.content`         | -                        |
| `device.type`              | Yes                      |
| `device.id`                | Yes                      |
| `device.advertisingId`     | Yes                      |
| `device.adTrackingEnabled` | -                        |
| `device.manufacturer`      | Yes                      |
| `device.model`             | Yes                      |
| `device.name`              | Yes                      |
| `library.name`             | Yes                      |
| `library.version`          | Yes                      |
| `ip`                       | Yes                      |
| `locale`                   | Yes                      |
| `network.bluetooth`        | Yes                      |
| `network.carrier`          | Yes                      |
| `network.cellular`         | Yes                      |
| `network.wifi`             | Yes                      |
| `os.name`                  | Yes                      |
| `os.version`               | Yes                      |
| `page.path`                | -                        |
| `page.referrer`            | -                        |
| `page.search`              | -                        |
| `page.title`               | -                        |
| `page.url`                 | -                        |
| `screen.density`           | Yes                      |
| `screen.height`            | Yes                      |
| `screen.width`             | Yes                      |
| `traits`                   | Yes                      |
| `userAgent`                | Yes                      |
| `timezone`                 | Yes                      |

### iOS SDK

| Field                      | Automatically Collected? |
| -------------------------- | ------------------------ |
| `app.name`                 | Yes                      |
| `app.version`              | Yes                      |
| `app.build`                | Yes                      |
| `campaign.name`            | -                        |
| `campaign.source`          | -                        |
| `campaign.medium`          | -                        |
| `campaign.term`            | -                        |
| `campaign.content`         | -                        |
| `device.type`              | -                        |
| `device.id`                | Yes                      |
| `device.advertisingId`     | Yes                      |
| `device.adTrackingEnabled` | Yes                      |
| `device.manufacturer`      | Yes                      |
| `device.model`             | Yes                      |
| `device.name`              | -                        |
| `library.name`             | Yes                      |
| `library.version`          | Yes                      |
| `ip`                       | Yes                      |
| `locale`                   | Yes                      |
| `network.bluetooth`        | -                        |
| `network.carrier`          | Yes                      |
| `network.cellular`         | Yes                      |
| `network.wifi`             | Yes                      |
| `os.name`                  | Yes                      |
| `os.version`               | Yes                      |
| `page.path`                | -                        |
| `page.referrer`            | -                        |
| `page.search`              | -                        |
| `page.title`               | -                        |
| `page.url`                 | -                        |
| `screen.density`           | -                        |
| `screen.height`            | Yes                      |
| `screen.width`             | Yes                      |
| `traits`                   | Yes                      |
| `userAgent`                | -                        |
| `timezone`                 | Yes                      |

## Sample payload with common fields

The following sample payload highlights how the above common and contextual fields are used:

```json
{
  "anonymousId": "7e32188a4dab669f",
  "channel": "mobile",
  "context": {
    "app": {
      "build": "1",
      "name": "RudderAndroidClient",
      "namespace": "com.rudderstack.demo.android",
      "version": "1.0"
    },
    "device": {
      "id": "7e32188a4dab669f",
      "manufacturer": "Google",
      "model": "Android SDK built for x86",
      "name": "generic_x86",
      "type": "android"
    },
    "library": {
      "name": "com.rudderstack.android.sdk.core",
      "version": "0.1.4"
    },
    "locale": "en-US",
    "network": {
      "carrier": "Android",
      "bluetooth": false,
      "cellular": true,
      "wifi": true
    },
    "campaign": {
      "source": "google",
      "medium": "medium",
      "term": "keyword",
      "content": "some content",
      "name": "some campaign"
    },
    "os": { "name": "Android", "version": "9" },
    "screen": { "density": 420, "height": 1794, "width": 1080 },
    "timezone": "Asia/Mumbai",
    "traits": { "anonymousId": "7e32188a4dab669f" },
    "userAgent": "Dalvik/2.1.0 (Linux; U; Android 9; Android SDK built for x86 Build/PSR1.180720.075)"
  },
  "event": "Product Reviewed",
  "integrations": { "All": true },
  "messageId": "1578564113557-af022c68-429e-4af4-b99b-2b9174056383",
  "properties": {
    "review_id": "review_id_1",
    "product_id": "product_id_1",
    "rating": 2.0,
    "review_body": "Sample Review Body"
  },
  "originalTimestamp": "2020-01-09T10:01:53.558Z",
  "type": "track",
  "sentAt": "2020-01-09T10:02:03.257Z"
}
```

## Contact us

For more information on the common fields, feel free to [**contact us**](mailto:%20docs@rudderstack.com) or start a conversation in our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community) community.