Events and Tracking
The events Coframe tracks — treatment impressions and conversions — and how they're delivered
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.
Coframe records two categories of events: treatment events that capture which visitors were assigned to which experiment variants, and conversion events that capture the outcomes you care about. Understanding these two event types is the foundation for using Coframe data in your analytics platform and interpreting experiment results.
01Treatment Events
When Coframe applies a treatment to a visitor’s page, it records the experiment assignment and makes it available to your code. This is the impression data at the heart of any experiment analysis — which visitors saw which variant.
The SDK fires treatment assignments through the treatmentApplied subscription. You subscribe by pushing a subscribe command to window.CFQ at any point before or after the SDK loads.
The preferred callback field is bulkCallbackV2. It receives all active treatment assignments in a single array and is gated on cookie consent (see How Events Are Delivered below). If you need the assignment data before consent is granted, use bulkCallbackV2WithoutConsent instead — it fires regardless of consent state.
For the subscribe command syntax and a ready-to-use callback snippet, see Tracking Settings. For the full CFQ command reference, see CFQ Commands.
Treatment Data Fields
Each entry delivered to your bulkCallbackV2 callback is a CoframeTreatmentDataV2 object with eight fields:
| Field | Type | Description |
|---|---|---|
coframe_experiment_id |
string |
Experiment ID for the assignment (uses holdout experiment ID when applicable) |
coframe_experiment_slug |
string |
Human-readable experiment name |
coframe_variant_id |
string |
The specific variant assigned to this visitor |
coframe_variant_slug |
string |
'baseline', 'global_holdout', or the variant name |
coframe_user_token |
string |
Visitor identity token for this session |
coframe_impression_id |
string |
Session UUID that uniquely identifies this impression |
coframe_in_global_holdout |
boolean |
true if the visitor is excluded from all experiments by the project-level global holdout |
coframe_in_exp_baseline |
boolean |
true if the visitor is in the experiment-level baseline control group |
For the full meaning of each field and how it relates to Coframe’s three-level assignment model, see Experiment Assignment.
02Conversion Events
A conversion event records that a visitor completed a meaningful action — a purchase, a sign-up, a checkout step — so that the outcome can be attributed to the experiment variant they were shown.
You report conversions by pushing a conversion command to window.CFQ at the point in your code where the action occurs. The payload requires at least one of metricId or metricName to identify which metric the event counts toward. If neither is present, the SDK discards the event.
For the full setup guide — including the push snippet, all payload fields (metricId, metricName, value, metadata), and tracking-only mode — see Tracking Settings.
03How Events Are Delivered
Batching. The SDK collects events and sends them in batches. The number of events per batch is controlled by the batchSize config option, which defaults to 32. You can override this value in your config command.
Consent gating. When waitForCookiesEnabled: true is set in your SDK config, the SDK delays both cookie writes and event sending until you push { cookiesEnabled: true } to window.CFQ. This consent gate applies to all consent-gated event paths, including the bulkCallbackV2 treatment callback. If you need to receive treatment assignment data before consent is granted, use bulkCallbackV2WithoutConsent — it fires independently of the consent gate.
See Tracking Settings for how to wire up consent-aware tracking in practice.
# Events and Tracking
The events Coframe tracks — treatment impressions and conversions — and how they're delivered
Coframe records two categories of events: treatment events that capture which visitors were assigned to which experiment variants, and conversion events that capture the outcomes you care about. Understanding these two event types is the foundation for using Coframe data in your analytics platform and interpreting experiment results.
## Treatment Events
When Coframe applies a treatment to a visitor’s page, it records the experiment assignment and makes it available to your code. This is the impression data at the heart of any experiment analysis — which visitors saw which variant.
The SDK fires treatment assignments through the `treatmentApplied` subscription. You subscribe by pushing a `subscribe` command to `window.CFQ` at any point before or after the SDK loads.
The preferred callback field is `bulkCallbackV2`. It receives all active treatment assignments in a single array and is gated on cookie consent (see [How Events Are Delivered](#how-events-are-delivered) below). If you need the assignment data before consent is granted, use `bulkCallbackV2WithoutConsent` instead — it fires regardless of consent state.
For the subscribe command syntax and a ready-to-use callback snippet, see [Tracking Settings](../docs/tracking-settings.html). For the full CFQ command reference, see [CFQ Commands](../docs/cfq-commands.html).
Treatment Data Fields
Each entry delivered to your `bulkCallbackV2` callback is a `CoframeTreatmentDataV2` object with eight fields:
Field |
Type |
Description |
`coframe_experiment_id` |
`string` |
Experiment ID for the assignment (uses holdout experiment ID when applicable) |
`coframe_experiment_slug` |
`string` |
Human-readable experiment name |
`coframe_variant_id` |
`string` |
The specific variant assigned to this visitor |
`coframe_variant_slug` |
`string` |
`'baseline'`, `'global_holdout'`, or the variant name |
`coframe_user_token` |
`string` |
Visitor identity token for this session |
`coframe_impression_id` |
`string` |
Session UUID that uniquely identifies this impression |
`coframe_in_global_holdout` |
`boolean` |
`true` if the visitor is excluded from all experiments by the project-level global holdout |
`coframe_in_exp_baseline` |
`boolean` |
`true` if the visitor is in the experiment-level baseline control group |
For the full meaning of each field and how it relates to Coframe’s three-level assignment model, see [Experiment Assignment](../docs/experiment-assignment.html).
## Conversion Events
A conversion event records that a visitor completed a meaningful action — a purchase, a sign-up, a checkout step — so that the outcome can be attributed to the experiment variant they were shown.
You report conversions by pushing a `conversion` command to `window.CFQ` at the point in your code where the action occurs. The payload requires at least one of `metricId` or `metricName` to identify which metric the event counts toward. If neither is present, the SDK discards the event.
For the full setup guide — including the push snippet, all payload fields (`metricId`, `metricName`, `value`, `metadata`), and tracking-only mode — see [Tracking Settings](../docs/tracking-settings.html).
## How Events Are Delivered
Batching. The SDK collects events and sends them in batches. The number of events per batch is controlled by the `batchSize` config option, which defaults to `32`. You can override this value in your `config` command.
Consent gating. When `waitForCookiesEnabled: true` is set in your SDK config, the SDK delays both cookie writes and event sending until you push `{ cookiesEnabled: true }` to `window.CFQ`. This consent gate applies to all consent-gated event paths, including the `bulkCallbackV2` treatment callback. If you need to receive treatment assignment data before consent is granted, use `bulkCallbackV2WithoutConsent` — it fires independently of the consent gate.
See [Tracking Settings](../docs/tracking-settings.html) for how to wire up consent-aware tracking in practice.
## Related
- [Tracking Settings](../docs/tracking-settings.html) — conversion events, tracking-only mode, and the analytics callback snippet
- [CFQ Commands](../docs/cfq-commands.html) — full reference for all `window.CFQ` commands including `subscribe` and `conversion`
- [Experiment Assignment](../docs/experiment-assignment.html) — how Coframe assigns visitors and what the treatment data fields mean
- [Analytics Integrations](../docs/segment.html) — platform-specific guides for Segment, Amplitude, and other tools