Identity and Sessions
How Coframe identifies visitors and tracks sessions — first-party identity, custom tokens, and consent
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 needs two identifiers to operate correctly: a visitor identity that keeps experiment assignments stable across page loads, and a session ID that scopes each individual page view. This page explains what those identifiers are, how they are resolved, and how consent gating affects them.
On this page
01Visitor Identity
When a visitor loads a page that has Coframe installed, the SDK resolves a
visitor identity token and stores it as Coframe.userToken. By default this is
handled automatically: the SDK generates or retrieves a UUID from a first-party
cookie so that the same visitor receives a consistent experiment assignment on
return visits.
The visitor token is used throughout the SDK lifecycle:
- Experiment assignment — the token is the stable key that determines which variant a visitor sees. Because it persists across page loads, a visitor who qualifies for a variant will continue to see that same variant.
- Analytics callbacks — the token is forwarded as
coframe_user_tokenin every entry of thebulkCallbackV2payload (CoframeTreatmentDataV2). You can use this field to join Coframe experiment data back to your own user records in a downstream analytics platform.
Coframe.userToken is a property on the
Coframe global object and is readable
at any point after identity resolution completes.
02Providing Your Own Identity (Cookieless Mode)
If your site already manages visitor identity — for example, through a logged-in
user system — you can supply that identity to Coframe instead of relying on its
cookie-based default. Setting waitForUserToken: true disables cookie-based
identity entirely; the SDK then waits for your application to push a
setUserToken command before proceeding with experiment assignment. No Coframe
identity cookies are written in this mode.
For setup steps and the exact snippet, see Identity Settings.
03Consent and Cookies
By default the SDK writes its first-party identity cookie as soon as it initializes. If your site uses a cookie consent prompt — for example, to comply with GDPR — you can delay this write until the visitor has accepted.
Setting waitForCookiesEnabled: true in your SDK config puts the SDK into
consent-gated mode. In this mode:
- Cookie writes and event sending are held until the SDK receives a
{ cookiesEnabled: true }command pushed towindow.CFQ. - If the visitor declines and the command is never pushed, the SDK writes no cookies and sends no events for that session.
- If a
cookiesEnabledcommand was pushed before the SDK script loaded, the SDK replays it synchronously on startup — so you do not need to coordinate timing between your consent library and the SDK load order. - You can also push
{ cookiesEnabled: false }to revoke consent dynamically; the SDK responds to consent state changes at any point after initialization.
For the configuration snippet and an integration example, see SDK Options — Cookies Consent.
04Sessions
In addition to the visitor identity, Coframe generates a fresh UUID at
script-load time that scopes the current page view. This is stored as
Coframe.sessionId and represents a single impression rather than a persistent
visitor identity — it changes every time the page is loaded.
The session ID is forwarded as coframe_impression_id in the
CoframeTreatmentDataV2 callback payload. Use it to correlate a specific
page-view impression with Coframe experiment data in your analytics pipeline.
See Coframe Global Object for the full
list of runtime properties, including userToken and sessionId.
# Identity and Sessions
How Coframe identifies visitors and tracks sessions — first-party identity, custom tokens, and consent
Coframe needs two identifiers to operate correctly: a visitor identity that
keeps experiment assignments stable across page loads, and a session ID that
scopes each individual page view. This page explains what those identifiers are,
how they are resolved, and how consent gating affects them.
## Visitor Identity
When a visitor loads a page that has Coframe installed, the SDK resolves a
visitor identity token and stores it as `Coframe.userToken`. By default this is
handled automatically: the SDK generates or retrieves a UUID from a first-party
cookie so that the same visitor receives a consistent experiment assignment on
return visits.
The visitor token is used throughout the SDK lifecycle:
- Experiment assignment — the token is the stable key that determines which
variant a visitor sees. Because it persists across page loads, a visitor who
qualifies for a variant will continue to see that same variant.
- Analytics callbacks — the token is forwarded as `coframe_user_token` in
every entry of the `bulkCallbackV2` payload
([CoframeTreatmentDataV2](../docs/experiment-assignment.html)).
You can use this field to join Coframe experiment data back to your own user
records in a downstream analytics platform.
`Coframe.userToken` is a property on the
[Coframe global object](../docs/coframe-global.html) and is readable
at any point after identity resolution completes.
## Providing Your Own Identity (Cookieless Mode)
If your site already manages visitor identity — for example, through a logged-in
user system — you can supply that identity to Coframe instead of relying on its
cookie-based default. Setting `waitForUserToken: true` disables cookie-based
identity entirely; the SDK then waits for your application to push a
`setUserToken` command before proceeding with experiment assignment. No Coframe
identity cookies are written in this mode.
For setup steps and the exact snippet, see
[Identity Settings](../docs/identity-settings.html).
## Consent and Cookies
By default the SDK writes its first-party identity cookie as soon as it
initializes. If your site uses a cookie consent prompt — for example, to comply
with GDPR — you can delay this write until the visitor has accepted.
Setting `waitForCookiesEnabled: true` in your SDK config puts the SDK into
consent-gated mode. In this mode:
- Cookie writes and event sending are held until the SDK receives a
`{ cookiesEnabled: true }` command pushed to `window.CFQ`.
- If the visitor declines and the command is never pushed, the SDK writes no
cookies and sends no events for that session.
- If a `cookiesEnabled` command was pushed before the SDK script loaded, the SDK
replays it synchronously on startup — so you do not need to coordinate timing
between your consent library and the SDK load order.
- You can also push `{ cookiesEnabled: false }` to revoke consent dynamically;
the SDK responds to consent state changes at any point after initialization.
For the configuration snippet and an integration example, see
[SDK Options — Cookies Consent](../docs/sdk-options.html#cookies-consent).
## Sessions
In addition to the visitor identity, Coframe generates a fresh UUID at
script-load time that scopes the current page view. This is stored as
`Coframe.sessionId` and represents a single impression rather than a persistent
visitor identity — it changes every time the page is loaded.
The session ID is forwarded as `coframe_impression_id` in the
`CoframeTreatmentDataV2` callback payload. Use it to correlate a specific
page-view impression with Coframe experiment data in your analytics pipeline.
See [Coframe Global Object](../docs/coframe-global.html) for the full
list of runtime properties, including `userToken` and `sessionId`.
## Related
- [Identity Settings](../docs/identity-settings.html) — how to configure
cookieless mode and supply your own visitor token.
- [SDK Options — Cookies Consent](../docs/sdk-options.html#cookies-consent)
— delaying cookie writes until consent.
- [CFQ Commands](../docs/cfq-commands.html) — `setUserToken` and
`cookiesEnabled` command reference.
- [Coframe Global Object](../docs/coframe-global.html) — `userToken`,
`sessionId`, and other runtime properties.
- [Experiment Assignment & IDs](../docs/experiment-assignment.html)
— the full `CoframeTreatmentDataV2` field reference, including `coframe_user_token`
and `coframe_impression_id`.