Il consenso negli iframe cross-origin: il pattern __tcfapiLocator e __gppLocator
Il problema: il consenso vive nella finestra principale
Un CMP gira sulla tua pagina, nella finestra di livello superiore. Gran parte della tua pubblicità no. I creativi display, il rich media, i renderer di header bidding e molti widget di terze parti girano dentro iframe, spesso su un'origine diversa. Il codice in un iframe cross-origin non può chiamare direttamente una funzione della pagina padre, quindi non può semplicemente chiamare __tcfapi o __gpp e leggere la scelta del visitatore.
I framework IAB risolvono il problema con una convenzione di messaggistica piccola e ben definita. Se sviluppi prodotti pubblicitari, embed o script di misurazione che girano in frame, o se fai il debug di stack pubblicitari che lo fanno, vale la pena sapere esattamente come funziona.
Il frame locator
Oltre all'API JavaScript, un CMP TCF aggiunge alla pagina di livello superiore un iframe vuoto e invisibile chiamato __tcfapiLocator. Un CMP GPP fa lo stesso con un frame chiamato __gppLocator. I frame non hanno contenuto. Il loro unico compito è essere individuabili: qualsiasi script in qualsiasi frame annidato può risalire la gerarchia delle finestre e controllare a ogni livello se esiste un frame con quel nome.
Poiché i nomi dei frame sono visibili tra origini tramite window.frames, uno script in un iframe cross-origin profondamente annidato può individuare la finestra che ospita il CMP senza avere accesso a nient'altro di quella pagina.
Come uno script incorniciato trova il CMP
- Parti dalla finestra corrente. Se __tcfapi esiste localmente, usalo direttamente — lo script non è in un frame, oppure il frame condivide il CMP.
- Altrimenti, risali in un ciclo: controlla se la finestra corrente contiene un frame chiamato __tcfapiLocator; se no, passa a window.parent e controlla di nuovo, fermandoti alla finestra di livello superiore.
- Quando il locator viene trovato, la finestra che lo contiene è la finestra del CMP. La comunicazione avviene ora tramite postMessage.
Racchiudi ogni accesso in un try/catch, perché alcuni browser o impostazioni di sandboxing generano un'eccezione sull'accesso cross-origin alle proprietà, e interrompi il ciclo quando window.parent è uguale alla finestra corrente.
Il formato dei messaggi
Per TCF, lo script incorniciato invia alla finestra del CMP un messaggio contenente un oggetto con una proprietà __tcfapiCall. Al suo interno ci sono quattro campi:
- command — per esempio getTCData, ping o addEventListener;
- parameter — qualsiasi argomento di cui il comando abbia bisogno, oppure null;
- version — la versione dell'API, 2 per TCF v2;
- callId — un valore univoco generato dal chiamante.
Il CMP ascolta questi messaggi, esegue il comando e rimanda un oggetto con una proprietà __tcfapiReturn contenente returnValue, success e lo stesso callId. Il chiamante tiene una mappa dei callback in sospeso indicizzata per callId, ascolta gli eventi message e smista ogni risposta al callback giusto. GPP segue lo stesso schema con __gppCall e __gppReturn.
Molte integrazioni scrivono un piccolo proxy: una funzione locale chiamata __tcfapi dentro il frame che traduce le chiamate in messaggi. Il codice scritto per la finestra di livello superiore funziona così senza modifiche all'interno del frame.
Gli event listener tra frame
Una chiamata addEventListener inviata tramite postMessage non è una richiesta singola. Il CMP rimanderà un messaggio di risposta ogni volta che lo stato del consenso cambia, tutti con lo stesso callId. Il tuo dispatcher deve quindi mantenere quel callback registrato anziché eliminarlo dopo la prima risposta. Dimenticarlo è un bug classico: lo script incorniciato legge il consenso una volta e non si accorge mai di una revoca successiva.
Considerazioni sulla sicurezza
- Convalida la forma del messaggio. Ignora qualsiasi messaggio che non contenga la proprietà attesa, e analizza con cautela i payload di tipo stringa, perché alcune implementazioni inviano stringhe JSON anziché oggetti.
- Non fidarti ciecamente. Qualsiasi pagina può inviare messaggi al tuo frame. Tratta le risposte come segnali di consenso da rispettare, non come dati autenticati, e non lasciare mai che attivino azioni privilegiate.
- Usa origini di destinazione specifiche quando puoi. Quando l'origine del CMP è nota, invia il messaggio a quella anziché a tutte le origini.
Dove il pattern non arriva
Alcuni ambienti pubblicitari isolano i creativi in modo più rigoroso. I contenitori SafeFrame, gli iframe in sandbox senza i permessi giusti e i creativi renderizzati in documenti separati possono non essere in grado di percorrere l'albero dei frame né di ricevere messaggi. In questi casi il segnale di consenso di solito deve essere passato esplicitamente, per esempio come parametri della richiesta pubblicitaria o come valori consegnati al creativo dall'ad server, come i parametri gdpr e gdpr_consent supportati da molti tag pubblicitari.
Checklist di debug
- Nei DevTools della finestra di livello superiore, conferma che i frame locator esistano nel pannello Elements.
- Passa il contesto della console all'iframe e verifica se il locator è raggiungibile da lì.
- Registra nei log gli eventi message in entrata in entrambe le finestre per confermare che chiamate e risposte circolino.
- Cambia il consenso nel banner e verifica che i listener incorniciati ricevano un aggiornamento.
- Testa con il CMP caricato in ritardo, per assicurarti che il codice incorniciato riprovi o attenda anziché arrendersi subito.
Punti chiave
- I frame cross-origin raggiungono il CMP tramite i frame __tcfapiLocator e __gppLocator.
- Chiamate e risposte usano postMessage con __tcfapiCall/__tcfapiReturn o gli equivalenti GPP, abbinati tramite callId.
- Mantieni registrati i callback dei listener in modo che arrivino i successivi cambiamenti del consenso.
- Convalida ogni messaggio ed evita di trattarlo come input attendibile.
- Dove i frame sono completamente isolati, passa il consenso esplicitamente nella richiesta pubblicitaria.