Runtime Overview
What the Coframe SDK does at runtime — from install script to applied treatments
Copy this guide and your current settings as a prompt for your AI agent.
Preview agent promptSee the guide, code and settings included when you copy.
The Coframe runtime spans the life of a page load: the browser fetches the install script from the edge, configuration is read from window.CFQ, the SDK initialises, experiments are assigned, and treatments are applied to the page. This page describes each stage at a conceptual level and points to the reference pages where the full detail lives.
01The CFQ queue
window.CFQ is a plain JavaScript array. Your page code pushes command objects onto it at any time — before or after the SDK script has loaded. The SDK replays those commands on startup, so the order in which your code and the SDK execute does not matter.
Push config, readiness signals, and events.
window.CFQCommands remain available to registered listeners.
Resolve waits and dispatch matching callbacks.
waitForCmd scans in reverse for a match. listenForCmd replays every matching entry.
Patched queue.push immediately dispatches new commands to registered listeners.
Startup waits for a config command containing at least projectId.
Two replay mechanisms are used internally. waitForCmd performs a reverse scan of the existing queue and resolves immediately if a matching command is already present; it then registers a push listener for future items. listenForCmd iterates the full existing queue, fires the callback for each matching entry, and also hooks push for future items. Once the SDK is running, queue.push is patched so new commands are dispatched immediately to all registered listeners. The queue itself is protected from re-assignment: the SDK installs a getter/setter via Object.defineProperty so that window.CFQ = window.CFQ || [] is always safe, and any attempt to replace the queue with a different value is silently ignored.
The most important command is config. The SDK blocks at startup on waitForCmd until a command carrying a config object (with at minimum projectId) arrives. Other commands — cookiesEnabled, setUserToken, featureFlagSet, pageHydrated, conversion, and subscribe — let you co-ordinate cookie consent, visitor identity, feature gates, SSR hydration, manual conversions, and treatment callbacks with the SDK from your own page code.
For the full command reference, see CFQ Commands.
02How the SDK initialises
When the browser fetches the install script URL, the edge worker returns a single JavaScript response that contains two things concatenated together: a window.CFQ.push({ projectData: ... }) call that bakes the project JSON and personalization headers into the response for the current visitor, and the compiled SDK bundle (a modern or legacy build, selected by User-Agent). Because the project data arrives in the same response as the code, there is no separate fetch round-trip for project configuration.
projectDataProject JSON + personalization headersCoframe.init()Runs automatically on load- 01Resolve config
Wait for
config, read URL parameters, and validate. - 02Resolve project
Read the
projectDataincluded in the response. - 03Resolve identity
Restore, generate, or wait for a visitor token.
- 04Track & modify
Set up tracking, assign experiments, and apply treatments.
window.CoframeResolved session state · status.initialized = true
The standard path uses baked-in project data. Preview variants can fall back to a separate edge fetch. Configured identity and consent gates still apply.
The SDK bundle runs Coframe.init() automatically on load. init() executes four steps in sequence:
- Resolve config — waits for the
configCFQ command, reads URL parameters, and validates the configuration. - Resolve project — reads the baked-in
projectDatathat arrived with the script response (or falls back to a separate edge fetch for preview variants). - Resolve identity — determines the visitor’s token. If
config.waitForUserTokenis set, the SDK waits for asetUserTokenCFQ command and skips its own cookie-based UUID generation; otherwise it generates or restores a UUID from a cookie. Ifconfig.waitForCookiesEnabledis set, cookie writes and event sending are held until acookiesEnabledcommand arrives. - Setup tracking and modify page — sets up analytics listeners, assigns the visitor to experiments, applies variant changes, and fires treatment events.
After init() completes, window.Coframe is populated with the resolved state for the session: projectId, orgId, userToken, sessionId, treatmentsDataV2, experimentInfo, and status.initialized (set to true). The Coframe.debug sub-object exposes utilities for inspecting queue state, resolving DOM selectors, and flushing queued events from the browser console.
For the full window.Coframe property reference, see The Coframe Global. For how the script tag URL is constructed and how versioned bundles work, see Delivery & Versioning.
03Applying treatments and tracking
After identity is resolved, the SDK assigns the visitor to experiments and — if the assignment is terminal — applies the corresponding variant changes to the page and emits treatment events. The assignment uses a three-level coin-flip structure (global holdout → experiment holdout → variant selection); only assignments with final_state: true result in variant modifications and appear in Coframe.treatmentsDataV2.
For the full assignment flow, the IDs each step produces, and the shape of the treatmentsDataV2 payload, see Experiment Assignment & IDs. For what a frame and a treatment are, see Frames and Treatments. For how the SDK hides the page while variants load and reveals it after they are applied, see Anti-Flicker.
# Runtime Overview
What the Coframe SDK does at runtime — from install script to applied treatments
The Coframe runtime spans the life of a page load: the browser fetches the install script from the edge, configuration is read from `window.CFQ`, the SDK initialises, experiments are assigned, and treatments are applied to the page. This page describes each stage at a conceptual level and points to the reference pages where the full detail lives.
Going deeper
For the function-level version of this page, with narrated videos, see
[Runtime Walkthrough](../docs/sdk-internals-overview.html).
## The CFQ queue
`window.CFQ` is a plain JavaScript array. Your page code pushes command objects onto it at any time — before or after the SDK script has loaded. The SDK replays those commands on startup, so the order in which your code and the SDK execute does not matter.
COMMAND DELIVERYOne queue, before and after startup
YOUR WEBSITEPage codePush config, readiness signals, and events.
SHARED QUEUE`window.CFQ`Commands remain available to registered listeners.
COFRAME SDKCommand listenersResolve waits and dispatch matching callbacks.
ALREADY IN THE QUEUERead existing commands`waitForCmd` scans in reverse for a match. `listenForCmd` replays every matching entry.
AFTER LISTENERS REGISTERHandle new pushesPatched `queue.push` immediately dispatches new commands to registered listeners.
Startup waits for a `config` command containing at least `projectId`.
Two replay mechanisms are used internally. `waitForCmd` performs a reverse scan of the existing queue and resolves immediately if a matching command is already present; it then registers a push listener for future items. `listenForCmd` iterates the full existing queue, fires the callback for each matching entry, and also hooks push for future items. Once the SDK is running, `queue.push` is patched so new commands are dispatched immediately to all registered listeners. The queue itself is protected from re-assignment: the SDK installs a getter/setter via `Object.defineProperty` so that `window.CFQ = window.CFQ || []` is always safe, and any attempt to replace the queue with a different value is silently ignored.
The most important command is `config`. The SDK blocks at startup on `waitForCmd` until a command carrying a `config` object (with at minimum `projectId`) arrives. Other commands — `cookiesEnabled`, `setUserToken`, `featureFlagSet`, `pageHydrated`, `conversion`, and `subscribe` — let you co-ordinate cookie consent, visitor identity, feature gates, SSR hydration, manual conversions, and treatment callbacks with the SDK from your own page code.
For the full command reference, see [CFQ Commands](../docs/cfq-commands.html).
## How the SDK initialises
When the browser fetches the install script URL, the edge worker returns a single JavaScript response that contains two things concatenated together: a `window.CFQ.push({ projectData: ... })` call that bakes the project JSON and personalization headers into the response for the current visitor, and the compiled SDK bundle (a modern or legacy build, selected by User-Agent). Because the project data arrives in the same response as the code, there is no separate fetch round-trip for project configuration.
EDGE → BROWSEROne response. Four initialization steps.
Single JavaScript responseFrom the edge
`projectData`Project JSON + personalization headers
+SDK bundleModern or legacy build
↓`Coframe.init()`Runs automatically on load
- 01Resolve configWait for `config`, read URL parameters, and validate.
- 02Resolve projectRead the `projectData` included in the response.
- 03Resolve identityRestore, generate, or wait for a visitor token.
- 04Track & modifySet up tracking, assign experiments, and apply treatments.
↓`window.Coframe`Resolved session state · `status.initialized = true`
The standard path uses baked-in project data. Preview variants can fall back to a separate edge fetch. Configured identity and consent gates still apply.
The SDK bundle runs `Coframe.init()` automatically on load. `init()` executes four steps in sequence:
- Resolve config — waits for the `config` CFQ command, reads URL parameters, and validates the configuration.
- Resolve project — reads the baked-in `projectData` that arrived with the script response (or falls back to a separate edge fetch for preview variants).
- Resolve identity — determines the visitor’s token. If `config.waitForUserToken` is set, the SDK waits for a `setUserToken` CFQ command and skips its own cookie-based UUID generation; otherwise it generates or restores a UUID from a cookie. If `config.waitForCookiesEnabled` is set, cookie writes and event sending are held until a `cookiesEnabled` command arrives.
- Setup tracking and modify page — sets up analytics listeners, assigns the visitor to experiments, applies variant changes, and fires treatment events.
After `init()` completes, `window.Coframe` is populated with the resolved state for the session: `projectId`, `orgId`, `userToken`, `sessionId`, `treatmentsDataV2`, `experimentInfo`, and `status.initialized` (set to `true`). The `Coframe.debug` sub-object exposes utilities for inspecting queue state, resolving DOM selectors, and flushing queued events from the browser console.
For the full `window.Coframe` property reference, see [The Coframe Global](../docs/coframe-global.html). For how the script tag URL is constructed and how versioned bundles work, see [Delivery & Versioning](../docs/delivery-and-versioning.html).
## Applying treatments and tracking
After identity is resolved, the SDK assigns the visitor to experiments and — if the assignment is terminal — applies the corresponding variant changes to the page and emits treatment events. The assignment uses a three-level coin-flip structure (global holdout → experiment holdout → variant selection); only assignments with `final_state: true` result in variant modifications and appear in `Coframe.treatmentsDataV2`.
For the full assignment flow, the IDs each step produces, and the shape of the `treatmentsDataV2` payload, see [Experiment Assignment & IDs](../docs/experiment-assignment.html). For what a frame and a treatment are, see [Frames and Treatments](../docs/frames-and-treatments.html). For how the SDK hides the page while variants load and reveals it after they are applied, see [Anti-Flicker](../docs/anti-flicker.html).
## Related
- [CFQ Commands](../docs/cfq-commands.html) — every command `window.CFQ` accepts
- [The Coframe Global](../docs/coframe-global.html) — `window.Coframe` runtime state
- [Delivery & Versioning](../docs/delivery-and-versioning.html) — how the script tag and edge bundles work
- [Frames and Treatments](../docs/frames-and-treatments.html) — the core concepts behind variant changes
- [Experiment Assignment & IDs](../docs/experiment-assignment.html) — the assignment flow and payload fields
- [Anti-Flicker](../docs/anti-flicker.html) — preventing flash of original content during variant application