Skip to content

ConsentAlly works with AI assistants. A merchant can have their assistant set up, sign in to or check their ConsentAlly account from the chat: the assistant needs only the merchant's email address, and the merchant approves it on one ConsentAlly page with a code. Nothing is created or connected before that approval. How it works: https://consentally.com/auth.md

Docs pages

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

HTML
<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.

  • src names the script on ConsentAlly's edge. A file there never changes under its name, so browsers keep it in their cache.

  • data-ca-key is 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:

HTML
<!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, defer or type="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-src in place of src;
  • optionally, data-ca-category naming the category: necessary, functional, analytics, marketing or the ID of one of your own categories. Add data-ca-vendor with 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 type was module, 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.

HTML
<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.

HTML
<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.

HTML
<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:

Text
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

  1. 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.

  2. 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.

  3. 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.