Eventi JavaScript del consenso: guida per sviluppatori

Questa guida è per chi scrive codice: sviluppatori frontend, backend che si occupano di tracking, chi costruisce integrazioni custom su misura del cliente.

Se hai attiva la funzionalità Statistiche di My Agile Privacy e usi Google Analytics 4, le variazioni del consenso arrivano già a GA4: non devi scrivere una riga di codice, solo abilitare la funzionalità. Gli eventi JavaScript raccontati qui servono a tutto il resto. Sincronizzare il tuo data layer, attivare moduli proprietari, misurare come gli utenti interagiscono con il banner: tutto ciò che la configurazione standard non copre.

Il consenso, per definizione, viene salvato dentro la Consent Management Platform. Con questi eventi puoi propagarlo ovunque ti serva.

Il problema: il consenso accade dentro il cookie banner

Hai un modulo di analytics interno. Uno script di terze parti che non passa dal blocco automatico. Un'interfaccia che deve adattarsi quando l'utente rifiuta.

Il tuo codice ha bisogno di sapere, nel momento esatto in cui accade, che l'utente ha accettato, rifiutato o personalizzato il consenso. Ma quella scelta avviene dentro il banner di My Agile Privacy, e il tuo JavaScript, fuori, non ne sa niente.

Aspettare il reload della pagina non basta: il consenso cambia senza ricaricare. Leggere i cookie dal tuo script significa interrogare uno stato, non reagire a un evento.

Il consenso non è uno stato da interrogare quando ti serve. È un evento da ascoltare quando accade.

Perché non arrangiarsi con un hack

La strada artigianale esiste: un MutationObserver sul banner, un polling periodico sui cookie, un observer sugli attributi del pulsante.

Funziona finché funziona. Poi il widget viene ridisegnato, la classe CSS cambia nome, il markup si sposta, e il tuo observer smette di vedere qualcosa che continua ad accadere. Nessun errore in console: solo dati che non arrivano più.

E soprattutto: un hack sul DOM non distingue un "Accetta tutto" da un toggle su un singolo servizio. Non sa che esistono il pannello IAB, il riconsenso, i due livelli del banner. Ti perdi esattamente la granularità che ti serviva.

Se stai facendo polling su un cookie, stai costruendo il tuo prossimo bug.

La soluzione: eventi documentati, lanciati sul window

My Agile Privacy emette un evento JavaScript per ogni azione di consenso, come CustomEvent lanciato sul window. Sono eventi pubblici, con un nome stabile e documentato: ti ci agganci con window.addEventListener() e il tuo codice reagisce nel momento esatto, con la granularità giusta.

Niente polling, niente observer sul DOM, niente dipendenze dal markup del banner. Solo un contratto: l'utente fa una scelta, MAP emette l'evento, il tuo ascoltatore parte.

Come funzionano gli eventi

Schema base:

window.addEventListener('nome_evento', function() {
	// la tua logica qui
});

Regola di timing: registra l'ascoltatore prima che l'evento scatti. Il punto sicuro è un tag <script> nel <head> o l'inizio del tuo file JavaScript principale. Un listener registrato a fondo pagina può perdersi gli eventi della fase iniziale di caricamento.

La mappa completa degli eventi

Eventi globali (accetta tutto / rifiuta tutto)

myagileprivacy_gcmode_consent_granted

Scatta quando l'utente concede il consenso tramite Google Consent Mode. Si attiva dopo "Accetta tutto" o dopo una personalizzazione che risulta in almeno uno scopo concesso.

window.addEventListener('myagileprivacy_gcmode_consent_granted', function() {
	console.log('GCM - Consenso CONCESSO');
	// Esempio: attiva analytics, manda push al dataLayer
});

myagileprivacy_gcmode_consent_denied

Scatta quando l'utente nega il consenso tramite Google Consent Mode. Si attiva dopo "Rifiuta tutto" o dopo una personalizzazione che risulta in tutti gli scopi negati.

window.addEventListener('myagileprivacy_gcmode_consent_denied', function() {
	console.log('GCM - Consenso NEGATO');
	// Esempio: disattiva tracking, cancella cookie non tecnici
});

myagileprivacy_cookie_accept

Scatta quando l'utente clicca il pulsante "Accetta tutto" nel banner. Riflette l'azione esplicita sull'interfaccia, indipendentemente dallo stato GCM. Tutti i singoli cookie/servizi configurati vengono attivati.

window.addEventListener('myagileprivacy_cookie_accept', function() {
	console.log('Banner - ACCETTA TUTTO');
	// Esempio: attiva tutti gli script, lancia trigger GTM
});

myagileprivacy_cookie_reject

Scatta quando l'utente clicca il pulsante "Rifiuta tutto" nel banner. Riflette l'azione esplicita sull'interfaccia, indipendentemente dallo stato GCM. Tutti i singoli cookie/servizi configurati vengono disattivati.

window.addEventListener('myagileprivacy_cookie_reject', function() {
	console.log('Banner - RIFIUTA TUTTO');
	// Esempio: registra il rifiuto, aggiorna UI
});

myagileprivacy_cookie_customize

Scatta quando l'utente apre il pannello di personalizzazione del consenso, prima di confermare una scelta definitiva. È l'evento che misura l'engagement con l'interfaccia: quante persone vogliono davvero scegliere.

window.addEventListener('myagileprivacy_cookie_customize', function() {
	console.log('Banner - PERSONALIZZA aperto');
	// Esempio: avvia caricamento differito della vendor list IAB
});

myagileprivacy_resurface

Scatta quando il banner viene mostrato di nuovo a seguito del click su uno dei widget del riconsenso. È il momento in cui un consenso già dato torna sul tavolo: il tuo codice custom dovrebbe comportarsi di conseguenza.

window.addEventListener('myagileprivacy_resurface', function() {
	console.log('Banner - RICOMPARSO');
	// Esempio: sospendi analytics fino al nuovo consenso
});

Eventi granulari (singolo cookie/servizio)

myagileprivacy_single_cookie_accept

Scatta quando l'utente attiva il consenso per un singolo cookie/servizio di terze parti dal pannello di personalizzazione (secondo layer). Ogni toggle corrisponde a un servizio specifico: Google Analytics, Facebook Pixel e così via. Non viene emesso da "Accetta tutto": riguarda solo i toggle individuali.

window.addEventListener('myagileprivacy_single_cookie_accept', function() {
	console.log('Preferenze - Cookie/servizio ATTIVATO');
	// Esempio: sblocca lo script del servizio appena accettato
});

myagileprivacy_single_cookie_reject

Scatta quando l'utente disattiva il consenso per un singolo cookie/servizio di terze parti dal pannello di personalizzazione (secondo layer). Non viene emesso da "Rifiuta tutto": riguarda solo i toggle individuali.

window.addEventListener('myagileprivacy_single_cookie_reject', function() {
	console.log('Preferenze - Cookie/servizio DISATTIVATO');
	// Esempio: rimuovi i cookie del servizio appena rifiutato
});

Eventi IAB TCF (vendor e finalità)

myagileprivacy_iab_item_accept

Scatta quando l'utente concede il consenso a un singolo vendor o finalità IAB TCF dal pannello di personalizzazione (tab IAB). Riguarda solo i toggle individuali: per il pulsante complessivo esiste myagileprivacy_iab_accept_all.

window.addEventListener('myagileprivacy_iab_item_accept', function() {
	console.log('IAB TCF - Voce ACCETTATA');
	// Esempio: aggiorna il TC String, notifica il framework CMP
});

myagileprivacy_iab_item_reject

Scatta quando l'utente nega il consenso a un singolo vendor o finalità IAB TCF dal pannello di personalizzazione (tab IAB). Riguarda solo i toggle individuali: per il pulsante complessivo esiste myagileprivacy_iab_reject_all.

window.addEventListener('myagileprivacy_iab_item_reject', function() {
	console.log('IAB TCF - Voce RIFIUTATA');
	// Esempio: aggiorna il TC String, blocca il vendor corrispondente
});

myagileprivacy_iab_accept_all

Scatta quando l'utente preme "Accetta tutto" dentro il pannello delle preferenze pubblicitarie (tab IAB). Riguarda il solo pulsante complessivo: i singoli toggle emettono myagileprivacy_iab_item_accept.

window.addEventListener('myagileprivacy_iab_accept_all', function() {
	console.log('IAB TCF - Accetta tutto');
});

myagileprivacy_iab_reject_all

Scatta quando l'utente preme "Rifiuta tutto" dentro il pannello delle preferenze pubblicitarie (tab IAB). Riguarda il solo pulsante complessivo: i singoli toggle emettono myagileprivacy_iab_item_reject.

window.addEventListener('myagileprivacy_iab_reject_all', function() {
	console.log('IAB TCF - Rifiuta tutto');
});

Binding globale: tutti gli eventi in un colpo solo

Quando ti servono più eventi, o vuoi un punto unico di ascolto per debug e logging centralizzato, puoi collegarli in cascata:

const MAP_EVENTS = [
	'myagileprivacy_gcmode_consent_granted',
	'myagileprivacy_gcmode_consent_denied',
	'myagileprivacy_cookie_accept',
	'myagileprivacy_cookie_reject',
	'myagileprivacy_cookie_customize',
	'myagileprivacy_resurface',
	'myagileprivacy_single_cookie_accept',
	'myagileprivacy_single_cookie_reject',
	'myagileprivacy_iab_item_accept',
	'myagileprivacy_iab_item_reject',
	'myagileprivacy_iab_accept_all',
	'myagileprivacy_iab_reject_all',
];

MAP_EVENTS.forEach(function(eventName) {
	window.addEventListener(eventName, function() {
		console.log('[MAP Event]', eventName);
		// La tua logica centralizzata qui
	});
});

Due casi d'uso concreti

1. Push sul data layer per Google Tag Manager

Trasformi ogni azione di consenso in un evento dataLayer, così in GTM puoi creare trigger, variabili e dimensioni personalizzate. GA4 con la funzionalità Statistiche è già coperto: questo schema serve per gli altri strumenti collegati a GTM.

window.dataLayer = window.dataLayer || [];

['cookie_accept', 'cookie_reject', 'cookie_customize', 'resurface'].forEach(function(name) {
	window.addEventListener('myagileprivacy_' + name, function() {
		window.dataLayer.push({
			event: 'map_consent',
			map_action: name,
		});
	});
});

In GTM ti basta un trigger su evento personalizzato map_consent e una variabile map_action per distinguere le quattro azioni.

2. Mettere in pausa il tracking quando il consenso torna sul tavolo

Quando l'utente riapre il banner con un widget di riconsenso, il consenso dato in precedenza non va più dato per scontato: il tuo tracking custom dovrebbe fermarsi finché non arriva una scelta nuova. Poche righe bastano.

(function() {
	let consensoInAttesa = false;

	window.addEventListener('myagileprivacy_resurface', function() {
		consensoInAttesa = true;
	});

	window.addEventListener('myagileprivacy_cookie_accept', function() {
		consensoInAttesa = false;
	});

	window.addEventListener('myagileprivacy_gcmode_consent_granted', function() {
		consensoInAttesa = false;
	});

	// Il tuo invio custom consulta il flag prima di partire
	function inviaEvento(payload) {
		if (consensoInAttesa) return;
		// ...la tua logica di invio
	}
})();

Punti di attenzione

• Registra l'ascoltatore presto. Meglio nel <head> o all'inizio del tuo script principale: gli eventi possono scattare subito, e un listener in ritardo perde i primi.
• Distingui i livelli. "Accetta tutto" non emette gli eventi single_cookie_*: sono due canali diversi, che raccontano azioni diverse. Se conti i consensi, non sommare le cose sbagliate.
• Il riconsenso è un evento a sé. Dopo myagileprivacy_resurface il consenso precedente non va dato per scontato: attendi la nuova scelta prima di riattivare qualunque cosa.

Quando il consenso parla, il tuo codice ascolta

Il banner chiede, l'utente risponde, My Agile Privacy traduce. Questa API è il punto d'incontro tra la conformità e il tuo codice: un contratto stabile, documentato, che non dipende dal markup né dagli stili del widget.

Se ti serve una integrazione che questi eventi non coprono, oppure vuoi un parere sull'architettura del tuo tracking, i nostri sviluppatori (persone vere, non bot o intelligenze artificiali) sono a tua disposizione: Contattaci!