PrivacyKit

PrivacyKit API Reference

This page documents the public JavaScript API used to read consent state, react to consent changes, and control the dialog flow from application code.

Table of Contents

  1. Script setup
  2. Usage
  3. Window namespace
  4. Public methods
  5. Related events
  6. Framework notes

Script setup

Load PrivacyKit once globally before calling any API methods.

<script type="module" src="https://cdn.privacykit.eu/privacykit/index.esm.js"></script>

Usage

All public access goes through the global window.PrivacyKit object, regardless of how the script loads.

const api = window.PrivacyKit;

if (api?.hasConsent('analytics')) {
  // analytics consent granted
}

const unsubscribe = api?.onConsentChanged(consent => {
  console.log('Consent changed', consent);
});

Window namespace

PrivacyKit exposes the full API on window.PrivacyKit. subscriptionStatus is optional and may be null when unavailable.

window.PrivacyKit = {
  onReady,
  readConsent,
  hasConsent,
  onConsentChanged,
  openConsentDialog,
  onConsentDialogClosed,
  openPrivacyPolicyDialog,
  getSubscriptionStatus,
  subscriptionStatus,
};

Public methods

onReady

Subscribes to the privacykit:ready lifecycle event when the API becomes available.

onReady(callback: () => void): () => void
Returns an unsubscribe function.
window.PrivacyKit?.onReady(() => {
  // Safe to call PrivacyKit API methods here
  const consent = window.PrivacyKit.readConsent();
  // ...
});
onReady is replay-safe — if it has already fired, newly subscribed listeners are invoked immediately.

openConsentDialog

Opens the PrivacyKit dialog programmatically.

openConsentDialog(): void

onConsentDialogClosed

Subscribes to dialog close events.

onConsentDialogClosed(callback: () => void): () => void
Returns an unsubscribe function.

openPrivacyPolicyDialog

Opens the Privacy Policy dialog programmatically in standalone mode, reusing the styling and slot content from the declared consent-dialog.

openPrivacyPolicyDialog(): void
Useful when linking to Privacy Policy from your own UI.

getSubscriptionStatus

Returns the current subscription status for the domain. This is a read-only helper — subscription and billing are managed automatically by PrivacyKit via Paddle.

getSubscriptionStatus(): {
  status: string | null;
  billingInterval: string | null;
  subscriptionEnd: string | null;
  trailingEnd: string | null;
} | null

Framework notes

Framework-specific setup notes for integrating PrivacyKit custom elements.

  1. React: custom element typings ship in the distributed definition file — privacykit.d.ts.
  2. Vue 3: configure compilerOptions.isCustomElement for PrivacyKit tags.
  3. Angular: add CUSTOM_ELEMENTS_SCHEMA where custom elements are used.
  4. Svelte: no extra setup needed for runtime usage.

Next.js note

When PrivacyKit is loaded via script tags, call API methods from client components after the script finishes loading.

'use client';

import { useEffect } from 'react';

export default function Example() {
  useEffect(() => {
    const stop = window.PrivacyKit?.onConsentChanged(consent => {
      console.log(consent);
    });

    return () => {
      stop?.();
    };
  }, []);

  return null;
}

tsconfig.json

In modern tooling (Next.js / Vite / TypeScript 5+), .d.ts files outside src must be explicitly included to be picked up by the compiler.

{ 
  "include": ["src", "types/**/*.d.ts"] 
}