JavaScript API

The consent runtime exposes a flat API at window.OptinStack. Use it to read consent state, record decisions programmatically, subscribe to changes, and delegate UI helpers to the mounted banner plugin.

Initialization

Wait for the SDK to finish bootstrapping before calling API methods:

await window.OptinStack.ready;
console.log(window.OptinStack.version);

ready is a Promise that resolves once the consent kernel, blocking, and plugins have initialized and the banner UI has been scheduled to load. It rejects if initialization fails. The banner plugin may register slightly after ready resolves; use ui.* helpers (which are safe no-ops until it mounts) or listen for consent-updated to react to user interaction.

Consent state

choices

Returns the current consent choices as an object:

const choices = window.OptinStack.choices;
// { necessary: true, analytics: false, marketing: false, preferences: false }

Assign a full object to update multiple categories at once. necessary is always forced to true.

window.OptinStack.choices = {
  necessary: true,
  analytics: true,
  marketing: false,
  preferences: false,
};

Category getters and setters

Each category is available as a top-level property:

window.OptinStack.necessary; // always true (read-only)
window.OptinStack.analytics; // boolean
window.OptinStack.marketing; // boolean
window.OptinStack.preferences; // boolean

window.OptinStack.analytics = true;

all

Write-only shorthand to accept or reject all optional categories:

window.OptinStack.all = true; // accept all
window.OptinStack.all = false; // reject all optional categories

acceptAll(source?) and rejectAll(source?)

window.OptinStack.acceptAll('api');
window.OptinStack.rejectAll('api');

The optional source argument is 'banner', 'preferences', or 'api'. It is included in consent records and consent-updated events.

renew()

Clears stored consent, resets choices to rule defaults, and sets hasConsented to false. The banner reappears when the user has not yet consented.

window.OptinStack.renew();

hasConsented

Whether the visitor has an active stored consent record:

if (window.OptinStack.hasConsented) {
  console.log('Returning visitor with saved consent');
}

Consent choices are also persisted in the first-party optinstack cookie. See Consent Cookie for the cookie format and subdomain sharing behavior.

Context properties

const mode = window.OptinStack.mode;
const bannerType = window.OptinStack.uiVariant;
const policy = window.OptinStack.config.policy;

mode is the consent model (how optional categories default and what counts as a decision). uiVariant is the banner presentation, which can be dont-sell while the underlying model remains opt-out. Prefer uiVariant when you need to know which UI the visitor sees.

Server consent token

getServerConsentToken()

Returns a short-lived signed token that your backend can verify with the @optinstack/server package. Use it when a server route should only run after the visitor has granted specific categories.

await window.OptinStack.ready;

const token = await window.OptinStack.getServerConsentToken();

await fetch('/api/personalize', {
  headers: {
    'X-OptinStack-Consent': token,
  },
});

Behavior:

• Tokens are cached in the browser until near expiry, then refreshed automatically.
• On opt-in policies, the call throws until the visitor has stored consent (hasConsented === true). On opt-out and informational policies, a default token may be available before an explicit interaction.
• The token is meant for your backend verification. It is not a substitute for reading OptinStack.choices in the browser.

Verify tokens in Node with verifyConsentToken and isConsentAllowed from @optinstack/server. See that package's README for install and server-side examples.

subscribe(callback)

React to consent state changes. The first synchronous callback is skipped so you only receive updates after subscribing.

const unsubscribe = window.OptinStack.subscribe((state) => {
  console.log(state.choices, state.mode, state.gpc);
});

// Later
unsubscribe();

Keyed subscribe

Subscribe to a single key:

window.OptinStack.subscribe('analytics', (value) => {
  console.log('Analytics consent:', value);
});

window.OptinStack.subscribe('choices', (choices) => {
  console.log(choices);
});

Supported keys: 'choices', 'hasConsented', 'necessary', 'analytics', 'marketing', and 'preferences'.

events.on() and events.off()

Subscribe to the typed event bus. See the Events reference for all event names and payloads.

function onConsentUpdated(detail) {
  console.log(detail.choices, detail.source, detail.action);
}

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

Wildcard listener:

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

Every bus event also fires as a DOM CustomEvent on document.documentElement with the optinstack: prefix (for example optinstack:consent-updated).

ui

UI helpers delegated to the mounted banner plugin. These are no-ops until the banner bundle registers.

ui.setPlaceholderHTML(fn)

Customize HTML shown inside blocked iframe placeholders when consent is denied:

window.OptinStack.ui.setPlaceholderHTML((categories) => {
  return '<p>Accept consent to view this content.</p>';
});

ui.renderDeclaration(target?, options?)

Render the tracker declaration widget into host-page elements. Default target: [data-optinstack-declaration].

window.OptinStack.ui.renderDeclaration();
window.OptinStack.ui.renderDeclaration('#my-declaration', {
  styles: '.custom { color: red; }',
});

Returns a cleanup function, or undefined if the banner plugin is not mounted yet.

Advanced

registerUiPlugin(plugin)

Register a custom UI plugin. The production banner bundle calls this automatically. Advanced use only.

destroy()

Tears down blocking, plugins, UI, and event listeners.

window.OptinStack.destroy();