Events

Subscribe to consent, blocking, and reporting events from the OptinStack runtime.

OptinStack emits events through two channels simultaneously:

SDK events via OptinStack.events.on() / OptinStack.events.off()
DOM CustomEvents on document.documentElement with the optinstack: prefix

Both fire for every event. Use whichever fits your integration.

SDK initialization is not an event. Await window.OptinStack.ready instead of listening for a ready event.

Subscribing

SDK event API

await window.OptinStack.ready;

function handler(detail) {
  console.log(detail);
}

window.OptinStack.events.on('consent-updated', handler);
window.OptinStack.events.off('consent-updated', handler);

Wildcard listener

window.OptinStack.events.on('*', (eventName, detail) => {
  console.log('Event:', eventName, detail);
});

DOM CustomEvents

document.documentElement.addEventListener('optinstack:consent-updated', (e) => {
  console.log('Consent changed:', e.detail.choices);
});

Events have bubbles: true so they propagate through the document tree.

`accept-all`

Fires immediately before all categories are set to true.

window.OptinStack.events.on('accept-all', () => {
  console.log('User accepted all categories');
});

`reject-all`

Fires immediately before optional categories are set to false.

window.OptinStack.events.on('reject-all', () => {
  console.log('User rejected optional categories');
});

Fires after consent choices change. This is the primary event for reacting to consent state.

window.OptinStack.events.on('consent-updated', (detail) => {
  console.log(detail.id); // Consent record ID
  console.log(detail.choices); // { necessary, analytics, marketing, preferences }
  console.log(detail.previousChoices); // Previous state (if available)
  console.log(detail.action); // "accept_all" | "reject_all" | "submit" | "preferences"
  console.log(detail.source); // "banner" | "preferences" | "api"
  console.log(detail.timestamp); // Unix timestamp
});

This event only fires when choices actually change. Duplicate updates are deduplicated.

Fires after renew() clears stored consent and resets choices to the active rule defaults. Use this when you need to hide consent-gated UI until the visitor makes a new choice.

window.OptinStack.events.on('consent-cleared', (detail) => {
  console.log(detail.id);
  console.log(detail.choices);
  console.log(detail.timestamp);
});

`open-preferences`

Fires when the preferences dialog should open. You can also dispatch optinstack:open-preferences on window from page code. See Banner control.

Blocking events

These events fire when the runtime blocks or unblocks third-party resources based on consent.

`script-blocked` / `script-unblocked`

window.OptinStack.events.on('script-blocked', (detail) => {
  console.log(detail.src);
  console.log(detail.element); // HTMLScriptElement
  console.log(detail.categories); // ["analytics", "marketing"]
});

`iframe-blocked` / `iframe-unblocked`

window.OptinStack.events.on('iframe-blocked', (detail) => {
  console.log(detail.src);
  console.log(detail.element); // HTMLIFrameElement
  console.log(detail.categories);
});

`map-blocked` / `map-unblocked`

Specific to Webflow map embeds:

window.OptinStack.events.on('map-blocked', (detail) => {
  console.log(detail.element);
  console.log(detail.categories);
});

`storage-blocked`

Fires when access to localStorage or sessionStorage is blocked for a key that requires consent:

window.OptinStack.events.on('storage-blocked', (detail) => {
  console.log(detail.key);
  console.log(detail.storageType); // "localStorage" | "sessionStorage"
  console.log(detail.categories);
});

Fires when a tracker is blocked or purged:

window.OptinStack.events.on('cookie-blocked', (detail) => {
  console.log(detail.name);
  console.log(detail.categories);
  console.log(detail.action); // "blocked" | "purged"
});

Reporting events

Fires when the runtime cannot record a consent update:

window.OptinStack.events.on('consent-sync-failed', (detail) => {
  console.error(detail.error, detail.payload);
});

Event reference

Event	Payload	Description
`accept-all`	:	All categories accepted
`reject-all`	:	Optional categories rejected
`consent-updated`	`{ id, choices, previousChoices?, action?, source?, timestamp }`	Consent state changed
`consent-cleared`	`{ id, choices, timestamp }`	Stored consent cleared and defaults restored
`open-preferences`	:	Preferences dialog should open
`script-blocked`	`{ src, element, categories }`	Script blocked
`script-unblocked`	`{ src, element, categories }`	Script unblocked
`iframe-blocked`	`{ src, element, categories }`	Iframe blocked
`iframe-unblocked`	`{ src, element, categories }`	Iframe unblocked
`map-blocked`	`{ element, categories }`	Map embed blocked
`map-unblocked`	`{ element, categories }`	Map embed unblocked
`storage-blocked`	`{ key, storageType, categories }`	Storage access blocked
`cookie-blocked`	`{ name, categories, action }`	Tracker blocked or purged
`consent-sync-failed`	`{ error, payload }`	Consent record could not be reported

Events

On this page