Perché i tuoi script dovrebbero ascoltare, non fare polling

Qualsiasi script che dipende dal consenso — un tag pubblicitario, un loader di analytics, un wrapper di header bidding — deve sapere due cose: se il CMP ha già una decisione e quale sia. Un errore comune è leggere un cookie al caricamento della pagina, o fare polling sul CMP con un timer finché non compare qualcosa. Entrambi gli approcci falliscono in modi prevedibili: il formato del cookie è interno al CMP e può cambiare, e il polling o scatta troppo presto o spreca tempo in attesa.

L’IAB TCF definisce un’interfaccia JavaScript standard proprio per questo compito: la funzione __tcfapi. Questo tutorial illustra i comandi di cui hai davvero bisogno, gli eventi che riceverai e i bug che compaiono più spesso in produzione.

Lo stub e la coda

Ci si aspetta che un CMP TCF inserisca nella pagina un piccolo stub il prima possibile, prima che si carichi lo script completo del CMP. Lo stub definisce window.__tcfapi e mette in coda le chiamate fatte prima che il CMP sia pronto. Quando il CMP ha finito di caricarsi, elabora la coda e risponde a ogni chiamata.

È questo che rende sicuro per gli altri script chiamare subito __tcfapi: finché lo stub è nella pagina prima di loro, le loro chiamate non vanno perse. Se uno script genera un errore perché __tcfapi non è definito, lo stub manca o si carica troppo tardi — correggi l’ordine di caricamento invece di aggiungere tentativi.

I comandi che contano

ping

__tcfapi('ping', 2, callback) restituisce lo stato di base senza attendere la decisione dell’utente. La risposta include cmpLoaded, un cmpStatus come stub, loading, loaded o error e un displayStatus con valore visible, hidden o disabled. Segnala anche gdprApplies una volta noto. Usalo per la diagnostica e per decidere se il TCF sia rilevante per questo visitatore.

addEventListener

__tcfapi('addEventListener', 2, callback) è il comando che la maggior parte delle integrazioni dovrebbe usare. La callback riceve un oggetto tcData e un flag di successo, e viene richiamata ogni volta che lo stato del consenso cambia. Dal TCF v2.2 questo è il modo raccomandato per ottenere i dati di consenso; il vecchio comando getTCData è stato deprecato.

removeEventListener

Ogni oggetto tcData porta un listenerId. Passalo a __tcfapi('removeEventListener', 2, callback, listenerId) quando il tuo script non ha più bisogno di aggiornamenti — per esempio, un loader monouso che ha già preso la sua decisione.

Leggere eventStatus

Il campo chiave in tcData è eventStatus. Ha tre valori:

• tcloaded — il CMP ha trovato una decisione archiviata valida e non verrà mostrato alcun banner. Puoi agire subito sui dati.
• cmpuishown — il banner è in fase di visualizzazione. I dati riflettono l’eventuale stato precedente, ma l’utente potrebbe essere sul punto di cambiarlo.
• useractioncomplete — l’utente ha appena effettuato o confermato una scelta. Agisci sui nuovi dati.

Un loader tipico attende tcloaded oppure useractioncomplete, poi controlla le finalità e i fornitori che gli servono. Ignora cmpuishown, se non magari per registrare che è comparso un banner.

Controllare finalità e fornitori

All’interno di tcData, consenso e legittimo interesse sono esposti come oggetti indicizzati per ID:

• tcData.purpose.consents[1] — consenso per la finalità 1 (archiviazione sul dispositivo).
• tcData.purpose.legitimateInterests[7] — stato del legittimo interesse per la finalità 7.
• tcData.vendor.consents[ID] e tcData.vendor.legitimateInterests[ID] — stato per fornitore, usando l’ID del fornitore nella Global Vendor List.
• tcData.gdprApplies — se il CMP ha stabilito che il GDPR si applica a questo visitatore. Se è false, il tuo script dovrebbe seguire la sua logica non TCF.
• tcData.tcString — la stringa codificata, che passi ai partner che la richiedono.

Controlla sia la finalità sia il fornitore. Un consenso alla finalità senza consenso del fornitore, o viceversa, non basta alla maggior parte dei fornitori per trattare i dati.

Iframe e chiamate tra frame

Annunci e widget girano spesso dentro iframe che non vedono il __tcfapi della pagina padre. Il TCF risolve il problema con un protocollo postMessage: il CMP aggiunge alla pagina principale un frame chiamato __tcfapiLocator e il codice dentro un iframe può individuarlo, inviare un messaggio __tcfapiCall e ricevere una risposta __tcfapiReturn. La maggior parte degli SDK pubblicitari lo fa già. Se scrivi codice iframe tuo, implementa lo stesso schema invece di leggere i cookie tra frame.

Bug comuni e come individuarli

1. Agire su cmpuishown. Gli script che si caricano non appena scatta una qualsiasi callback verranno eseguiti prima che l’utente decida. Filtra su eventStatus.
2. Rimuovere il listener troppo presto. Se lo rimuovi dopo la prima callback, perderai un successivo useractioncomplete e non caricherai mai.
3. Ignorare le revoche. Gli script persistenti dovrebbero continuare ad ascoltare e fermarsi o riconfigurarsi quando il consenso viene revocato.
4. Ignorare gdprApplies. Fuori dalle regioni TCF, gli oggetti delle finalità possono essere vuoti; trattarli come “nessun consenso” può spegnere ricavi che hai il diritto di generare.
5. Non controllare il flag di successo. Quando success è false, registralo; di solito segnala una configurazione del CMP guasta.

Testare la tua integrazione

Nella console del browser, chiama __tcfapi('ping', 2, console.log) per confermare che il CMP sia presente, poi registra un listener con console.log come callback e percorri il banner. Dovresti vedere cmpuishown seguito da useractioncomplete alla prima visita, e tcloaded a un ricaricamento. Ripeti con accetta tutto, rifiuta tutto e una selezione personalizzata, e conferma che il tuo script si comporti correttamente in ogni caso.

Punti chiave

• Usa __tcfapi invece di leggere i cookie del CMP o fare polling.
• Assicurati che lo stub del CMP si carichi prima di qualsiasi script che chiami l’API.
• Usa addEventListener e agisci solo su tcloaded o useractioncomplete.
• Controlla sia lo stato della finalità sia quello del fornitore e rispetta gdprApplies.
• Usa lo schema postMessage di __tcfapiLocator dentro gli iframe.