跨源 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

  1. 从当前窗口开始。如果本地存在 __tcfapi,就直接使用它 — 说明脚本不在框架中,或该框架共享 CMP。
  2. 否则,向上循环:检查当前窗口是否包含名为 __tcfapiLocator 的框架;如果没有,就移到 window.parent 再次检查,在顶层窗口处停止。
  3. 找到定位器后,包含它的窗口就是 CMP 的窗口。此后的通信通过 postMessage 进行。

将每次访问包裹在 try/catch 中,因为某些浏览器或沙盒设置在跨源属性访问时会抛出异常,并在 window.parent 等于当前窗口时停止循环。

消息格式

对于 TCF,框架内的脚本向 CMP 窗口发送一条消息,其中包含一个带有 __tcfapiCall 属性的对象。其内部有四个字段:

CMP 监听这些消息,运行命令,并回传一个带有 __tcfapiReturn 属性的对象,其中包含 returnValue、success 以及相同的 callId。调用方维护一个以 callId 为键的待处理回调映射,监听 message 事件,并将每个返回分派给正确的回调。GPP 使用 __gppCall 和 __gppReturn,遵循同样的模式。

许多集成会编写一个小型代理:在框架内定义一个名为 __tcfapi 的本地函数,把调用转换为消息。这样,为顶层窗口编写的代码无需修改即可在框架内工作。

跨框架的事件监听器

通过 postMessage 发送的 addEventListener 调用不是一次性请求。每当同意状态发生变化,CMP 都会回传一条消息,且全部带有相同的 callId。因此,你的分派器必须保持该回调处于注册状态,而不是在第一次响应后就删除它。忘记这一点是一个经典缺陷:框架内的脚本只读取一次同意,永远不会注意到之后的撤回。

安全考量

该模式无法触及之处

某些广告环境会更严格地隔离创意。SafeFrame 容器、没有适当权限的沙盒 iframe,以及在独立文档中渲染的创意,可能无法遍历框架树或接收消息。在这些情况下,同意信号通常必须被明确传入,例如作为广告请求的参数,或由广告服务器交给创意的值,如许多广告标签支持的 gdpr 和 gdpr_consent 参数。

调试核对清单

核心要点

← 博客 阅读全部 →