FencedFrameConfig

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

FencedFrameConfig 接口表示 <fencedframe> 的导航，即在其中显示什么内容。

FencedFrameConfig 对象不能通过 JavaScript 手动构造。 它们是从诸如 受保护的受众 API 等来源返回的，并设置为 HTMLFencedFrameElement.config 的值。

FencedFrameConfig 对象实例有一个公开方法，但它也映射到包含不可从 JavaScript 访问的不透明属性的内部配置信息。 这包括诸如加载内容的来源和用于广告目的的兴趣组等信息。 它是围栏框架如何帮助实现关键用例同时尊重用户隐私的关键。

实例方法

setSharedStorageContext()

将来自嵌入文档的数据传递到 <fencedframe> 的共享存储中。

示例

基本用法

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

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

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

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

注意： 必须将 resolveToConfig: true 传递给 runAdAuction() 调用才能获得 FencedFrameConfig 对象。 如果未设置，结果 Promise 将解析为一个 URN，该 URN 只能在 <iframe> 中使用。

通过 setSharedStorageContext() 传递上下文数据

您可以使用 私有聚合 API 创建报告，将围栏框架内的事件级数据与嵌入文档中的上下文数据相结合。 setSharedStorageContext() 可用于将上下文数据从嵌入者传递到由 受保护的受众 API 启动的共享存储工作程序。

在以下示例中，我们将来自嵌入页面和围栏框架的数据存储在 共享存储 中。

在嵌入页面中，我们将使用 setSharedStorageContext() 将模拟事件 ID 设置为共享存储上下文。

js
const frameConfig = await navigator.runAdAuction({ resolveToConfig: true });

// Data from the embedder that you want to pass to the shared storage worklet
frameConfig.setSharedStorageContext("some-event-id");

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

在围栏框架内部，我们使用 window.sharedStorage.worklet.addModule() 添加工作程序模块，然后使用 window.sharedStorage.run() 将事件级数据发送到共享存储工作程序（这与来自嵌入文档的上下文数据无关）。

js
const frameData = {
  // Data available only inside the fenced frame
};

await window.sharedStorage.worklet.addModule("reporting-worklet.js");

await window.sharedStorage.run("send-report", {
  data: {
    frameData,
  },
});

在 reporting-worklet.js 工作程序中，我们从 sharedStorage.context 读取嵌入文档的事件 ID，从数据对象读取框架的事件级数据，然后通过 私有聚合 报告它们。

js
class ReportingOperation {
  convertEventIdToBucket(eventId) { ... }
  convertEventPayloadToValue(info) { ... }

  async run(data) {
    // Data from the embedder
    const eventId = sharedStorage.context;

    // Data from the fenced frame
    const eventPayload = data.frameData;

    privateAggregation.sendHistogramReport({
      bucket: convertEventIdToBucket(eventId),
      value: convertEventPayloadToValue(eventPayload)
    });
  }
}

register('send-report', ReportingOperation);

规范

规范
Fenced Frame
# fenced-frame-config-interface

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅