docs · for developers

Runtime API

Everything the banner can do is scriptable. The runtime exposes one global, fires five events, and renders no UI at all if you would rather build your own.

The global

window.CookieCrumbs.ready.then(() => {
  const choice = window.CookieCrumbs.get();
  // { necessary: true, analytics: false, … } or null before any decision
});

Member	What it does
`ready`	Promise resolving once config and state are loaded.
`get()`	The current category map, or `null` before a decision.
`set(partial)`	Merge and record a decision programmatically.
`acceptAll() / rejectAll()`	Record a full grant or refusal.
`withdraw()`	Record a withdrawal (everything off, typed as withdrawn).
`open(layer?) / close()`	Open the banner (layer 2 is the settings panel) or hide it.
`consentId()`	The visitor's pseudonymous consent ID, or `null`.
`version() / regime() / country() / lang()`	The live version number, resolved regime, detected country and active language.
`setLang(tag)`	Switch the banner language (must be configured).
`declaration(el?, lang?)`	Render the cookie declaration into an element (default: the first `[data-cc-declaration]`).
`declarationUrl(lang?)`	The hosted declaration URL.
`myConsent()`	The visitor's own stored record, for a "my consent" page.
`on(event, cb) / off(event, cb)`	Subscribe to events.
`sdk`	The runtime version string.

Events

Five events: ready, show (a layer opened), decision, update (a changed choice) and withdraw. Decision-family events carry { categories, type, consentId, regime }.

The reopen control

Any element with data-cc-open reopens the banner: <a href="#" data-cc-open>Cookie settings</a>. Visitors must always have a way back in; if you disable the floating button, this link is required.

Headless mode

With the Headless layout no banner is rendered at all. You build the interface and drive it entirely through this API; the blocking, the consent log, regimes and Consent Mode all keep working underneath.

How blocking and release actually work

The interceptor installs synchronously, before the config fetch. Tagged scripts (type="text/plain" with data-cc-category) and untagged scripts or iframes whose host matches the published block map are kept in the DOM in a neutralised form, then re-created in document order the moment their category is granted. Nodes released once are never neutralised again.

Embed code on consent

A tracker recorded in the dashboard can carry its own embed code. At publish this compiles into the configuration, and the runtime runs each entry exactly once when its category is granted, at decision time or on a later visit with stored consent. Code that has already run cannot be un-run by a withdrawal; it simply does not run again on the next page load.

State, honestly

The decision lives in one first-party cookie, cc_consent (SameSite=Lax, Secure on https), so it survives reloads. Consent events queue in localStorage["cc:q"] and post to the consent endpoint, falling back to sendBeacon when the page is closing; the queue is only cleared on success, so a failed delivery retries on the next load. No IP address, user agent or page URL is stored beside a consent record.