JavaScript-Events und API des PrivacyBee Cookie-Banners

Geändert am Mi, 27 Mai um 5:25 NACHMITTAGS

JavaScript-Events und API des PrivacyBee Cookie-Banners

Manchmal reicht es nicht, das Banner einfach nur einzubinden — du möchtest auf deiner Webseite selbst auf Consent-Ereignisse reagieren, zum Beispiel um ein Analytics-Skript nachzuladen, ein Chat-Widget zu initialisieren oder einfach mitzubekommen, wann das Banner einsatzbereit ist.

Genau dafür gibt es zwei Schnittstellen, die das Cookie-Banner nach der Einbindung (siehe Wie kann ich den Cookie-Banner von PrivacyBee in meine Website einbinden?) automatisch bereitstellt:

DOM-Events auf dem document — ideal, wenn du dich nur an einer Stelle "einklinken" möchtest.
Das globale window.PrivacyBee-Objekt — wenn du den aktuellen Consent-Status aktiv abfragen oder verändern willst.

Du kannst beides parallel verwenden.

Schnellüberblick

Schnittstelle	Typ	Wann sie feuert / verfügbar ist
`privacybee:ready`	DOM-Event	Das Banner hat seine Initialisierung abgeschlossen.
`privacybee:consent-changed`	DOM-Event	Der Consent ändert sich (durch Nutzer:in oder programmatisch).
`window.PrivacyBee`	Globale API	Steht ab dem Zeitpunkt zur Verfügung, an dem `privacybee:ready` feuert.

Beide DOM-Events werden auf document ausgelöst (nicht auf window) und sind CustomEvent-Instanzen mit einem detail-Objekt.

Event: `privacybee:ready`

Dieses Event wird einmal ausgelöst, sobald das Banner vollständig initialisiert ist — also nachdem die Konfiguration geladen, der bestehende Consent (z. B. aus dem Cookie eines früheren Besuchs) angewendet und die globale API bereitgestellt wurde. Erst ab diesem Zeitpunkt kannst du dich auf window.PrivacyBee verlassen.

document.addEventListener('privacybee:ready', (event) => {
  console.log('Verfügbare Kategorien:', event.detail.categories)
  console.log('Hat die Nutzerin/der Nutzer schon entschieden?', event.detail.hasExplicitConsent)

  // Jetzt ist es sicher, die API zu nutzen:
  if (window.PrivacyBee.getConsent('ANALYTICS_STORAGE')) {
    // Analytics-Skript nachladen
  }
})

event.detail-Struktur:

Feld	Typ	Beschreibung
`categories`	`string[]`	Alle verfügbaren technischen Consent-Kategorien (siehe Liste unten).
`hasExplicitConsent`	`boolean`	`true`, wenn die Nutzerin oder der Nutzer bereits eine bewusste Entscheidung getroffen hat. `false`, wenn das Banner noch sichtbar ist und auf eine Eingabe wartet.

Tipp: Registriere den Listener so früh wie möglich auf der Seite — idealerweise direkt im <head>, noch vor dem Banner-Skript. So gehst du sicher, dass du das Event nicht verpasst, falls das Banner bereits aus dem Cache lädt.

Event: `privacybee:consent-changed`

Wird ausgelöst, wann immer sich der Consent ändert. Das passiert in zwei Situationen:

Explizite Änderung: Die Nutzerin oder der Nutzer klickt auf "Alle akzeptieren", "Alle ablehnen" oder speichert eine eigene Auswahl. Auch programmatische Aufrufe wie window.PrivacyBee.acceptAll() zählen dazu.
Implizite Änderung: Beim Seitenaufruf wird ein bestehender Consent (z. B. aus dem Cookie der letzten Sitzung) wiederhergestellt. Das Banner ist in diesem Fall nicht sichtbar.

Du kannst die beiden Fälle über das Flag explicitConsent unterscheiden:

document.addEventListener('privacybee:consent-changed', (event) => {
  const { consents, explicitConsent } = event.detail

  if (consents.ANALYTICS_STORAGE) {
    loadAnalytics()
  }

  if (explicitConsent) {
    // Nutzer:in hat gerade aktiv eine Entscheidung getroffen — z. B. Dank-Hinweis zeigen
  }
})

event.detail-Struktur:

Feld	Typ	Beschreibung
`consents`	`Record<string, boolean>`	Aktuelle Zustimmung pro Kategorie. Schlüssel = Kategorie-Name, Wert = `true` / `false`.
`explicitConsent`	`boolean`	`true`, wenn die Änderung auf einer bewussten Aktion beruht. `false`, wenn das Banner einen bestehenden Consent wiederherstellt.

Die globalen Kategorien

Folgende technischen Kategorien gibt das Banner aus. Die Namen entsprechen dem Google-Consent-Mode v2, was die Integration mit Google Tag Manager und ähnlichen Tools vereinfacht.

Kategorie	Pflicht?	Wofür sie steht
`SECURITY_STORAGE`	Ja	Sicherheitsrelevante Speicherung (z. B. Authentifizierung, Betrugsprävention). Immer `true`.
`FUNCTIONALITY_STORAGE`	Ja	Notwendige Funktionalität (z. B. Spracheinstellung, Login-State). Immer `true`.
`ANALYTICS_STORAGE`	Nein	Reichweitenmessung, Analytics.
`AD_STORAGE`	Nein	Speicherung im Zusammenhang mit Werbung.
`AD_USER_DATA`	Nein	Übermittlung von Nutzerdaten an Werbenetzwerke.
`AD_PERSONALIZATION`	Nein	Personalisierte Werbung.
`PERSONALIZATION_STORAGE`	Nein	Personalisierung jenseits von Werbung (z. B. Empfehlungssysteme).

Die beiden Pflicht-Kategorien sind aus DSGVO-Sicht "berechtigtes Interesse" oder "technisch notwendig" und können vom Nutzer nicht abgewählt werden — rejectAll() lässt sie deshalb auf true.

Die API: `window.PrivacyBee`

Sobald privacybee:ready gefeuert hat, steht window.PrivacyBee zur Verfügung. Hier sind alle Methoden im Überblick:

Lesen

// Einzelne Kategorie abfragen
window.PrivacyBee.getConsent('ANALYTICS_STORAGE')   // → true | false

// Alle Kategorien als Objekt
window.PrivacyBee.getAllConsents()
// → {
//     SECURITY_STORAGE: true,
//     FUNCTIONALITY_STORAGE: true,
//     ANALYTICS_STORAGE: false,
//     AD_STORAGE: false,
//     …
//   }

// Hat die Nutzerin/der Nutzer bereits eine bewusste Entscheidung getroffen?
window.PrivacyBee.hasExplicitConsent()   // → true | false

Auf Änderungen reagieren

Eine Alternative zum DOM-Event privacybee:consent-changed — funktional gleichwertig, dafür mit einem etwas kürzeren Aufruf:

window.PrivacyBee.onConsentChange((consents) => {
  if (consents.ANALYTICS_STORAGE) {
    // …
  }
})

Du kannst beliebig viele Callbacks registrieren; alle werden bei jeder Änderung aufgerufen.

Schreiben

Diese Methoden ändern den Consent programmatisch und lösen anschliessend privacybee:consent-changed mit explicitConsent: true aus. Setze sie nur ein, wenn du wirklich eine bewusste Nutzeraktion abbildest (etwa über einen eigenen "Cookie-Einstellungen"-Button im Footer).

// Alle nicht-essentiellen Kategorien aktivieren
window.PrivacyBee.acceptAll()

// Alle nicht-essentiellen Kategorien deaktivieren
window.PrivacyBee.rejectAll()

// Komplettes Set explizit setzen (alle Kategorien müssen angegeben werden)
window.PrivacyBee.setAllConsents({
  SECURITY_STORAGE: true,
  FUNCTIONALITY_STORAGE: true,
  ANALYTICS_STORAGE: true,
  AD_STORAGE: false,
  AD_USER_DATA: false,
  AD_PERSONALIZATION: false,
  PERSONALIZATION_STORAGE: false,
})

Debugging

Du kannst dir die Events live in der Konsole anzeigen lassen:

document.addEventListener('privacybee:ready', console.log)
document.addEventListener('privacybee:consent-changed', console.log)

Häufige Fragen

Auf welchem Element werden die Events ausgelöst — window oder document?
Auf document. window.addEventListener('privacybee:ready', …) wird nicht funktionieren.

Kann ich die Events stoppen oder verhindern (preventDefault)?
Nein, sie sind nicht cancelable. Sie sind reine Benachrichtigungen.

Was passiert, wenn ich window.PrivacyBee benutze, bevor privacybee:ready gefeuert hat?
Dann ist das Objekt schlicht undefined. Verlasse dich nur innerhalb deines privacybee:ready-Handlers (oder danach) darauf.

Bekomme ich auch ein Event, wenn das Banner gar nicht angezeigt wird (weil der Consent bereits gespeichert ist)?
Ja. privacybee:ready feuert immer, sobald die Initialisierung abgeschlossen ist — unabhängig davon, ob das Banner sichtbar wird oder nicht. Wenn ein gespeicherter Consent wiederhergestellt wird, feuert zusätzlich privacybee:consent-changed mit explicitConsent: false.

Ich nutze Google Tag Manager. Muss ich die Events selbst weitergeben?
Nein. Das Cookie-Banner integriert sich automatisch mit GTM und übermittelt die Consent-Zustände im Google-Consent-Mode-v2-Format. Du kannst die Events natürlich trotzdem für eigene Zwecke nutzen.

Wenn du eine Integration baust, die hier nicht abgedeckt ist, melde dich gern bei unserem Support — wir helfen dir weiter und erweitern diese Dokumentation laufend.

JavaScript-Events und API des PrivacyBee Cookie-Banners

JavaScript-Events und API des PrivacyBee Cookie-Banners

Schnellüberblick

Event: privacybee:ready

Event: privacybee:consent-changed

Die globalen Kategorien

Die API: window.PrivacyBee

Lesen

Auf Änderungen reagieren

Schreiben

Debugging

Häufige Fragen

Event: `privacybee:ready`

Event: `privacybee:consent-changed`

Die API: `window.PrivacyBee`