Context Object

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).

Layer	Answers	Fields
Identity	Who?	`userId`, `anonymousId`, `traits`
Event	What happened?	`event` / `name`, `properties`
Context	On 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

Field	Type	Description
`ip`	string	Client IP address. Useful for geo when sending from a server.
`locale`	string	Locale / language tag (for example `en-US`).
`timezone`	string	IANA timezone (for example `America/New_York`).
`userAgent`	string	Browser or client user-agent string. Helps infer web platform.

`library`

Which SDK or integration produced the event.

Field	Type	Description
`library.name`	string	Library name (for example `@zixflow/analytics-browser`, `@zixflow/analytics-node`)
`library.version`	string	Library version

`app`

Field	Type	Description
`app.name`	string	Application name
`app.version`	string	Marketing / semver version (for example `2.1.0`)
`app.build`	string	Build number (for example `403`)

`device`

Field	Type	Description
`device.id`	string	Device identifier when available
`device.manufacturer`	string	Manufacturer (for example `Apple`)
`device.model`	string	Model (for example `iPhone 14 Pro`)
`device.name`	string	User-facing device name when available
`device.type`	string	Platform hint: `ios`, `android`, or `web`

`os`

Field	Type	Description
`os.name`	string	OS name (for example `iOS`, `Android`)
`os.version`	string	OS version

`screen`

Display metrics (typically from mobile / browser SDKs).

Field	Type	Description
`screen.width`	number	Width in pixels
`screen.height`	number	Height in pixels
`screen.density`	number	Pixel density

`page`

Mostly used by the browser SDK for page views and tracks.

Field	Type	Description
`page.path`	string	URL path
`page.url`	string	Full URL
`page.referrer`	string	Referrer URL
`page.title`	string	Document title

`campaign`

UTM / campaign attribution (typically browser).

Field	Type	Description
`campaign.source`	string	`utm_source`
`campaign.medium`	string	`utm_medium`
`campaign.name`	string	`utm_campaign`
`campaign.term`	string	`utm_term`
`campaign.content`	string	`utm_content`

How Zixflow uses context

Platform detection (devices / push) prefers, in order:

context.device.type (ios / android / web)
context.os.name
context.library.name (browser libraries → web)
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:

Identify
Track
Screen
Page
Each item inside Batch

Zixflow AI

Sendflow

Events

WhatsApp

RCS

SMS

Email

Delivery Report

When to send it

Example

Field reference

Top-level

`library`

`app`

`device`

`os`

`screen`

`page`

`campaign`

How Zixflow uses context

Server-side example

What not to put in context

Applies to

​When to send it

​Example

​Field reference

​Top-level

​library

​app

​device

​os

​screen

​page

​campaign

​How Zixflow uses context

​Server-side example

​What not to put in context

​Applies to

When to send it

Example

Field reference

Top-level

`library`

`app`

`device`

`os`

`screen`

`page`

`campaign`

How Zixflow uses context

Server-side example

What not to put in context

Applies to