FencedFrameConfig

Deprecated

To be removed

This feature is pending removal from browsers. Using it now may lead to broken functionality in future updates. Following the announcement that Chrome will maintain its current approach to third-party cookies, Chrome decided to withdraw certain Privacy Sandbox features including the <fencedframe> element and related APIs.

Vollständige Kompatibilität anzeigen
Mehr erfahren

Die FencedFrameConfig-Schnittstelle repräsentiert die Navigation eines <fencedframe>, d.h. welche Inhalte darin angezeigt werden.

FencedFrameConfig-Objekte können nicht manuell über JavaScript konstruiert werden. Sie werden von einer Quelle wie der Protected Audience API zurückgegeben und als Wert von HTMLFencedFrameElement.config gesetzt.

Eine FencedFrameConfig-Objektinstanz hat eine zugängliche Methode, aber sie verweist auch auf interne Konfigurationsinformationen mit undurchsichtigen Eigenschaften, die von JavaScript nicht zugänglich sind. Dazu gehören Informationen wie die Quelle des geladenen Inhalts und Interessengruppen für Werbezwecke. Es ist zentral dafür, wie fenced frames wesentliche Anwendungsfälle umsetzen, während die Privatsphäre der Nutzer respektiert wird.

Instanzmethoden

setSharedStorageContext(): Überträgt Daten aus dem einbettenden Dokument in den <fencedframe>-Shared Storage.

Beispiele

Grundlegende Verwendung

Um festzulegen, welche Inhalte in einem <fencedframe> angezeigt werden, generiert eine nutzende API (wie Protected Audience oder Shared Storage) ein FencedFrameConfig-Objekt, das dann als Wert der config-Eigenschaft des <fencedframe> gesetzt wird.

Im folgenden Beispiel wird ein FencedFrameConfig von einer Ad-Auktion der Protected Audience API abgerufen, das dann verwendet wird, um die gewonnene Anzeige in einem <fencedframe> anzuzeigen:

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

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

Hinweis: resolveToConfig: true muss beim runAdAuction()-Aufruf übergeben werden, um ein FencedFrameConfig-Objekt zu erhalten. Wenn es nicht gesetzt ist, wird das resultierende Promise zu einem URN auflösen, der nur in einem <iframe> verwendet werden kann.

Kontextbezogene Daten mittels `setSharedStorageContext()` übergeben

Sie können die Private Aggregation API verwenden, um Berichte zu erstellen, die Ereignis-Ebene-Daten innerhalb von fenced frames mit kontextbezogenen Daten aus dem einbettenden Dokument kombinieren. setSharedStorageContext() kann verwendet werden, um kontextbezogene Daten vom Einbettenden an die von der Protected Audience API initiierte Shared Storage Worklets zu übergeben.

Im folgenden Beispiel speichern wir Daten sowohl von der einbettenden Seite als auch dem fenced frame in shared storage.

Auf der einbettenden Seite setzen wir eine Beispiel-Ereignis-ID als Shared Storage-Kontext mit setSharedStorageContext():

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;

Innerhalb des fenced frames fügen wir das Worklet-Modul mit window.sharedStorage.worklet.addModule() hinzu und senden dann die Ereignis-Ebene-Daten in das Shared Storage-Worklet mittels window.sharedStorage.run() (dies steht in keinem Zusammenhang mit den kontextbezogenen Daten des einbettenden Dokuments):

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

Im reporting-worklet.js-Worklet lesen wir die Ereignis-ID des einbettenden Dokuments aus sharedStorage.context und die Ereignis-Ebene-Daten des Frames aus dem Datenobjekt, und berichten sie dann durch 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);