围栏框架 API

实验性： 这是一个实验性技术
在生产环境中使用此功能之前，请仔细查看浏览器兼容性表。

围栏框架 API 提供了用于控制嵌入在 <fencedframe> 元素中的内容的功能。

概念和用法

Web 上隐私和安全问题的一个主要来源是嵌入在 <iframe> 元素中的内容。从历史上看，<iframe> 已被用于设置第三方 Cookie，这些 Cookie 可用于跨站点共享信息和跟踪用户。此外，嵌入在 <iframe> 中的内容可以与其嵌入文档通信（例如，使用 Window.postMessage()）。

嵌入文档还可以使用脚本读取 <iframe> 中的各种形式的信息——例如，您可以从读取 src 属性中的嵌入 URL 获取重要的跟踪/指纹数据，尤其是在它包含 URL 参数的情况下。<iframe> 还可以访问嵌入上下文的 DOM，反之亦然。

大多数现代浏览器正在开发分区存储的机制，以便 Cookie 数据不再可用于跟踪（例如，请参阅具有独立分区状态的 Cookie (CHIPS) 或 Firefox 状态分区）。

<fencedframe> 元素旨在解决此难题的另一部分——它们在形式和功能上与 <iframe> 非常相似，但不同之处在于

<fencedframe> 内容与其嵌入站点之间无法共享通信。
<fencedframe> 可以访问跨站点数据，但仅限于一组非常具体的受控情况下，以保护用户隐私。
<fencedframe> 不能被随意操作或通过常规脚本访问其数据（例如读取或设置源 URL）。<fencedframe> 内容只能通过特定 API 嵌入。
<fencedframe> 无法访问嵌入上下文的 DOM，嵌入上下文也无法访问 <fencedframe> 的 DOM。

有关围栏框架通信模型的更多信息，请阅读与嵌入式框架通信指南。

用例

<fencedframe> 由其他 API 用于嵌入不同类型的跨站点内容或收集数据，以隐私保护的方式满足不同的用例。以前大多数这些用例都依赖于第三方 Cookie 或其他不利于隐私的机制。

共享存储 API 提供了在安全环境中访问未分区跨站点数据的功能，并在 <fencedframe> 中计算和/或显示结果。例如
- 广告商可以衡量广告的覆盖范围，或根据用户在其他网站上已查看的广告投放后续广告。
- 开发人员可以进行 A/B 测试，根据用户所属的组或每个组已有多少用户查看过，向用户显示不同的变体。
- 企业可以根据用户在其他网站上看到的内容自定义用户的体验。例如，如果他们已经购买了会员资格，您可能不希望在您的其他属性上向他们显示会员注册广告。
受保护受众 API 允许开发人员实现基于兴趣组的广告，即再营销和自定义受众用例。它可以评估多个广告位的出价，并在 <fencedframe> 中显示中标广告。
私有聚合 API 可以从 <fencedframe>（源自共享存储或受保护受众 API）收集数据并创建聚合报告。

`<fencedframe>` 如何工作？

如上所述，您无法通过常规脚本直接控制嵌入在 <fencedframe> 中的内容。

要设置将在 <fencedframe> 中显示的内容，利用 API（例如受保护受众或共享存储）会生成一个 FencedFrameConfig 对象，然后通过 JavaScript 将其设置为 <fencedframe> 的 HTMLFencedFrameElement.config 属性的值。

以下示例从受保护受众 API 的广告拍卖中获取 FencedFrameConfig，然后将其用于在 <fencedframe> 中显示中标广告

const frameConfig = await navigator.runAdAuction({
  // ...auction configuration
  resolveToConfig: true,
});

const frame = document.createElement("fencedframe");
frame.config = frameConfig;

必须将 resolveToConfig: true 传递给 runAdAuction() 调用以获取 FencedFrameConfig 对象。如果 resolveToConfig 设置为 false，则生成的 Promise 将解析为不透明的 URN（例如 urn:uuid:c36973b5-e5d9-de59-e4c4-364f137b3c7a），只能在 <iframe> 中使用。

无论哪种方式，浏览器都会存储一个包含要嵌入内容的目标位置的 URL——映射到不透明的 URN 或 FencedFrameConfig 的内部 url 属性。嵌入上下文中运行的 JavaScript 无法读取 URL 值。

注意：在 <iframe> 中提供了对不透明 URN 的支持，以方便将现有实现迁移到隐私沙盒 API。此支持旨在临时使用，并且随着采用率的提高将在未来删除。

注意：FencedFrameConfig 具有一个 setSharedStorageContext() 方法，用于将数据从嵌入文档传递到 <fencedframe> 的共享存储。例如，它可以在 Worklet 中通过 <fencedframe> 访问，并用于生成报告。有关更多详细信息，请参阅共享存储 API。

Sec-Fetch-Dest: fencedframe

对于任何打算加载到 <fencedframe> 或嵌入在 <fencedframe> 中的 <iframe> 中的文档，服务器必须设置值为 fenced-frame 的 Supports-Loading-Mode 响应标头。

http

Supports-Loading-Mode: fenced-frame

围栏框架对 HTTP 标头的其他影响如下

用户代理客户端提示在围栏框架内部不可用，因为它们依赖于权限策略代理，这可能被用来泄露数据。
在从围栏框架内部打开的新浏览上下文中强制执行严格的 Cross-Origin-Opener-Policy 设置，否则它们可能被用来将信息泄露到其他来源。从围栏框架内部打开的任何新窗口都将设置 rel="noopener" 和 Cross-Origin-Opener-Policy: same-origin，以确保 Window.opener 返回 null 并将其置于其自己的浏览上下文组中。
Content-Security-Policy: fenced-frame-src 已添加用于指定加载到 <fencedframe> 元素中的嵌套浏览上下文的有效来源。
Content-Security-Policy: sandbox 自定义设置不能被围栏框架继承，以减轻隐私问题。要加载围栏框架，您需要指定没有 sandbox CSP（这意味着以下值），或指定以下沙盒值
- allow-same-origin
- allow-forms
- allow-scripts
- allow-popups
- allow-popups-to-escape-sandbox
- allow-top-navigation-by-user-activation

`beforeunload` 和 `unload` 事件

beforeunload 和 unload 事件不会在围栏框架上触发，因为它们可能会以页面删除时间戳的形式泄露信息。实现旨在消除尽可能多的潜在泄漏。

接口

FencedFrameConfig

表示 <fencedframe> 的导航，即将在其中显示的内容。FencedFrameConfig 来自某个来源（例如受保护受众 API）并设置为 HTMLFencedFrameElement.config 的值。

Fence

包含多个与隔离框架功能相关的函数。仅适用于嵌入在<fencedframe>中的文档。

HTMLFencedFrameElement

在 JavaScript 中表示一个<fencedframe>元素，并提供用于配置它的属性。

其他接口的扩展

Navigator.deprecatedReplaceInURN(): 替换给定不透明 URN 或FencedFrameConfig的内部url属性对应映射 URL 中的指定字符串。
Window.fence: 返回当前文档上下文的Fence对象实例。仅适用于嵌入在<fencedframe>中的文档。