Consentimento dentro de iframes de orixe cruzada: o patrón __tcfapiLocator e __gppLocator
O problema: o consentimento vive na xanela superior
Un CMP execútase na túa páxina, na xanela de nivel superior. Gran parte da túa publicidade non. Os creativos display, o rich media, os renderizadores de header bidding e moitos widgets de terceiros execútanse dentro de iframes, a miúdo doutra orixe. O código dun iframe de orixe cruzada non pode chamar directamente unha función da páxina pai, así que non pode chamar sen máis a __tcfapi ou __gpp e ler a elección do visitante.
Os marcos de IAB resólvenno cunha convención de mensaxaría pequena e ben definida. Se creas produtos publicitarios, incrustacións ou scripts de medición que se executan en frames, ou se depuras pilas publicitarias que o fan, vale a pena saber exactamente como funciona.
O frame locator
Xunto coa API JavaScript, un CMP de TCF engade á páxina de nivel superior un iframe baleiro e invisible chamado __tcfapiLocator. Un CMP de GPP fai o mesmo cun frame chamado __gppLocator. Os frames non levan contido. A súa única tarefa é ser localizables: calquera script de calquera frame aniñado pode subir pola xerarquía de xanelas e comprobar se en cada nivel hai un frame con ese nome.
Como os nomes dos frames son visibles entre orixes mediante window.frames, un script dun iframe de orixe cruzada aniñado en profundidade pode localizar a xanela que aloxa o CMP sen ter acceso a nada máis daquela páxina.
Como atopa o CMP un script dentro dun frame
- Comeza coa xanela actual. Se __tcfapi existe localmente, úsao directamente — o script non está nun frame, ou o frame comparte o CMP.
- Se non, sobe en bucle: comproba se a xanela actual contén un frame chamado __tcfapiLocator; se non, pasa a window.parent e comproba de novo, parando na xanela superior.
- Cando se atopa o locator, a xanela que o contén é a xanela do CMP. A comunicación pasa agora por postMessage.
Envolve cada acceso nun try/catch, porque algúns navegadores ou configuracións de sandbox lanzan un erro ao acceder a propiedades de orixe cruzada, e para o bucle cando window.parent sexa igual á xanela actual.
O formato da mensaxe
Para TCF, o script dentro do frame envía unha mensaxe á xanela do CMP cun obxecto que ten unha propiedade __tcfapiCall. Dentro hai catro campos:
- command — por exemplo getTCData, ping ou addEventListener;
- parameter — calquera argumento que necesite a orde, ou null;
- version — a versión da API, 2 para TCF v2;
- callId — un valor único xerado por quen chama.
O CMP escoita estas mensaxes, executa a orde e devolve un obxecto cunha propiedade __tcfapiReturn que contén returnValue, success e o mesmo callId. Quen chama mantén un mapa de callbacks pendentes indexado por callId, escoita os eventos message e entrega cada resposta ao callback correcto. GPP segue o mesmo patrón con __gppCall e __gppReturn.
Moitas integracións escriben un pequeno proxy: unha función local chamada __tcfapi dentro do frame que traduce as chamadas en mensaxes. Así o código escrito para a xanela superior funciona sen cambios dentro do frame.
Listeners de eventos entre frames
Unha chamada addEventListener enviada por postMessage non é unha solicitude única. O CMP enviará unha mensaxe de retorno cada vez que cambie o estado do consentimento, todas co mesmo callId. O teu distribuidor, polo tanto, debe manter ese callback rexistrado en lugar de eliminalo despois da primeira resposta. Esquecelo é un erro clásico: o script dentro do frame le o consentimento unha vez e nunca se decata dunha retirada posterior.
Consideracións de seguridade
- Valida a forma da mensaxe. Ignora calquera mensaxe que non conteña a propiedade esperada, e analiza con coidado as cargas en forma de cadea, xa que algunhas implementacións envían cadeas JSON en lugar de obxectos.
- Non confíes cegamente. Calquera páxina pode enviar mensaxes ao teu frame. Trata as respostas como sinais de consentimento que hai que respectar, non como datos autenticados, e non deixes nunca que activen accións privilexiadas.
- Usa orixes de destino específicas cando poidas. Cando a orixe do CMP é coñecida, envíalle a mensaxe a ela e non a todas as orixes.
Onde non chega o patrón
Algúns contornos publicitarios illan os creativos de maneira máis estrita. Os contedores SafeFrame, os iframes en sandbox sen os permisos adecuados e os creativos renderizados en documentos separados poden non poder percorrer a árbore de frames nin recibir mensaxes. Nestes casos, o sinal de consentimento normalmente ten que transmitirse explicitamente, por exemplo como parámetros da solicitude de anuncio ou como valores que o servidor de anuncios lle entrega ao creativo, como os parámetros gdpr e gdpr_consent que admiten moitas etiquetas de anuncios.
Lista de verificación de depuración
- Nas DevTools da xanela superior, confirma que os frames locator existen no panel Elements.
- Cambia o contexto da consola ao iframe e comproba se o locator é accesible desde alí.
- Rexistra os eventos message entrantes nas dúas xanelas para confirmar que as chamadas e as respostas flúen.
- Cambia o consentimento no banner e verifica que os listeners dentro dos frames reciban unha actualización.
- Proba co CMP cargado tarde, para asegurarte de que o código dentro do frame o reintenta ou agarda en lugar de rendirse de inmediato.
Puntos clave
- Os frames de orixe cruzada acceden ao CMP mediante os frames __tcfapiLocator e __gppLocator.
- As chamadas e as respostas usan postMessage con __tcfapiCall/__tcfapiReturn ou os equivalentes de GPP, emparellados por callId.
- Mantén rexistrados os callbacks dos listeners para que cheguen os cambios de consentimento posteriores.
- Valida cada mensaxe e evita tratala como entrada de confianza.
- Onde os frames estean totalmente illados, transmite o consentimento explicitamente na solicitude de anuncio.