Install the script
On any website, ConsentAlly is one script tag placed as the first script in the head of every page. It runs before every script after it, holds the third-party tags those scripts add, loads the banner and the rest of the widget from ConsentAlly's edge, and releases what the visitor allows.
Using an AI assistant? It can do this with you from the chat. Give it your email address, and it connects to your ConsentAlly account, new or existing: it gives you one ConsentAlly link and a code, and nothing is created or connected until you approve there. Assistants find how in auth.md.
The tag
<script src="https://edge.consentally.com/adc9dd9ee6208e3b.js" data-ca-key="yourstorekey2345" crossorigin="anonymous"></script>Replace yourstorekey2345 with your store's key. On Shopify, use the app embed instead: it adds the tag for you.
-
srcnames the script on ConsentAlly's edge. A file there never changes under its name, so browsers keep it in their cache. -
data-ca-keyis your store's key, 16 characters: lowercase letters and the digits 2 to 7. The script reads it before it requests anything. Without a valid key it requests nothing and shows no banner, and what it holds stays held. -
crossorigin="anonymous"fetches the script without cookies.
Where it goes
Put the tag first in <head>, above every other script, on every page:
<!doctype html><html lang="en"> <head> <meta charset="utf-8" /> <!-- First: the ConsentAlly tag. --> <!-- Then everything else: your tag manager, analytics and theme scripts. --> <script src="/assets/theme.js" defer></script> <title>Your store</title> </head> <body></body></html>-
First. The script can only hold what loads after it. A tag above it runs as if ConsentAlly were not there.
-
As written. No
async,deferortype="module": the script has to run at once, before the page's other scripts. -
Once. A second copy on the same page does nothing, so a second copy left in a template does no harm.
Trackers written in your HTML
ConsentAlly holds a tracker written straight into your page's HTML before it runs, but the browser's preload scanner can fetch a script, image or iframe written in the HTML before any script sees it, so the visitor's address reaches the vendor even though nothing runs. Write such a tracker as a manual tag instead: the browser never fetches a manual tag, and ConsentAlly loads it once the visitor allows its category. The Scripts screen marks a held script it found written in your HTML in the last seven days and shows the manual tag to write in its place.
A manual tag is your tag with these changes:
type="text/plain"on a script, so the browser leaves it alone;data-ca-srcin place ofsrc;- optionally,
data-ca-categorynaming the category:necessary,functional,analytics,marketingor the ID of one of your own categories. Adddata-ca-vendorwith a vendor's ID from your configuration (or several, separated by spaces) to load it when the visitor allows that vendor alone. - on a script whose
typewasmodule,data-ca-type="module", so it runs as a module.
A manual tag without data-ca-category loads exactly when ConsentAlly would load the same address
written as a plain tag: its address decides, as the Scripts screen classifies it. A tag with a
category loads when the visitor allows that category, or its vendor; a necessary one loads at
once. Inline code needs a category. A tag naming a category your configuration does not have never
loads. ConsentAlly still checks the address itself, so a tag never loads before its own script
would: an address you have not classified yet waits for marketing until you classify it on the
Scripts screen.
A script tag runs where it stands, keeping its other attributes; an inline one written after an external one runs once that has loaded. When the visitor withdraws consent, the page reloads and the tags wait again.
Google Analytics 4: the library becomes a manual tag; the lines after it only queue commands, so they can stay as they are.
<script type="text/plain" data-ca-category="analytics" data-ca-src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX" async></script><script> window.dataLayer = window.dataLayer || []; function gtag() { dataLayer.push(arguments); } gtag("js", new Date()); gtag("config", "G-XXXXXXXXXX");</script>Meta Pixel: the whole inline snippet becomes a manual tag.
<script type="text/plain" data-ca-category="marketing"> !(function (f, b, e, v, n, t, s) { if (f.fbq) return; n = f.fbq = function () { n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments); }; if (!f._fbq) f._fbq = n; n.push = n; n.loaded = !0; n.version = "2.0"; n.queue = []; t = b.createElement(e); t.async = !0; t.src = v; s = b.getElementsByTagName(e)[0]; s.parentNode.insertBefore(t, s); })(window, document, "script", "https://connect.facebook.net/en_US/fbevents.js"); fbq("init", "YOUR_PIXEL_ID"); fbq("track", "PageView");</script>A YouTube video: the iframe keeps every attribute but src.
<iframe data-ca-category="marketing" data-ca-src="https://www.youtube-nocookie.com/embed/VIDEO_ID" width="560" height="315" title="Our product video" allowfullscreen></iframe>An image pixel works the same way: <img data-ca-category="marketing" data-ca-src="...">. Until the visitor allows it, an iframe stays an empty box and an image loads nothing. If your site sends a Content Security Policy with a nonce, give each manual script tag your nonce attribute too: under a nonce, a manual script tag without it never runs, so markup slipped into your page cannot use ConsentAlly to run a script. A policy that trusts the ConsentAlly tag by its hash (an integrity attribute, no nonce) cannot vouch for a manual script tag, so none runs there, and a manual script's address must be an https: or http: one.
Content Security Policy
If your site sends a Content Security Policy, allow ConsentAlly's edge for scripts and for connections. The script loads the rest of the widget, your configuration and the banner's language from there, and sends each consent record to it:
script-src 'self' https://edge.consentally.com;connect-src 'self' https://edge.consentally.com;If your policy allows scripts by nonce, add your nonce attribute to the tag: the script hands it on to the script it loads, and the banner's fallback stylesheet carries it too. If your banner shows a logo, allow the logo's host in img-src.
What happens on each page view
-
The script runs. It reads the browser's Global Privacy Control signal, sets the Google Consent Mode, Microsoft UET and Microsoft Clarity defaults to denied, and starts holding third-party scripts, iframes, images and requests. Files from your site's own host and its subdomains load, and so do Google Tag Manager's container and Shopify's platform hosts.
-
It fetches your published configuration from the edge, with two attempts within ten seconds. The other domains your configuration lists then load too, and so do the payment and captcha scripts ConsentAlly knows; known trackers and every other third party stay held.
-
It loads the rest of the widget, which reads the visitor's stored choice or your rules for their region, shows the banner when a choice is needed, and releases what the visitor allows without reloading the page.
If something fails
-
The configuration does not arrive (the edge cannot be reached, or the key is wrong): no banner shows and every third party stays held but Google Tag Manager's container and Shopify's platform hosts, payment and captcha scripts included. Your own files load. Nothing is ever released by a timer.
-
A visitor's ad blocker removes the script: nothing is held and no banner shows. ConsentAlly does not try to get around the visitor's blocker.
Where the choice is kept
The visitor's decision is stored in a first-party cookie named ca_state_ followed by your store
key, on the widest domain of your site the browser accepts (Secure, SameSite=Lax), with a copy
in localStorage. Two stores on one domain never share a decision.
Safari keeps a cookie written by script for at most seven days, so a Safari visitor who stays away longer is asked again.