JavaScript API
A small browser API on window.consenter for working with consent programmatically
This work is licensed under CC BY-SA 4.0
The Consenter banner exposes a small browser API on window.consenter for reading
consent, reacting to changes, granting contextual consent, and opening the banner
from your own UI.
Waiting for the API
window.consenter is set once the banner script has loaded, which may be after
your own code runs. Guard with the consenter:ready event:
function start() {
// window.consenter is ready here
}
if (window.consenter) {
start();
} else {
document.addEventListener("consenter:ready", start);
}get()
Takes no arguments and returns the current consent state synchronously:
Prop
Type
subscribe(callback, selector?)
Runs callback with the current state and again on every change, and returns
a function that removes the subscription.
Omit the selector to receive the full ConsentRecord. Pass one to watch a
single service instead:
Prop
Type
The shape of purposeIds decides what the callback receives:
purposeIds: "service-improvement"→boolean,trueonly when that purpose is granted for the service.purposeIds: ["service-improvement", "customise-ads"]→Record<string, boolean>, e.g.{ "service-improvement": true, "customise-ads": false }.
const unsubscribe = window.consenter.subscribe(
function (granted) {
if (granted) showContent();
},
{ serviceId: "YOUR_SERVICE_ID", purposeIds: "YOUR_PURPOSE_ID" },
);has(selector)
The one-shot version of subscribe: evaluates the selector once,
synchronously, against the current state:
Prop
Type
Returns what subscribe would pass to its callback: boolean for a single
purpose ID, Record<string, boolean> for an array.
if (
window.consenter.has({
serviceId: "YOUR_SERVICE_ID",
purposeIds: "YOUR_PURPOSE_ID",
})
) {
showContent();
}grantContextualConsent(tppId, purposeIds)
Grants consent for a single service across the given purposes, without re-opening the banner. See Contextual Consent for the full custom-UI flow.
Prop
Type
Returns "success", or a validation error string. The consent is saved
asynchronously — use subscribe or has to react once it lands.
banner.open()
Opens the cookie banner from your own UI — typically a "Cookie settings" link in your footer that gives visitors a route back into their consent choices. Takes no arguments:
<button type="button" onclick="window.consenter.banner.open();">
Cookie settings
</button>consenter:ready
Dispatched on document once window.consenter is available — see
Waiting for the API.
Deprecated
Everything here keeps working but logs a console warning and will be removed in a future major release.
subscribe(callback, identifier[, purposeId])— the string-argument forms. Use a selector instead:subscribe(callback)for the full record, orsubscribe(callback, { serviceId, purposeIds })for a service. The string forms still return"success"instead of an unsubscribe function.unsubscribe(identifier)— only removes string-identifier subscriptions. Call the function returned bysubscribeinstead.data-consenter-tpp-purpose-*attributes — the per-purpose flags on contextual consent embeds (…-improve-the-service,…-marketing-analytics,…-customise-ads). List the purposes in a singledata-consenter-purpose-ids="id1,id2"attribute instead.
How is this guide?
Shape Consenter Together
Consenter is built on an open and participatory process that grows through community collaboration. Whether you share feedback, improve the documentation, or contribute to the Risk Configuration Guides or Technical Integration Guides, your expertise helps make Consenter more privacy-friendly, interoperable, and useful for everyone—including your own users and services: Get finally your benefits and control the risks when sharing personal data.
Last updated on