FencedFrameConfig

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

实验性: 这是一项实验性技术
在将其用于生产之前，请仔细检查浏览器兼容性表格。

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({
  // 竞价配置
  resolveToConfig: true,
});

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

备注：在调用 runAdAuction() 时，必须传入 resolveToConfig: true 以获得 FencedFrameConfig 对象。如果没有设置，则所得的 Promise 将兑现为一个只能在 <iframe> 中使用的 URN。

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

你可以使用隐私聚合 API 来创建报告，该报告将围栏框架内的事件级数据与嵌入文档的上下文数据相结合。setSharedStorageContext() 可用于将从嵌入方传递的上下文数据传递给由受保护的受众 API 启动的共享存储 worklet。

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

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

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

// 你想要从嵌入方传递给共享存储 worklet 的数据
frameConfig.setSharedStorageContext("some-event-id");

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

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

js
const frameData = {
  // 数据仅在围栏框架内可用
};

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

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

在 reporting-worklet.js worklet 中，我们从 sharedStorage.context 中读取嵌入文档的事件 ID，并从数据对象中读取框架的事件级数据，然后通过隐私聚合进行报告：

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

  async run(data) {
    // 来自于嵌入方的数据
    const eventId = sharedStorage.context;

    // 来自于围栏框架的数据
    const eventPayload = data.frameData;

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

register('send-report', ReportingOperation);

规范

Specification
Fenced Frame
# fenced-frame-config-interface

浏览器兼容性

BCD tables only load in the browser

参见