Componenti web di PrivacyKit

Documentazione pubblica dei web component consent-dialog, consent-guard, consent-missing e compliance-monitor.

Indice

<consent-dialog>

Componente principale dell'interfaccia di consenso PrivacyKit e della logica di orchestrazione.

Attributi

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 dell'utente.
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

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

Localizzazione

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

Rilevamento automatico

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.

Sovrascrivere la lingua

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.

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

Design token

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>

Slot di contenuto

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

HTML
<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>

Pulsante flottante della finestra di dialogo

Quando show-fab è impostato su true, <consent-dialog> mostra un floating action button (FAB) che consente agli utenti di riaprire le proprie scelte di consenso dopo l'invio iniziale. Usa fab-position per fissarlo in basso a sinistra o in basso a destra del viewport.

Regole di visibilità

Nascosto finché il consenso iniziale non è stato inviato.
Nascosto mentre il dialogo di consenso o il dialogo dell'informativa sulla privacy è aperto.
Nascosto se show-fab non è impostato o è impostato su false.

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

Profili di privacy automatici

PrivacyKit applica automaticamente un profilo di privacy appropriato in base alla posizione rilevata del visitatore. Non è richiesta alcuna configurazione aggiuntiva.

Europa

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.

Fuori dall'Europa

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.

Come viene determinata la posizione

PrivacyKit determina automaticamente se il visitatore si trova in Europa. Non è richiesta alcuna configurazione.

Google Consent Mode v2

Quando google-consent-mode è abilitato, PrivacyKit legge le scelte di consenso dell'utente 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 l'utente modifica il proprio consenso. Non è richiesta alcuna configurazione aggiuntiva oltre all'aggiunta dell'attributo.

Configurazione consigliata

Abbinare <consent-guard> attorno al proprio snippet GTM con google-consent-mode sulla finestra di dialogo è un approccio basato sull'applicazione: GTM non può caricarsi affatto prima che il consenso venga concesso, e i segnali di Google Consent Mode v2 vengono inviati immediatamente non appena ciò accade. GTM è solo un contenitore — può ospitare tag di analisi, tag di marketing, o entrambi, a seconda di ciò che è stato configurato al suo interno. Imposta l'espressione consent su <consent-guard> di conseguenza: marketing se GTM attiva solo tag di marketing/pubblicitari, analytics se riguarda solo l'analisi, oppure analytics+marketing se attiva entrambi.

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>

Mappatura dei segnali di consenso

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.

Come vengono inviati i segnali

PrivacyKit verifica se window.gtag è disponibile (Google Tag Manager o gtag.js caricato). In tal caso, chiama:

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

Se gtag non è disponibile ma window.dataLayer sì, PrivacyKit invia l'aggiornamento del consenso direttamente al dataLayer. Se nessuno dei due è presente, non viene inviato alcun segnale e nulla viene messo in coda.

Quando Google Tag Manager è protetto da <consent-guard> — cioè si carica solo dopo che l'utente ha concesso il consenso — PrivacyKit ritenta automaticamente l'invio del segnale una volta terminato il caricamento di GTM.

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 update emitted.
Un segnale di consenso è stato inviato a gtag o al dataLayer.
[PrivacyKit] Google Consent Mode v2 update skipped because no Google tag was detected.
Non è stato rilevato né gtag né dataLayer nel browser, quindi non è stato inviato nulla.

Metodi della finestra di dialogo

TypeScriptDocumentazione API

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

<consent-guard>

Renderizza i figli solo quando l'espressione di consenso fornita risulta vera.

Attributi

Attributo	Tipo	Default / Obblig.	Descrizione
consent	string	unset	Espressione di consenso da soddisfare prima di renderizzare i contenuti.

Espressioni di consenso

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 Compliance Monitor per le risorse necessarie non riconosciute automaticamente da PrivacyKit.
preferences	Preferenze
analytics	Analisi
marketing	Marketing
preferences+analytics	Preferenze E Analisi
preferences\|analytics	Preferenze O Analisi
preferences+marketing	Preferenze E Marketing
preferences\|marketing	Preferenze O Marketing
analytics+marketing	Analisi E Marketing
analytics\|marketing	Analisi O Marketing

Esempio 1 – Proteggere gli script

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

Esempio 2 – Proteggere i contenuti incorporati

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>

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 Compliance Monitor.

<consent-missing>

Mostra contenuti di fallback quando il consent-guard associato blocca l'esperienza principale.

Attributi

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>

<compliance-monitor>

Compliance Monitor 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.

Attributi

Attributo	Tipo	Default / Obblig.	Descrizione
debug	boolean	false	Abilita il pannello Compliance Monitor al caricamento della pagina. Solo per ambienti di sviluppo.
delay	number	5000	Finestra di osservazione della rete (in millisecondi) prima che Compliance Monitor 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 Compliance Monitor.

Esempio

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

Compliance Monitor rimane nascosto ai visitatori anche quando è incluso nel bundle di produzione. Il modo consigliato per attivarlo su un sito in produzione è aggiungere ?privacykit=monitor all'URL — questo attiva il monitor solo per quella sessione del browser, senza influire sull'esperienza dei visitatori.

Attiva a livello di codice:

TypeScriptDocumentazione API

window.PrivacyKit?.toggleComplianceMonitor();

Appendici

Frammenti CSS

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.

NPM

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

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

consent-missing:not([active]) {
  display: none;
}
Se usi contenuti con slot oppure usi i consent-guard con HTML, inserisci questo snippet nel tuo foglio di stile globale o in un tag <style> che venga eseguito prima del rendering dei web component di PrivacyKit.