docs · for developers

Install the snippet

One script tag puts the banner on your site and holds every non-essential tracker back until the visitor decides. There are two rules, and that is the whole job.

The tag

Copy the tag from Site settings → Install in the dashboard. It carries your site's public key and the environment it should load:

<script src="https://app.cookiecrumbs.eu/runtime/cc.js"
        data-cc-site="pk_live_…"
        data-cc-env="production"></script>

Each site has two keys: the production key for real visitors and the preview key, which loads whatever is published to preview so you can test on a staging page without touching anyone.

Rule one: the tag goes first

Place the tag as the first script inside <head>, before every other script. Anything that runs before it can set a cookie while the visitor is still deciding, and the runtime cannot take that back. The runtime installs its interceptor synchronously, before it even fetches your configuration, so nothing non-essential runs before a choice exists.

Rule two: consent-gated scripts become inert

Scripts that need consent are marked so the banner can release them once their category is granted:

<script type="text/plain"
        data-cc-category="analytics"
        src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>

A type="text/plain" script does nothing on its own. When the visitor grants the category, the runtime re-creates the script in document order and it runs normally. Inline scripts work the same way: give them type="text/plain" and a data-cc-category.

Untagged scripts: the block list

You do not have to tag everything. Trackers recorded in your dashboard carry host patterns, and those are compiled into a block map at publish. Any untagged <script src> or <iframe src> whose host matches is neutralised in place (scripts become text/plain, iframes are held with their source parked in data-cc-src) and released when its category is granted. Blocked iframes show a placeholder text, editable per language under Banner → Words.

Content management systems

WordPress: Appearance → Theme file editor → header.php, before wp_head(), or use a header-scripts plugin.
Shopify: Online store → Themes → Edit code → layout/theme.liquid, first line inside <head>.
Webflow: Project settings → Custom code → Head code.

The tag-manager caveat

Do not load the CookieCrumbs tag through a tag manager. The tag must run before the tag manager does; a consent tag fired from inside the manager runs too late to hold anything back. Paste it directly into the page, above the manager, and let Consent Mode carry decisions into your tags (see the Consent Mode guide).

The install check

The dashboard's install check loads your page in a real browser, accepts once, and reports what it actually saw. Nothing is taken on trust. It looks at:

the snippet is present in the page, and placed before other tags,
Consent Mode defaults are set before any Google tag runs,
the banner rendered, and the public key in the page belongs to this site,
a consent cookie is written after accepting,
__tcfapi is not provided: CookieCrumbs does not implement the IAB TCF today.

Each failing check comes with a verdict sentence naming the next step, for example: "The snippet is there, but other tags run before it. Move the tag above every other script in the head, then run the check again." A real consent decision from a visitor also counts as proof that the install works.

Prefer a package?

If your site is built with Next.js, React, Astro, Nuxt or SvelteKit, the framework SDKs place the tag for you, and npx cookiecrumbs init detects your framework and writes the config.