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, bevor Sie diese produktiv verwenden.

Die FencedFrameConfig-Schnittstelle repräsentiert die Navigation eines <fencedframe>, d.h. welchen Inhalt es anzeigen wird.

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 der HTMLFencedFrameElement.config gesetzt.

Eine Instanz eines FencedFrameConfig-Objekts hat eine zugängliche Methode, sie entspricht jedoch auch internen Konfigurationsinformationen, die undurchsichtige Eigenschaften enthalten, die nicht von JavaScript aus zugänglich sind. Dies schließt Informationen wie die Quelle des geladenen Inhalts und Interessengruppen für Werbezwecke ein. Dies ist der Schlüssel, wie fenced frames helfen, wichtige Anwendungsfälle zu implementieren und gleichzeitig die Privatsphäre der Benutzer zu respektieren.

Instanzmethoden

setSharedStorageContext() Experimentell

Überträgt Daten aus dem einbettenden Dokument in den <fencedframe>-Gemeinsamen Speicher.

Beispiele

Grundlegende Verwendung

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

Das folgende Beispiel erhält ein FencedFrameConfig aus einer Anzeigenauktion der Protected Audience API, das dann verwendet wird, um die gewonnene Anzeige in einem <fencedframe> anzuzeigen:

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

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

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

Kontextuelle Daten über setSharedStorageContext() übergeben

Sie können die Private Aggregation API verwenden, um Berichte zu erstellen, die Ereignisebenen-Daten innerhalb von fenced frames mit kontextuellen Daten aus dem einbettenden Dokument kombinieren. setSharedStorageContext() kann verwendet werden, um kontextuelle Daten vom Einbettungsprogramm an gemeinsam genutzte Speicher-Worklets zu übergeben, die von der Protected Audience API initiiert werden.

Im folgenden Beispiel speichern wir Daten sowohl von der Einbettungsseite als auch vom fenced frame im Gemeinsamen Speicher.

Auf der Einbettungsseite setzen wir eine simulierte Ereignis-ID als Kontext des gemeinsamen Speichers mit setSharedStorageContext():

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 dann die Ereignissebenen-Daten in das gemeinsame Speicher-Worklet mit window.sharedStorage.run() (dies ist nicht verwandt mit den kontextuellen Daten 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 aus sharedStorage.context und die ereignisbezogenen Daten 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

BCD tables only load in the browser

Siehe auch