Applies to: Anyone installing the Cookie Compliance banner with a snippet (including via an AI assistant)

WordPress sites should install the plugin instead of pasting. The rule below is why blocking works — or does not.

The banner can only block scripts that have not run yet. Placement is not cosmetic. A snippet that loads after analytics, a pixel, or a tag-manager container leaves those tags free to fire before the visitor chooses.

The rule

  1. Put the snippet in <head>.
  2. It must be the first script on the page — before Google Analytics / gtag, before Meta or Microsoft pixels, and before any tag-manager container.
  3. Put it on every page, not only the homepage. Use a layout or theme file that wraps the whole site.
  4. Leave both tags as classic synchronous scripts. Do not add defer, async, or type="module". Do not let a bundler or a “combine JavaScript” optimiser move or inline them.

The live install is two tags in this order: an inline var huOptions = { … } block, then the loader script from our CDN: <script src="https://cdn.hu-manity.co/v2/hu-banner.min.js" type="text/javascript" charset="utf-8"></script> for an app on the New banner engine (a site created from the dashboard, an AI assistant or the WordPress plugin starts on it), or the same address without /v2/ for an app on the Classic engine. Always copy the exact snippet from Integrations.

What is inside the snippet

The inline block is generated for you — copy it from Admin Portal → Integrations → Manual Integration. It carries your App ID, your default language, and the two blocking keys. It does not contain your App Secret Key, and nothing in it is sensitive; it is meant to sit in public HTML.

  • blockingEngine — the master switch. While this is true (the default) Cookie Compliance may hold your third-party scripts. Set it to false and the banner never touches your scripts at all: nothing is blocked for any visitor, in any region, regardless of privacy signals. Use that only if you handle script blocking yourself.
  • blocking — block before consent. Holds third-party scripts until the visitor makes a choice. With this false, scripts load immediately; once the visitor chooses, their choice is enforced either way.

Edit these in the snippet on your own site — the Admin Portal’s Site-wide autoblocking setting (Configuration → Laws) applies only to WordPress sites running plugin 3.1.11 or later and does not change them on a snippet install. Re-copying the snippet from the portal later will bring back the defaults, so re-apply your edit if you made one.

If an older snippet on your site has no blockingEngine key at all, that is fine: a missing key is read as true, so blocking still works. Add the key only if you want to switch the engine off.

WordPress

Install Cookie Compliance for WordPress rather than pasting a snippet. The plugin handles placement and script order. An AI assistant can still preview the look via the MCP server.

Layouts (usual files)

These are typical document-head files. Confirm the path in your framework version before treating it as exact.

  • Next.js App Router — app/layout.tsx, in the document <head>, not a client component that hydrates later.
  • Next.js Pages Router — pages/_document.tsx <Head>.
  • Nuxt — app.vue head, or nuxt.config app.head.
  • Astro — the base layout <head>, with is:inline on both tags. Without it, Astro turns them into deferred modules and blocking stops working.
  • Static HTML — the first tags inside <head> on every page.

Do not wrap the CDN script in a helper that adds async/defer or injects it after hydration.

Google Tag Manager

Do not put this snippet inside a GTM container as another tag. Consent defaults have to exist before the container’s own gtm.js start event is processed. Leave GTM where it is, below the Cookie Compliance snippet in the page <head>. Do not delete the existing tags. With Google Consent Mode on, Cookie Compliance lets GTM run so Google tags can follow Consent Mode, which means tags GTM fires are not held by the Cookie Compliance banner: gate your non-Google tags inside GTM with consent triggers.

Shopify and anything else

The rule does not change. Find the theme or layout file that emits <head> on every page and put the snippet first. If you cannot put a synchronous script there, say so rather than loading it from a tag manager.

Colours that flash then revert

A live banner loads the app’s published configuration and overwrites design set only on the page. Change appearance in the Cookie Compliance dashboard (Design), then publish. To try a look with no account, use a preview snippet from the MCP server — that preview records no consent and expires after 24 hours.

Related Articles

Was this article helpful?
YesNo