Developer API - Common Data and Fields

Overview

Each call to Darwin includes some context information designed to help us with filtering and segmentation later.

Most of this "common" data will be included by default, when appropriate.

However, you may want to customize this context information to suit your use case.

How Common Fields Apply

When you're making a tracking or identification request, you can add context information like this:

darwinClient.track("User Registered", {
  plan: "Pro Annual",
  accountType: "Facebook",
  // now common fields can be added
  anonymousId: "random123",
  context: {
    // my context fields
  },
})

Standard Data for API Calls

Every request made to Darwin can include context information. Some of this information is set by use "implicitly" can be optionally set by you when you make a call.

Basic fields

Here are the basic fields

{
  "anonymousId": "randomId5555555555",
  "userId": "userId5555555",
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "receivedAt": "2024-12-10T00:00:00.000Z",
  "sentAt": "2024-12-10T00:00:00.000Z",
  "timestamp": "2024-12-10T00:00:00.000Z",
  "type": "track",
  "context": {
    // discussed below
  }
}

Field Type Description
anonymousIdstringA pseudo-unique substitute for a User ID. Will be set automatically if no userId outside of server analytics. (set implicitly)
userIdstringThe unique identifier for the user in your database. (optional)
contextobjectProvide standard context information to your request. (optional)

Context Data

Context is a dictionary of extra information that provides useful context about a datapoint, for example the user’s ip address or locale. You should only use Context fields for their intended meaning.

Context information is a set of extra information useful for analysis and segmenting. It is set based information from the user's device as well as information set on Darwin's server.

Field Type Description
activebooleanWhether an update was created by an active user. Set to false to prevent 'lastSeen' from being updated. (optional)
appobjectObject describing the current app. Collected automatically when possible. (optional)
localestringLocale language string for the device making the call. (set implicitly)
timezonestringThe user's time zone (set implicitly)
groupIdstringThe ID of any group or organization that the user should be associated with. (optional)
traitsobjectAn object of user traits to associate with the user making the request. (optional)
userAgentstringThe user agent of the device making a request (set implicitly)
campaignobjectObject describing the referring campaign that created a call. (optional)
Fields:
nameversionbuild
campaignobjectObject describing the referring campaign that created a call. (optional)
Fields:
namesourcemediumtermcontent
deviceobjectObject describing the device making the call. (implicit)
Fields:
idadvertisingIdmanufacturermodelnametypeversion
locationobjectObject describing the user's location. (optional)
Fields:
citycountrylatitudelongituderegionspeed
networkobjectObject describing the user's network. (optional)
Fields:
bluetoothcarriercellularwifi
osobjectObject describing the user's OS. (optional)
Fields:
nameversion
pageobjectObject describing the user's current web page (set implicitly)
Fields:
pathreferrersearchtitleurl
referrerobjectObject describing the how a user was referred to the app. (set implicitly)
Fields:
typenameurllink
screenobjectObject describing the user's screen. (set implicitly)
Fields:
densityheightwidth
libraryobjectObject describing the Darwin API library. (set implicitly)
Fields:
nameversion