No Result

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:

NameData typePresenceDescription
anonymousIdStringRequiredUnique identification for the user. This is the same as the deviceId.
channelStringRequiredIdentifies the source of the event. Permitted values are mobile, web, server.
contextObjectRequiredContains all the additional user information. The RudderStack SDKs populate this information automatically.
eventStringOptionalCaptures the user action that you want to record.
typeStringRequiredCaptures the type of event. Values can be either track, screen, identify, page.
integrationsObjectOptionalYou can specify the destinations for which you want to enable/disable sending events.
messageIdStringOptionalUnique identification for the event.
propertiesObjectOptionalPasses all the relevant information associated with the event.
originalTimestampDateTimeRequiredRecords 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.
sentAtDateTimeRequiredCaptures 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:

FieldDescription
originalTimestampRecords the actual time when the event occurred at the source.
sentAtCaptures the time when the event was sent from the client to RudderStack.
receivedAtThe timestamp when the event is received(ingested) by the RudderStack server.
timestampCalculated 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):

originalTimestampsentAtreceivedAttimestamp = receivedAt - (sentAt - originalTimestamp)
2020-04-26 07:00:43.4002020-04-26 07:00:45.1242020-04-26 07:00:45.5582020-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):

originalTimestampsentAtreceivedAttimestamp = receivedAt - (sentAt - originalTimestamp)
2020-04-26 07:00:45.5582020-04-26 07:00:46.1242020-04-26 07:00:43.4002020-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:

NameData typeDescription
appObjectGives detailed information related to your app, like build, name, namespace and version.
deviceObjectInformation about the device from which you are capturing the event. It contains deviceId, manufacturer, model, name and type.
libraryObjectDetails about the RudderStack SDK you are using, like name and version.
localeStringCaptures the language of the device.
ipStringThe user's IP address.
networkObjectContains information about the reachability of the device. Also, it gives you the status of the device's bluetooth, wifi, cellular network and carrier name.
osObjectCaptures the operating system details of the device you are tracking.
screenObjectGives you the screen dimensions of the device, i.e. height, width and the density.
timezoneStringCaptures the timezone of the user you are tracking.
traitsObjectCaptures 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.
userAgentStringThe user agent of the device that you are tracking.
campaignObjectGives 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

FieldAutomatically Collected?
app.name-
app.version-
app.build-
campaign.nameYes
campaign.sourceYes
campaign.mediumYes
campaign.termYes
campaign.contentYes
device.type-
device.advertisingId-
device.adTrackingEnabled-
device.manufacturer-
device.model-
library.nameYes
library.versionYes
ipYes
localeYes
location.latitude-
location.longitude-
location.speed-
network.bluetooth-
network.carrier-
network.cellular-
network.wifi-
os.name-
os.version-
page.pathYes
page.referrerYes
page.searchYes
page.titleYes
page.urlYes
screen.density-
screen.height-
screen.width-
traits-
userAgentYes
timezone-

Android SDK

FieldAutomatically Collected?
app.nameYes
app.versionYes
app.buildYes
campaign.name-
campaign.source-
campaign.medium-
campaign.term-
campaign.content-
device.typeYes
device.idYes
device.advertisingIdYes
device.adTrackingEnabled-
device.manufacturerYes
device.modelYes
device.nameYes
library.nameYes
library.versionYes
ipYes
localeYes
network.bluetoothYes
network.carrierYes
network.cellularYes
network.wifiYes
os.nameYes
os.versionYes
page.path-
page.referrer-
page.search-
page.title-
page.url-
screen.densityYes
screen.heightYes
screen.widthYes
traitsYes
userAgentYes
timezoneYes

iOS SDK

FieldAutomatically Collected?
app.nameYes
app.versionYes
app.buildYes
campaign.name-
campaign.source-
campaign.medium-
campaign.term-
campaign.content-
device.type-
device.idYes
device.advertisingIdYes
device.adTrackingEnabledYes
device.manufacturerYes
device.modelYes
device.name-
library.nameYes
library.versionYes
ipYes
localeYes
network.bluetooth-
network.carrierYes
network.cellularYes
network.wifiYes
os.nameYes
os.versionYes
page.path-
page.referrer-
page.search-
page.title-
page.url-
screen.density-
screen.heightYes
screen.widthYes
traitsYes
userAgent-
timezoneYes

Sample payload with common fields

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

{
  "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 or start a conversation in our Slack community.

Contents