FencedFrameConfig

Limited availability

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

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

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

FencedFrameConfig-Objekte können nicht manuell über JavaScript erstellt 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 exponierte Methode, sie entspricht jedoch auch internen Konfigurationsinformationen, die undurchsichtige Eigenschaften enthalten, die von JavaScript nicht zugänglich sind. Dazu gehören Informationen wie die Quelle des geladenen Inhalts und Interessengruppen für Werbezwecke. Sie ist entscheidend dafür, wie fenced frames helfen, wichtige Anwendungsfälle zu verwirklichen und gleichzeitig die Privatsphäre der Benutzer zu respektieren.

Instanzmethoden

setSharedStorageContext()

Überträgt Daten aus dem einbettenden Dokument in den <fencedframe>'s gemeinsamen Speicher.

Beispiele

Grundlegende Nutzung

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 aus einer Anzeigenauktion der Protected Audience API ein FencedFrameConfig abgerufen, das dann verwendet wird, um die gewinnende Anzeige in einem <fencedframe> darzustellen:

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

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

Hinweis: resolveToConfig: true muss im Aufruf von runAdAuction() übergeben werden, um ein FencedFrameConfig-Objekt zu erhalten. Wenn dies nicht festgelegt ist, wird das resultierende Promise auf einen URN aufgelöst, der nur in einem <iframe> verwendet werden kann.

Übergabe von Kontextdaten über setSharedStorageContext()

Sie können die Private Aggregation API verwenden, um Berichte zu erstellen, die Ereignisdaten innerhalb von fenced frames mit Kontextdaten aus dem einbettenden Dokument kombinieren. setSharedStorageContext() kann verwendet werden, um Kontextdaten vom Einbettungsdokument auf gemeinsame Speicher-Worklets weiterzugeben, die von der Protected Audience API initiiert werden.

Im folgenden Beispiel speichern wir Daten sowohl von der einbettenden Seite als auch vom fenced frame im gemeinsamen Speicher.

Auf der einbettenden Seite werden wir eine simulierte Ereignis-ID als gemeinsamen Speicher-Kontext mit setSharedStorageContext() setzen:

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;

Innerhalb des fenced frame fügen wir das Worklet-Modul mit window.sharedStorage.worklet.addModule() hinzu und senden die Ereignisdatenebene mit window.sharedStorage.run() in das gemeinsame Speicher-Worklet (dies steht in keinem Zusammenhang mit den Kontextdaten aus dem einbettenden Dokument):

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

Im reporting-worklet.js Worklet lesen wir die Ereignis-ID des einbettenden Dokuments von sharedStorage.context und die Ereignisdatenebene des Frames aus dem Datenobjekt, und berichten sie dann durch Private Aggregation:

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

Spezifikationen

Specification
Fenced Frame
# fenced-frame-config-interface

Browser-Kompatibilität

Siehe auch