PrivacyKit API Reference

Questa pagina descrive l'API JavaScript pubblica usata per leggere lo stato del consenso, reagire ai cambiamenti e controllare il dialogo dal codice dell'applicazione.

Indice

Configurazione script

Carica PrivacyKit globalmente prima di chiamare qualunque metodo dell'API.

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

Utilizzo

Tutto l'accesso pubblico passa dall'oggetto globale window.PrivacyKit, indipendentemente da come viene caricato lo script.

const api = window.PrivacyKit;

if (api?.hasConsent('analytics')) {
  // consenso analitico concesso
}

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

Namespace window

PrivacyKit espone l'intera API su window.PrivacyKit.

window.PrivacyKit = {
  onReady,
  readConsent,
  hasConsent,
  onConsentChanged,
  openConsentDialog,
  onConsentDialogClosed,
  openPrivacyPolicyDialog,
  toggleComplianceMonitor,
  getSubscriptionStatus,
  subscriptionStatus,
};
subscriptionStatus è opzionale e può essere null quando non disponibile.

Metodi pubblici

onReady

Si iscrive all'evento privacykit:ready quando l'API diventa disponibile.

onReady(callback: () => void): () => void
Restituisce una funzione di annullamento.

window.PrivacyKit?.onReady(() => {
  // Qui puoi chiamare in sicurezza i metodi dell'API PrivacyKit
  const consent = window.PrivacyKit.readConsent();
  // ...
});
onReady è sicuro rispetto ai replay — se è già stato emesso, i listener sottoscritti successivamente vengono invocati immediatamente.

readConsent

Legge il cookie di consenso corrente e restituisce un oggetto normalizzato.

readConsent(): {
  analytics: boolean;
  marketing: boolean;
  preferences: boolean;
} | null
Restituisce null quando non esiste un cookie valido.

hasConsent

Valuta il consenso per una categoria o un'espressione.

hasConsent(expression?: string): boolean

Espressione omessa: richiede tutte le categorie.
Categoria singola: analytics, marketing o preferences.
Espressione AND: analytics+marketing.
Espressione OR: analytics|marketing.

onConsentChanged

Si iscrive agli aggiornamenti di consenso e restituisce una funzione di annullamento.

onConsentChanged(callback: (consent: {
  analytics: boolean;
  marketing: boolean;
  preferences: boolean;
} | null) => void): () => void
Restituisce una funzione di annullamento.

openConsentDialog

Apre il dialogo PrivacyKit via codice.

openConsentDialog(): void

onConsentDialogClosed

Si iscrive agli eventi di chiusura del dialogo.

onConsentDialogClosed(callback: () => void): () => void
Restituisce una funzione di annullamento.

openPrivacyPolicyDialog

Apre il dialogo dell'Informativa sulla privacy via codice in modalità standalone e riutilizza lo stile e il contenuto degli slot del consent-dialog dichiarato.

openPrivacyPolicyDialog(): void
Utile quando vuoi collegare l'Informativa sulla privacy dalla tua interfaccia.

toggleComplianceMonitor

Abilita o disabilita il PrivacyKit Compliance Monitor. Quando è abilitato, compare un pulsante di azione flottante in un angolo della pagina che consente di accedere al dialogo del Monitor.

toggleComplianceMonitor(): void

getSubscriptionStatus

Restituisce lo stato di abbonamento corrente per il dominio. È un helper di sola lettura — abbonamento e fatturazione sono gestiti automaticamente da PrivacyKit tramite Paddle.

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

Eventi correlati

privacykit:ready

Emanato quando PrivacyKit è completamente caricato e pronto.

window.addEventListener('privacykit:ready', () => {
  // Qui puoi usare window.PrivacyKit in sicurezza
});

privacykit:consent-changed

Emesso ogni volta che il consenso salvato cambia.

privacykit:open

Emesso quando si apre il dialogo di consenso.

privacykit:dialog-closed

Emesso dopo la chiusura del dialogo di consenso.

privacykit:open-privacy-policy

Emesso quando si apre il dialogo dell'Informativa sulla privacy.