Getting Started

Installation

Add the OptinStack script tag to your page. The server injects your project configuration and serves the runtime bundle automatically:

<script src="https://api.optinstack.com/banner/{siteId}.js" defer></script>

Replace {siteId} with your project's site ID from the OptinStack dashboard.

Versioned Scripts

You can pin to a specific version for stability:

<script src="https://api.optinstack.com/banner/v1/{siteId}.js" defer></script>

How It Works

When the script loads, the SDK:

1. Reads the server-injected configuration from window.optinstackConfig and window.optinstackMeta
2. Detects the user's region and matches the appropriate consent rule
3. Checks for existing consent stored in cookies
4. Renders the consent banner inside a Shadow DOM (isolated from your page styles)
5. Blocks third-party scripts and iframes that require consent
6. Integrates with Google Consent Mode v2 (if GTM is present)

Callback Queue

Before the SDK loads, window.OptinStack acts as a callback queue. Push functions into it and they'll execute once the SDK is ready:

window.OptinStack = window.OptinStack || [];

window.OptinStack.push(function (os) {
  // Runs after the SDK is fully initialized
  console.log('SDK version:', os.version);
  console.log('Current consent:', os.consent.get());
});

After initialization, push() still works — callbacks execute immediately:

// This works both before and after SDK init
window.OptinStack.push(function (os) {
  os.events.on('consent-updated', function (detail) {
    console.log('Consent changed:', detail.choices);
  });
});

Consent Categories

OptinStack uses four fixed consent categories:

Banner Modes

The consent banner behavior depends on the configured mode for the matched region:

Global Privacy Control

When the browser sends a Global Privacy Control signal (navigator.globalPrivacyControl === true), the SDK automatically sets all optional category defaults to false, regardless of the banner mode.

You can check whether GPC was detected:

window.OptinStack.push(function (os) {
  if (os.gpc) {
    console.log('GPC signal detected — optional categories defaulted to false');
  }
});