How do consent flags work in Trace?

Add the Trace script to your site's <head>. Trace sends data (/v1/event) and only promotes events to full journey tracking after affirmative consent is registered on our servers (/v1/consent). If the banner has not yet returned a clear allow or deny, we do not assume consent.

What you need to do

Add the Trace snippet (see your dashboard, the script URL includes v=2 for the current behaviour).
Use a cookie banner or CMP we support, or set window.traceConsent from your own CMP when the user accepts or declines analytics cookies.

How Trace knows consent

The snippet reads consent in this order:

Do Not Track: if enabled, we do not register analytics consent.
window.traceConsent: if you set it to true or false, that value wins (use your CMP’s callback if we do not auto-detect your vendor).
Automatic CMP detection (statistics / analytics category only):

Cookiebot: statistics consent flag
OneTrust: Performance/Analytics (e.g. C0002)
IAB TCF: purpose 7 (measurement)
CookieYes: analytics/performance

Default: If none of the above applies, we treat consent as not given until a clear signal exists. We do not treat “CMP not loaded yet” as consent.

When consent becomes allowed, the snippet calls POST /v1/consent (site is inferred from your API key). That sets the first-party consent cookie on the API origin and can flush events that were held in a short quarantine (up to 60 minutes) into full journey processing.

Two tiers of data

Tier 1 (opt-in): after consent is GRANTED, we use events for journeys, attribution, and the Events list in the dashboard (consented rows only). Individual paths are available here.
Tier 2 (statistical / no analytics consent): events without consent are not stored as individual journey rows. After the quarantine window, they roll into anonymous aggregate counts by site, day, and channel (see Analytics → Real time → Statistical tier). This is for high-level channel performance only, not singling out users. Whether you may rely on this for your legal basis (e.g. UK statistical exemptions) requires your own legal advice.

Legacy `POST /events`

Older integrations may still call /events. That path now follows the same consent and quarantine rules as /v1/event and only writes to the Event table when consent is GRANTED (for dashboard compatibility).

How we treat the data (summary)

Consent given: full journey tracking (Tier 1); events appear in consented streams.
Consent declined or unknown: no Tier 1 storage; pre-consent activity may be held briefly in quarantine, then counted only in Tier 2 aggregates after expiry, or flushed into Tier 1 if the user accepts within the window.
Do Not Track: no analytics consent registration.

For UK/EU audiences, use a consent banner and, where possible, a CMP we support so consent is explicit and synchronised with Trace.

For developers

Engineering changes to CMP detection (Cookiebot, OneTrust, TCF, CookieYes) and to the cmp_vendor sent with POST /v1/consent should follow the internal checklist in the repo (docs/EXTENDING_TRACE.md): update lib/trace-snippet/cmp.ts, keep the inline trace.js snippet in sync, and extend the Vitest coverage there.