Eventi del banner
Il banner emette eventi del browser sul document, più l'evento avacy_consent sul window. Il codice del sito li ascolta con addEventListener.
Il banner v2 non emette gli eventi avacy:* e ne usa altri. Emette anche avacy_consent, con differenze nei fornitori. Vedi Eventi JavaScript (v2). Se non sai quale banner usa il tuo sito, leggi Quale banner sta usando il tuo sito.
Prerequisiti
Prima di cominciare controlla che:
- il banner sia installato nella pagina. Vedi Snippet HTML;
- lo script con i listener stia nella pagina prima del banner, oppure usi il controllo dello step 2.
Dove ascoltare gli eventi
Il banner emette ogni evento avacy:* sul document, senza bubbles. Ascolta con document.addEventListener. Un listener su window o su un elemento della pagina non riceve gli eventi.
Quale evento usare
| Momento | Evento |
|---|---|
| Al caricamento della pagina | avacy:ready |
| Dopo la scelta del visitatore | avacy:consent-saved |
Dopo avacy:ready getConsent() risponde con il consenso salvato. Nel listener di avacy:consent-saved è già aggiornato.
Gli eventi
Il dato dell'evento sta in event.detail.
| Evento | Quando parte | detail |
|---|---|---|
avacy:ready | Il banner ha finito l'avvio e ha montato l'interfaccia. | null |
avacy:consent-loaded | Il banner ha letto il consenso salvato, a ogni avvio. Parte anche senza consenso salvato, con { valid: false }. | { valid, type?, timestamp?, gcm? } |
avacy:consent-saved | Il visitatore ha fatto una scelta. | { type, timestamp, gcm } |
avacy:consent-updated | Un campo del consenso salvato è cambiato senza una nuova scelta. | { fields, ... } |
avacy:consent-changed | Il consenso è cambiato in qualsiasi modo. Parte dopo l'evento specifico. | { cause?, valid, type?, timestamp?, gcm?, fields? } |
avacy:banner-shown | Il banner del primo livello compare. | { layer: 'first' } |
avacy:banner-hidden | Il banner del primo livello sparisce. | { reason: 'consent' }, { reason: 'destroy' } oppure { reason: 'dismissed' } |
avacy:cpc-opened | Il pannello delle preferenze si apre. | null |
avacy:cpc-closed | Il pannello delle preferenze si chiude. | null |
avacy:language-changed | La lingua del banner cambia. | { lang, prev } |
Il contenuto dei campi
Il significato dei campi di detail:
typevale'AcceptAll','RejectAll'o'Personalized'. Una scelta personalizzata uguale a "accetta tutto" o "rifiuta tutto" arriva con il tipo corrispondente;timestampè il momento della scelta, in millisecondi dal 1970;gcmcontiene i sette permessi di Google Consent Mode (ad_storage,ad_user_data,ad_personalization,analytics_storage,functionality_storage,personalization_storage,security_storage), ciascuno'granted'o'denied'. Il campo manca se il banner non ha Google Consent Mode attivo;valid: falseindica consenso assente o scaduto, non rifiutato. Vedi Leggere il consenso;causediavacy:consent-changedvale'decision'(scelta del visitatore),'load'(lettura all'avvio) o'record-update'(campo aggiornato);reasondiavacy:banner-hiddenvale'consent'quando il visitatore ha scelto e'destroy'quando il banner viene ricaricato. Vale'dismissed'quando un rifiuto o una chiusura non riesce per un errore tecnico, per esempio perché l'elenco dei fornitori IAB non si scarica: il banner si chiude fino alla chiusura della scheda e non salva nessun consenso. Non trattarlo come una scelta del visitatore.
Il dato dell'evento ha tipo, ora e permessi Google, senza le scelte per fornitore o finalità. Per quelle chiama window.Avacy.getConsent() nel listener.
L'evento avacy_consent
Il banner manda anche avacy_consent, con le scelte per finalità e fornitore nel detail. Lo emette sul window, non sul document, e non ha il prefisso avacy:. Ascoltalo con window.addEventListener. L'evento esiste su ogni spazio web e la dashboard lo attiva da sola, tramite l'add-on consent-event.
detail.trigger | Quando parte |
|---|---|
page_load | Il banner ha letto un consenso salvato, all'avvio. |
consent_update | Il visitatore ha fatto una scelta, anche un rifiuto. |
Senza consenso salvato l'evento non parte, finché il visitatore non sceglie.
window.addEventListener('avacy_consent', function (event) {
console.log(event.detail.trigger, event.detail.optin, event.detail.customVendorsWithConsent);
});
I campi principali del detail:
optinèfalsedopo un rifiuto totale,truenegli altri casi. Sono rifiuti totali Rifiuta tutto, la X, Continua senza accettare e le preferenze salvate con tutto spento;purposes,legitimateInterestsespecialFeatureselencano gli id IAB con consenso o con legittimo interesse;iabVendorsWithConsentelenca i fornitori IAB con il consenso al fornitore, come{ id, name }. Il nome manca finché il pannello delle preferenze non è stato aperto;customVendorsWithConsentelenca i fornitori personalizzati, come{ id, name }. Un fornitore entra con il consenso al fornitore e a tutte le finalità che dichiara. Un fornitore senza finalità dichiarate entra con il solo consenso al fornitore;gcmè un array dei tipi di Consent Mode concessi, per esempio['ad_storage']. Non è l'oggetto diavacy:consent-saved.
Il banner scarica il file dei fornitori personalizzati, per leggere le finalità dichiarate, quando almeno un fornitore personalizzato ha il consenso. Se il file non arriva entro 3 secondi, nessun fornitore personalizzato entra in customVendorsWithConsent, e l'evento parte lo stesso con il resto dei campi.
La guida Blocco preventivo con Google Tag Manager spiega come far partire un tag di Google Tag Manager per fornitore con questo evento.
L'ordine degli eventi
Al caricamento di una pagina senza consenso gli eventi arrivano in questo ordine:
avacy:consent-loadedcon{ valid: false };avacy:consent-changedconcause: 'load';avacy:banner-shown;avacy:ready.
Con un consenso già salvato avacy:banner-shown non parte.
Dopo una scelta arrivano avacy:consent-saved, avacy:consent-changed con cause: 'decision' e avacy:banner-hidden con reason: 'consent'.
Step
-
Metti lo script con i listener nella pagina, prima del banner. L'esempio scrive in console ogni evento.
<script>['ready', 'consent-loaded', 'consent-saved', 'consent-updated', 'consent-changed','banner-shown', 'banner-hidden', 'cpc-opened', 'cpc-closed', 'language-changed'].forEach(function (name) {document.addEventListener('avacy:' + name, function (event) {console.log('avacy:' + name, event.detail);});});</script> -
Se lo script sta dopo il banner, controlla prima lo stato. Gli eventi di avvio (
avacy:readyeavacy:consent-loaded) partono una volta sola e un listener registrato dopo li perde.function alCaricamento(callback) {var consent = window.Avacy && window.Avacy.getConsent();if (consent && consent.ready) {callback();} else {document.addEventListener('avacy:ready', callback, { once: true });}}alCaricamento(function () {console.log('banner pronto', window.Avacy.getConsent());}); -
Reagisci alla scelta del visitatore.
document.addEventListener('avacy:consent-saved', function (event) {console.log('scelta:', event.detail.type);console.log('dettaglio:', window.Avacy.getConsent().choices);});
Un esempio completo è in Far partire uno script solo con il consenso.
Verifica
- Apri la pagina con lo script dello step 1 e la console aperta, senza consenso salvato.
- Ricarica. In console compaiono
avacy:consent-loaded,avacy:consent-changed,avacy:banner-showneavacy:ready, in questo ordine. - Scegli nel banner. In console compaiono
avacy:consent-saved,avacy:consent-changedeavacy:banner-hidden.
Problemi comuni
I problemi più frequenti:
- Il listener su
windowo su un elemento non scatta: gli eventiavacy:*partono daldocumente non risalgono. Usadocument.addEventListener. Fa eccezioneavacy_consent, che sta sulwindow; - Il listener di
avacy_consentnon scatta alla prima visita: senza consenso salvato l'evento parte dopo la prima scelta del visitatore; - Il listener di
avacy:readynon scatta: lo hai registrato dopo l'evento. Usa il controllo dello step 2; event.detail.gcmèundefined: il banner non ha Google Consent Mode attivo.undefinednon vuol dire "tutto negato";avacy:banner-hiddenarriva senza scelta del visitatore: il banner è stato ricaricato (reason: 'destroy');- Il listener scatta due volte per ogni scelta:
avacy:consent-savedeavacy:consent-changedpartono insieme. Ascolta uno solo dei due. Con l'archiviazione dei consensi attiva ancheavacy:consent-changedscatta due volte, la seconda concause: 'record-update'. Per reagire solo alle scelte del visitatore usaavacy:consent-saved.
Ultimo aggiornamento: 30/10/2026.