Installation guide

Consentaur is installed with a single line of code. This guide explains how to add the script correctly, so cookies stay blocked until your visitors consent, and how to add it on WordPress, Shopify, Wix and Squarespace.

Quick start

Copy your personal script tag from your dashboard and paste it into the <head> section of your website:

Why must the script come first?

The browser runs scripts from top to bottom. If the Google Analytics script sits above Consentaur, Google Analytics sets its cookies before Consentaur can block them. As the first script, Consentaur can:

• Set Google Consent Mode v2 to "denied" by default before any Google script loads
• Watch and block every later script that tries to set cookies without consent
• Show the cookie banner as early as possible

Platform guides

Add the cookie banner to WordPress

With a plugin (recommended): Install a plugin such as WPCode (Insert Headers and Footers). Go to Code Snippets → Header & Footer and paste the Consentaur script into the "Header" box, at the very top, before any other scripts.

In the theme: Edit your theme's header.php file and paste the script straight after the opening <head> tag:

<head>
  <script src="https://cdn.consentaur.com/v1/YOUR_SITE_ID.js"></script>
  <?php wp_head(); ?>
</head>

Replace YOUR_SITE_ID with your site ID from your dashboard. Changes to header.php can be overwritten by a theme update, so use a child theme or the plugin route.

Caching and optimisation plugins: plugins that delay, combine or defer JavaScript must leave the Consentaur script alone. Exclude cdn.consentaur.com from those optimisations in the plugin's settings.

For a step-by-step walkthrough, read our guide to cookie consent on WordPress.

Shopify

Go to Online Store → Themes and choose Edit code for your live theme. Open theme.liquid and paste the Consentaur script straight after the <head> tag, before all other scripts:

<head>
  <script src="https://cdn.consentaur.com/v1/YOUR_SITE_ID.js"></script>
  {{ content_for_header }}
  ...
</head>

Replace YOUR_SITE_ID with your site ID from your dashboard.

Wix

In your site's settings, open Custom Code. Add the Consentaur script, choose "Head" as the placement and load it on all pages.

Squarespace

Open your site's Code Injection settings and paste the Consentaur script into the "Header" field.

Custom site / HTML

Paste the script straight into your HTML template as the first script in <head>. The script must not have an async or defer attribute: it has to load synchronously to be able to block other scripts.

Blocking scripts manually

Consentaur automatically blocks scripts from third-party domains that set cookies during the scan, including scripts that a tag manager or other code adds later. It also recognises well-known trackers that set their cookies on your own domain, such as the Meta Pixel, Hotjar, TikTok and LinkedIn, once the scan has found their cookies. Google's tags are covered by Google Consent Mode (see below). Mark any other scripts with type="text/plain" and data-consentaur-category. The browser then does not run them at all, and Consentaur starts them once the visitor consents to the category:

<!-- Runs once the visitor consents to marketing -->
<script
  type="text/plain"
  data-consentaur-category="marketing"
  src="https://example.com/tracking.js"
></script>

<!-- Runs once the visitor consents to analytics -->
<script type="text/plain" data-consentaur-category="analytics">
  // Inline analytics code
</script>

Scripts run in the order they appear on the page. For a JavaScript module, add data-consentaur-type="module".

Scripts for signing in, CAPTCHAs and payments are never blocked automatically, so they keep working before consent: Sign in with Google, Apple or Microsoft, reCAPTCHA, hCaptcha, Cloudflare Turnstile, Stripe, PayPal and Klarna. For the Meta Pixel, Consentaur blocks the pixel's own scripts, not the Facebook SDK that Facebook Login uses. If you use Facebook's social plugins, such as the Like button, mark the SDK script as shown above, with data-consentaur-category="marketing".

Valid categories:

• necessary: necessary cookies (never blocked)
• analytics: statistics and analytics
• marketing: marketing and advertising
• preferences: preferences and functionality

YouTube, Google Maps and other embedded content

Embedded content such as YouTube and Vimeo videos, Google Maps, Spotify, SoundCloud, Instagram, X, TikTok and Facebook's plugins sets cookies as soon as it loads. Consentaur holds it back until the visitor consents to its category and shows a box in its place that says who provides it, with a button that accepts the category and shows the content straight away.

Consentaur catches embedded content as the page loads, but Chrome and Firefox can start fetching it before any script can stop it. To be certain, write data-consentaur-src instead of src. The browser then never loads it by itself:

<!-- Loads once the visitor consents to marketing -->
<iframe
  data-consentaur-src="https://www.youtube.com/embed/VIDEO-ID"
  data-consentaur-category="marketing"
  width="560" height="315"
  title="Our video"
  allowfullscreen
></iframe>

The category decides when the content is shown. Without data-consentaur-category, Consentaur uses the category it knows for the provider: analytics for Vimeo, marketing for the others. To never hold back an iframe, such as your own booking system, add data-consentaur-ignore. The cookie scan shows in the dashboard which embeds on your website aren't marked yet.

Google Consent Mode v2

Consentaur supports Google Consent Mode v2 out of the box. When the script loads, every consent signal is set to "denied" by default. When a visitor consents, Consent Mode is updated automatically:

• analytics_storage: follows the "Analytics" category
• ad_storage, ad_user_data, ad_personalization: follow the "Marketing" category
• personalization_storage: follows the "Preferences" category
• functionality_storage, security_storage: always "granted"

You do not need to set up Google Consent Mode separately: Consentaur handles it for you. Until a visitor consents, Google tags therefore run without cookies. If they should not load at all before consent, turn on Block Google tags until consent in your site's settings in the dashboard.

Cookie declaration

Consentaur can show an automatically updated list of your website's cookies, grouped by category. You find the code under Cookie declaration on your site's page in the dashboard. Paste it into your cookie policy or privacy policy page:

<script src="https://cdn.consentaur.com/v1/YOUR_SITE_ID-declaration.js" defer></script>
<div data-consentaur-declaration></div>

The list shows the cookies recorded for your site and stays current after every new scan. When the Consentaur script is on the same page, it includes a link visitors can use to change their consent.

JavaScript API

Consentaur exposes a global window.Consentaur object that you can use to control consent from your own code, for example for a "Cookie settings" link in your footer.

Open the consent settings

Show the settings panel so visitors can change their choices:

// Example: attach to a button in your footer
document.getElementById('cookie-settings-btn')
  .addEventListener('click', () => {
    window.Consentaur.showSettings()
  })

Or without any JavaScript of your own: any element with the data-consentaur-settings attribute opens the settings when clicked.

<button data-consentaur-settings>
  Cookie settings
</button>

Read the current consent

Read the current consent state, for example to load a script conditionally:

const consent = window.Consentaur.getConsent()
// { necessary: true, analytics: true, marketing: false, preferences: false }

if (consent?.analytics) {
  // Load an analytics script manually
}

Wait for the visitor's choice

Third-party widgets such as chat, video and maps should only load once the visitor has answered the cookie banner. That way they do not sit on top of the banner and do not set cookies early. onConsent() calls your function once a choice has been made. If a valid consent from an earlier visit exists, it is called straight away:

let chatLoaded = false

window.Consentaur.onConsent((consent) => {
  // consent.action:     'accept_all' | 'reject_all' | 'customize' | 'stored'
  // consent.categories: { necessary, analytics, marketing, preferences }
  if (chatLoaded) return
  chatLoaded = true
  loadChatWidget()   // your own code, e.g. insert the chat script
})

The same signal is dispatched as an event on window every time consent is decided or changed:

window.addEventListener('consentaur:consent', (event) => {
  const { action, categories } = event.detail
})

// Has the visitor already decided?
window.Consentaur.hasDecided()   // true / false

Mobile

In your dashboard, under Banner → Layout → "Mobile layout", you can choose Compact. On screens up to 640 px wide the banner then shows one line of text with "Read more", "Reject all" and "Accept all" side by side and "Customize" as a link. The choices, the categories and the way consent is stored stay the same; only the layout changes. Compact takes up about 20% of the screen on a typical phone, against about 30% for the standard layout, which shows the banner as on desktop.

If your website has a chat button or similar that would otherwise sit on top of the banner, load it only after the visitor has answered. See Wait for the visitor's choice above.

Letting the Consentaur scanner through bot protection

Consentaur scans your website regularly to keep your cookie list and your banner up to date. Bot protection such as Cloudflare, DataDome, HUMAN or Imperva can take the scanner for an unwanted bot and answer with a check instead of your website. Your dashboard then says that bot protection is blocking the scanner, and your cookie list can't be checked until the scanner gets through.

Let the scanner through with a secret request header that only you and Consentaur know:

1. In the dashboard, open your site's Settings. Under Advanced, in Scanner access through bot protection, select Generate a secret and copy it.
2. In your bot protection, add a rule that skips bot checks for requests that carry the header X-Consentaur-Scan with exactly that secret. See below for Cloudflare and other providers.
3. Save the header and the secret in the dashboard, then select Scan now. When the scan gets through, the notice disappears.

Cloudflare

What you can do depends on your Cloudflare plan:

• Pro, Business and Enterprise use Super Bot Fight Mode. A custom rule with the Skip action lets requests with your header past it.
• Free uses Bot Fight Mode, which no rule can skip. Turn it off under Security → Settings (filter by Bot traffic, then Bot fight mode), or upgrade to Pro for Super Bot Fight Mode.

Create the rule in your domain's Cloudflare dashboard:

1. Go to Security → Security rules.
2. Select Create rule → Custom rules and give the rule a name, for example "Consentaur scanner".
3. Under When incoming requests match, select Edit expression and paste the expression below, with your secret instead of YOUR-SECRET.
4. Under Then take action, choose Skip, and under the components to skip select All Super Bot Fight Mode rules. If your own custom rules or rate limiting rules challenge bots as well, also select All remaining custom rules and All rate limiting rules.
5. Under Place at, choose First, so the rule runs before your other custom rules, and select Deploy.

any(http.request.headers["x-consentaur-scan"][*] eq "YOUR-SECRET")

Cloudflare writes header names in lower case in expressions, whatever their spelling in the request. The secret is compared exactly, including upper and lower case. If you chose another header name, use it in lower case. While you generate a secret, the dashboard shows this expression with your secret filled in.

With Cloudflare's Enterprise Bot Management, your bot score rules are custom rules themselves. The skip rule above, placed first with All remaining custom rules selected, covers them.

Other bot protection

• AWS WAF with Bot Control: add a scope-down statement to the Bot Control managed rule group that leaves out requests whose X-Consentaur-Scan header exactly matches your secret. AWS describes this for trusted bots that send a shared secret in a header. Your other rules still apply.
• HUMAN (Bot Defender): create a custom policy rule with a header condition on X-Consentaur-Scan and your secret, with the action Allow, and give it a higher priority than the rules that block or challenge.
• DataDome: custom rules can't compare a header's value, and a rule that only checks for the header name would let anyone through. Ask DataDome support to allow requests that carry your secret header.
• Akamai Bot Manager: define the scanner as a custom bot in a category you allow. If your setup can match a request header, match X-Consentaur-Scan with your secret; otherwise ask your Akamai account team.
• Imperva: its bot exceptions don't match on headers. Ask Imperva support to add the scanner as a good bot that is recognised by your secret header.
• Sucuri and Wordfence: their allowlists work by IP address or address on your site, not by header. Contact their support or us at support@consentaur.com.

Keep it secure

• Use a long, random secret. Generate a secret in the dashboard makes one from 32 random bytes.
• Skip only the bot checks. Don't skip the managed rules or turn off the whole firewall for requests with the header: everything else should still protect them.
• Change the secret now and then, and whenever someone who knew it leaves. Update both places: put the new secret in your rule, save it in the dashboard, then remove the old one. To avoid a blocked scan in between, let the rule accept both secrets until you have saved the new one.
• Consentaur stores the secret encrypted and shows only its last characters once it is saved. The scanner sends the header only over HTTPS and only to your own domain and its subdomains (and to the domain your home page redirects to, if it moved), never to other websites such as analytics or advertising services.
• The header is the way to let the scanner through. We don't publish scanner IP addresses, so a rule based on IP addresses won't work.

Auditing pages behind a login

The scanner visits your website like an anonymous visitor. It never logs in, so it never sees the cookies and stored items your website only sets for logged-in users, such as a session cookie or a dashboard's settings in local storage. An audit lets your own browser show Consentaur what they are called.

1. In the dashboard, open your site's Cookies page and go to Audit while logged in. Choose a start page if you like (for example /login) and select Start audit.
2. Your website opens in a new tab with a small bar: Consentaur audit running. Log in, and use the pages your logged-in users use.
3. Select Finish in the bar or in the dashboard. What the audit found is on your cookie list, marked Seen in your audit. Check the categories and descriptions, as for scanned cookies.

Sign-in cookies the audit can't see

Most sign-in cookies are HttpOnly: your browser keeps them out of reach of the scripts on the page, the audit included. Under Does your site have a login? on the Cookies page you can add them:

• Sign-in libraries: Auth.js, NextAuth.js, Supabase, Clerk, Firebase, Django, Laravel, ASP.NET Core Identity and WordPress. Consentaur fills in the names from what it has found on your site, and adds the cookies with the lifetimes from the library's documentation.
• Custom login cookie: the name of your own sign-in cookie, whether it is kept after the browser closes, and for how long. You find it in your browser's developer tools (Application, Cookies) while you are logged in.

Cookies that are only set after login show "Only set after you log in" in your banner and your cookie declaration. If your website has a Content Security Policy, the audit needs the same addresses as the banner: scripts from cdn.consentaur.com and requests to api.consentaur.com.

Troubleshooting

The cookie banner does not appear

• Check that the script tag is in <head>
• Open the browser console (F12) and look for error messages from Consentaur
• If you have already consented, delete the consentaur_consent cookie (and the localStorage key of the same name) and reload the page

Cookies are set before consent

• Make sure the Consentaur script is the first script in <head>
• Remove async and defer from the Consentaur script if you added them
• Check whether a caching or optimisation plugin moves or delays the script
• Scan your site again to update the list of cookies to block

Content Security Policy (CSP)

If your website uses a Content Security Policy, allow scripts from cdn.consentaur.com:

Content-Security-Policy: script-src 'self' https://cdn.consentaur.com;