Consentiment dins d'iframes d'origen creuat: el patró __tcfapiLocator i __gppLocator
El problema: el consentiment viu a la finestra superior
Un CMP s'executa a la teva pàgina, a la finestra de nivell superior. Gran part de la teva publicitat no. Els creatius display, el rich media, els renderitzadors de header bidding i molts widgets de tercers s'executen dins d'iframes, sovint d'un altre origen. El codi d'un iframe d'origen creuat no pot cridar directament una funció de la pàgina pare, de manera que no pot cridar simplement __tcfapi o __gpp i llegir l'elecció del visitant.
Els marcs d'IAB ho resolen amb una convenció de missatgeria petita i ben definida. Si crees productes publicitaris, incrustacions o scripts de mesura que s'executen en frames, o si depures piles publicitàries que ho fan, val la pena saber exactament com funciona.
El frame locator
Al costat de l'API JavaScript, un CMP de TCF afegeix a la pàgina de nivell superior un iframe buit i invisible anomenat __tcfapiLocator. Un CMP de GPP fa el mateix amb un frame anomenat __gppLocator. Els frames no porten contingut. L'única feina que tenen és ser localitzables: qualsevol script de qualsevol frame niuat pot pujar per la jerarquia de finestres i comprovar si a cada nivell hi ha un frame amb aquest nom.
Com que els noms dels frames són visibles entre orígens mitjançant window.frames, un script d'un iframe d'origen creuat niuat profundament pot localitzar la finestra que allotja el CMP sense tenir accés a res més d'aquella pàgina.
Com troba el CMP un script dins d'un frame
- Comença amb la finestra actual. Si __tcfapi existeix localment, fes-lo servir directament — l'script no és en un frame, o el frame comparteix el CMP.
- Si no, puja en bucle: comprova si la finestra actual conté un frame anomenat __tcfapiLocator; si no, passa a window.parent i torna a comprovar, aturant-te a la finestra superior.
- Quan es troba el locator, la finestra que el conté és la finestra del CMP. La comunicació passa ara per postMessage.
Embolcalla cada accés en un try/catch, perquè alguns navegadors o configuracions de sandbox llancen un error en accedir a propietats d'origen creuat, i atura el bucle quan window.parent sigui igual a la finestra actual.
El format del missatge
Per a TCF, l'script dins del frame envia un missatge a la finestra del CMP amb un objecte que té una propietat __tcfapiCall. A dins hi ha quatre camps:
- command — per exemple getTCData, ping o addEventListener;
- parameter — qualsevol argument que necessiti l'ordre, o null;
- version — la versió de l'API, 2 per a TCF v2;
- callId — un valor únic generat per qui crida.
El CMP escolta aquests missatges, executa l'ordre i retorna un objecte amb una propietat __tcfapiReturn que conté returnValue, success i el mateix callId. Qui crida manté un mapa de callbacks pendents indexat per callId, escolta els esdeveniments message i lliura cada resposta al callback correcte. GPP segueix el mateix patró amb __gppCall i __gppReturn.
Moltes integracions escriuen un petit proxy: una funció local anomenada __tcfapi dins del frame que tradueix les crides en missatges. Així el codi escrit per a la finestra superior funciona sense canvis dins del frame.
Listeners d'esdeveniments entre frames
Una crida addEventListener enviada per postMessage no és una sol·licitud única. El CMP enviarà un missatge de retorn cada vegada que canviï l'estat del consentiment, tots amb el mateix callId. El teu distribuïdor, doncs, ha de mantenir aquest callback registrat en lloc d'eliminar-lo després de la primera resposta. Oblidar-ho és un error clàssic: l'script dins del frame llegeix el consentiment una vegada i no s'assabenta mai d'una retirada posterior.
Consideracions de seguretat
- Valida la forma del missatge. Ignora qualsevol missatge que no contingui la propietat esperada, i analitza amb cura les càrregues en forma de cadena, ja que algunes implementacions envien cadenes JSON en lloc d'objectes.
- No hi confiïs a cegues. Qualsevol pàgina pot enviar missatges al teu frame. Tracta les respostes com a senyals de consentiment que cal honorar, no com a dades autenticades, i no deixis mai que activin accions privilegiades.
- Fes servir orígens de destinació específics quan puguis. Quan l'origen del CMP és conegut, envia-li el missatge a ell i no a tots els orígens.
On no arriba el patró
Alguns entorns publicitaris aïllen els creatius de manera més estricta. Els contenidors SafeFrame, els iframes en sandbox sense els permisos adequats i els creatius renderitzats en documents separats poden no poder recórrer l'arbre de frames ni rebre missatges. En aquests casos, el senyal de consentiment normalment s'ha de transmetre explícitament, per exemple com a paràmetres de la sol·licitud d'anunci o com a valors que el servidor d'anuncis lliura al creatiu, com els paràmetres gdpr i gdpr_consent que admeten moltes etiquetes d'anuncis.
Llista de verificació de depuració
- A DevTools de la finestra superior, confirma que els frames locator existeixen al panell Elements.
- Canvia el context de la consola a l'iframe i comprova si el locator hi és accessible.
- Registra els esdeveniments message entrants a totes dues finestres per confirmar que les crides i les respostes flueixen.
- Canvia el consentiment al bàner i verifica que els listeners dins dels frames rebin una actualització.
- Prova amb el CMP carregat tard, per assegurar-te que el codi dins del frame ho reintenta o espera en lloc de rendir-se de seguida.
Punts clau
- Els frames d'origen creuat arriben al CMP mitjançant els frames __tcfapiLocator i __gppLocator.
- Les crides i les respostes fan servir postMessage amb __tcfapiCall/__tcfapiReturn o els equivalents de GPP, aparellats per callId.
- Mantén registrats els callbacks dels listeners perquè arribin els canvis de consentiment posteriors.
- Valida cada missatge i evita tractar-lo com a entrada de confiança.
- On els frames estiguin totalment aïllats, transmet el consentiment explícitament a la sol·licitud d'anunci.