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.

Platform consent APIs

On top of the events above, the widget passes each choice to the consent API of the platform it runs on, when that API is present:

Google Consent Mode. Every page load and every change. See Google Consent Mode.

Shopify Customer Privacy API. Every visitor action (accept, reject, save settings) on a Shopify storefront. See Installing on Shopify.

WP Consent API. Every page load and every change on a WordPress site with the WP Consent API plugin active. See Installing on WordPress.

Nothing runs on platforms that do not expose these APIs.

The consent cookie

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

onePrivacyConsent cookie

groups=C0001,C0002,C0003&createdAt=2026-04-25T08:14:23.512Z&updatedAt=2026-04-25T08:14:23.512Z&userId=1f2e...&cgbu=1

Key	Meaning
groups	Accepted category IDs.
createdAt	When the cookie was first written.
updatedAt	When the visitor last changed their choice.
userId	Random ID used to link consent records.
cgbu	Consent given by user. 1 after the visitor accepted, rejected, or confirmed their choices. 0 while the value only reflects the region's defaults.

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.

Open cookie settings from your own link or button

Many sites add their own "Cookie Settings" link in the footer so visitors can reopen their preferences without the floating button. To wire that up, add the class op-custom-cookie-settings-trigger to any clickable element:

footer-link.html

<button class="op-custom-cookie-settings-trigger">Cookie Settings</button>

When a visitor clicks the element, the widget opens the same Cookie Settings popup that appears behind Manage Settings and the floating button.

A few details:

The class works on any element, and clicks on children inside it (an icon or a span) count too.

If you use it on an <a href="#"> link, the widget prevents the default navigation, so the page won't jump.

Elements added after page load also work. The widget listens at the document level, so single-page apps don't need to re-bind anything on route changes.

We recommend a <button> over a link where possible; native buttons are keyboard-accessible out of the box.

Render programmatically (for SPAs and previews)

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, opt in to manual rendering before the snippet loads:

manual-render.js

// Must run before the One Privacy script tag loads.
window.onePrivacyOptions = {renderManually: true};

With that flag set, the widget skips auto-rendering and exposes a render function on the global scope instead, which you call when you're ready:

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. Without renderManually: true, window.renderOnePrivacyWidget is not defined; the widget has already rendered itself.

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.