JavaScript API

The One Privacy widget exposes a small, dependency-free API on the page. Use it to read the visitor's current consent state and to wire your own scripts so they only run once consent is given.

This page is for developers integrating One Privacy alongside other scripts on a customer site.

What you get

When the widget loads, it does three things:

1. Sets window.onePrivacyCookieGroups to a comma-separated string of accepted category IDs.
2. Fires a one-privacy-consent-updated event on window whenever consent changes.
3. Pushes a one-privacy-consent-updated event into the GTM dataLayer for tag-manager based workflows.

Reading the current consent state

The simplest way to check whether a category is allowed is the global variable:

check-consent.js

// "C0001,C0002" -> Necessary and Functional accepted
const accepted = window.onePrivacyCookieGroups || '';

if (accepted.includes('C0003')) {
  // Performance cookies allowed: load analytics
  loadAnalytics();
}

The category IDs are stable. See Cookie category IDs for the full list.

⏳

Wait for the event before checking

The variable is set as soon as the widget initializes, which can be a tick or two after page load. If you need to act exactly when consent is ready, listen for the event below instead of polling the variable.

Listening for consent changes

One Privacy fires a CustomEvent named one-privacy-consent-updated whenever the visitor accepts, rejects, or changes their preferences.

listen-for-consent.js

window.addEventListener('one-privacy-consent-updated', () => {
  const accepted = window.onePrivacyCookieGroups || '';

  if (accepted.includes('C0003')) {
    enableAnalytics();
  }

  if (accepted.includes('C0004')) {
    enableMarketing();
  }
});

The event fires:

The first time the widget initializes on the page.

Every time the visitor saves a new choice (Accept All, Reject All, Confirm My Choices).

When the visitor reopens preferences via the floating button and changes a setting.

The consent cookie

One Privacy stores the current state in a cookie named onePrivacyConsent. The value is a URL-encoded query string with three keys:

onePrivacyConsent cookie

groups=C0001,C0002,C0003&createdAt=2026-04-25T08:14:23.512Z&updatedAt=2026-04-25T08:14:23.512Z

You don't normally need to read this cookie; the global variable and event are easier to work with. It's documented here so you know what's there.

Render programmatically (for SPAs and previews)

The widget exposes a render function on the global scope. Most sites don't need this because the <script data-oneprivacy-widget="true"> snippet handles initialization automatically.

If you build a single-page app and want to control when the banner mounts, you can call:

manual-render.js

window.renderOnePrivacyWidget('one-privacy-container-id', {
  projectId: 'YOUR_PROJECT_ID',
  // optional: force a region for testing
  locationCode: 'DE',
});

The function creates a container element if one with that id doesn't already exist, then mounts the widget into it.

What's next

Consent events covers the event payloads in detail.

Cookie category IDs lists every category and what it maps to.

Google Consent Mode explains the gtag calls One Privacy makes for you.

GTM dataLayer integration covers Tag Manager triggers.