StrongPrivacy

Global object

The global API is available after the v1 runtime initializes. Listen for the ready DOM event when application code might run first, then use onReady inside the connected application lifecycle.

Readiness and changes

let stopListening = () => {};

function connectStrongPrivacy() {
  const api = window.StrongPrivacy;
  if (!api) return;

  api.onReady((consent) => {
    console.log('StrongPrivacy is ready', consent);
  });

  stopListening = api.onChange((consent) => {
    updateApplicationState(consent);
  });
}

if (window.StrongPrivacy?.isReady) {
  connectStrongPrivacy();
} else {
  window.addEventListener('strongprivacy:ready', connectStrongPrivacy, {
    once: true
  });
}

// Call stopListening() when your component is disposed.

Method	Behavior
getConsent()	Returns the current consent object.
hasConsent(category)	Returns whether a consent category is currently allowed.
openPreferences()	Opens the hosted preference interface.
onReady(callback)	Runs after initialization and returns an unsubscribe function.
onChange(callback)	Subscribes to consent changes and returns an unsubscribe function.
registerScript(options)	Registers a consent-gated script and loads it when allowed.
isScriptLoaded(id)	Returns whether a registered script has executed.
getLoadedScriptIds()	Returns the identifiers of scripts loaded by the runtime.
removeScript(id)	Removes a registered script managed by the runtime.

The object also exposes read-only runtime context: isReady, siteId, platform, version, and configurationVersion.

Register a gated script

Use programmatic registration for widgets or vendors created after the initial document is parsed.

window.StrongPrivacy.registerScript({
  id: 'support-widget',
  category: 'functional',
  src: 'https://widget.example.com/widget.js',
  async: true,
  attributes: {
    'data-region': 'global'
  }
});

Option	Notes
id	Required stable identifier; must be unique on the page.
category	Required optional category: functional, analytics, marketing, or media. The legacy measurement alias remains accepted.
src / textContent	Provide a remote source or trusted inline script content.
attributes	Additional script attributes as string key-value pairs.
async / defer	Standard script loading flags.
target	Insertion target: head or body.
nonce	Content Security Policy nonce for the created script.
persistAfterConsentRevoked	Keeps the created tag after withdrawal. Use only when unloading would break the page and ensure the vendor stops processing independently.

Necessary scripts are not registered here

Load strictly necessary scripts normally. The registration API is for functional, analytics, marketing, and media resources that must wait for a visitor choice.

DOM events

Events are dispatched on window for framework-agnostic integrations.

window.addEventListener('strongprivacy:change', (event) => {
  console.log(event.detail);
});

strongprivacy:ready: initialization completed.
strongprivacy:change: the active consent state changed.
strongprivacy:script-load: a gated script was created.
strongprivacy:error: the runtime encountered a recoverable error.

Public runtime endpoints

These endpoints are consumed by the browser runtime. They are origin-checked and use the property’s public identity, not workspace secrets.

Endpoint	Purpose
GET /api/public/config/[siteId]	Returns the published consent configuration for an allowed origin.
POST /api/public/consent	Records a consent decision and its evidence for the property.

Do not proxy workspace credentials to the browser

The runtime never needs the database URL, authentication secret, Shopify secret, or integration encryption key. Keep all private credentials on the server.

A consent write requires siteId, a pseudonymous visitorKey, boolean preferences, the exact configurationVersion returned to that banner, and a unique decisionId. Reuse the decision ID only when retrying the same choice. A conflicting reuse returns 409; missing or invalid evidence fields return 400. The hosted runtime supplies these values automatically.

New permission grants wait for the server acknowledgment. Withdrawal still restricts local permissions when the service is unavailable; the banner reports the save failure so the visitor can retry. Browser origin checks are integration controls, not proof of visitor identity.

Private server API

Use a workspace API key from server-side code to read operational data. Responses are isolated to the key’s workspace; evidence is paginated and scan responses contain the 100 newest runs.

Authenticated request

curl http://localhost:3210/api/v1/sites \
  --header "Authorization: Bearer strongprivacy_live_your_api_key"

Endpoint	Returns
GET /api/v1/sites	Workspace properties
GET /api/v1/scans	Latest verification runs
GET /api/v1/consent-records	Consent evidence, 100 records per page

Keep API keys on trusted servers

Create and revoke keys from the Developer page. Send the key in the Authorization header, never a query string, browser bundle, log, or public repository. A key is shown only once.

The consent-records response contains data and nextCursor. Send the returned cursor as the ?cursor= query parameter for the next page, until it is null. Preserve the opaque cursor unchanged. Invalid cursors return 400. All API clients should respect 429 responses and the Retry-After header.