Common Fields

RudderStack defines some common fields (event type, timestamps, and more) across all API calls that make up the core event data structure.

This guide covers the common and contextual fields in detail.

Common fields

RudderStack also sets the following fields automatically, so you do not have to set them explicitly:

Contextual fields

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

Automatically collected contextual fields

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

Note that:

• For Android (Kotlin) and iOS (Swift) SDKs, you can still collect the fields marked as No** by adding Custom Plugins maintained by RudderStack in the sample applications of the Android (Kotlin) and iOS (Swift) SDKs on GitHub.
• For Android (Kotlin) SDK and Android (Java) 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 (Obj-C) SDK v1.6.3 and above, the Bluetooth status is not collected in the network.bluetooth field as it is a runtime 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"
    },
    "ip": "192.0.2.0",
    "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": 5.0,
    "review_body": "It's the greatest!"
  },
  "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",
    },
    "ip": "192.0.2.0",
    "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": 5.0,
    "review_body": "It's the greatest!"
  },
  "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",
    },
    "ip": "192.0.2.0",
    "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": 5.0,
    "review_body": "It's the greatest!"
  },
  "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.

Note that:

• The request_ip field is available in the final event received at the destination and in the Live Events.
• RudderStack leverages the automatically collected IP address for Geolocation Enrichment if enabled, allowing RudderStack to look up geographic information based on that IP address.

Set custom IP address

You can set a custom IP address or anonymize it in your events using two methods:

Method 1: Include IP in the context object (Recommended)

Set the IP address in the context.ip field:

rudderanalytics.identify(
  "1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
    firstName: "Alex",
    lastName: "Keener",
    email: "alex@example.com",
    phone: "+1-202-555-0146"
  }, {
    context: {
      ip: "192.0.2.0"
    }
  },
  () => {
    console.log("Identify event successfully submitted to the RudderStack SDK.");
  }
);

Method 2: Include IP in the request_ip field

Set the IP address directly in the request_ip field in the event payload:

{
  "type": "track",
  "event": "Page Viewed",
  "userId": "1hKOmRA4GRlm",
  "properties": {
    "page": "/home"
  },
  "request_ip": "192.168.1.100"  // Custom IP address
}

How RudderStack prioritizes IP address collection

RudderStack prioritizes the below fields when determining which IP address to use:

1. context.ip (if provided)
2. request_ip (if provided)
3. Fallback: Automatically detected IP from the request

RudderStack only adds the automatically captured IP address if no request_ip field exists, even if context.ip is already present in the event.

Clock skew considerations

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

Note that all the below timestamps are in UTC.

Important considerations for using timestamps in analysis

• RudderStack does not recommend using originalTimestamp and sentAt for analysis as they both reflect client-side clock skew. Likewise, receivedAt does not guarantee preservation of the chronological order of events, and should not be used for analysis where chronological order is needed.
• When importing historical events, use the timestamp field to preserve the chronological order.

SDK sources

If you do not specify the timestamp field in the payload for SDK sources, RudderStack calculates it based on the originalTimestamp and sentAt to account for the client clock skew.

sentAt > originalTimestamp is always true. However, timestamp can be greater or less than the originalTimestamp:

Case 1: originalTimestamp < receivedAt

When the client-side time is less than the time registered by RudderStack:

In this case, timestamp will be greater than originalTimestamp.

Case 2: originalTimestamp > receivedAt

When the client-side time is greater than the time registered by RudderStack:

In this case, timestamp will be less than originalTimestamp.

HTTP/Webhook-based sources

RudderStack does not consider any clock skew for HTTP/Webhook-based sources and uses the timestamp passed in the timestamp payload field.

Case 1: When the client-side time is less than the time registered by RudderStack:

Case 2: When the client-side time is greater than the time registered by RudderStack:

In the above cases, timestamp is the same as specified in the payload. RudderStack sets the originalTimestamp as the currentTime. You can add a transformation to correct the clock skew.

Case 3: If none of the originalTimestamp, sentAt, receivedAt, and timestamp fields are passed in the payload:

RudderStack sets the originalTimestamp and sentAt fields to the current time and calculates timestamp (same as receivedAt/current time).

Destinations

RudderStack gives priority to the timestamp field over originalTimestamp. Refer to the destination documentation for more details.

Timestamp mapping for Reverse ETL sources

When you map your warehouse columns to destination fields using JSON mapper, RudderStack prefers the timestamp to be set in the following event traits/properties (in the exact preference order):

Note that:

• If the timestamp is not present in any of the outermost timestamp fields, RudderStack takes the timestamp value from the originalTimestamp field (at the outermost level in the event payload).
• RudderStack generates the root level timestamp field and it changes every time a full sync is triggered.