Passa al contenuto principale

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.

Banner v2

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​

MomentoEvento
Al caricamento della paginaavacy:ready
Dopo la scelta del visitatoreavacy: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.

EventoQuando partedetail
avacy:readyIl banner ha finito l'avvio e ha montato l'interfaccia.null
avacy:consent-loadedIl banner ha letto il consenso salvato, a ogni avvio. Parte anche senza consenso salvato, con { valid: false }.{ valid, type?, timestamp?, gcm? }
avacy:consent-savedIl visitatore ha fatto una scelta.{ type, timestamp, gcm }
avacy:consent-updatedUn campo del consenso salvato è cambiato senza una nuova scelta.{ fields, ... }
avacy:consent-changedIl consenso è cambiato in qualsiasi modo. Parte dopo l'evento specifico.{ cause?, valid, type?, timestamp?, gcm?, fields? }
avacy:banner-shownIl banner del primo livello compare.{ layer: 'first' }
avacy:banner-hiddenIl banner del primo livello sparisce.{ reason: 'consent' }, { reason: 'destroy' } oppure { reason: 'dismissed' }
avacy:cpc-openedIl pannello delle preferenze si apre.null
avacy:cpc-closedIl pannello delle preferenze si chiude.null
avacy:language-changedLa lingua del banner cambia.{ lang, prev }

Il contenuto dei campi​

Il significato dei campi di detail:

  • type vale '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;
  • gcm contiene 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: false indica consenso assente o scaduto, non rifiutato. Vedi Leggere il consenso;
  • cause di avacy:consent-changed vale 'decision' (scelta del visitatore), 'load' (lettura all'avvio) o 'record-update' (campo aggiornato);
  • reason di avacy:banner-hidden vale '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.

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.triggerQuando parte
page_loadIl banner ha letto un consenso salvato, all'avvio.
consent_updateIl 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 è false dopo un rifiuto totale, true negli altri casi. Sono rifiuti totali Rifiuta tutto, la X, Continua senza accettare e le preferenze salvate con tutto spento;
  • purposes, legitimateInterests e specialFeatures elencano gli id IAB con consenso o con legittimo interesse;
  • iabVendorsWithConsent elenca i fornitori IAB con il consenso al fornitore, come { id, name }. Il nome manca finché il pannello delle preferenze non è stato aperto;
  • customVendorsWithConsent elenca 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 di avacy: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:

  1. avacy:consent-loaded con { valid: false };
  2. avacy:consent-changed con cause: 'load';
  3. avacy:banner-shown;
  4. 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​

  1. 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>
  2. Se lo script sta dopo il banner, controlla prima lo stato. Gli eventi di avvio (avacy:ready e avacy: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());
    });
  3. 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​

  1. Apri la pagina con lo script dello step 1 e la console aperta, senza consenso salvato.
  2. Ricarica. In console compaiono avacy:consent-loaded, avacy:consent-changed, avacy:banner-shown e avacy:ready, in questo ordine.
  3. Scegli nel banner. In console compaiono avacy:consent-saved, avacy:consent-changed e avacy:banner-hidden.

Problemi comuni​

I problemi più frequenti:

  • Il listener su window o su un elemento non scatta: gli eventi avacy:* partono dal document e non risalgono. Usa document.addEventListener. Fa eccezione avacy_consent, che sta sul window;
  • Il listener di avacy_consent non scatta alla prima visita: senza consenso salvato l'evento parte dopo la prima scelta del visitatore;
  • Il listener di avacy:ready non 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. undefined non vuol dire "tutto negato";
  • avacy:banner-hidden arriva senza scelta del visitatore: il banner è stato ricaricato (reason: 'destroy');
  • Il listener scatta due volte per ogni scelta: avacy:consent-saved e avacy:consent-changed partono insieme. Ascolta uno solo dei due. Con l'archiviazione dei consensi attiva anche avacy:consent-changed scatta due volte, la seconda con cause: 'record-update'. Per reagire solo alle scelte del visitatore usa avacy:consent-saved.

Ultimo aggiornamento: 30/10/2026.