trace.
Log in
Start for free No card required

How do consent flags work in Trace?

Updated 30 September 2026

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

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

The snippet reads consent in this order:

  1. Do Not Track: if enabled, we do not register analytics consent.
  2. 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).
  3. 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.

Was this useful?