Documentation publique des web components consent-dialog, consent-guard, consent-missing et consent-validator.
Composant principal de l'interface de consentement PrivacyKit et de la logique d'orchestration.
| Attribut | Type | Valeur par défaut / Obligatoire | Description |
|---|---|---|---|
| variant | standard | panel | modern | modest | standard | Variante visuelle du dialogue. |
| theme | standard | dark | teal | slate | light | vibrant | high-contrast | standard | Thème visuel du dialogue. |
| expires-days | number | 180 | Durée de vie du cookie en jours. |
| version | number | 0 | Version du schéma de consentement utilisée pour les relances. |
| google-consent-mode | boolean | unset | Émet des signaux de consentement Google Consent Mode v2 en fonction des choix de consentement PrivacyKit du visiteur. |
| locale | da | de | en | es | fi | fr | it | nl | no | pl | sv | dérivé du navigateur | Force une locale spécifique. |
| hide-summary-part-2 | boolean | unset | Masque la section de résumé partie 2 (dialog-summary-part-2) de la boîte de dialogue. |
| hide-necessary | boolean | unset | Masque la catégorie Nécessaire. |
| hide-preferences | boolean | unset | Masque la catégorie Préférences. |
| hide-analytics | boolean | unset | Masque la catégorie Analytique. |
| hide-marketing | boolean | unset | Masque la catégorie Marketing. |
| hide-readmore | boolean | unset | Masque la section extensible « En savoir plus ». |
| hide-privacykit-badge | boolean | unset | Masque le badge PrivacyKit affiché en bas du contenu de la boîte de dialogue de consentement. |
| hide-privacy-policy-link | boolean | unset | Masque entièrement le lien par défaut vers la politique de confidentialité. Utilisez `privacy-policy-url` pour conserver le lien visible et rediriger les utilisateurs vers votre propre page de politique. |
| privacy-policy-url | string | unset | URL vers laquelle les utilisateurs sont redirigés en cliquant sur le lien de politique de confidentialité. Lorsqu'il est défini, le lien ouvre cette URL au lieu du dialogue de politique de confidentialité intégré. |
| demo | boolean | unset | Mode démo : désactive l'ouverture automatique et limite certaines fonctions. Non conforme RGPD, à ne pas utiliser en production. |
| dismissible | boolean | false | Contrôle si le dialogue peut être fermé par le fond/Échap tant qu'aucune décision n'est prise. |
| show-fab | boolean | false | Active le bouton des préférences de consentement. N'a aucun effet visible tant qu'un cookie de consentement n'existe pas. |
| fab-position | left | right | left | Fixe le bouton en bas à gauche ou en bas à droite de la fenêtre d’affichage. |
| dialog-position | left | right | left | Contrôle de quel côté de l'écran la boîte de dialogue apparaît. S'applique uniquement aux variantes modern et modest — standard et panel sont toujours centrés. |
Exemple
<consent-dialog theme="panel" variant="dark" expires-days="90"
version="1" locale="fr" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>Les design tokens exposent un ensemble stable de variables CSS pour personnaliser couleurs, espacements, typographies et plus encore sans toucher à l'implémentation interne. Les thèmes intégrés s’appuient sur le même système de tokens, ce qui vous permet de surcharger des styles individuels ou de créer une apparence entièrement personnalisée.
| Design tokens | Description |
|---|---|
| --pk-transparency | Transparence de la surface de la boîte de dialogue et de ses cartes/accordéons imbriqués, exprimée en pourcentage. 0 % (par défaut) est entièrement opaque ; la valeur est plafonnée à 50 % maximum. |
| --pk-bg-color | Couleur d'arrière-plan de l'ensemble du conteneur de dialogue. Mélangée avec --pk-transparency pour produire la couleur finale. |
| --pk-paper-color | Couleur papier pour les cartes, accordéons et panneaux à l'intérieur de la boîte de dialogue. Également mélangée avec --pk-transparency. |
| --pk-text-color | Couleur de base appliquée aux titres et au texte. |
| --pk-text-color-on-primary | Couleur du texte utilisée sur les éléments remplis avec la couleur principale, comme les boutons pleins. |
| --pk-primary-color | Accent principal pour les CTA, focus et liens. |
| --pk-secondary-color | Accent secondaire, notamment pour les interrupteurs. |
| --pk-focus-ring-color | Couleur du contour de focus (outline) pour les états de focus au clavier. |
| --pk-font-family | Famille de polices utilisée pour tout le texte, avec repli sur la police du body. |
| --pk-spacing-unit | Unité d'espacement contrôlant les paddings et les intervalles. |
| --pk-control-border-color | Couleur de bordure pour les contrôles à l'intérieur de la boîte de dialogue — cartes, accordéons, boutons et éléments similaires. |
| --pk-control-border-width | Largeur de bordure pour les contrôles à l'intérieur de la boîte de dialogue — cartes, accordéons, boutons et éléments similaires. |
| --pk-control-border-radius | Rayon des angles pour les boutons, champs et contrôles interactifs. |
| --pk-dialog-border-color | Couleur de bordure pour le cadre propre de la boîte de dialogue — le contour du panneau extérieur et les lignes de séparation de l'en-tête/pied de page. |
| --pk-dialog-border-width | Largeur de bordure pour le cadre propre de la boîte de dialogue — le contour du panneau extérieur et les lignes de séparation de l'en-tête/pied de page. |
| --pk-dialog-border-radius | Rayon des angles du conteneur externe du dialogue de consentement. |
| --pk-dialog-max-height | Hauteur maximale de la boîte de dialogue de consentement ; lorsque le contenu dépasse cette limite, le corps de la boîte de dialogue devient défilable. |
| --pk-dialog-shadow | Ombre appliquée à la boîte de dialogue de consentement. |
Exemple
<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>Injectez du contenu personnalisé dans des parties précises d’un composant grâce à des slots HTML nommés — pour garder un contrôle total sur le contenu et le style sans modifier le composant lui‑même.
| Nom du slot | Description |
|---|---|
| dialog-logo-top | Logo ou image de marque optionnel affiché dans l'en-tête de la boîte de dialogue de consentement. |
| dialog-logo-right | Logo ou image de marque optionnel affiché en haut à droite de la boîte de dialogue de consentement. |
| dialog-title | Remplace le titre dans l’en-tête de la boîte de dialogue. |
| dialog-summary-part-1 | Ajoute du texte personnalisé dans le premier paragraphe d’introduction sous le titre de la boîte de dialogue. |
| dialog-summary-part-2 | Ajoute du texte personnalisé dans le second paragraphe introductif qui explique les choix de consentement. |
| necessary-content | Remplace la description de la catégorie Nécessaire. |
| preferences-content | Texte personnalisé dans l'accordéon Préférences. |
| analytics-content | Texte personnalisé dans l'accordéon Analytique. |
| marketing-content | Texte personnalisé dans l'accordéon Marketing. |
| read-more-title | Définit le titre de la section « En savoir plus ». |
| read-more-content | Contenu affiché lorsque « En savoir plus » est ouvert. |
| privacy-policy-content | Remplace le texte par défaut de la politique de confidentialité. Utilisez uniquement une formulation validée par votre propre service juridique, car PrivacyKit ne peut plus vérifier GDPR compliance une fois personnalisée. |
Exemple
<consent-dialog theme="standard" variant="standard" locale="fr" version="1">
<img slot="dialog-logo-top" width="100px" src="/logo.png" alt="Logo de l’entreprise" />
<div slot="dialog-title" class="votre-classe">
<h2>Nous utilisons des cookies</h2>
</div>
<span slot="marketing-content">
<b>Nous ne collectons actuellement pas de cookies à des fins marketing.</b>
</span>
</consent-dialog>
PrivacyKit applique automatiquement un profil de confidentialité adapté en fonction de la localisation détectée du visiteur. Aucune configuration supplémentaire n'est requise.
Les visiteurs situés en Europe se voient présenter le modèle de consentement RGPD/ePrivacy. Les technologies d'analyse, de marketing et autres non essentielles restent bloquées tant que le visiteur n'a pas donné son consentement.
Les visiteurs situés hors d'Europe se voient présenter le modèle de confidentialité CPRA. Le consentement est accordé automatiquement, ce qui permet au site de fonctionner sans boîte de dialogue de consentement initiale. Les visiteurs peuvent ouvrir la boîte de dialogue PrivacyKit à tout moment pour consulter ou retirer leurs choix de confidentialité. Si le consentement est retiré, PrivacyKit demande une actualisation de la page pour garantir que les technologies bloquées ne s'exécutent plus.
PrivacyKit détermine automatiquement si le visiteur se trouve en Europe. Aucune configuration n'est requise.
<consent-dialog> intègre des traductions prêtes à l'emploi pour l'anglais, le norvégien, l'allemand, le polonais, l'espagnol, le français, l'italien, le néerlandais, le suédois, le danois et le finnois — aucun fichier de traduction à charger ou à maintenir soi-même.
Par défaut, la boîte de dialogue lit la langue du navigateur du visiteur et affiche automatiquement la traduction correspondante. Si le navigateur est configuré dans une langue que PrivacyKit ne prend pas en charge, elle bascule sur l'anglais.
Pour forcer une langue spécifique indépendamment des paramètres du navigateur du visiteur, définissez l'attribut locale — consultez le tableau ci-dessus pour la liste complète des codes pris en charge.
<consent-dialog locale="fr"></consent-dialog>Lorsque google-consent-mode est activé, PrivacyKit lit les choix de consentement du visiteur et les transmet à Google Tag Manager ou gtag via le protocole Google Consent Mode v2. Cela se produit automatiquement au chargement de la page et chaque fois que le visiteur modifie son consentement. Aucune configuration supplémentaire n'est requise au-delà de l'ajout de l'attribut.
PrivacyKit fait correspondre ses trois catégories de consentement aux sept champs de Consent Mode v2 de Google :
| Champ GCM v2 | Correspond à | Valeur |
|---|---|---|
| analytics_storage | Analytique | granted / denied |
| ad_storage | Marketing | granted / denied |
| ad_user_data | Marketing | granted / denied |
| ad_personalization | Marketing | granted / denied |
| functionality_storage | Préférences | granted / denied |
| personalization_storage | Préférences | granted / denied |
| security_storage | — | Always granted |
security_storage est toujours granted, car il couvre le stockage du navigateur essentiel à la sécurité et n'est pas soumis au consentement de suivi optionnel.
Au chargement de la page, PrivacyKit s'assure que window.dataLayer et une fonction gtag existent, en utilisant l'extrait standard de Google et en conservant ceux déjà présents sur la page. Il met en file d'attente une valeur par défaut où tout est refusé, puis le consentement actuel du visiteur, et met en file d'attente une mise à jour à chaque changement de consentement :
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'
});Le dataLayer est une file d'attente en mémoire dans la page ; rien n'est stocké. Google Tag Manager et gtag.js traitent les commandes en file d'attente dans l'ordre lors de leur chargement, de sorte que l'état du consentement s'applique avant l'exécution de toute balise Google, même lorsque Google se charge plus tard.
Si votre page possède son propre extrait Google, il doit conserver un dataLayer existant (window.dataLayer = window.dataLayer || [], comme le font les extraits de Google).
Astuce de débogage : PrivacyKit journalise son activité Google Consent Mode v2 dans la console du navigateur, afin que vous puissiez vérifier le comportement directement dans les DevTools :
[PrivacyKit] Google Consent Mode v2 enabled.
Affiché une fois au chargement de la page lorsque google-consent-mode est défini. La valeur par défaut où tout est refusé est mise en file d'attente au même moment.
[PrivacyKit] Google Consent Mode v2 update queued.
Une mise à jour du consentement a été mise en file d'attente dans le dataLayer, au chargement de la page et à chaque changement de consentement. Google l'applique lorsque ses balises se chargent.
openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): voidAffiche son contenu lorsque l'expression de consentement fournie est vérifiée.
| Attribut | Type | Valeur par défaut / Obligatoire | Description |
|---|---|---|---|
| consent | string | unset | Expression de consentement à vérifier avant de rendre le contenu. |
| source | string | unset | D’où le consentement est lu. S’il n’est pas défini, le guard utilise le consentement de la boîte de dialogue de consentement PrivacyKit. "google-consent-mode" lit le consentement recueilli par votre bannière de consentement existante via Google Consent Mode v2. Les valeurs inconnues laissent le guard bloqué. |
| Expression | Consentement requis | Description |
|---|---|---|
| Toutes les catégories | Si l'attribut consent est omis, toutes les catégories doivent être acceptées pour que le guard s'active. | |
| necessary | Aucun | Évite les faux positifs dans le Consent Validator pour les ressources nécessaires qui ne sont pas automatiquement reconnues par PrivacyKit. |
| preferences | Préférences | |
| analytics | Analytique | |
| marketing | Marketing | |
| preferences+analytics | Préférences ET Analytique | Pour les scripts qui nécessitent les deux types de consentement, p. ex. le suivi HubSpot. |
| preferences|analytics | Préférences OU Analytique | Pour les conteneurs qui vérifient le consentement balise par balise, p. ex. Google Tag Manager. |
| preferences+marketing | Préférences ET Marketing | Pour les scripts qui nécessitent les deux types de consentement, p. ex. le suivi HubSpot. |
| preferences|marketing | Préférences OU Marketing | Pour les conteneurs qui vérifient le consentement balise par balise, p. ex. Google Tag Manager. |
| analytics+marketing | Analytique ET Marketing | Pour les scripts qui nécessitent les deux types de consentement, p. ex. le suivi HubSpot. |
| analytics|marketing | Analytique OU Marketing | Pour les conteneurs qui vérifient le consentement balise par balise, p. ex. Google Tag Manager. |
Exemple 1 – Protéger les scripts
<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>
Exemple 2 – Protéger le contenu intégré
<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>
Important : Notez que les ressources gérées dans les exemples utilisent data-src à la place de src, et type="text/plain" est utilisé pour les scripts. PrivacyKit active le contenu géré après que le consentement a été accordé — sinon, des ressources peuvent se charger immédiatement et apparaître comme codées en dur dans Consent Validator.
Les guards peuvent faire respecter le consentement recueilli par votre bannière existante. Ajoutez source="google-consent-mode" à <consent-guard> : le guard lit alors le consentement depuis votre bannière au lieu de la boîte de dialogue de consentement PrivacyKit. Les scripts et contenus intégrés dans le guard ne se chargent qu’une fois que le visiteur a accepté.
window.dataLayer, à chaque chargement de page et à chaque changement de choix.Utiliser le consentement de votre bannière existante
<!-- Votre bannière de consentement existante, avec Google Consent Mode v2 activé. -->
<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 ne se charge qu'après que le visiteur a accepté l'analyse dans votre bannière -->
<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>
<!-- Contenu intégré nécessitant un consentement marketing -->
<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>
Vous pouvez utiliser PrivacyKit avec Google Tag Manager de deux façons : en mode strict, où Tag Manager attend le consentement, ou en mode souple, où Tag Manager se charge immédiatement et ses propres paramètres de consentement décident quelles balises se déclenchent. Dans les deux cas, ajoutez google-consent-mode à <consent-dialog> pour que les balises de Tag Manager connaissent le choix du visiteur.
Rien de Tag Manager ne se charge, et rien n’est envoyé à Google, tant que le visiteur n’a pas donné son consentement. Un tribunal allemand (VG Hannover, 2025) a jugé que le chargement de Google Tag Manager nécessite un consentement, et le mode strict suit cette lecture. Réglez le consentement du guard selon ce que déclenche le conteneur : analytics ou marketing s’il déclenche un seul type de balises, ou analytics|marketing s’il déclenche des balises des deux types, pour qu’il se charge dès que le visiteur accepte l’un des deux. Ensuite, Tag Manager gère le consentement de chaque balise.
<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>
Chargez Tag Manager comme d’habitude. Les balises Google suivent les signaux Consent Mode de la boîte de dialogue. Les autres balises du conteneur, comme Meta ou LinkedIn, ont besoin de paramètres de consentement dans Tag Manager. Consent Validator indique que Tag Manager n’est pas protégé par un guard. C’est voulu : le Validator signale tout ce qui ne se trouve pas dans un guard.
Le mode souple est aussi la configuration des sites web qui utilisent Consent Mode Advanced en connaissance de cause. Lorsque le consentement est refusé, les balises Google envoient toujours des données sans cookies, comme l’adresse de la page et des informations sur l’appareil, afin que Google puisse modéliser les conversions. PrivacyKit prend en charge cette configuration. Savoir si elle convient à votre site web est une décision qui vous revient, avec votre conseiller juridique.
Affiche un contenu de repli lorsqu'un consent-guard associé bloque l'expérience principale.
| Attribut | Type | Valeur par défaut / Obligatoire | Description |
|---|---|---|---|
| for | string | obligatoire | Identifiant de l'élément <consent-guard> associé. |
Exemple
<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">
Veuillez accepter les cookies d'analyse pour continuer.
</consent-missing>
Consent Validator surveille les requêtes sortantes et valide la couverture des gardes de consentement sur votre site en ligne, en détectant les traceurs non gérés et les régressions introduites par les modifications du site. Inactif par défaut, il reste invisible pour les visiteurs et peut être inclus en production sans risque.
| Attribut | Type | Valeur par défaut / Obligatoire | Description |
|---|---|---|---|
| debug | boolean | false | Active le panneau Consent Validator au chargement de la page. Pour les environnements de développement uniquement. |
| delay | number | 5000 | Fenêtre d'observation réseau (en millisecondes) avant que Consent Validator commence à valider l'utilisation des endpoints et la couverture des gardes de consentement. |
| ignore-first-party-subdomains | boolean | true | Lorsque true, les requêtes vers des sous-domaines du domaine actuel sont ignorées silencieusement. |
| fab-position | left | right | right | Détermine le côté du viewport auquel le FAB de Consent Validator est épinglé. |
Exemple
<consent-validator debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></consent-validator>
Consent Validator reste caché aux visiteurs même lorsqu'il est inclus dans le bundle de production. La méthode recommandée pour l'activer sur un site en ligne est d'ajouter ?privacykit=validate à l'URL — cela active le validateur uniquement pour cette session de navigateur, sans affecter l'expérience des visiteurs.
Activer de manière programmatique :
window.PrivacyKit?.toggleConsentValidator();
Évitez les clignotements avant le chargement complet des web components. Sans cet extrait, le HTML slotté ou protégé peut apparaître brièvement lorsque :
consent-dialog peut clignoter brièvement si vous utilisez des éléments slottés et qu'ils sont rendus avant le chargement de la définition du composant.consent-guard peut clignoter brièvement s'il est utilisé pour du HTML conditionnel et que le contenu est rendu avant que le composant ne s'active.consent-missing peut clignoter brièvement s'il est utilisé comme contenu de repli et qu'il est rendu avant que le composant ne s'active.Ajoutez des styles dans votre light DOM pour éviter ces clignotements.
consent-dialog:not(:defined) [slot] {
display: none;
}
consent-guard:not([active]) {
display: none;
}
consent-missing:not([active]) {
display: none;
}