FencedFrameConfig

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

FencedFrameConfig 介面表示 <fencedframe> 的導航，即將在其中顯示的內容。

FencedFrameConfig 物件無法透過 JavaScript 手動構造。它們是從 Protected Audience API 等源返回的，並設定為 HTMLFencedFrameElement.config 的值。

FencedFrameConfig 物件例項有一個公開的方法，但它也對映到包含無法從 JavaScript 訪問的不透明屬性的內部配置資訊。這包括載入內容源和用於廣告目的的興趣組等資訊。這是 fenced frames 如何在尊重使用者隱私的同時幫助實現關鍵用例的關鍵。

例項方法

setSharedStorageContext() 實驗性: 將嵌入文件中的資料傳遞到 <fencedframe> 的共享儲存中。

示例

基本用法

要設定 <fencedframe> 中顯示的內容，一個利用的 API（例如 Protected Audience 或 Shared Storage）會生成一個 FencedFrameConfig 物件，然後將其設定為 <fencedframe> 的 config 屬性的值。

以下示例從 Protected Audience API 的廣告競價中獲取一個 FencedFrameConfig，然後用於在 <fencedframe> 中顯示中標廣告

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()` 傳遞上下文資料

您可以使用 Private Aggregation API 來建立報告，這些報告將隱私沙盒（fenced frame）內的事件級資料與嵌入文件的上下文資料相結合。setSharedStorageContext() 可用於將來自嵌入程式的上下文資料傳遞給由 Protected Audience API 啟動的共享儲存工作組。

在以下示例中，我們將來自嵌入頁面和 fenced frame 的資料儲存在共享儲存中。

在嵌入頁面中，我們將使用 setSharedStorageContext() 將模擬的事件 ID 設定為共享儲存上下文。

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;

在 fenced frame 內部，我們使用 window.sharedStorage.worklet.addModule() 新增 worklet 模組，然後使用 window.sharedStorage.run() 將事件級別資料傳送到共享儲存 worklet（這與來自嵌入文件的上下文資料無關）。

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 worklet 中，我們從 sharedStorage.context 讀取嵌入文件的事件 ID，並從資料物件中讀取 frame 的事件級別資料，然後透過 Private Aggregation 進行報告。

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);