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 (ga4, facebook, amplitude) read from cookies 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 always populated 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 advertising and analytics identifiers belonging to third party platforms these are what allow a conversion sent from chord to be matched back to the ad click, session, or profile that the destination platform already knows about, so they have a direct effect on match rates and attribution quality identifiers come from two places cookies , read fresh on every event, and url parameters , captured when the visitor lands and persisted for later events everything in this section is omitted entirely when the sdk is configured with privacy disableuserids read from cookies read on every event from the visitor's cookies field type source description ga4 clientid string ga google analytics 4 client id ga4 sessionids object ga ga4 session ids, keyed by measurement id (the ga prefix is stripped) fbc string fbc facebook click id fbp string fbp facebook browser id gcl aw string gcl aw google ads click id cookie, set by google's auto tagging ttp string ttp tiktok pixel cookie id ttclid string ttclid tiktok click id epik string epik pinterest click id amplitudesessionid string amp session amplitude session id amplitudedeviceid string live sdk amplitude device id posthog sessionid string live sdk posthog session id — used to join chord forwarded events to posthog session recordings posthog distinctid string live sdk posthog distinct id note for amplitude and posthog, chord pixel reads the values from the live sdk on the page when it is loaded, falling back to the cookie reading the live sdk avoids a race condition where an event fires before the vendor sdk has finished writing its cookie captured from url parameters some platforms pass their identifier as a query parameter on the landing page rather than setting a cookie chord pixel reads those parameters on arrival, stores them, and attaches them to every subsequent event for the retention period — so a click that happened days before checkout is still present on the conversion stored parameters are keyed in clientids by their provider name , not by the parameter name parameter appears as retention cleared on im ref impact 30 days order complete , order completed , purchase clearing on conversion prevents a single referral click from being credited to every future order the customer places capturing additional identifiers both sources are extensible, which is how identifiers not listed above — gclid , msclkid , sccid , an affiliate network's parameter — are captured when a destination needs them add cookies with the cookiecapture option, mapping the clientids key to the cookie name cookiecapture { msclkid " uetmsclkid", } add url parameters with the urlparamcapture option urlparamcapture { gclid { provider "gclid", expirydays 90 }, cjevent { provider "cj", expirydays 14, clearonevents \["order completed"] }, } option default description provider — the key the value appears under in context clientids required expirydays 30 how long the value persists after capture clearonevents none event names that clear the stored value custom parameters are not cleared on conversion unless you list the events explicitly urlpattern none only capture when the landing url matches this pattern when several parameters map to the same provider, the first one present on the url wins note destinations do not depend solely on clientids a destination that needs a click id will also look for it in the event's page url, its properties , and its integrations block, using whichever source is freshest capturing it here is what makes it survive across sessions utm parameters are captured through the same mechanism but are surfaced separately as context campaign docid 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