Documentazione pubblica dei web component consent-dialog, consent-guard, consent-missing e consent-validator.
Componente principale dell'interfaccia di consenso PrivacyKit e della logica di orchestrazione.
| Attributo | Tipo | Default / Obblig. | Descrizione |
|---|---|---|---|
| variant | standard | panel | modern | modest | standard | Variante visiva del dialogo. |
| theme | standard | dark | teal | slate | light | vibrant | high-contrast | standard | Tema visivo del dialogo. |
| expires-days | number | 180 | Durata del cookie in giorni. |
| version | number | 0 | Versione dello schema di consenso per le richieste successive. |
| google-consent-mode | boolean | unset | Emette segnali di consenso Google Consent Mode v2 in base alle scelte di consenso PrivacyKit del visitatore. |
| locale | da | de | en | es | fi | fr | it | nl | no | pl | sv | derivato dal browser | Forza una locale specifica. |
| hide-summary-part-2 | boolean | unset | Nasconde la sezione di riepilogo parte 2 (dialog-summary-part-2) della finestra di dialogo. |
| hide-necessary | boolean | unset | Nasconde la categoria Necessario. |
| hide-preferences | boolean | unset | Nasconde la categoria Preferenze. |
| hide-analytics | boolean | unset | Nasconde la categoria Analisi. |
| hide-marketing | boolean | unset | Nasconde la categoria Marketing. |
| hide-readmore | boolean | unset | Nasconde la sezione espandibile "Leggi di più". |
| hide-privacykit-badge | boolean | unset | Nasconde il badge PrivacyKit mostrato in fondo al corpo del dialogo di consenso. |
| hide-privacy-policy-link | boolean | unset | Nasconde completamente il link predefinito all’Informativa sulla privacy. Usa `privacy-policy-url` per mantenere il link visibile e reindirizzare gli utenti alla tua pagina della privacy. |
| privacy-policy-url | string | unset | URL a cui vengono reindirizzati gli utenti quando cliccano sul link dell’Informativa sulla privacy. Quando impostato, il link apre questo URL invece del dialogo integrato. |
| demo | boolean | unset | Modalità demo: disattiva l'auto-open e limita alcune funzioni. Non conforme al GDPR, da non usare in produzione. |
| dismissible | boolean | false | Controlla se il dialogo può essere chiuso via backdrop/ESC quando l'utente non ha ancora deciso. |
| show-fab | boolean | false | Abilita il pulsante delle preferenze di consenso. Non ha effetto visibile finché non esiste un cookie di consenso. |
| fab-position | left | right | left | Fissa il pulsante in basso a sinistra o in basso a destra del viewport. |
| dialog-position | left | right | left | Controlla su quale lato dello schermo appare la finestra di dialogo. Si applica solo alle varianti modern e modest — standard e panel sono sempre centrate. |
Esempio
<consent-dialog theme="panel" variant="dark" expires-days="90"
version="1" locale="it" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>I design token espongono un set stabile di variabili CSS per personalizzare colori, spaziature, tipografia e molto altro senza toccare l'implementazione interna. I temi integrati sono basati sullo stesso sistema di token, così puoi sovrascrivere singoli stili o creare un aspetto completamente personalizzato.
| Design token | Descrizione |
|---|---|
| --pk-transparency | Trasparenza della superficie del dialogo e delle sue card/fisarmoniche annidate, espressa in percentuale. 0% (predefinito) è completamente solido; il valore viene limitato a un massimo del 50%. |
| --pk-bg-color | Colore di sfondo dell'intero dialogo. Miscelato con --pk-transparency per produrre il colore finale. |
| --pk-paper-color | Colore carta per card, fisarmoniche e pannelli all'interno della finestra di dialogo. Anch'esso miscelato con --pk-transparency. |
| --pk-text-color | Colore base per titoli e testo. |
| --pk-text-color-on-primary | Colore del testo usato su elementi riempiti con il colore primario, come i pulsanti pieni. |
| --pk-primary-color | Accento principale per CTA, focus e link. |
| --pk-secondary-color | Accento secondario, usato soprattutto dai toggle. |
| --pk-focus-ring-color | Colore del contorno di focus (outline) per gli stati di focus da tastiera. |
| --pk-font-family | Famiglia di font per tutto il testo; torna al font del body se necessario. |
| --pk-spacing-unit | Unità di spaziatura che controlla padding e gap. |
| --pk-control-border-color | Colore del bordo per i controlli all'interno del dialogo — card, fisarmoniche, pulsanti ed elementi simili. |
| --pk-control-border-width | Spessore del bordo per i controlli all'interno del dialogo — card, fisarmoniche, pulsanti ed elementi simili. |
| --pk-control-border-radius | Raggio degli angoli per pulsanti, campi e controlli interattivi. |
| --pk-dialog-border-color | Colore del bordo per la struttura del dialogo stesso — il contorno del pannello esterno e le linee divisorie di intestazione/piè di pagina. |
| --pk-dialog-border-width | Spessore del bordo per la struttura del dialogo stesso — il contorno del pannello esterno e le linee divisorie di intestazione/piè di pagina. |
| --pk-dialog-border-radius | Raggio degli angoli per il contenitore esterno del dialogo di consenso. |
| --pk-dialog-max-height | Altezza massima del dialogo di consenso; quando il contenuto supera questo limite, il corpo del dialogo scorre. |
| --pk-dialog-shadow | Ombra applicata al dialogo di consenso. |
Esempio
<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>Inserisci contenuti personalizzati in parti specifiche di un componente usando slot HTML con nome — così hai pieno controllo su contenuti e stile senza modificare il componente stesso.
| Nome slot | Descrizione |
|---|---|
| dialog-logo-top | Logo o immagine del brand opzionale visualizzato nell'intestazione della finestra di dialogo del consenso. |
| dialog-logo-right | Logo o immagine del brand opzionale visualizzato in alto a destra della finestra di dialogo del consenso. |
| dialog-title | Sostituisce il titolo nell’intestazione del dialogo. |
| dialog-summary-part-1 | Inserisce testo personalizzato nel primo paragrafo introduttivo sotto il titolo del dialogo. |
| dialog-summary-part-2 | Inserisce testo personalizzato nel secondo paragrafo introduttivo che spiega le scelte di consenso. |
| necessary-content | Sostituisce la descrizione della categoria Necessario. |
| preferences-content | Testo personalizzato nell'accordion Preferenze. |
| analytics-content | Testo personalizzato nell'accordion Analisi. |
| marketing-content | Testo personalizzato nell'accordion Marketing. |
| read-more-title | Imposta il titolo della sezione "Scopri di più". |
| read-more-content | Contenuto mostrato quando "Scopri di più" viene aperto. |
| privacy-policy-content | Sostituisce il testo predefinito dell'Informativa sulla privacy. Usa solo un testo approvato dal tuo consulente legale, perché PrivacyKit non può verificare GDPR compliance dopo la personalizzazione. |
Esempio
<consent-dialog theme="standard" variant="standard" locale="it" version="1">
<img slot="dialog-logo-top" width="100px" src="/logo.png" alt="Logo dell'azienda" />
<div slot="dialog-title" class="tua-classe">
<h2>Usiamo i cookie</h2>
</div>
<span slot="marketing-content">
<b>Attualmente non raccogliamo cookie per finalità di marketing.</b>
</span>
</consent-dialog>
PrivacyKit applica automaticamente un profilo di privacy appropriato in base alla posizione rilevata del visitatore. Non è richiesta alcuna configurazione aggiuntiva.
Ai visitatori situati in Europa viene presentato il modello di consenso GDPR/ePrivacy. Le tecnologie di analisi, marketing e altre non essenziali rimangono bloccate finché il visitatore non ha concesso il consenso.
Ai visitatori situati fuori dall'Europa viene presentato il modello di privacy CPRA. Il consenso viene concesso automaticamente, consentendo al sito web di funzionare senza una finestra di dialogo di consenso iniziale. I visitatori possono aprire la finestra di dialogo di PrivacyKit in qualsiasi momento per rivedere o revocare le proprie scelte sulla privacy. Se il consenso viene revocato, PrivacyKit richiede un aggiornamento della pagina per garantire che le tecnologie bloccate non vengano più eseguite.
PrivacyKit determina automaticamente se il visitatore si trova in Europa. Non è richiesta alcuna configurazione.
<consent-dialog> include traduzioni integrate per inglese, norvegese, tedesco, polacco, spagnolo, francese, italiano, olandese, svedese, danese e finlandese — nessun file di traduzione da caricare o mantenere autonomamente.
Per impostazione predefinita, la finestra di dialogo legge la lingua del browser del visitatore e mostra automaticamente la traduzione corrispondente. Se il browser è impostato su una lingua non supportata da PrivacyKit, viene usato l'inglese come ripiego.
Per forzare una lingua specifica indipendentemente dalle impostazioni del browser del visitatore, imposta l'attributo locale — consulta la tabella sopra per l'elenco completo dei codici supportati.
<consent-dialog locale="it"></consent-dialog>Quando google-consent-mode è abilitato, PrivacyKit legge le scelte di consenso del visitatore e le segnala a Google Tag Manager o gtag utilizzando il protocollo Google Consent Mode v2. Questo avviene automaticamente al caricamento della pagina e ogni volta che il visitatore modifica il proprio consenso. Non è richiesta alcuna configurazione aggiuntiva oltre all'aggiunta dell'attributo.
PrivacyKit mappa le sue tre categorie di consenso sui sette campi di Consent Mode v2 di Google:
| Campo GCM v2 | Mappato da | Valore |
|---|---|---|
| analytics_storage | Analisi | granted / denied |
| ad_storage | Marketing | granted / denied |
| ad_user_data | Marketing | granted / denied |
| ad_personalization | Marketing | granted / denied |
| functionality_storage | Preferenze | granted / denied |
| personalization_storage | Preferenze | granted / denied |
| security_storage | — | Always granted |
security_storage è sempre granted, poiché copre l'archiviazione del browser essenziale per la sicurezza e non è soggetta al consenso di tracciamento opzionale.
Al caricamento della pagina, PrivacyKit si assicura che esistano window.dataLayer e una funzione gtag, usando lo snippet standard di Google e mantenendo quelli già presenti nella pagina. Mette in coda un valore predefinito con tutto negato, poi il consenso attuale del visitatore, e mette in coda un aggiornamento a ogni modifica del consenso:
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'
});Il dataLayer è una coda in memoria nella pagina; non viene salvato nulla. Google Tag Manager e gtag.js elaborano i comandi in coda nell'ordine al caricamento, così lo stato del consenso viene applicato prima che venga eseguito qualsiasi tag di Google, anche quando Google si carica più tardi.
Se la pagina ha un proprio snippet di Google, deve mantenere un dataLayer esistente (window.dataLayer = window.dataLayer || [], come fanno gli snippet di Google).
Suggerimento per il debug: PrivacyKit registra la propria attività di Google Consent Mode v2 nella console del browser, così puoi verificare il comportamento direttamente negli DevTools:
[PrivacyKit] Google Consent Mode v2 enabled.
Mostrato una volta al caricamento della pagina quando è impostato google-consent-mode. Allo stesso tempo viene messo in coda il valore predefinito con tutto negato.
[PrivacyKit] Google Consent Mode v2 update queued.
Un aggiornamento del consenso è stato messo in coda nel dataLayer, al caricamento della pagina e a ogni modifica del consenso. Google lo applica quando si caricano i suoi tag.
openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): voidRenderizza i figli solo quando l'espressione di consenso fornita risulta vera.
| Attributo | Tipo | Default / Obblig. | Descrizione |
|---|---|---|---|
| consent | string | unset | Espressione di consenso da soddisfare prima di renderizzare i contenuti. |
| source | string | unset | Da dove viene letto il consenso. Se non è impostato, il guard usa il consenso della finestra di dialogo per il consenso di PrivacyKit. "google-consent-mode" legge il consenso raccolto dal tuo banner per il consenso esistente tramite Google Consent Mode v2. I valori sconosciuti mantengono il guard bloccato. |
| Espressione | Consenso richiesto | Descrizione |
|---|---|---|
| Tutte le categorie | Se l'attributo consent viene omesso, tutte le categorie devono essere accettate affinché il guard si attivi. | |
| necessary | Nessuno | Evita falsi positivi nel Consent Validator per le risorse necessarie non riconosciute automaticamente da PrivacyKit. |
| preferences | Preferenze | |
| analytics | Analisi | |
| marketing | Marketing | |
| preferences+analytics | Preferenze E Analisi | Per gli script che richiedono entrambi i tipi di consenso, ad es. il tracciamento di HubSpot. |
| preferences|analytics | Preferenze O Analisi | Per i contenitori che verificano il consenso per ogni tag, ad es. Google Tag Manager. |
| preferences+marketing | Preferenze E Marketing | Per gli script che richiedono entrambi i tipi di consenso, ad es. il tracciamento di HubSpot. |
| preferences|marketing | Preferenze O Marketing | Per i contenitori che verificano il consenso per ogni tag, ad es. Google Tag Manager. |
| analytics+marketing | Analisi E Marketing | Per gli script che richiedono entrambi i tipi di consenso, ad es. il tracciamento di HubSpot. |
| analytics|marketing | Analisi O Marketing | Per i contenitori che verificano il consenso per ogni tag, ad es. Google Tag Manager. |
Esempio 1 – Proteggere gli script
<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>
Esempio 2 – Proteggere i contenuti incorporati
<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>
Importante: Nota che le risorse gestite negli esempi usano data-src invece di src, e type="text/plain" viene utilizzato per gli script. PrivacyKit attiva i contenuti gestiti dopo che il consenso è stato concesso — altrimenti le risorse possono caricarsi subito e risultare come hardcoded nel Consent Validator.
I guard possono applicare il consenso raccolto dal tuo banner esistente. Aggiungi source="google-consent-mode" a <consent-guard> e il guard leggerà il consenso dal tuo banner invece che dalla finestra di dialogo per il consenso di PrivacyKit. Script e contenuti incorporati nel guard si caricano solo dopo che il visitatore ha accettato.
window.dataLayer, a ogni caricamento della pagina e ogni volta che la scelta cambia.Usare il consenso del tuo banner esistente
<!-- Il tuo banner per il consenso esistente, con Google Consent Mode v2 attivo. -->
<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 si carica solo dopo che il visitatore ha accettato l'analisi nel tuo banner -->
<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>
<!-- Contenuti incorporati che richiedono il consenso 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>
Puoi usare PrivacyKit con Google Tag Manager in due modi: rigoroso, in cui Tag Manager attende il consenso, oppure flessibile, in cui Tag Manager si carica subito e le sue impostazioni di consenso decidono quali tag si attivano. In entrambi i casi, aggiungi google-consent-mode a <consent-dialog>, così i tag in Tag Manager sanno cosa ha scelto il visitatore.
Niente di Tag Manager si carica, e niente viene inviato a Google, finché il visitatore non ha dato il consenso. Un tribunale tedesco (VG Hannover, 2025) ha stabilito che il caricamento di Google Tag Manager richiede il consenso, e la modalità rigorosa segue questa interpretazione. Imposta il consenso del guard in base a ciò che attiva il contenitore: analytics o marketing se attiva un solo tipo di tag, oppure analytics|marketing se attiva tag di entrambi i tipi, così si carica non appena il visitatore accetta uno dei due. Da lì in poi, Tag Manager gestisce il consenso per ogni tag.
<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>
Carica Tag Manager come di consueto. I tag di Google seguono i segnali di Consent Mode della finestra di dialogo. Gli altri tag del contenitore, come Meta o LinkedIn, hanno bisogno di impostazioni di consenso in Tag Manager. Consent Validator mostra Tag Manager come non protetto da un guard. È voluto: il Validator segnala tutto ciò che non si trova dentro un guard.
La modalità flessibile è anche la configurazione per i siti web che usano Consent Mode Advanced di proposito. Con il consenso negato, i tag di Google inviano comunque dati senza cookie, come l’indirizzo della pagina e i dettagli del dispositivo, così Google può modellare le conversioni. PrivacyKit supporta questa configurazione. Se sia adatta al tuo sito web è una decisione che spetta a te e al tuo consulente legale.
Mostra contenuti di fallback quando il consent-guard associato blocca l'esperienza principale.
| Attributo | Tipo | Default / Obblig. | Descrizione |
|---|---|---|---|
| for | string | obbligatorio | ID dell'elemento <consent-guard> collegato. |
Esempio
<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">
Accetta i cookie di analisi per continuare.
</consent-missing>
Consent Validator monitora le richieste in uscita e convalida la copertura dei consent guard sul tuo sito web, rilevando tracker non gestiti e regressioni introdotte da modifiche al sito. Inattivo per impostazione predefinita, rimane invisibile ai visitatori ed è sicuro da includere in produzione.
| Attributo | Tipo | Default / Obblig. | Descrizione |
|---|---|---|---|
| debug | boolean | false | Abilita il pannello Consent Validator al caricamento della pagina. Solo per ambienti di sviluppo. |
| delay | number | 5000 | Finestra di osservazione della rete (in millisecondi) prima che Consent Validator inizi a validare l'utilizzo degli endpoint e la copertura dei consent guard. |
| ignore-first-party-subdomains | boolean | true | Quando è true, le richieste verso sottodomini del dominio corrente vengono ignorate silenziosamente. |
| fab-position | left | right | right | Controlla su quale lato del viewport viene fissato il FAB di Consent Validator. |
Esempio
<consent-validator debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></consent-validator>
Consent Validator rimane nascosto ai visitatori anche quando è incluso nel bundle di produzione. Il modo consigliato per attivarlo su un sito in produzione è aggiungere ?privacykit=validate all'URL — questo attiva il validatore solo per quella sessione del browser, senza influire sull'esperienza dei visitatori.
Attiva a livello di codice:
window.PrivacyKit?.toggleConsentValidator();
Evita sfarfallii prima che i web component abbiano finito di caricarsi. Senza questo snippet gli HTML slottati o protetti possono apparire per un attimo quando:
consent-dialog può lampeggiare brevemente se usi elementi slottati e si renderizzano prima che la definizione del componente sia caricata.consent-guard può lampeggiare brevemente se viene usato per HTML condizionale e il contenuto si renderizza prima che il componente si attivi.consent-missing può lampeggiare brevemente se viene usato come fallback e si renderizza prima che il componente si attivi.Aggiungi stili nel tuo light DOM per evitare gli sfarfallii.
consent-dialog:not(:defined) [slot] {
display: none;
}
consent-guard:not([active]) {
display: none;
}
consent-missing:not([active]) {
display: none;
}