PrivacyKit Webkomponenten

Öffentliche Dokumentation der Webkomponenten consent-dialog, consent-guard, consent-missing und compliance-monitor.

Inhaltsverzeichnis

<consent-dialog>

Zentrale Komponente für die PrivacyKit-Einwilligungsoberfläche und die Orchestrierung.

Attribute

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 des Nutzers 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

HTML
<consent-dialog theme="panel" variant="dark" expires-days="90" 
  version="1" locale="de" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>

Lokalisierung

<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.

Automatische Erkennung

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.

Sprache überschreiben

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.

HTML
<consent-dialog locale="de"></consent-dialog>

Design Tokens

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>

Content-Slots

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

HTML
<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>

Schwebende Dialog-Schaltfläche

Wenn show-fab auf true gesetzt ist, zeigt <consent-dialog> einen Floating Action Button (FAB), über den Nutzer ihre Einwilligungsentscheidungen nach der ersten Abgabe erneut öffnen können. Verwende fab-position, um ihn unten links oder unten rechts im Viewport zu fixieren.

Sichtbarkeitsregeln

Ausgeblendet, bis die initiale Einwilligung abgegeben wurde.
Ausgeblendet, während der Einwilligungsdialog oder der Datenschutzrichtlinien-Dialog geöffnet ist.
Ausgeblendet, wenn show-fab nicht gesetzt ist oder auf false gesetzt ist.

HTML
<consent-dialog show-fab fab-position="left">
</consent-dialog>

Google Consent Mode v2

Wenn google-consent-mode aktiviert ist, liest PrivacyKit die Einwilligungsentscheidungen des Nutzers 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 der Nutzer seine Einwilligung ändert. Es ist keine zusätzliche Konfiguration erforderlich, außer das Attribut hinzuzufügen.

Empfohlenes Setup

Die Kombination von <consent-guard> um Ihren GTM-Schnipsel mit google-consent-mode am Dialog ist ein durchsetzungsorientierter Ansatz: GTM kann überhaupt erst laden, wenn die Einwilligung erteilt wurde, und Google Consent Mode v2-Signale werden sofort danach gesendet. GTM ist nur ein Container — er kann Analyse-Tags, Marketing-Tags oder beides enthalten, je nachdem, was Sie darin konfiguriert haben. Setzen Sie den consent-Ausdruck auf <consent-guard> entsprechend: marketing, wenn GTM nur Marketing-/Anzeigen-Tags auslöst, analytics, wenn es sich nur um Analyse handelt, oder analytics+marketing, wenn beides ausgelöst wird.

HTML
<!-- Match the consent expression to what GTM actually fires: "analytics" or "marketing" -->
<consent-guard consent="analytics">
  <script type="text/plain" data-src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX"></script>
</consent-guard>

<consent-dialog google-consent-mode>
</consent-dialog>

Zuordnung der Einwilligungssignale

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.

Wie Signale gesendet werden

PrivacyKit prüft, ob window.gtag verfügbar ist (Google Tag Manager oder gtag.js geladen). Falls ja, ruft es auf:

JavaScript
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'
});

Ist gtag nicht verfügbar, aber window.dataLayer schon, schreibt PrivacyKit das Einwilligungs-Update direkt in den dataLayer. Ist keines von beiden vorhanden, wird kein Signal gesendet und nichts in die Warteschlange gestellt.

Wenn Google Tag Manager durch <consent-guard> geschützt ist — also erst nach erteilter Einwilligung lädt — versucht PrivacyKit automatisch erneut, das Signal zu senden, sobald GTM fertig geladen ist.

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 update emitted.
Ein Einwilligungssignal wurde an gtag oder den dataLayer gesendet.
[PrivacyKit] Google Consent Mode v2 update skipped because no Google tag was detected.
Weder gtag noch dataLayer wurden im Browser gefunden, daher wurde nichts gesendet.

Dialog-Methoden

TypeScriptAPI-Referenz

openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): void

<consent-guard>

Rendert Inhalte nur, wenn der angegebene Einwilligungsausdruck wahr ist.

Attribute

Attribut	Typ	Standard / Pflicht	Beschreibung
consent	string	unset	Einwilligungsausdruck, der erfüllt sein muss, bevor Inhalte gerendert werden.

Einwilligungsausdrücke

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 Compliance Monitor für notwendige Ressourcen, die von PrivacyKit nicht automatisch erkannt werden.
preferences	Präferenzen
analytics	Analyse
marketing	Marketing
preferences+analytics	Präferenzen UND Analyse
preferences\|analytics	Präferenzen ODER Analyse
preferences+marketing	Präferenzen UND Marketing
preferences\|marketing	Präferenzen ODER Marketing
analytics+marketing	Analyse UND Marketing
analytics\|marketing	Analyse ODER Marketing

Beispiel 1 – Skripte schützen

HTML
<consent-guard consent="marketing">
  <script type="text/plain" data-src="https://www.googletagmanager.com/gtm/js"></script>
</consent-guard>

Beispiel 2 – Eingebettete Inhalte schützen

HTML
<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 Compliance Monitor als fest eingebunden erscheinen.

<consent-missing>

Zeigt Fallback-Inhalte, wenn der zugehörige consent-guard das Haupterlebnis blockiert.

Attribute

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>

<compliance-monitor>

Der Compliance Monitor ü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.

Attribute

Attribut	Typ	Standard / Pflicht	Beschreibung
debug	boolean	false	Aktiviert das Compliance-Monitor-Panel beim Laden der Seite. Nur für Entwicklungsumgebungen.
delay	number	5000	Netzwerkbeobachtungsfenster (in Millisekunden), bevor der Compliance Monitor 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 Compliance Monitor fixiert wird.

Beispiel

HTML
<compliance-monitor debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></compliance-monitor>

Der Compliance Monitor 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=monitor an die URL — dies aktiviert den Monitor nur für diese Browsersitzung, ohne das Besuchererlebnis zu beeinträchtigen.

Programmgesteuert umschalten:

TypeScriptAPI-Referenz

window.PrivacyKit?.toggleComplianceMonitor();

Anhänge

CSS-Snippets

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.

NPM

CSS
consent-dialog:not(:defined) [slot] {
  display: none;
}

consent-guard:not([active]) {
  display: none;
}

consent-missing:not([active]) {
  display: none;
}
Wenn Sie geslotteten Inhalt verwenden oder consent-guards mit HTML nutzen, fügen Sie dieses Snippet in Ihr globales Stylesheet oder in ein <style>-Tag ein, das ausgeführt wird, bevor die PrivacyKit Web Components gerendert werden.