Documentation publique des web components consent-dialog, consent-guard, consent-missing et compliance-monitor.
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 de l’utilisateur. |
| 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><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>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>
Lorsque google-consent-mode est activé, PrivacyKit lit les choix de consentement de l'utilisateur 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 l'utilisateur modifie son consentement. Aucune configuration supplémentaire n'est requise au-delà de l'ajout de l'attribut.
Associer <consent-guard> autour de votre extrait GTM avec google-consent-mode sur la boîte de dialogue est une approche axée sur l'application : GTM ne peut pas du tout se charger avant que le consentement ne soit donné, et les signaux Google Consent Mode v2 sont envoyés immédiatement une fois que c'est le cas. GTM n'est qu'un conteneur — il peut héberger des balises d'analyse, des balises marketing, ou les deux, selon ce que vous y avez configuré. Définissez l'expression consent sur <consent-guard> en conséquence : marketing si GTM ne déclenche que des balises marketing/publicitaires, analytics s'il s'agit uniquement d'analytique, ou analytics+marketing s'il déclenche les deux.
<!-- 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>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.
PrivacyKit vérifie si window.gtag est disponible (Google Tag Manager ou gtag.js chargé). Si c'est le cas, il appelle :
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'
});Si gtag n'est pas disponible mais que window.dataLayer l'est, PrivacyKit envoie la mise à jour du consentement directement au dataLayer. Si aucun des deux n'est présent, aucun signal n'est envoyé et rien n'est mis en file d'attente.
Lorsque Google Tag Manager est protégé par <consent-guard> — c'est-à-dire qu'il ne se charge qu'après que l'utilisateur a donné son consentement — PrivacyKit retente automatiquement l'envoi du signal une fois le chargement de GTM terminé.
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 update emitted.
Un signal de consentement a été envoyé à gtag ou au dataLayer.
[PrivacyKit] Google Consent Mode v2 update skipped because no Google tag was detected.
Ni gtag ni dataLayer n'ont été détectés dans le navigateur, donc rien n'a été envoyé.
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. |
| 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 Compliance Monitor 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 | |
| preferences|analytics | Préférences OU Analytique | |
| preferences+marketing | Préférences ET Marketing | |
| preferences|marketing | Préférences OU Marketing | |
| analytics+marketing | Analytique ET Marketing | |
| analytics|marketing | Analytique OU Marketing |
Exemple 1 – Protéger les scripts
<consent-guard consent="marketing">
<script type="text/plain" data-src="https://www.googletagmanager.com/gtm/js"></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 Compliance Monitor.
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>
Compliance Monitor 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 Compliance Monitor 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 Compliance Monitor 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 Compliance Monitor est épinglé. |
Exemple
<compliance-monitor debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></compliance-monitor>
Compliance Monitor 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=monitor à l'URL — cela active le moniteur uniquement pour cette session de navigateur, sans affecter l'expérience des visiteurs.
Activer de manière programmatique :
window.PrivacyKit?.toggleComplianceMonitor();
É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;
}