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

  1. Parti dalla finestra corrente. Se __tcfapi esiste localmente, usalo direttamente — lo script non è in un frame, oppure il frame condivide il CMP.
  2. 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.
  3. 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:

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

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

Punti chiave

← Blog Leggi tutto →