70

Common fields

How it works

In general, your source calls will be short, but we capture much more information from our libraries and information implicit in each call, like:

• context for the source of your calls
• the ip and locale of the person the call represents
• timestamps that help you understand the chronology of your data

The added context these common fields provide can help you debug issues with your data or add special handling in actionsThe source event and data that triggers an API call to your destination. For example, an incoming identify event from your sources adds or updates a person in our Customer.io Journeys destination. for downstream applications.

A full payload

Imagine you send the track call (using our JavaScript source) below. The call itself simply contains the event name and a properties object:

analytics.track("Report Submitted", {
  reportType: "sales",
  reportFormat: "csv"
})

But, when you look at your call in Data Pipelines, you’ll see the complete payload below. Our libraries and API automatically capture the context, integrations, messageId, receivedAt, sentAt, version, type (which is implicit in the method/endpoint you call), and timestamp properties.

{
  "userId": "AiUGstSDIg",
  "event": "Report Submitted",
  "properties": {
    "reportType": "sales",
    "reportFormat": "csv"
  },
  "integrations": {
    "All": true
  },
  "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "context": {
    "active": true,
    "ip": "108.0.78.21",
    "locale": "string",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML like Gecko) Chrome/46.0.2490.86 Safari/537.36",
    "channel": "browser",
    "campaign": {
      "name": "string",
      "source": "string",
      "medium": "string",
      "term": "string",
      "content": "string",
    },
    "page": {
      "name": "string",
      "path": "/docs/",
      "referrer": null,
      "search": null,
      "title": "Customer.io Docs",
      "url": "https://customer.io/docs",
      "keywords": [
        "report"
      ]
    },
    "library": {
      "name": "analytics.js",
      "version": "2.11.1"
    }
  },
  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  "receivedAt": "2015-12-12T19:11:01.266Z",
  "sentAt": "2015-12-12T19:11:01.169Z",
  "type": "track",
  "originalTimestamp": "2015-12-12T19:11:01.152Z"
}

The context object

The context object contains useful information about the origin of a call, like the page the call originates from, or the ip address of the user the call represents.

You’ll notice slightly different context depending on whether the source of a call is a mobile SDK or non-mobile libraries. Our mobile libraries capture information about a device rather than a page.

If you use our server libraries, you’ll need to set this information yourself. Make sure that you use these properties for their originally-intended purpose; setting values that don’t make sense for the property can result in unexpected behaviors in downstream applications that rely on context.

Automatically-collected fields

Our JavaScript, mobile, and server libraries capture the information below.

For now, our mobile libraries collect very few fields but we’re working on changes that will increase the context they capture.

Our server-side libraries generally require you to send context and other common fields yourself. They’ll set the context.library property, but you should check with the appropriate documentation for the server library you use for help adding context to your calls.

The integrations object

By default, we send your source data to all destinations connected to the source. But you can limit a source call to a specific subset of destinations using the integrations object.

In general, we recommend that you filter calls for each destination using actionsThe source event and data that triggers an API call to your destination. For example, an incoming identify event from your sources adds or updates a person in our Customer.io Journeys destination., because they’re easier to change and manage than your source code. But you might want to modify the integrations object if:

• You have a destination that bills you for incoming API calls and you want to limit traffic to that destination.
• if you know that information in the individual call is only useful in specific downstream destinations.

To limit a call to specific destinations, you need to set "All": false and set true for the integrations you want to send to.

Within the integrations object, you need to use the integration name exactly as we show it at the top of every destination page in our catalog. For example, if you simply used Mixpanel below, we may not recognize the integration and send the call to your Mixpanel destination.

{
    "integrations": {
        "All": false,
        "Actions Customerio": true,
        "Google Analytics 4 Cloud": true,
        "Mixpanel (Actions)": true
    }
}

Timestamps

Every call includes ISO-8601 timestamps, originalTimestamp, timestamp, sentAt, and receivedAt, each with different purposes.

When analyzing your data, we recommend that you use receivedAt when chronology doesn’t matter and timestamp when it does. This is because receivedAt is typically correct but not guaranteed to be in chronological order, but the formula we apply to timestamp ensures that it is always in chronological order.

Reserved traits and properties in Customer.io

Some traits and properties in semantic events have special meanings within Customer.io. You should only use these fields for their intended purposes when you send data into your Customer.io Journeys destination(s).