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

  1. Empieza con la ventana actual. Si __tcfapi existe localmente, úsalo directamente — el script no está en un frame, o el frame comparte el CMP.
  2. 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.
  3. 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:

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

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

Conclusiones clave

← Blog Leer todo →