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:
// 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,truewhen granted.necessaryis alwaystrue.vendors: every vendor id in your configuration,truewhen granted.gpc:truewhen the browser sends the Global Privacy Control signal.jurisdiction: the id of the rule applied to the visitor, such asgdpr_eprivacyorccpa_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.nullwhen 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.
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.
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.
// 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
trueorfalse. - It was made from inside an
onChangelistener. 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.
Open the preference centre from a link or button
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:
<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:
<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:
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 {};