Developers
JavaScript API
Control the banner from your own code with window.allowedit: open it, read or set consent, listen for changes, and react to the allowedit_consent events.
The allowedit script adds a small API at window.allowedit. Use it to open the banner from your own buttons, check what's allowed right now, react when it changes, or set consent from your own interface.
Two questions, two methods
Most code asks one of two things:
- "Should I load X now?" Use
ready()orgetState(). They give the effective state for this visitor, even before they've chosen. In a notice or opt-out region, analytics may be allowed with no choice at all. - "Has the visitor chosen?" Use
getConsent(). It returns the stored choice, ornullif there isn't one.
Wait for the script
The API exists once the script has run. Because the script is the first in your head, it's usually ready before your own code. To be safe, guard your calls:
window.allowedit?.showPreferences();
The visitor's zone (which decides the default state) is worked out just after the script starts. ready() waits for it:
window.allowedit?.ready(() => {
const state = window.allowedit.getState();
if (state.analytics) startMyAnalytics();
});
Reference
| Member | Returns | What it does |
|---|---|---|
version | string | The script version, e.g. "1.0.0" |
ready(callback) | void | Calls callback once the visitor's zone is known (straight away if it already is) |
getState() | object | The effective state: what's allowed now, the zone and mode, and whether the visitor has chosen |
getConsent() | object or null | The stored choice, or null if there isn't one yet |
show() | void | Shows the banner (the first layer) |
showPreferences() | void | Opens the preferences panel with a switch per category |
hide() | void | Closes the banner or panel without saving a choice |
acceptAll() | void | Allows every category and saves the choice |
rejectAll() | void | Refuses every optional category and saves the choice |
setConsent(choices) | void | Saves a choice for the categories you pass |
onChange(callback) | function | Calls callback when consent changes; returns a function that stops listening |
getState()
type State = {
preferences: boolean;
analytics: boolean;
marketing: boolean;
zone: "eu" | "us" | "other";
mode: "optin" | "optout" | "notice" | "none";
decided: boolean; // true once the visitor has made a choice
};
window.allowedit.getState(); // State
The category values are what's allowed right now. Before a choice, they follow the zone's mode: off in an opt-in zone, on in an opt-out or notice zone (except marketing for a browser sending Global Privacy Control). After a choice, they're the visitor's choice.
zone is where the visitor is: eu (the EU and EEA, the UK, Switzerland and Quebec), us (US states with privacy laws) or other. mode is your rule for that zone. See Region rules and GPC.
Call getState() inside ready(), or after the first allowedit:consent event, so the zone is known.
getConsent()
type Consent = {
id: string; // the consent id, also in the consent log
preferences: boolean;
analytics: boolean;
marketing: boolean;
action: "accept" | "reject" | "custom" | "optout" | "gpc";
at: number; // when the choice was made, in milliseconds since 1970
};
window.allowedit.getConsent(); // Consent | null
null means the visitor hasn't chosen yet, or their choice was made under an older consent version and they need to choose again.
action says how the choice was made:
accept: Accept all.reject: Reject all.custom: saved from the preferences panel.optout: the Do not sell or share link, in US opt-out regions.gpc: applied automatically from a Global Privacy Control signal.
onChange(callback)
const stop = window.allowedit.onChange((consent) => {
if (consent.analytics) startMyAnalytics();
});
// Later, to stop listening:
stop();
The callback gets the same object as getConsent().
setConsent(choices)
Pass only the categories you want to change. The others keep their current value, or stay off if there's no choice yet.
window.allowedit.setConsent({ analytics: true });
window.allowedit.setConsent({ preferences: true, marketing: false });
The choice is saved in the visitor's consent cookie and recorded in your consent log as a custom choice. Only call it from a clear action the visitor took, like switching a toggle in your own settings page.
Events
The window event
The script dispatches allowedit:consent on window:
- once, as soon as the state is known, with
action: "default"; - again every time consent is set or changed, with the action of that choice.
event.detail holds the consent fields (as in getConsent()) plus state, which has the same shape as getState(). Read event.detail.state to know what's allowed right now:
window.addEventListener("allowedit:consent", (event) => {
const { action, state } = event.detail;
if (state.marketing) loadChatWidget();
if (action !== "default") console.log("The visitor chose:", action);
});
The dataLayer event
For Google Tag Manager, the script pushes allowedit_consent to window.dataLayer with a field per category:
{
event: "allowedit_consent",
allowedit_preferences: "granted",
allowedit_analytics: "granted",
allowedit_marketing: "denied"
}
Open GTM's Preview mode to see the exact fields on your site. Setup steps are in Google Tag Manager.
Examples
A "Cookie settings" button
No code needed: any element with data-allowedit="settings", or any link to #cookie-settings, opens the preferences panel.
<button type="button" data-allowedit="settings">Cookie settings</button>
<a href="#cookie-settings">Cookie settings</a>
Load something only when it's allowed
function whenAllowed(category, run) {
window.allowedit?.ready(() => {
if (window.allowedit.getState()[category]) return run();
const stop = window.allowedit.onChange((consent) => {
if (consent[category]) {
stop();
run();
}
});
});
}
whenAllowed("preferences", () => loadChatWidget());
Reload after consent is withdrawn
Scripts that already ran can't be stopped. If a visitor turns analytics off, reload so the page starts clean:
let last;
window.addEventListener("allowedit:consent", (event) => {
const now = event.detail.state;
if (last && last.analytics && !now.analytics) location.reload();
last = now;
});
Ask only visitors who haven't chosen
window.allowedit?.ready(() => {
if (!window.allowedit.getState().decided) window.allowedit.show();
});
Still stuck? Email support@allowedit.com with your site's address and what you see.