Docs menu

Global Privacy Control

Privacy signals in CookieHug: Global Privacy Control (GPC), DNT and the US Privacy (USP) adapter — modes, user override, the toaster and events.

Global Privacy Control (Sprint 1)

CookieHug detects navigator.globalPrivacyControl === true on every page and reacts according to bannerConfig.gpc.mode.

GPC modes

Mode	Behaviour
`auto_deny_toaster` (recommended)	Auto-denies all non-essential categories, hides the banner, shows a small toaster offering an override.
`auto_deny_silent`	Same auto-deny, no toaster.
`preselect_off_banner`	Banner is shown with all non-essential toggles off by default.
`ignore`	GPC is read for analytics only; does not affect consent state.

User override

When gpc.allowUserOverride is true (default), the toaster contains an "Adjust" button that re-opens the full banner. The chosen state is stored as method="gpc_override".

Toaster appearance

bannerConfig.gpc.visual controls the toaster (variant/position/colors/icon/animation/buttons/behavior). The toaster renders inside a Shadow DOM to isolate styles, and respects prefers-reduced-motion.

Events

Event	Detail
`CookieHugOnGpcDetected`	`{ mode, autoDenied, userOverrideAvailable }`
`CookieHugOnGpcToasterShown`	`{ mode }`
`CookieHugOnGpcToasterDismissed`	`{ reason: 'user' \\| 'auto' }`
`CookieHugOnGpcOverrideRequested`	`{}` — fired before the banner is re-opened. A session flag is set so the next `setConsent` is recorded as `method="gpc_override"`.
`CookieHugOnDntDetected`	`{ autoDenied: false, userOverrideAvailable: true }` — emitted when `respectDnt=true` and the visitor's browser sends `DNT: 1` (and GPC has not already taken precedence).

Do Not Track

When respectDnt is enabled and navigator.doNotTrack === '1', the policy engine triggers a soft preselect-off: the banner is shown normally but all non-essential checkboxes start unchecked. The user can still consent explicitly. GPC always wins over DNT (precedence: GPC > DNT > normal flow). Disabling respectDnt keeps doNotTrack as a telemetry-only signal in event payloads and the consent cookie.

What CookieHug does NOT do

Does not modify Privacy Sandbox APIs. accounts.google.com/gsi/, FedCM, Topics API, Attribution Reporting and Private State Tokens are explicitly whitelisted from the script blocker.
Does not store the visitor's IP or geolocation; region is resolved transiently per request.

Consent cookie v2

When the resolution is non-trivial, CookieHugConsent is upgraded to v2 with extra fields:

{
  "v": 2,
  "necessary": true,
  "preferences": true,
  "statistics": true,
  "marketing": false,
  "stamp": 1712345678901,
  "method": "gpc_auto_deny",
  "region": "US-CA",
  "signals": {
    "ad_storage": "denied",
    "ad_user_data": "denied",
    "ad_personalization": "denied",
    "analytics_storage": "granted"
  }
}

Reader is backward-compatible with v1 (missing fields treated as defaults). method extends to: explicit, gpc_auto_deny, gpc_override, migrated_v1, notice_only.

US Privacy (USP / CCPA) adapter

An opt-in, per-domain adapter for the IAB US Privacy API v1 — enable it in Domain → Advanced → Consent policy → US Privacy (USP). When enabled, the SDK registers window.__uspapi (only if the page does not already provide one), so ad partners can read the CCPA/CPRA "usp string":

window.__uspapi('getUSPData', 1, function (data, success) {
  // data.uspString — e.g. "1YNN"
});

The string is derived from the visitor's banner decision: position 2 (notice) becomes Y once the visitor has responded to the banner, position 3 (opt-out of sale) is Y when the Marketing category was refused and N when it was accepted, and position 4 (LSPA) is always N. Before any decision the adapter returns 1N-N. After every decision (accept, reject, withdraw, restore on a return visit) a uspChange CustomEvent with detail.uspString is dispatched on window.