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

JavaScript API

The widget gives your own code one object, window.ConsentAlly, to read the visitor's choice, hear about a new one, open the preference centre and change the choice from a control on your page. It has six methods and dispatches no events of its own: a listener you register with onChange is told about every new decision.

When it is there

window.ConsentAlly is defined once the widget has started on the page: it has loaded your configuration and applied the visitor's stored choice or your rules for their region. Until then it is undefined, and it stays undefined when the widget cannot start (the configuration does not arrive, or a visitor's ad blocker removed the script). If a script on your page defined window.ConsentAlly first, the widget leaves it alone and installs nothing.

Check for it before you call it, or wait for it with a helper like this one:

JavaScript
// Calls back with the API once the widget has started; gives up after 10 s.function withConsentAlly(callback) {  let waited = 0;  (function check() {    if (window.ConsentAlly) callback(window.ConsentAlly);    else if ((waited += 100) <= 10000) setTimeout(check, 100);  })();} withConsentAlly(function (api) {  console.log(api.getConsent().categories);});

Every method catches its own errors: a call never throws into your page.

Methods

ConsentAlly.getConsent()

Returns a snapshot of the current decision:

  • categories: every category id in your configuration, true when granted. necessary is always true.
  • vendors: every vendor id in your configuration, true when granted.
  • gpc: true when the browser sends the Global Privacy Control signal.
  • jurisdiction: the id of the rule applied to the visitor, such as gdpr_eprivacy or ccpa_cpra. When no rule lists the visitor's location, your published fallback rule applies; strict, the built-in opt-in rule, applies only when there is no valid fallback.
  • configVersion: the version of your published configuration the decision was made under.
  • method: how the decision came about when it is new in this page view: "banner", "api", or "gpc" when the Global Privacy Control signal settled it. null when the decision was not made in this page view: a choice stored on an earlier visit, or no choice yet.

Before the visitor chooses, the snapshot shows the defaults your rules give their region. The snapshot and its maps are frozen: it never changes after you have it, and writing to it does nothing (or throws in strict mode). Call getConsent() again for the current state.

ConsentAlly.onChange()

onChange(listener) calls listener with a new snapshot after every new decision in this page view: a choice in the banner or the preference centre, a call to this API, or Shopify's consent taken over. It is not called for the decision the page loaded with; read getConsent() for that. It returns a function that removes the listener.

JavaScript
const stop = window.ConsentAlly.onChange(function (consent) {  if (consent.categories.analytics) {    startMyAnalytics();  }}); // Later, when the listener is no longer needed:stop();

A listener that throws does not stop the next one. A call made from inside a listener returns false at once; it is applied after the current round, unless it would grant anything.

ConsentAlly.openPreferences()

Opens the preference centre, where the visitor sees every category, and every vendor when your configuration shows vendors, and can change their choice. It always works. When the preference centre closes, focus goes back to the element that had it when you called.

JavaScript
document.querySelector("#privacy-choices").addEventListener("click", function () {  window.ConsentAlly.openPreferences();});

ConsentAlly.acceptAll()

Grants every category and vendor, except what the visitor's Global Privacy Control signal locks: under a rule that treats the signal as an opt-out of sale and sharing, marketing and vendors that sell or share data stay denied. It needs the visitor (see below). Returns true when the decision changed, false when the call was refused or changed nothing.

ConsentAlly.rejectAll()

Denies everything but the necessary category. It always works. Returns true when the decision changed.

ConsentAlly.setConsent()

setConsent({ categories, vendors }) sets each category and vendor you name to true or false. Granting a category that was not granted also grants its vendors you do not name, except a vendor the visitor refused before; to keep a vendor off, name it false in the same call. A vendor in a category that is off never loads, whatever its own state. Everything else you do not name keeps its state, and ids that are not in your configuration are ignored. A value other than true or false, or a map that is not an object, refuses the whole call. Granting needs the visitor; narrowing always works. Returns true when the decision changed.

JavaScript
// Narrowing works at any time: turn analytics off and leave the rest as it is.window.ConsentAlly.setConsent({ categories: { analytics: false } }); // Granting needs the visitor's own click: allow marketing, but not one vendor.document.querySelector("#allow-marketing").addEventListener("click", function () {  window.ConsentAlly.setConsent({    categories: { marketing: true },    vendors: { meta: false },  });});

Grants need the visitor

A call that grants anything (acceptAll(), or setConsent() with a true the decision does not have yet) works only while the browser reports a user gesture (navigator.userActivation.isActive): call it from the visitor's click or key press on a control of your own. A script running as the page loads cannot grant itself consent, and a browser without navigator.userActivation refuses every grant.

A grant is also refused when it would borrow the visitor's answer in the banner: while a choice is being applied, during an event on the banner itself, and until the visitor has pressed something again since their last choice in the banner.

Rejecting, narrowing, reading and opening the preference centre always work. What the visitor's Global Privacy Control signal locks stays denied: under a rule that treats the signal as an opt-out of sale and sharing, marketing and vendors that sell or share data.

When a call returns false

  • The call would change nothing.
  • It would grant something without the visitor's gesture, or by borrowing their answer in the banner.
  • Its argument is not an object, or a value in it is not true or false.
  • It was made from inside an onChange listener. Such a call is applied after the current round, unless it would grant something.

What a change does

A change through the API takes the same path as a choice in the banner. What is now allowed loads without a page reload, and what is denied is held again. Google Consent Mode, Microsoft UET and Clarity get the update. The decision is stored in the visitor's browser and recorded as a consent record with the method api, and your onChange listeners are called.

When a change takes back something granted before, the widget deletes the cookies scripts can see and the local and session storage keys of those vendors and of the known trackers withdrawn with them and, once the new decision is stored, reloads the page so tags already running stop.

A link to #consentally-preferences opens the preference centre instead of moving the page, on any page with the widget. No script of yours is needed:

HTML
<a href="#consentally-preferences">Privacy choices</a>

A click without modifier keys on a link to the current page's #consentally-preferences opens it, and so does opening any page of your site with that fragment in its address, such as a link from an email. Try it here: change your privacy choices opens ConsentAlly's own preference centre on this site.

A click without modifier keys on an element whose id is consentally-preferences, or the id you set in the banner editor under Layout, opens it as well, and so does a click on anything inside that element. When the preference centre closes, focus goes back to the element if it can take focus, as a button or a link can. This works with the button to change choices later turned off:

HTML
<button type="button" id="site-settings">Cookie settings</button>

Make it a button or a link, so keyboard users can reach it. Choose an id without words such as cookie, consent or privacy, which ad blockers' filter lists look for in ids.

Types

For TypeScript, declare the object on Window:

TypeScript
interface ConsentSnapshot {  readonly configVersion: number;  readonly jurisdiction: string;  readonly categories: Readonly<Record<string, boolean>>;  readonly vendors: Readonly<Record<string, boolean>>;  readonly gpc: boolean;  readonly method: "banner" | "gpc" | "api" | null;} interface ConsentAllyApi {  openPreferences(): void;  getConsent(): ConsentSnapshot;  acceptAll(): boolean;  rejectAll(): boolean;  setConsent(choices: {    categories?: Readonly<Record<string, boolean>>;    vendors?: Readonly<Record<string, boolean>>;  }): boolean;  onChange(listener: (consent: ConsentSnapshot) => void): () => void;} declare global {  interface Window {    ConsentAlly?: ConsentAllyApi;  }} export {};