Common Fields | RudderStack Docs

Every RudderStack API call shares the same common fields that define the core event data structure. The following table describes the common fields in every call.

Name	Data type	Description
`anonymousId` Required	String	Unique identification for the user. This is the same as the `deviceId`.
`channel` Required	String	Identifies the source of the event. Permitted values are `mobile`, `web`, `server`, and `sources`.
`context` Required	Object	Contains all the additional user information. The RudderStack SDKs populate this information automatically.
`type` Required	String	Captures the type of event. Values can be either `track`, `screen`, `identify`, `page`.
`originalTimestamp` Required	Timestamp	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` Required	Timestamp	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`.
`event`	String	Captures the user action that you want to record.
`integrations`	Object	You can specify the destinations for which you want to enable/disable sending events.
`messageId`	String	Unique identification for the event.
`properties`	Object	Passes all the relevant information associated with the event.

Upon receving an 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.

Contextual fields

Contextual fields give additional information about a particular event. The following table describes the available contextual fields.

Name	Data type	Description
`app`	Object	Gives detailed information related to your app, like `build`, `name`, `namespace` and `version`.
`campaign`	Object	Gives detailed information about campaigns, like `name`, `source`, `medium`, `content` and `term`.
`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.
`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 from the previously-made `identify` call from the SDK.
`userAgent`	String	The user agent of the device that you are tracking.

Automatically collected contextual fields

The following table describes contextual fields that are automatically collected and populated by the RudderStack SDKs:

Field	JavaScript	Android	iOS	Description
`app.name`	-	Yes	Yes	Name of the application.
`app.version`	-	Yes	Yes	Version of the application.
`app.build`	-	Yes	Yes	Build of the application.
`campaign.name`	Yes	-	-	Name of the campaign.
`campaign.source`	Yes	-	-	Source of the campaign.
`campaign.medium`	Yes	-	-	Medium of the campaign.
`campaign.term`	Yes	-	-	Term of the campaign.
`campaign.content`	Yes	-	-	Content of the campaign.
`device.type`	-	Yes	Yes	Type of the device.
`device.id`	-	Yes	Yes	ID of the device.
`device.advertisingId`	-	Yes	Yes	Advertising ID of the device.
`device.adTrackingEnabled`	-	-	Yes	If ad tracking is enabled on the device.
`device.manufacturer`	-	Yes	Yes	Manufacturer of the device.
`device.model`	-	Yes	Yes	Model of the device.
`device.name`	-	Yes	Yes	Name of the device.
`library.name`	Yes	Yes	Yes	Name of the library.
`library.version`	Yes	Yes	Yes	Version of the library.
`locale`	Yes	Yes	Yes	Locale string of the user.
`network.bluetooth`	-	Yes*	-	Bluetooth information.
`network.carrier`	-	Yes	Yes	Carrier information about the network connection.
`network.cellular`	-	Yes	Yes	Cellular information about the network connection.
`network.wifi`	-	Yes	Yes	WiFi information about the network connection.
`os.name`	-	Yes	Yes	Name of the operating system.
`os.version`	-	Yes	Yes	Version of the operating system.
`page.path`	Yes	-	-	Path of the current page in the browser.
`page.initial_referrer`	Yes	-	-	Initial referrer of the current page in the browser.
`page.initial_referring_domain`	Yes	-	-	Initial referring domain of the current page in the browser.
`page.referrer`	Yes	-	-	Referrer of the current page in the browser.
`page.referring_domain`	Yes	-	-	Referring domain of the current page in the browser.
`page.search`	Yes	-	-	Search of the current page in the browser.
`page.title`	Yes	-	-	Title of the current page in the browser.
`page.url`	Yes	-	-	URL of the current page in the browser.
`screen.density`	Yes	Yes	Yes	Density of the device's screen.
`screen.height`	Yes	Yes	Yes	Height of the device's screen.
`screen.width`	Yes	Yes	Yes	Width of the device's screen.
`screen.innerWidth`	Yes	-	-	Inner width of the device's screen.
`screen.innerHeight`	Yes	-	-	Inner height of the device's screen.
`traits`	-	Yes	Yes	Traits of the user.
`userAgent`	Yes	Yes	-	User agent of the device making the request.
`timezone`	-	Yes	Yes	Information about the user's timezone.

For Android SDK v1.6.0 and above, the Bluetooth status is collected in the network.bluetooth field only if the Bluetooth permission is present in the app.
For iOS SDK v1.6.3 and above, the Bluetooth status is not collected in the network.bluetooth field as it is a run-time permission.

Sample payload with contextual fields

The following sample payload highlights the usage of the common and contextual fields in web and mobile modes:

{
  "anonymousId": "78c53c15-32a1-4b65-adac-bec2d7bb8fab",
  "channel": "web",
  "context": {
    "campaign": {
      "name": "sales campaign",
      "source": "google",
      "medium": "medium",
      "term": "event data",
      "content": "Make sense of the modern data stack"
    },
    "library": {
      "name": "RudderLabs JavaScript SDK",
      "version": "2.9.1"
    },
    "locale": "en-US",
    "page": {
      "path": "/best-seller/1",
      "initial_referrer": "https://www.google.com/search",
      "initial_referring_domain": "google.com",
      "referrer": "https://www.google.com/search?q=estore+bestseller",
      "referring_domain": "google.com",
      "search": "estore bestseller",
      "title": "The best sellers offered by EStore",
      "url": "https://www.estore.com/best-seller/1"
    },
    "screen": { 
      "density": 420, 
      "height": 1794, 
      "width": 1080, 
      "innerHeight": 200, 
      "innerWidth": 100 
      },
    "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"
}

{
  "anonymousId": "78c53c15-32a1-4b65-adac-bec2d7bb8fab",
  "channel": "mobile",
  "context": {
    "app": {
      "name": "RudderAndroidClient",
      "version": "1.0",
      "build": "1"
    },
    "device": {
      "type": "android",
      "id": "78c53c15-32a1-4b65-adac-bec2d7bb8fab",
      "advertisingId":"435o4GRlm",
      "manufacturer": "Google",
      "model": "Android SDK built for x86",
      "name": "generic_x86",
    },
    "library": {
      "name": "com.rudderstack.android.sdk.core",
      "version": "0.1.4"
    },
    "locale": "en-US",
    "network": {
      "bluetooth": false,
      "carrier": "Android",
      "cellular": true,
      "wifi": true
    },
    "os": { 
      "name": "Android", 
      "version": "9" 
      },
    "screen": { 
      "density": 420, 
      "height": 1794, 
      "width": 1080 
      },
     "traits": { 
      "anonymousId": "78c53c15-32a1-4b65-adac-bec2d7bb8fab" 
      },
    "timezone": "Asia/Mumbai",
    "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"
}

{
  "anonymousId": "78c53c15-32a1-4b65-adac-bec2d7bb8fab",
  "channel": "mobile",
  "context": {
    "app": {
      "name": "RudderSampleAppObjC",
      "version": "1.0",
      "build": "1"
    },
    "device": {
      "type": "iOS",
      "id": "78c53c15-32a1-4b65-adac-bec2d7bb8fab",
      "advertisingId":"435o4GRlm",
      "adTrackingEnabled": false,
      "manufacturer": "Apple",
      "model": "iPhone",
      "name": "iPhone 12",
    },
    "library": {
      "name": "rudder-ios-library",
      "version": "1.5.0"
    },
    "locale": "en-US",
    "network": {
      "carrier": "unavailable",
      "cellular": false,
      "wifi": true
    },
    "os": { 
      "name": "iOS", 
      "version": "15.2" 
      },
    "screen": { 
      "height": 1794, 
      "width": 1080 
      },
     "traits": { 
      "anonymousId": "78c53c15-32a1-4b65-adac-bec2d7bb8fab" 
      },
    "timezone": "Asia/Mumbai"
  },
  "event": "Product Reviewed",
  "integrations": { 
    "All": true 
    },
  "messageId": "1643629072-8ce81faf-7489-4508-b21b-659e81510991",
  "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"
}

How RudderStack collects IP address

RudderStack automatically collects the user's IP address in the request_ip property as a common field. You can see it in the event received at the destination but not in the Live Events tab. This is because RudderStack adds the IP in the backend while sending the event sent to the destination; it is not a part of the initial event data generated at the source.

You can also specify the ip field explicitly to anonymize the IP address, in which case it will be captured as a contextual field at the source itself.

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.

Merge

Contact us

For more information on the topics covered on this page, email us or start a conversation in our Slack community.

Contextual fields

Automatically collected contextual fields

Sample payload with contextual fields

How RudderStack collects IP address

Clock skew considerations

Case 1: `originalTimestamp` < `receivedAt`

Case 2: `originalTimestamp` > `receivedAt`

Merge

E-commerce Events

Contact us

On this page

Contextual fields

Automatically collected contextual fields

Sample payload with contextual fields

How RudderStack collects IP address

Clock skew considerations

Case 1: originalTimestamp < receivedAt

Case 2: originalTimestamp > receivedAt

Merge

E-commerce Events

Contact us

@media (max-width: 1200px){.css-1x56nmx{display:none;}}On this page

Case 1: `originalTimestamp` < `receivedAt`

Case 2: `originalTimestamp` > `receivedAt`

On this page