PrivacyKit Webcomponenten

Openbare documentatie van de webcomponenten consent-dialog, consent-guard, consent-missing en compliance-monitor.

Inhoudsopgave

<consent-dialog>

Hoofdcomponent voor de PrivacyKit-consent UI en orkestratie.

Attributen

Attribuut	Type	Standaard / Vereist	Beschrijving
variant	standard \| panel \| modern \| modest	standard	Visuele variant van de dialoog.
theme	standard \| dark \| teal \| slate \| light \| vibrant \| high-contrast	standard	Visueel thema van de dialoog.
expires-days	number	180	Levensduur van de cookie in dagen.
version	number	0	Versie van het consent-schema voor hernieuwde toestemming.
google-consent-mode	boolean	unset	Verzendt Google Consent Mode v2-toestemmingssignalen op basis van de PrivacyKit-toestemmingskeuzes van de gebruiker.
locale	da \| de \| en \| es \| fi \| fr \| it \| nl \| no \| pl \| sv	browser-afgeleid	Overschrijft de taalinstelling.
hide-summary-part-2	boolean	unset	Verbergt het tweede samenvattingsgedeelte (dialog-summary-part-2) in de dialoog.
hide-necessary	boolean	unset	Verbergt de categorie Noodzakelijk.
hide-preferences	boolean	unset	Verbergt de categorie Voorkeuren.
hide-analytics	boolean	unset	Verbergt de categorie Analyse.
hide-marketing	boolean	unset	Verbergt de categorie Marketing.
hide-readmore	boolean	unset	Verbergt de uitklapbare Lees meer-sectie.
hide-privacykit-badge	boolean	unset	Verbergt het PrivacyKit-badge dat onderaan de inhoud van het toestemmingsdialoogvenster wordt weergegeven.
hide-privacy-policy-link	boolean	unset	Verbergt de standaardlink naar het privacybeleid volledig. Gebruik `privacy-policy-url` om de link zichtbaar te houden en gebruikers door te verwijzen naar je eigen privacypagina.
privacy-policy-url	string	unset	URL waarnaar gebruikers worden doorgestuurd wanneer ze op de privacybeleidlink klikken. Indien ingesteld, opent de link deze URL in plaats van het ingebouwde privacydialoogvenster.
demo	boolean	unset	Demo-modus: schakelt automatisch openen uit en beperkt functies. Niet AVG-conform; niet gebruiken in productie.
dismissible	boolean	false	Bepaalt of de dialoog via backdrop/Escape kan sluiten zolang de gebruiker geen keuze heeft gemaakt.
show-fab	boolean	false	Schakelt de knop voor toestemmingsvoorkeuren in. Heeft geen zichtbaar effect totdat er een consent-cookie bestaat.
fab-position	left \| right	left	Zet de knop vast linksonder of rechtsonder in de viewport.
dialog-position	left \| right	left	Bepaalt aan welke kant van het scherm het dialoogvenster verschijnt. Alleen van toepassing op de modern en modest varianten — standard en panel zijn altijd gecentreerd.

Voorbeeld

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

Lokalisatie

<consent-dialog> wordt geleverd met ingebouwde vertalingen voor Engels, Noors, Duits, Pools, Spaans, Frans, Italiaans, Nederlands, Zweeds, Deens en Fins — geen vertaalbestanden om zelf te laden of te onderhouden.

Automatische detectie

Standaard leest de dialoog de browsertaal van de bezoeker en toont automatisch de bijbehorende vertaling. Als de browser is ingesteld op een taal die PrivacyKit niet ondersteunt, valt deze terug op Engels.

Taal overschrijven

Om een specifieke taal af te dwingen, ongeacht de browserinstellingen van de bezoeker, stel je het attribuut locale in — zie de tabel hierboven voor de volledige lijst met ondersteunde codes.

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

Design tokens

Design tokens bieden stabiele CSS-variabelen voor kleur, spacing, typografie en meer zonder de interne implementatie te wijzigen. Ingebouwde thema’s worden aangedreven door hetzelfde token-systeem, waardoor je individuele stijlen kunt overschrijven of een volledig aangepaste uitstraling kunt creëren.

Design tokens	Beschrijving
--pk-transparency	Transparantie van het dialoogoppervlak en de geneste kaarten/accordeons, als percentage. 0% (standaard) is volledig dekkend; de waarde wordt begrensd op maximaal 50%.
--pk-bg-color	Achtergrondkleur van de volledige dialoogshell. Gemengd met --pk-transparency om de uiteindelijke kleur te bepalen.
--pk-paper-color	Papierkleur voor kaarten, accordeons en panelen in de dialoog. Wordt ook gemengd met --pk-transparency.
--pk-text-color	Basistekstkleur voor koppen en bodytekst.
--pk-text-color-on-primary	Tekstkleur die wordt gebruikt op elementen met de primaire kleur als vulling, zoals volle knoppen.
--pk-primary-color	Primaire accentkleur voor CTA's, focus en links.
--pk-secondary-color	Secundair accent, vooral voor schakelaars.
--pk-focus-ring-color	Kleur van de focus-omlijning (outline) voor toetsenbordfocus.
--pk-font-family	Fontstack voor alle tekst; valt terug op de body-font.
--pk-spacing-unit	Spatie-eenheid die padding en gaps stuurt.
--pk-control-border-color	Randkleur voor bedieningselementen in de dialoog — kaarten, accordeons, knoppen en vergelijkbare elementen.
--pk-control-border-width	Randdikte voor bedieningselementen in de dialoog — kaarten, accordeons, knoppen en vergelijkbare elementen.
--pk-control-border-radius	Hoekradius voor knoppen, invoervelden en interactieve bedieningselementen.
--pk-dialog-border-color	Randkleur voor de dialoog zelf — de contour van het buitenste paneel en de scheidingslijnen tussen header en footer.
--pk-dialog-border-width	Randdikte voor de dialoog zelf — de contour van het buitenste paneel en de scheidingslijnen tussen header en footer.
--pk-dialog-border-radius	Hoekradius voor de buitenste container van de toestemmingsdialoog.
--pk-dialog-max-height	Maximale hoogte van de toestemmingsdialoog; wanneer de inhoud deze limiet overschrijdt, wordt de inhoud van de dialoog scrollbaar.
--pk-dialog-shadow	Schaduw toegepast op de toestemmingsdialoog.

Voorbeeld

<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

Voeg aangepaste content toe aan specifieke delen van een component met benoemde HTML-slots — zo heb je volledige controle over content en styling zonder de component zelf aan te passen.

Slotnaam	Beschrijving
dialog-logo-top	Optioneel logo of merkafbeelding weergegeven in de koptekst van het toestemmingsdialoogvenster.
dialog-logo-right	Optioneel logo of merkafbeelding weergegeven rechtsboven in het toestemmingsdialoogvenster.
dialog-title	Vervangt de titel in de kop van de dialoog.
dialog-summary-part-1	Voegt aangepaste tekst toe aan de eerste introductieparagraaf onder de dialoogtitel.
dialog-summary-part-2	Voegt aangepaste tekst toe aan de tweede introductieparagraaf die de toestemmingskeuzes uitlegt.
necessary-content	Vervangt de beschrijving van de categorie Noodzakelijk.
preferences-content	Eigen tekst in de accordion Voorkeuren.
analytics-content	Eigen tekst in de accordion Analyse.
marketing-content	Eigen tekst in de accordion Marketing.
read-more-title	Stelt de titel in van de sectie "Meer lezen".
read-more-content	Inhoud die verschijnt wanneer "Meer lezen" wordt geopend.
privacy-policy-content	Vervangt de standaardtekst van het privacybeleid. Gebruik alleen door je eigen juridisch adviseur goedgekeurde tekst, want PrivacyKit kan de AVG-naleving niet controleren zodra je het aanpast.

Voorbeeld

HTML
<consent-dialog theme="standard" variant="standard" locale="nl" version="1">
  <img slot="dialog-logo-top" width="100px" src="/logo.png" alt="Bedrijfslogo" />
  <div slot="dialog-title" class="jouw-class">
    <h2>Wij gebruiken cookies</h2>
  </div>
  <span slot="marketing-content">
    <b>We verzamelen momenteel geen cookies voor marketingdoeleinden.</b>
  </span>
</consent-dialog>

Zwevende dialoogknop

Wanneer show-fab op true staat, toont <consent-dialog> een floating action button (FAB) waarmee gebruikers hun toestemmingskeuzes opnieuw kunnen openen na de eerste verzending. Gebruik fab-position om deze linksonder of rechtsonder in de viewport vast te zetten.

Zichtbaarheidsregels

Verborgen totdat de initiële toestemming is ingediend.
Verborgen terwijl het toestemmingsdialoogvenster of het privacybeleid-dialoogvenster geopend is.
Verborgen als show-fab niet is ingesteld of is ingesteld op false.

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

Google Consent Mode v2

Wanneer google-consent-mode is ingeschakeld, leest PrivacyKit de toestemmingskeuzes van de gebruiker en signaleert deze naar Google Tag Manager of gtag via het Google Consent Mode v2-protocol. Dit gebeurt automatisch bij het laden van de pagina en telkens wanneer de gebruiker zijn toestemming wijzigt. Er is geen extra configuratie nodig, behalve het toevoegen van het attribuut.

Aanbevolen configuratie

Het combineren van <consent-guard> rond je GTM-snippet met google-consent-mode op de dialoog is een handhavingsgerichte aanpak: GTM kan helemaal niet laden voordat toestemming is gegeven, en Google Consent Mode v2-signalen worden direct verzonden zodra dat wel gebeurt. GTM is slechts een container — het kan analysetags, marketingtags, of beide bevatten, afhankelijk van wat je erin hebt geconfigureerd. Stel de consent-expressie op <consent-guard> dienovereenkomstig in: marketing als GTM alleen marketing-/advertentietags activeert, analytics als het alleen analyse betreft, of analytics+marketing als het beide activeert.

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>

Toestemmingssignaal-mapping

PrivacyKit koppelt zijn drie toestemmingscategorieën aan de zeven Consent Mode v2-velden van Google:

GCM v2-veld	Gekoppeld aan	Waarde
analytics_storage	Analyse	granted / denied
ad_storage	Marketing	granted / denied
ad_user_data	Marketing	granted / denied
ad_personalization	Marketing	granted / denied
functionality_storage	Voorkeuren	granted / denied
personalization_storage	Voorkeuren	granted / denied
security_storage	—	Always granted

security_storage staat altijd op granted, omdat het beveiligingsessentiële browseropslag dekt en niet onderhevig is aan optionele trackingtoestemming.

Hoe signalen worden verzonden

PrivacyKit controleert of window.gtag beschikbaar is (Google Tag Manager of gtag.js geladen). Als dat zo is, roept het aan:

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

Als gtag niet beschikbaar is maar window.dataLayer wel, stuurt PrivacyKit de toestemmingsupdate rechtstreeks naar de dataLayer. Als geen van beide aanwezig is, wordt er geen signaal verzonden en niets in de wachtrij geplaatst.

Wanneer Google Tag Manager wordt beschermd door <consent-guard> — dat wil zeggen dat het pas laadt nadat de gebruiker toestemming heeft gegeven — probeert PrivacyKit automatisch opnieuw het signaal te verzenden zodra GTM klaar is met laden.

Debugtip: PrivacyKit logt zijn Google Consent Mode v2-activiteit naar de browserconsole, zodat je het gedrag rechtstreeks in DevTools kunt verifiëren:

[PrivacyKit] Google Consent Mode v2 update emitted.
Er is een toestemmingssignaal verzonden naar gtag of de dataLayer.
[PrivacyKit] Google Consent Mode v2 update skipped because no Google tag was detected.
Er werd geen gtag of dataLayer gevonden in de browser, dus er is niets verzonden.

Dialoogmethoden

TypeScriptAPI-referentie

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

<consent-guard>

Toont kinderen pas wanneer de opgegeven consent-expressie waar is.

Attributen

Attribuut	Type	Standaard / Vereist	Beschrijving
consent	string	unset	Consent-expressie die moet slagen voordat er gerenderd wordt.

Toestemmingsexpressies

Expressie	Vereiste toestemming	Omschrijving
	Alle categorieën	Als het consent-attribuut ontbreekt, moeten alle categorieën worden geaccepteerd voordat de guard activeert.
necessary	Geen	Voorkomt fout-positieven in de Compliance Monitor voor noodzakelijke resources die niet automatisch worden herkend door PrivacyKit.
preferences	Voorkeuren
analytics	Analyse
marketing	Marketing
preferences+analytics	Voorkeuren EN Analyse
preferences\|analytics	Voorkeuren OF Analyse
preferences+marketing	Voorkeuren EN Marketing
preferences\|marketing	Voorkeuren OF Marketing
analytics+marketing	Analyse EN Marketing
analytics\|marketing	Analyse OF Marketing

Voorbeeld 1 – Scripts beschermen

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

Voorbeeld 2 – Ingesloten inhoud beschermen

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>

Belangrijk: Let op dat beheerde resources in de voorbeelden data-src gebruiken in plaats van src, en type="text/plain" wordt gebruikt voor scripts. PrivacyKit activeert beheerde content pas nadat toestemming is gegeven — anders kunnen resources direct laden en in Compliance Monitor als hardcoded verschijnen.

<consent-missing>

Toont fallback-inhoud wanneer een gekoppelde consent-guard de ervaring blokkeert.

Attributen

Attribuut	Type	Standaard / Vereist	Beschrijving
for	string	vereist	Id van het gerelateerde <consent-guard>-element.

Voorbeeld

<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">
  Accepteer analytische cookies om verder te gaan.
</consent-missing>

<compliance-monitor>

Compliance Monitor bewaakt uitgaande verzoeken en valideert de consent guard-dekking op uw live website, en brengt onbeheerde trackers en regressies aan het licht die zijn veroorzaakt door websitewijzigingen. Standaard inactief blijft het onzichtbaar voor bezoekers en is het veilig om in productie op te nemen.

Attributen

Attribuut	Type	Standaard / Vereist	Beschrijving
debug	boolean	false	Schakelt het Compliance Monitor-paneel in bij het laden van de pagina. Alleen voor ontwikkelomgevingen.
delay	number	5000	Netwerkobservatievenster (in milliseconden) voordat de Compliance Monitor begint met het valideren van eindpuntgebruik en consent guard-dekking.
ignore-first-party-subdomains	boolean	true	Wanneer true, worden verzoeken naar subdomeinen van het huidige domein stilzwijgend genegeerd.
fab-position	left \| right	right	Bepaalt aan welke kant van de viewport de FAB van Compliance Monitor wordt vastgezet.

Voorbeeld

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

Compliance Monitor blijft verborgen voor bezoekers, zelfs wanneer het is opgenomen in de productiebundel. De aanbevolen manier om het op een live website te activeren is door ?privacykit=monitor aan de URL toe te voegen — dit activeert de monitor alleen voor die browsersessie, zonder de bezoekervaring te beïnvloeden.

Programmatisch in-/uitschakelen:

TypeScriptAPI-referentie

window.PrivacyKit?.toggleComplianceMonitor();

Bijlagen

CSS-fragmenten

Voorkom flikkeren vóórdat de webcomponenten geladen zijn. Zonder dit fragment kan HTML in slots of guards kort zichtbaar zijn wanneer:

consent-dialog kan kort flikkeren als je slotted elementen gebruikt en ze renderen voordat de componentdefinitie is geladen.
consent-guard kan kort flikkeren als hij wordt gebruikt voor conditionele HTML en de inhoud rendert voordat de component activeert.
consent-missing kan kort flikkeren als hij als fallback wordt gebruikt en hij rendert voordat de component activeert.

Voeg styling toe in je eigen light DOM om flikkeren te voorkomen.

NPM

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

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

consent-missing:not([active]) {
  display: none;
}
Als je slotted content gebruikt of consent-guards met HTML, plaats dit fragment in je globale stylesheet of in een <style>-tag die wordt uitgevoerd voordat de PrivacyKit web components renderen.