> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zixflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Object

> Environment metadata attached to identify, track, screen, page, and batch events

`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

```json theme={null}
{
  "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:

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:

```json theme={null}
{
  "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](/api-reference/zixflow-ai/events/identify)
* [Track](/api-reference/zixflow-ai/events/track)
* [Screen](/api-reference/zixflow-ai/events/screen)
* [Page](/api-reference/zixflow-ai/events/page)
* Each item inside [Batch](/api-reference/zixflow-ai/events/batch)