Skip to main content
context is optional environment metadata about where and how an event was produced. It is not identity (userId, traits) and not business event data (event, properties).
LayerAnswersFields
IdentityWho?userId, anonymousId, traits
EventWhat happened?event / name, properties
ContextOn what device, app, page, or network?device, os, app, ip, locale, …
SDKs populate most of this automatically. When calling the HTTP API from your server, send only what you know (often just ip and/or library).

​
When to send it

  • From SDKs: Usually leave it alone — the SDK attaches context on every call.
  • From your backend: Include useful server-known fields such as ip, library, and optionally app.
  • Optional: Events are accepted without context. Richer context improves platform detection, segmentation, and debugging.

​
Example

{
  "context": {
    "ip": "203.0.113.1",
    "locale": "en-US",
    "timezone": "America/New_York",
    "userAgent": "Mozilla/5.0 ...",
    "library": {
      "name": "@zixflow/analytics-browser",
      "version": "2.x.x"
    },
    "app": {
      "name": "Acme",
      "version": "2.1.0",
      "build": "403"
    },
    "device": {
      "id": "device-uuid",
      "manufacturer": "Apple",
      "model": "iPhone 14 Pro",
      "type": "ios"
    },
    "os": {
      "name": "iOS",
      "version": "17.4.1"
    },
    "screen": {
      "width": 1170,
      "height": 2532,
      "density": 3
    },
    "page": {
      "path": "/pricing",
      "referrer": "https://google.com",
      "title": "Pricing",
      "url": "https://app.example.com/pricing"
    },
    "campaign": {
      "source": "google",
      "medium": "cpc",
      "name": "spring_sale",
      "term": "sneakers",
      "content": "ad_variant_a"
    }
  }
}
Omit any field you do not have. Nested objects may be partial.

​
Field reference

​
Top-level

FieldTypeDescription
ipstringClient IP address. Useful for geo when sending from a server.
localestringLocale / language tag (for example en-US).
timezonestringIANA timezone (for example America/New_York).
userAgentstringBrowser or client user-agent string. Helps infer web platform.

​
library

Which SDK or integration produced the event.
FieldTypeDescription
library.namestringLibrary name (for example @zixflow/analytics-browser, @zixflow/analytics-node)
library.versionstringLibrary version

​
app

FieldTypeDescription
app.namestringApplication name
app.versionstringMarketing / semver version (for example 2.1.0)
app.buildstringBuild number (for example 403)

​
device

FieldTypeDescription
device.idstringDevice identifier when available
device.manufacturerstringManufacturer (for example Apple)
device.modelstringModel (for example iPhone 14 Pro)
device.namestringUser-facing device name when available
device.typestringPlatform hint: ios, android, or web

​
os

FieldTypeDescription
os.namestringOS name (for example iOS, Android)
os.versionstringOS version

​
screen

Display metrics (typically from mobile / browser SDKs).
FieldTypeDescription
screen.widthnumberWidth in pixels
screen.heightnumberHeight in pixels
screen.densitynumberPixel density

​
page

Mostly used by the browser SDK for page views and tracks.
FieldTypeDescription
page.pathstringURL path
page.urlstringFull URL
page.referrerstringReferrer URL
page.titlestringDocument title

​
campaign

UTM / campaign attribution (typically browser).
FieldTypeDescription
campaign.sourcestringutm_source
campaign.mediumstringutm_medium
campaign.namestringutm_campaign
campaign.termstringutm_term
campaign.contentstringutm_content

​
How Zixflow uses context

Platform detection (devices / push) prefers, in order:
  1. context.device.type (ios / android / web)
  2. context.os.name
  3. context.library.name (browser libraries → web)
  4. Presence of userAgent → web
Context also supports segments (device type, OS, app version), locale/timezone-aware messaging, and debugging which client produced an event.

​
Server-side example

Minimal context from a backend track call: 
{
  "userId": "user_123",
  "event": "Order Fulfilled",
  "properties": {
    "order_id": "ord_789"
  },
  "context": {
    "ip": "203.0.113.1",
    "library": {
      "name": "acme-fulfillment",
      "version": "1.0.0"
    }
  }
}

​
What not to put in context

  • Business event details → use properties (track / screen / page)
  • Durable user profile fields → use identify traits
  • Required identity → use userId and/or anonymousId

​
Applies to

context can be sent on: