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.

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

Esempio

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

Pulsante delle preferenze di consenso

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>

Personalizza i contenuti

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	Contenuto del logo facoltativo mostrato nell’intestazione del dialogo.
dialog-logo-alt	Posizione alternativa per un logo del brand, mostrata in alto a destra del testo di dialog-summary-part-1.
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" 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>

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-bg-color	Colore di sfondo dell'intero dialogo.
--pk-paper-color	Colore carta per card, fisarmoniche e pannelli all'interno della finestra di dialogo.
--pk-text-color	Colore base per titoli e testo.
--pk-primary-color	Accento principale per CTA, focus e link.
--pk-text-color-on-primary	Colore del testo usato su elementi riempiti con il colore primario, come i pulsanti pieni.
--pk-secondary-color	Accento secondario, usato soprattutto dai toggle.
--pk-border-color	Colore del bordo per contorni dei pannelli, tabelle e divisori.
--pk-focus-ring-color	Colore del contorno di focus (outline) per gli stati di focus da tastiera.
--pk-border-width	Spessore del bordo per contorni dei pannelli, tabelle e divisori.
--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-radius	Raggio degli angoli per pulsanti, campi e controlli interattivi.
--pk-dialog-radius	Raggio degli angoli per il contenitore esterno del dialogo di consenso.
--pk-dialog-shadow	Ombra applicata al dialogo di consenso.
--pk-dialog-max-height	Altezza massima del dialogo di consenso; quando il contenuto supera questo limite, il corpo del dialogo scorre.

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-radius: 10px;
  --pk-dialog-radius: 20px;
  --pk-dialog-shadow: 10px 20px rgba(0, 0, 0, 0.5);
  --pk-dialog-max-height: 50vh;
">
</consent-dialog>

Metodi

TypeScriptDocumentazione API

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

<consent-guard>

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

Proprietà	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 - Bloccare/caricare script

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

Esempio 2 - Bloccare/caricare HTML

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.

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

Proprietà	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();