跨源 iframe 中的同意:__tcfapiLocator 与 __gppLocator 模式
问题:同意存在于顶层窗口
CMP 运行在你的页面上,即顶层窗口中。而你的大部分广告则不是。展示创意、富媒体、header bidding 渲染器以及许多第三方小部件都运行在 iframe 内,且通常处于不同的源。跨源 iframe 中的代码不能直接调用父页面上的函数,因此它无法简单地调用 __tcfapi 或 __gpp 来读取访客的选择。
IAB 框架通过一个小而定义明确的消息传递约定解决了这个问题。如果你构建在框架中运行的广告产品、嵌入内容或衡量脚本,或者调试这样的广告技术栈,了解它究竟如何工作是值得的。
定位器框架
除了 JavaScript API 之外,TCF CMP 还会向顶层页面添加一个名为 __tcfapiLocator 的空的、不可见的 iframe。GPP CMP 对名为 __gppLocator 的框架做同样的事。这些框架不承载任何内容。它们唯一的任务就是可被找到:任何嵌套框架中的任何脚本都可以沿窗口层级向上走,并检查每一层是否存在具有该名称的框架。
由于框架名称可通过 window.frames 跨源可见,深层嵌套的跨源 iframe 中的脚本可以定位承载 CMP 的窗口,而无需访问该页面上的任何其他内容。
框架内的脚本如何找到 CMP
- 从当前窗口开始。如果本地存在 __tcfapi,就直接使用它 — 说明脚本不在框架中,或该框架共享 CMP。
- 否则,向上循环:检查当前窗口是否包含名为 __tcfapiLocator 的框架;如果没有,就移到 window.parent 再次检查,在顶层窗口处停止。
- 找到定位器后,包含它的窗口就是 CMP 的窗口。此后的通信通过 postMessage 进行。
将每次访问包裹在 try/catch 中,因为某些浏览器或沙盒设置在跨源属性访问时会抛出异常,并在 window.parent 等于当前窗口时停止循环。
消息格式
对于 TCF,框架内的脚本向 CMP 窗口发送一条消息,其中包含一个带有 __tcfapiCall 属性的对象。其内部有四个字段:
- command — 例如 getTCData、ping 或 addEventListener;
- parameter — 命令所需的任何参数,或 null;
- version — API 版本,TCF v2 为 2;
- callId — 由调用方生成的唯一值。
CMP 监听这些消息,运行命令,并回传一个带有 __tcfapiReturn 属性的对象,其中包含 returnValue、success 以及相同的 callId。调用方维护一个以 callId 为键的待处理回调映射,监听 message 事件,并将每个返回分派给正确的回调。GPP 使用 __gppCall 和 __gppReturn,遵循同样的模式。
许多集成会编写一个小型代理:在框架内定义一个名为 __tcfapi 的本地函数,把调用转换为消息。这样,为顶层窗口编写的代码无需修改即可在框架内工作。
跨框架的事件监听器
通过 postMessage 发送的 addEventListener 调用不是一次性请求。每当同意状态发生变化,CMP 都会回传一条消息,且全部带有相同的 callId。因此,你的分派器必须保持该回调处于注册状态,而不是在第一次响应后就删除它。忘记这一点是一个经典缺陷:框架内的脚本只读取一次同意,永远不会注意到之后的撤回。
安全考量
- 验证消息结构。忽略任何不包含预期属性的消息,并谨慎解析字符串形式的负载,因为某些实现发送的是 JSON 字符串而不是对象。
- 不要盲目信任。任何页面都可以向你的框架发送消息。把响应视为需要尊重的同意信号,而不是经过认证的数据,并且绝不要让它们触发特权操作。
- 尽可能使用特定的目标源。当 CMP 的源已知时,向它发送,而不是向所有源发送。
该模式无法触及之处
某些广告环境会更严格地隔离创意。SafeFrame 容器、没有适当权限的沙盒 iframe,以及在独立文档中渲染的创意,可能无法遍历框架树或接收消息。在这些情况下,同意信号通常必须被明确传入,例如作为广告请求的参数,或由广告服务器交给创意的值,如许多广告标签支持的 gdpr 和 gdpr_consent 参数。
调试核对清单
- 在顶层窗口的 DevTools 中,确认定位器框架存在于 Elements 面板中。
- 将控制台上下文切换到该 iframe,检查从那里是否可以到达定位器。
- 在两个窗口中记录传入的 message 事件,确认调用和返回都在流动。
- 在横幅中更改同意,并验证框架内的监听器收到了更新。
- 在 CMP 延迟加载的情况下测试,确保框架内的代码会重试或等待,而不是立即放弃。
核心要点
- 跨源框架通过 __tcfapiLocator 和 __gppLocator 框架访问 CMP。
- 调用与返回使用 postMessage,搭配 __tcfapiCall/__tcfapiReturn 或 GPP 的对应项,并通过 callId 匹配。
- 保持监听器回调处于注册状态,以便接收之后的同意变更。
- 验证每一条消息,避免把它当作可信输入。
- 在框架被完全隔离的地方,通过广告请求显式传递同意。