El consentimiento dentro de iframes cross-origin: el patrón __tcfapiLocator y __gppLocator
El problema: el consentimiento vive en la ventana superior
Un CMP se ejecuta en tu página, en la ventana de nivel superior. Gran parte de tu publicidad, no. Los creativos display, el rich media, los renderizadores de header bidding y muchos widgets de terceros se ejecutan dentro de iframes, a menudo en un origen distinto. El código de un iframe cross-origin no puede llamar directamente a una función de la página padre, así que no puede simplemente llamar a __tcfapi o __gpp y leer la elección del visitante.
Los marcos del IAB resuelven esto con una convención de mensajería pequeña y bien definida. Si creas productos publicitarios, embeds o scripts de medición que se ejecutan en frames, o si depuras stacks publicitarios que lo hacen, merece la pena saber exactamente cómo funciona.
El frame locator
Además de la API de JavaScript, un CMP de TCF añade a la página de nivel superior un iframe vacío e invisible llamado __tcfapiLocator. Un CMP de GPP hace lo mismo con un frame llamado __gppLocator. Los frames no llevan contenido. Su única función es poder encontrarse: cualquier script de cualquier frame anidado puede subir por la jerarquía de ventanas y comprobar en cada nivel si existe un frame con ese nombre.
Como los nombres de los frames son visibles entre orígenes a través de window.frames, un script dentro de un iframe cross-origin profundamente anidado puede localizar la ventana que aloja el CMP sin tener acceso a nada más de esa página.
Cómo encuentra el CMP un script enmarcado
- Empieza con la ventana actual. Si __tcfapi existe localmente, úsalo directamente — el script no está en un frame, o el frame comparte el CMP.
- Si no, recorre hacia arriba en bucle: comprueba si la ventana actual contiene un frame llamado __tcfapiLocator; si no, pasa a window.parent y vuelve a comprobar, deteniéndote en la ventana superior.
- Cuando se encuentra el locator, la ventana que lo contiene es la ventana del CMP. La comunicación se realiza ahora mediante postMessage.
Envuelve cada acceso en un try/catch, porque algunos navegadores o ajustes de sandbox lanzan una excepción en el acceso cross-origin a propiedades, y detén el bucle cuando window.parent sea igual a la ventana actual.
El formato de los mensajes
Para TCF, el script enmarcado envía a la ventana del CMP un mensaje que contiene un objeto con una propiedad __tcfapiCall. Dentro hay cuatro campos:
- command — por ejemplo getTCData, ping o addEventListener;
- parameter — cualquier argumento que necesite el comando, o null;
- version — la versión de la API, 2 para TCF v2;
- callId — un valor único generado por quien llama.
El CMP escucha estos mensajes, ejecuta el comando y devuelve un objeto con una propiedad __tcfapiReturn que contiene returnValue, success y el mismo callId. Quien llama mantiene un mapa de callbacks pendientes indexado por callId, escucha los eventos message y despacha cada respuesta al callback correcto. GPP sigue el mismo patrón con __gppCall y __gppReturn.
Muchas integraciones escriben un pequeño proxy: una función local llamada __tcfapi dentro del frame que traduce las llamadas en mensajes. El código escrito para la ventana superior funciona entonces sin cambios dentro del frame.
Listeners de eventos entre frames
Una llamada addEventListener enviada por postMessage no es una solicitud puntual. El CMP enviará un mensaje de respuesta cada vez que cambie el estado del consentimiento, todos con el mismo callId. Por tanto, tu dispatcher debe mantener ese callback registrado en lugar de eliminarlo tras la primera respuesta. Olvidarlo es un error clásico: el script enmarcado lee el consentimiento una vez y nunca se entera de una retirada posterior.
Consideraciones de seguridad
- Valida la forma del mensaje. Ignora cualquier mensaje que no contenga la propiedad esperada y analiza con cautela las cargas de tipo cadena, ya que algunas implementaciones envían cadenas JSON en lugar de objetos.
- No confíes a ciegas. Cualquier página puede enviar mensajes a tu frame. Trata las respuestas como señales de consentimiento que hay que respetar, no como datos autenticados, y nunca dejes que desencadenen acciones privilegiadas.
- Usa orígenes de destino específicos cuando puedas. Cuando se conoce el origen del CMP, envía el mensaje a ese origen en lugar de a todos.
Dónde no llega el patrón
Algunos entornos publicitarios aíslan los creativos de forma más estricta. Los contenedores SafeFrame, los iframes en sandbox sin los permisos adecuados y los creativos renderizados en documentos separados pueden no poder recorrer el árbol de frames ni recibir mensajes. En esos casos, la señal de consentimiento normalmente debe pasarse de forma explícita, por ejemplo como parámetros de la solicitud de anuncio o como valores que el ad server entrega al creativo, como los parámetros gdpr y gdpr_consent que admiten muchas etiquetas publicitarias.
Checklist de depuración
- En las DevTools de la ventana superior, confirma que los frames locator existen en el panel Elements.
- Cambia el contexto de la consola al iframe y comprueba si el locator es accesible desde allí.
- Registra los eventos message entrantes en ambas ventanas para confirmar que fluyen llamadas y respuestas.
- Cambia el consentimiento en el banner y verifica que los listeners enmarcados reciben una actualización.
- Prueba con el CMP cargado tarde, para asegurarte de que el código enmarcado reintenta o espera en lugar de rendirse de inmediato.
Conclusiones clave
- Los frames cross-origin llegan al CMP a través de los frames __tcfapiLocator y __gppLocator.
- Las llamadas y respuestas usan postMessage con __tcfapiCall/__tcfapiReturn o los equivalentes de GPP, emparejados por callId.
- Mantén registrados los callbacks de los listeners para que lleguen los cambios de consentimiento posteriores.
- Valida cada mensaje y evita tratarlo como entrada de confianza.
- Donde los frames están totalmente aislados, pasa el consentimiento de forma explícita en la solicitud de anuncio.