Getting Started
Install OptinStack on your website and use the JavaScript API.
Installation
Add the OptinStack script tag to your page. It loads the consent runtime, which fetches your project configuration and renders the banner automatically:
<script
src="https://api.optinstack.com/v1/js/runtime/stable/optinstack.js"
data-optinstack-site="{projectId}"
></script>Replace {projectId} with your project ID from the OptinStack dashboard. Place the tag as the first element inside <head>, before any third-party scripts.
How it works
When the script loads, the runtime:
- Loads the consent runtime bundle and fetches your published project configuration using the
data-optinstack-siteattribute - Detects the visitor's region and matches the appropriate consent rule
- Checks for existing consent stored in the browser
- Renders the consent banner inside a Shadow DOM (isolated from your page styles)
- Blocks known third-party scripts and iframes from your published tracker inventory, plus resources you manually tag with consent categories
- Records consent updates so they are available in OptinStack reporting
The runtime resolves configuration for the current hostname only when that hostname has Free, paid, Enterprise, or Workspace coverage. For production, use the public hostname visitors see. Webflow and Framer development hostnames can carry Free or paid coverage while you build; Free can also activate on the verified production hostname, and paid plans include one self-service move. See Domain Scans for hostname, reverse-proxy, and scanner access guidance.
Using the API
Wait for initialization before calling API methods:
await window.OptinStack.ready;
console.log(window.OptinStack.version);
console.log(window.OptinStack.choices);If your code runs in a module or after the script tag, await OptinStack.ready is sufficient. For inline scripts that may run before the bundle finishes loading, defer your logic:
(async () => {
await window.OptinStack.ready;
window.OptinStack.events.on('consent-updated', (detail) => {
console.log('Consent changed:', detail.choices);
});
})();See the JavaScript API reference for the full surface.
Consent categories
OptinStack uses four fixed consent categories:
| Category | Default | Description |
|---|---|---|
necessary | Always true | Essential trackers, cannot be declined |
analytics | Varies by mode | Analytics and performance tracking |
marketing | Varies by mode | Advertising and marketing trackers |
preferences | Varies by mode | Functionality and personalization |
The necessary category is always true and cannot be set to false. This is enforced at every level of the SDK.
Consent model vs banner variant
Two related values describe the matched regional policy:
| Property | Values | Meaning |
|---|---|---|
mode (consentModel) | opt-in, opt-out, informational | How optional categories default and what counts as a decision |
uiVariant | opt-in, opt-out, informational, dont-sell | Which banner UI the visitor sees |
| Model / variant | Behavior |
|---|---|
opt-in | Optional categories default to false. The visitor must explicitly accept. |
opt-out | Optional categories default to true. The visitor can reject. |
informational | Banner acknowledges notice and records accept-all consent. |
dont-sell (uiVariant only) | Banner uses "Do Not Sell or Share" style copy; the underlying model is opt-out. |
await window.OptinStack.ready;
console.log(window.OptinStack.mode); // consent model
console.log(window.OptinStack.uiVariant); // banner UILanguages
English is the fixed source language. Free and Pro publish English only. On Business and Enterprise, you can enable secondary locales (22 languages beyond English, including major EU, APAC, and MENA languages). The runtime loads published packs from the CDN using the page html lang (normalized to a primary subtag such as fr from fr-CA). Languages you have not enabled fall back to English. Translations update when you publish configuration; they do not require reinstalling the script.
If you need a language that is not listed yet, contact us and we will review adding it.
See banner language settings in the dashboard.
Global Privacy Control
When the browser sends a Global Privacy Control signal (navigator.globalPrivacyControl === true), the runtime records gpc: true. By default, all optional category defaults become false. On plans with advanced GPC controls, you can configure which optional categories GPC rejects.
await window.OptinStack.ready;
if (window.OptinStack.gpc) {
console.log('GPC signal detected, optional categories defaulted to false');
}GPC is also reflected in consent records and in the GTM dataLayer event optinstack_gpc_signal_detected. See Google Consent Mode.
Next steps
Install
Add the runtime script and place it before third-party trackers.
Domain scans
Choose the right public hostname for scans, staging previews, and reverse proxies.
JavaScript API
Read and write consent state, subscribe to changes, and use UI helpers.
Consent cookie
Read stored consent state and understand subdomain sharing.
Banner control
Open preferences, reset consent, and build custom consent flows.
Events
Subscribe to consent, blocking, and reporting events.
Was this helpful?