The Context object

22 min

The Context Object

Every analytics event in the Chord CDP carries a context object alongside its properties. While properties describe what happened in the event, context describes the environment in which it happened — the page, the user's device, their location, and any identity traits that have been associated with them.

Destination plugins use context fields as fallback sources when event properties are not present. For example, a user's email set via an identify call will be available on all subsequent track events as context.traits.email.

How Context Is Populated

How context gets populated depends on whether the event originates from a browser (via the Chord SDK) or is sent server-to-server (S2S).

Browser Events

Browser events are those sent by the @chordcommerce/analytics SDK running in the user's browser. The SDK and Chord's ingest layer together populate context automatically — no extra configuration required:

Automatically by the Chord SDK

context.page — current URL, path, referrer, title

context.userAgent — browser user agent string

context.locale — browser locale (e.g. en-US)

context.library — SDK name and version

context.screen — screen dimensions and density

context.campaign — UTM parameters parsed from the URL

context.clientIds — third-party client IDs and ad click IDs, read from cookies, from the landing page URL, and from vendor SDKs already loaded on the page

From identify calls

When your code calls identify(userId, traits), the traits are stored and attached to all subsequent events as context.traits. This is the mechanism that makes user attributes like email, name, and address available on track events without repeating them in every event's properties.

Enriched at ingest (browser events only)

Chord's ingest layer adds the following from the HTTP request headers for browser-originated events:

context.ip — originating IP address

context.userAgent — extracted from the User-Agent header if not already set by the SDK

context.locale — extracted from the Accept-Language header if not already set by the SDK

context.page.url/path/search/host — populated from the HTTP Referer header if not already set

Server-to-Server (S2S) Events

S2S events are sent directly from your backend using a server-side write key. Because there is no browser involved, no context fields are added automatically — the ingest layer does not extract user agent, locale, or page data from S2S requests.

For S2S events, context contains only what you explicitly include in the event payload. If your server-side event should carry page, trait, or campaign context, you must attach it yourself before sending.

Recommended practice: When sending S2S events that correspond to a browser action (e.g. an order confirmation triggered server-side), forward the user agent and any UTM parameters your frontend captured, and include them in the event's context object.

Geolocation Enrichment

context.geo is resolved from context.ip and is only meaningful for browser events. For browser events, context.ip is captured automatically from the HTTP request, so geo fields are populated when GeoIP resolution is configured.

For S2S events, the originating IP belongs to your server, not the end user, so geolocation derived from it has no value. context.geo will not be present on S2S events.

Schema Reference

context.page

URL and navigation context for the current page. Populated automatically by the browser SDK for browser events. For S2S events, populate these fields manually if the event relates to a specific page.

Field	Type	Description
url	string	Full page URL
path	string	URL path component
host	string	Hostname
referrer	string	Referrer URL
referring_domain	string	Referrer hostname
search	string	Query string
title	string	Page title

context.traits

User traits from the most recent identify call. These persist across events for the browser session. Destination plugins use these as fallbacks when event properties do not carry the same information.

Standard Traits

Field	Type	Description
email	string	User email address
phone	string	Phone number
first_name	string	First name
last_name	string	Last name
name	string	Full name
address	object	See address schema below

context.traits.address

The standard address schema for context.traits.address aligns with the Chord tracking plan address conventions:

Field	Type	Description
address1	string	Street address line 1
address2	string	Street address line 2
city	string	City
state	string	State or province
country	string	Country
zipcode	string	Postal / ZIP code
name	string	Recipient name
company	string	Company name
phone	string	Address-specific phone number

Note: The event extractor also recognises legacy field names as fallbacks — street for address1, street2 for address2, and zip / postalCode for zipcode. These are supported for backwards compatibility but address1, address2, and zipcode are the canonical names.

context.clientIds

Identifiers for third-party tracking tools, including ad click IDs. These are what let a destination attribute a conversion back to the ad click, email, or session that caused it. They are also written to the warehouse, so they are available for attribution modelling even when no destination reads them.

They come from three places.

From browser cookies

Read on every event from cookies the vendor's own script sets. A field is absent until that script has run — and, where the vendor gates on consent, until the visitor has consented. An absent value is a normal state, not an error.

Field	Type	Cookie	Description
ga4.clientId	string	_ga	Google Analytics 4 client ID
ga4.sessionIds	any	_ga_*	GA4 session IDs, keyed by measurement ID
fbc	string	_fbc	Facebook click ID
fbp	string	_fbp	Facebook browser ID
gcl_aw	string	_gcl_aw	Google Ads click cookie
ttclid	string	ttclid	TikTok click ID
ttp	string	_ttp	TikTok browser ID
epik	string	_epik	Pinterest click ID
openai_oppref	string	__oppref	OpenAI Ads click identifier
openai_obref	string	__obref	OpenAI Ads browser reference
nosto_cid	string	2c.cId	Nosto session identifier
amplitudeSessionId	number	_amp_session	Amplitude session ID (Unix ms)

From the landing page URL

Click identifiers usually appear only on the URL of the page the visitor lands on. The SDK stores each one in the browser and replays it on every later event, so a visitor who lands on an ad and converts several pages later still carries the identifier that earned the conversion.

Stored values last 30 days. Most are cleared once an Order Completed event has been sent, so one click is not credited to two separate orders. Clearing happens after the event is sent, so the order event itself still carries the identifier.

URL parameter	Field	Cleared at purchase	Description
irclickid	irclickid	Yes	Impact click ID
im_ref	impact	Yes	Impact UTT referrer
_kx	klaviyo_kx	No	Klaviyo exchange ID, set on links in Klaviyo emails
brid	meta_brid	Yes	Meta in-app-browser reference
oppref	openai_oppref	Yes	OpenAI Ads click identifier
rdt_cid	reddit_rdt_cid	Yes	Reddit Ads click ID

_kx is the exception to the clear-at-purchase rule. It identifies a Klaviyo profile rather than crediting a single click, so there is nothing to de-duplicate at purchase, and it is kept for the full 30 days.

UTM parameters are captured by the same mechanism but surface under context.campaign rather than here.

From a vendor SDK on the page

Read directly from the vendor's SDK when it is already loaded, which avoids a race with cookie writes during SDK startup.

Field	Type	Description
amplitudeSessionId	number	Amplitude session ID, overriding the cookie value
amplitudeDeviceId	string	Amplitude device ID
posthog.sessionId	string	PostHog session ID, for joining events to session recordings
posthog.distinctId	string	PostHog distinct ID

Forwarded from a storefront integration

Shopify storefronts capture click IDs on the landing page, write them to cart attributes, and forward them with the order. These arrive on the event without the browser SDK having seen them, and include gclid, wbraid, gbraid, msclkid, fbclid, twclid, dclid, li_fat_id, sc_cid, irclickid, and im_ref.

context.clientIds is open-ended — a destination or transformation may add fields beyond those listed above.

context.campaign

UTM parameters parsed from the page URL.

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

context.geo

Geolocation data resolved from context.ip. Only present on browser events — for S2S events the originating IP is the server's IP, which has no meaningful geo value.

Field	Type	Description
country.code	string	ISO 3166-1 alpha-2 country code
country.name	string	Country name
region.code	string	Region / state code
region.name	string	Region / state name
city.name	string	City name
location.latitude	number	Latitude
location.longitude	number	Longitude

context.device

Mobile device information. Populated by mobile SDKs; typically absent for browser events.

Field	Type	Description
id	string	Device ID
type	string	Device type (e.g. ios, android)
manufacturer	string	Device manufacturer
model	string	Device model
name	string	Device name
advertisingId	string	Advertising ID (IDFA / GAID)
adTrackingEnabled	boolean	Whether ad tracking is enabled
token	string	Push notification token

context.os

Operating system information. Populated by mobile SDKs.

Field	Type	Description
name	string	OS name (e.g. iOS, Android)
version	string	OS version string

context.network

Network information. Populated by mobile SDKs.

Field	Type	Description
carrier	string	Mobile carrier name
wifi	boolean	Whether connected via WiFi
cellular	boolean	Whether connected via cellular
bluetooth	boolean	Whether Bluetooth is on

context.screen

Screen dimensions. Populated by the browser SDK and mobile SDKs.

Field	Type	Description
width	number	Screen width in pixels
height	number	Screen height in pixels
density	number	Pixel density (device pixel ratio)

context.app

Application metadata. Populated by mobile SDKs.

Field	Type	Description
name	string	App name
version	string	App version
build	string	Build number
namespace	string	App namespace / bundle ID

Other Fields

Field	Type	Description
ip	string	Originating IP address. Set automatically for browser events and used to populate context.geo. Not meaningful for S2S events (server IP, not user IP).
userAgent	string	Browser user agent string. Browser events only — not set on S2S events unless provided explicitly.
locale	string	Browser locale (e.g. en-US). Browser events only — not set on S2S events unless provided explicitly.
library.name	string	Chord SDK name
library.version	string	Chord SDK version

Updated 18 Aug 2026