Öffentliche Dokumentation der Webkomponenten consent-dialog, consent-guard, consent-missing und consent-validator.
Zentrale Komponente für die PrivacyKit-Einwilligungsoberfläche und die Orchestrierung.
| Attribut | Typ | Standard / Pflicht | Beschreibung |
|---|---|---|---|
| variant | standard | panel | modern | modest | standard | Visuelle Variante des Dialogs. |
| theme | standard | dark | teal | slate | light | vibrant | high-contrast | standard | Visuelles Theme des Dialogs. |
| expires-days | number | 180 | Lebensdauer des Cookies in Tagen. |
| version | number | 0 | Versionsnummer des Einwilligungsschemas für erneute Abfragen. |
| google-consent-mode | boolean | unset | Gibt Google Consent Mode v2-Einwilligungssignale basierend auf den PrivacyKit-Einwilligungsentscheidungen der Besucher aus. |
| locale | da | de | en | es | fi | fr | it | nl | no | pl | sv | vom Browser | Überschreibt die Sprache. |
| hide-summary-part-2 | boolean | unset | Blendet den zweiten Zusammenfassungsabschnitt (dialog-summary-part-2) im Dialog aus. |
| hide-necessary | boolean | unset | Blendet die Kategorie „Notwendig“ aus. |
| hide-preferences | boolean | unset | Blendet die Kategorie Präferenzen aus. |
| hide-analytics | boolean | unset | Blendet die Kategorie Analytics aus. |
| hide-marketing | boolean | unset | Blendet die Kategorie Marketing aus. |
| hide-readmore | boolean | unset | Blendet den ausklappbaren Abschnitt "Mehr erfahren" aus. |
| hide-privacykit-badge | boolean | unset | Blendet das PrivacyKit-Badge aus, das am unteren Rand des Einwilligungsdialog-Inhalts angezeigt wird. |
| hide-privacy-policy-link | boolean | unset | Blendet den standardmäßigen Link zur Datenschutzerklärung vollständig aus. Verwenden Sie stattdessen `privacy-policy-url`, um den Link sichtbar zu lassen und Nutzer zu Ihrer eigenen Datenschutzseite weiterzuleiten. |
| privacy-policy-url | string | unset | URL, zu der Nutzer weitergeleitet werden, wenn sie auf den Datenschutzlink klicken. Wenn gesetzt, öffnet der Link diese URL anstelle des integrierten Datenschutz-Dialogs. |
| demo | boolean | unset | Demo-Modus: deaktiviert Auto-Open und begrenzt Funktionen. Nicht DSGVO-konform und nicht für Produktion. |
| dismissible | boolean | false | Steuert, ob der Dialog per Backdrop/Escape geschlossen werden kann, wenn noch keine Entscheidung vorliegt. |
| show-fab | boolean | false | Aktiviert die Schaltfläche für Einwilligungseinstellungen. Hat keine sichtbare Wirkung, bis ein Consent-Cookie vorhanden ist. |
| fab-position | left | right | left | Fixiert die Schaltfläche unten links oder unten rechts im Viewport. |
| dialog-position | left | right | left | Legt fest, auf welcher Seite des Bildschirms der Dialog erscheint. Gilt nur für die Varianten modern und modest — standard und panel sind immer zentriert. |
Beispiel
<consent-dialog theme="panel" variant="dark" expires-days="90"
version="1" locale="de" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>Design Tokens stellen ein stabiles Set an CSS-Variablen bereit, um Farben, Abstände, Typografie u. v. m. anzupassen, ohne die Implementierung zu ändern. Die integrierten Themes basieren auf demselben Token-System, sodass Sie einzelne Styles überschreiben oder ein vollständig eigenes Erscheinungsbild erstellen können.
| Design Tokens | Beschreibung |
|---|---|
| --pk-transparency | Transparenz der Dialogfläche und ihrer verschachtelten Karten/Akkordeons, als Prozentwert. 0 % (Standard) ist vollständig deckend; der Wert wird auf maximal 50 % begrenzt. |
| --pk-bg-color | Hintergrundfläche für den gesamten Dialog. Wird mit --pk-transparency gemischt, um die endgültige Farbe zu erzeugen. |
| --pk-paper-color | Papierfarbe für Karten, Akkordeons und Panels innerhalb des Dialogs. Wird ebenfalls mit --pk-transparency gemischt. |
| --pk-text-color | Grundfarbe für Überschriften und Fließtext. |
| --pk-text-color-on-primary | Textfarbe für Elemente, die mit der Primärfarbe gefüllt sind, z. B. vollflächige Buttons. |
| --pk-primary-color | Primärer Akzent für CTAs, Fokusrahmen und Links. |
| --pk-secondary-color | Sekundärer Akzent, hauptsächlich für Switch/Thumb-Stati. |
| --pk-focus-ring-color | Farbe des Fokus-Outline für Tastaturfokuszustände. |
| --pk-font-family | Schriftfamilie für alle Texte; fällt auf die Body-Schrift zurück. |
| --pk-spacing-unit | Abstandseinheit, die Paddings und Gaps steuert. |
| --pk-control-border-color | Rahmenfarbe für Steuerelemente innerhalb des Dialogs — Karten, Akkordeons, Buttons und ähnliche Elemente. |
| --pk-control-border-width | Rahmenbreite für Steuerelemente innerhalb des Dialogs — Karten, Akkordeons, Buttons und ähnliche Elemente. |
| --pk-control-border-radius | Eckenradius für Buttons, Eingabefelder und interaktive Steuerelemente. |
| --pk-dialog-border-color | Rahmenfarbe für den Dialog selbst — die äußere Panelkontur sowie die Trennlinien in Kopf- und Fußbereich. |
| --pk-dialog-border-width | Rahmenbreite für den Dialog selbst — die äußere Panelkontur sowie die Trennlinien in Kopf- und Fußbereich. |
| --pk-dialog-border-radius | Eckenradius für den äußeren Container des Einwilligungsdialogs. |
| --pk-dialog-max-height | Maximale Höhe des Einwilligungsdialogs; überschreitet der Inhalt dieses Limit, wird der Dialoginhalt scrollbar. |
| --pk-dialog-shadow | Schlagschatten für den Einwilligungsdialog. |
Beispiel
<consent-dialog theme="light" style="
--pk-bg-color: #faf7f2;
--pk-paper-color: #f7eede;
--pk-primary-color: #b08968;
--pk-font-family: 'Segoe UI', Tahoma, sans-serif;
--pk-control-border-radius: 10px;
--pk-dialog-border-radius: 20px;
--pk-dialog-max-height: 50vh;
--pk-dialog-shadow: 10px 20px rgba(0, 0, 0, 0.5);
">
</consent-dialog>Füge benutzerdefinierte Inhalte in bestimmte Bereiche einer Komponente ein, indem du benannte HTML-Slots verwendest — so hast du volle Kontrolle über Inhalt und Styling, ohne die Komponente selbst zu verändern.
| Slot-Name | Beschreibung |
|---|---|
| dialog-logo-top | Optionales Logo oder Markenbild, das in der Kopfzeile des Einwilligungsdialogs angezeigt wird. |
| dialog-logo-right | Optionales Logo oder Markenbild, das oben rechts im Einwilligungsdialog angezeigt wird. |
| dialog-title | Überschreibt den Titel im Kopfbereich des Dialogs. |
| dialog-summary-part-1 | Überschreibt den ersten Einleitungsabsatz unter dem Dialogtitel. |
| dialog-summary-part-2 | Überschreibt den zweiten Einleitungsabsatz, der die Einwilligungsoptionen erklärt. |
| necessary-content | Ersetzt den Standardtext der Kategorie Notwendig. |
| preferences-content | Eigener Text im Akkordeon der Kategorie Präferenzen. |
| analytics-content | Eigener Text im Akkordeon der Kategorie Analytics. |
| marketing-content | Eigener Text im Akkordeon der Kategorie Marketing. |
| read-more-title | Setzt die Überschrift für den Bereich "Mehr erfahren". |
| read-more-content | Inhalt, der beim Aufklappen von "Mehr erfahren" angezeigt wird. |
| privacy-policy-content | Ersetzt den Standardtext der Datenschutzerklärung. Verwenden Sie nur Formulierungen, die von Ihrer eigenen Rechtsabteilung freigegeben wurden, da PrivacyKit keine DSGVO-Konformität garantieren kann, sobald Sie den Inhalt anpassen. |
Beispiel
<consent-dialog theme="standard" variant="standard" locale="de" version="1">
<img slot="dialog-logo-top" width="100px" src="/logo.png" alt="Firmenlogo" />
<div slot="dialog-title" class="ihre-klasse">
<h2>Wir verwenden Cookies</h2>
</div>
<span slot="marketing-content">
<b>Derzeit erfassen wir keine Cookies für Marketingzwecke.</b>
</span>
</consent-dialog>
PrivacyKit wendet automatisch ein passendes Datenschutzprofil basierend auf dem ermittelten Standort des Besuchers an. Es ist keine zusätzliche Konfiguration erforderlich.
Besuchern in Europa wird das DSGVO/ePrivacy-Einwilligungsmodell angezeigt. Analyse-, Marketing- und andere nicht wesentliche Technologien bleiben blockiert, bis der Besucher seine Einwilligung erteilt hat.
Besuchern außerhalb Europas wird das CPRA-Datenschutzmodell angezeigt. Die Einwilligung wird automatisch erteilt, sodass die Website ohne einen anfänglichen Einwilligungsdialog funktionieren kann. Besucher können den PrivacyKit-Dialog jederzeit öffnen, um ihre Datenschutzentscheidungen zu überprüfen oder zu widerrufen. Wird die Einwilligung widerrufen, fordert PrivacyKit eine Aktualisierung der Seite an, damit blockierte Technologien nicht mehr ausgeführt werden.
PrivacyKit ermittelt automatisch, ob sich der Besucher innerhalb Europas befindet. Es ist keine Konfiguration erforderlich.
<consent-dialog> wird mit integrierten Übersetzungen für Englisch, Norwegisch, Deutsch, Polnisch, Spanisch, Französisch, Italienisch, Niederländisch, Schwedisch, Dänisch und Finnisch ausgeliefert — keine Übersetzungsdateien, die Sie selbst laden oder pflegen müssen.
Standardmäßig liest der Dialog die Browsersprache der Besucher aus und zeigt automatisch die passende Übersetzung an. Ist der Browser auf eine von PrivacyKit nicht unterstützte Sprache eingestellt, wird auf Englisch zurückgegriffen.
Um unabhängig von den Browsereinstellungen der Besucher eine bestimmte Sprache zu erzwingen, setzen Sie das Attribut locale — die vollständige Liste der unterstützten Codes finden Sie in der Tabelle oben.
<consent-dialog locale="de"></consent-dialog>Wenn google-consent-mode aktiviert ist, liest PrivacyKit die Einwilligungsentscheidungen der Besucher aus und signalisiert sie an Google Tag Manager oder gtag über das Google Consent Mode v2-Protokoll. Dies geschieht automatisch beim Laden der Seite und immer, wenn Besucher ihre Einwilligung ändern. Es ist keine zusätzliche Konfiguration erforderlich, außer das Attribut hinzuzufügen.
PrivacyKit ordnet seine drei Einwilligungskategorien den sieben Consent Mode v2-Feldern von Google zu:
| GCM-v2-Feld | Zugeordnet zu | Wert |
|---|---|---|
| analytics_storage | Analyse | granted / denied |
| ad_storage | Marketing | granted / denied |
| ad_user_data | Marketing | granted / denied |
| ad_personalization | Marketing | granted / denied |
| functionality_storage | Präferenzen | granted / denied |
| personalization_storage | Präferenzen | granted / denied |
| security_storage | — | Always granted |
security_storage ist immer granted, da es sicherheitsrelevante Browser-Speicherung abdeckt und keiner optionalen Tracking-Einwilligung unterliegt.
Beim Laden der Seite stellt PrivacyKit sicher, dass window.dataLayer und eine gtag-Funktion vorhanden sind – mit Googles Standard-Snippet, wobei bereits vorhandene beibehalten werden. Es reiht einen Standardwert ein, bei dem alles abgelehnt ist, danach die aktuelle Einwilligung der Besucher, und reiht bei jeder Änderung der Einwilligung ein Update ein:
gtag('consent', 'update', {
analytics_storage: 'granted' | 'denied',
ad_storage: 'granted' | 'denied',
ad_user_data: 'granted' | 'denied',
ad_personalization: 'granted' | 'denied',
functionality_storage: 'granted' | 'denied',
personalization_storage: 'granted' | 'denied',
security_storage: 'granted'
});Der dataLayer ist eine Warteschlange im Arbeitsspeicher der Seite; es wird nichts gespeichert. Google Tag Manager und gtag.js verarbeiten die eingereihten Befehle beim Laden der Reihe nach, sodass der Einwilligungsstatus gilt, bevor ein Google-Tag ausgeführt wird – auch wenn Google erst später lädt.
Wenn Ihre Seite ein eigenes Google-Snippet hat, muss es einen vorhandenen dataLayer beibehalten (window.dataLayer = window.dataLayer || [], wie es Googles Snippets tun).
Debugging-Tipp: PrivacyKit protokolliert seine Google Consent Mode v2-Aktivität in der Browserkonsole, damit Sie das Verhalten direkt in den DevTools überprüfen können:
[PrivacyKit] Google Consent Mode v2 enabled.
Wird einmal beim Laden der Seite angezeigt, wenn google-consent-mode gesetzt ist. Gleichzeitig wird der Standardwert eingereiht, bei dem alles abgelehnt ist.
[PrivacyKit] Google Consent Mode v2 update queued.
Ein Einwilligungs-Update wurde im dataLayer eingereiht – beim Laden der Seite und bei jeder Änderung der Einwilligung. Google wendet es an, wenn seine Tags laden.
openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): voidRendert Inhalte nur, wenn der angegebene Einwilligungsausdruck wahr ist.
| Attribut | Typ | Standard / Pflicht | Beschreibung |
|---|---|---|---|
| consent | string | unset | Einwilligungsausdruck, der erfüllt sein muss, bevor Inhalte gerendert werden. |
| source | string | unset | Woher die Einwilligung gelesen wird. Ohne Angabe verwendet der Guard die Einwilligung aus dem PrivacyKit-Consent-Dialog. "google-consent-mode" liest die Einwilligung, die Ihr bestehendes Consent-Banner eingeholt hat, über Google Consent Mode v2. Unbekannte Werte halten den Guard blockiert. |
| Ausdruck | Erforderliche Einwilligung | Beschreibung |
|---|---|---|
| Alle Kategorien | Wenn das consent-Attribut fehlt, müssen alle Kategorien akzeptiert werden, damit der Guard aktiviert wird. | |
| necessary | Keine | Verhindert falsch-positive Ergebnisse im Consent Validator für notwendige Ressourcen, die von PrivacyKit nicht automatisch erkannt werden. |
| preferences | Präferenzen | |
| analytics | Analyse | |
| marketing | Marketing | |
| preferences+analytics | Präferenzen UND Analyse | Für Skripte, die beide Arten von Einwilligung benötigen, z. B. HubSpot-Tracking. |
| preferences|analytics | Präferenzen ODER Analyse | Für Container, die die Einwilligung pro Tag prüfen, z. B. Google Tag Manager. |
| preferences+marketing | Präferenzen UND Marketing | Für Skripte, die beide Arten von Einwilligung benötigen, z. B. HubSpot-Tracking. |
| preferences|marketing | Präferenzen ODER Marketing | Für Container, die die Einwilligung pro Tag prüfen, z. B. Google Tag Manager. |
| analytics+marketing | Analyse UND Marketing | Für Skripte, die beide Arten von Einwilligung benötigen, z. B. HubSpot-Tracking. |
| analytics|marketing | Analyse ODER Marketing | Für Container, die die Einwilligung pro Tag prüfen, z. B. Google Tag Manager. |
Beispiel 1 – Skripte schützen
<consent-guard consent="analytics">
<script type="text/plain" data-src="https://static.hotjar.com/c/hotjar-XXXXXXX.js?sv=6" data-async></script>
</consent-guard>
Beispiel 2 – Eingebettete Inhalte schützen
<consent-guard consent="analytics+marketing">
<iframe
title="YouTube video"
data-src="https://www.youtube.com/embed/abc123"
width="560"
height="315"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>
</consent-guard>
Wichtig: Beachten Sie, dass verwaltete Ressourcen in den Beispielen data-src statt src und type="text/plain" für Skripte verwendet wird. PrivacyKit aktiviert verwaltete Inhalte erst nach erteilter Einwilligung — andernfalls können Ressourcen sofort laden und im Consent Validator als fest eingebunden erscheinen.
Guards können die Einwilligung durchsetzen, die Ihr bestehendes Banner einholt. Fügen Sie source="google-consent-mode" zu <consent-guard> hinzu, und der Guard liest die Einwilligung aus Ihrem Banner statt aus dem PrivacyKit-Consent-Dialog. Skripte und eingebettete Inhalte im Guard laden erst, wenn die Besucher zugestimmt haben.
window.dataLayer, bei jedem Seitenaufruf und bei jeder Änderung der Auswahl.Die Einwilligung aus Ihrem bestehenden Banner verwenden
<!-- Ihr bestehendes Consent-Banner, mit aktiviertem Google Consent Mode v2. -->
<script src="https://cdn.your-consent-banner.com/banner.js"></script>
<!-- PrivacyKit -->
<script type="module" src="https://cdn.privacykit.eu/v1/privacykit.esm.js"></script>
<!-- Hotjar lädt erst, wenn die Besucher in Ihrem Banner Analyse akzeptieren -->
<consent-guard consent="analytics" source="google-consent-mode">
<script type="text/plain" data-src="https://static.hotjar.com/c/hotjar-XXXXXXX.js?sv=6" data-async></script>
</consent-guard>
<!-- Eingebettete Inhalte, die eine Marketing-Einwilligung erfordern -->
<consent-guard consent="marketing" source="google-consent-mode">
<iframe title="YouTube video" data-src="https://www.youtube.com/embed/abc123" width="560" height="315"></iframe>
</consent-guard>
Sie können PrivacyKit auf zwei Arten mit dem Google Tag Manager nutzen: strikt, wobei der Tag Manager auf die Einwilligung wartet, oder flexibel, wobei der Tag Manager sofort lädt und seine eigenen Einwilligungseinstellungen entscheiden, welche Tags ausgelöst werden. Fügen Sie in beiden Fällen google-consent-mode zu <consent-dialog> hinzu, damit die Tags im Tag Manager wissen, was die Besucher gewählt haben.
Nichts aus dem Tag Manager lädt, und nichts wird an Google gesendet, bis die Besucher eingewilligt haben. Ein deutsches Gericht (VG Hannover, 2025) hat entschieden, dass das Laden des Google Tag Managers eine Einwilligung erfordert, und der strikte Modus folgt dieser Auslegung. Stellen Sie die Einwilligung des Guards passend zu dem ein, was der Container auslöst: analytics oder marketing, wenn er nur eine Art von Tags auslöst, oder analytics|marketing, wenn er Tags beider Arten auslöst, damit er lädt, sobald die Besucher einer der beiden Arten zustimmen. Ab dann regelt der Tag Manager die Einwilligung für jedes Tag.
<consent-dialog google-consent-mode></consent-dialog>
<consent-guard consent="analytics|marketing">
<script type="text/plain" data-src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX" data-async></script>
</consent-guard>
Laden Sie den Tag Manager wie gewohnt. Die Tags von Google folgen den Consent-Mode-Signalen aus dem Dialog. Andere Tags im Container, etwa von Meta oder LinkedIn, benötigen Einwilligungseinstellungen im Tag Manager. Consent Validator zeigt den Tag Manager als nicht durch einen Guard geschützt an. Das ist beabsichtigt: Der Validator meldet alles, was nicht in einem Guard liegt.
Flexibel ist auch das Setup für Websites, die Consent Mode Advanced bewusst nutzen. Bei abgelehnter Einwilligung senden die Tags von Google weiterhin Daten ohne Cookies, etwa die Seitenadresse und Geräteangaben, damit Google Conversions modellieren kann. PrivacyKit unterstützt dieses Setup. Ob es für Ihre Website angemessen ist, entscheiden Sie gemeinsam mit Ihrer Rechtsberatung.
Zeigt Fallback-Inhalte, wenn der zugehörige consent-guard das Haupterlebnis blockiert.
| Attribut | Typ | Standard / Pflicht | Beschreibung |
|---|---|---|---|
| for | string | erforderlich | ID des zugehörigen <consent-guard>-Elements. |
Beispiel
<consent-guard id="analytics-guard" consent="analytics">
<script type="text/plain" data-src="https://example.com/analytics.js"></script>
</consent-guard>
<consent-missing for="analytics-guard">
Bitte akzeptieren Sie Analyse-Cookies, um fortzufahren.
</consent-missing>
Der Consent Validator überwacht ausgehende Anfragen und validiert die Consent-Guard-Abdeckung auf Ihrer Live-Website — er erkennt nicht verwaltete Tracker und Regressionen durch Website-Änderungen. Standardmäßig inaktiv bleibt er für Besucher unsichtbar und ist sicher für den Einsatz in der Produktion.
| Attribut | Typ | Standard / Pflicht | Beschreibung |
|---|---|---|---|
| debug | boolean | false | Aktiviert das Consent Validator-Panel beim Laden der Seite. Nur für Entwicklungsumgebungen. |
| delay | number | 5000 | Netzwerkbeobachtungsfenster (in Millisekunden), bevor der Consent Validator mit der Validierung der Endpunktnutzung und Consent-Guard-Abdeckung beginnt. |
| ignore-first-party-subdomains | boolean | true | Wenn true, werden Anfragen an Subdomains der aktuellen Domain stillschweigend ignoriert. |
| fab-position | left | right | right | Steuert, an welcher Seite des Viewports der FAB des Consent Validator fixiert wird. |
Beispiel
<consent-validator debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></consent-validator>
Der Consent Validator bleibt für Besucher verborgen, auch wenn er im Produktions-Bundle enthalten ist. Die empfohlene Methode zur Aktivierung auf einer Live-Website ist das Anhängen von ?privacykit=validate an die URL — dies aktiviert den Validator nur für diese Browsersitzung, ohne das Besuchererlebnis zu beeinträchtigen.
Programmgesteuert umschalten:
window.PrivacyKit?.toggleConsentValidator();
Vermeiden Sie Flackern, bevor die Webkomponenten geladen sind. Ohne dieses Snippet können geschützte Inhalte kurz aufblitzen, wenn:
consent-dialog kann kurz aufblitzen, wenn Sie slotted Elemente verwenden und sie rendern, bevor die Komponentendefinition geladen ist.consent-guard kann kurz aufblitzen, wenn er für bedingtes HTML verwendet wird und der Inhalt rendert, bevor die Komponente aktiviert ist.consent-missing kann kurz aufblitzen, wenn er als Fallback verwendet wird und er rendert, bevor die Komponente aktiviert ist.Fügen Sie Styling in Ihrem Light DOM hinzu, um Flackern zu vermeiden.
consent-dialog:not(:defined) [slot] {
display: none;
}
consent-guard:not([active]) {
display: none;
}
consent-missing:not([active]) {
display: none;
}