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.

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

Beispiel

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

Schaltfläche für Einwilligungseinstellungen

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>

Inhalte anpassen

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	Optionaler Logo-Inhalt, der im Kopfbereich des Dialogs angezeigt wird.
dialog-logo-alt	Alternative Platzierung für ein Markenlogo, angezeigt oben rechts am Text von dialog-summary-part-1.
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" 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>

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-bg-color	Hintergrundfläche für den gesamten Dialog.
--pk-paper-color	Papierfarbe für Karten, Akkordeons und Panels innerhalb des Dialogs.
--pk-text-color	Grundfarbe für Überschriften und Fließtext.
--pk-primary-color	Primärer Akzent für CTAs, Fokusrahmen und Links.
--pk-text-color-on-primary	Textfarbe für Elemente, die mit der Primärfarbe gefüllt sind, z. B. vollflächige Buttons.
--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-border-color	Rahmenfarbe für Panelkonturen, Tabellen und Trenner.
--pk-border-width	Rahmenbreite für Panelkonturen, Tabellen und Trenner.
--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-radius	Eckenradius für Buttons, Eingabefelder und interaktive Steuerelemente.
--pk-dialog-radius	Eckenradius für den äußeren Container des Einwilligungsdialogs.
--pk-dialog-shadow	Schlagschatten für den Einwilligungsdialog.
--pk-dialog-max-height	Maximale Höhe des Einwilligungsdialogs; überschreitet der Inhalt dieses Limit, wird der Dialoginhalt scrollbar.

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-radius: 10px;
  --pk-dialog-radius: 20px;
  --pk-dialog-shadow: 10px 20px rgba(0, 0, 0, 0.5);
  --pk-dialog-max-height: 50vh;
">
</consent-dialog>

Methoden

TypeScriptAPI-Referenz

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

<consent-guard>

Rendert Inhalte nur, wenn der angegebene Einwilligungsausdruck wahr ist.

Eigenschaft	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 blockieren/laden

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

Beispiel 2 – HTML-Inhalt blockieren/laden

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.

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

Eigenschaft	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();