FencedFrameConfig — Schnittstelle · JavaScript-Referenz

Signatur

interface FencedFrameConfig

Beschreibung

FencedFrameConfig gehört zur Fenced Frame API aus der Privacy Sandbox. Ein Objekt dieses Typs legt fest, welcher Inhalt in einem <fencedframe>-Element angezeigt wird. Anders als bei einem <iframe> mit einer src-URL ist die Konfiguration undurchsichtig (opak): Die einbettende Seite erfährt weder die Ziel-URL noch andere Details. So lässt sich zum Beispiel eine Werbeanzeige nach einer Auktion ausliefern, ohne dass Daten über den Nutzer zwischen den Websites weitergegeben werden.

Normalerweise erzeugt man FencedFrameConfig-Objekte nicht selbst. Man bekommt sie von APIs, die die Privatsphäre schützen, sofern dort die Option resolveToConfig: true gesetzt ist:

navigator.runAdAuction() aus der Protected Audience API: liefert die Gewinner-Anzeige einer Auktion auf dem Gerät.
window.sharedStorage.selectURL() aus der Shared Storage API: wählt anhand gespeicherter Daten eine URL aus, etwa für A/B-Tests.

Das Objekt weist man anschließend der Eigenschaft HTMLFencedFrameElement.config zu. Daraufhin navigiert der Browser den Fenced Frame zum hinterlegten Ziel. Mit der Instanzmethode setSharedStorageContext() kann die einbettende Seite außerdem eine Zeichenkette mitgeben. Diese ist im Fenced Frame nur in Shared-Storage-Worklets lesbar, also dort, wo keine Daten nach außen gelangen können.

Die Schnittstelle ist experimentell und nur in Chromium-basierten Browsern verfügbar. Für den Produktiveinsatz braucht man eine Feature-Erkennung und eine Ausweichlösung.

Parameter

Name	Typ	Default	Beschreibung
$contextString Pflicht	string		Parameter von `FencedFrameConfig.prototype.setSharedStorageContext(contextString)`: eine Zeichenkette mit Kontextdaten, etwa eine Kampagnen- oder Event-ID. Im Fenced Frame ist sie nur in Shared-Storage-Worklets über `sharedStorage.context` lesbar.

Rückgabewert

Typ

FencedFrameConfig

Beschreibung

Undurchsichtiges Konfigurationsobjekt. Man bekommt es als aufgelösten Wert von navigator.runAdAuction() oder sharedStorage.selectURL() mit resolveToConfig: true. setSharedStorageContext() selbst gibt undefined zurück.

Beispiele

Gewinner-Anzeige einer Protected-Audience-Auktion anzeigen

const showAd = async () => {
  const auctionConfig = {
    seller: 'https://ssp.example',
    decisionLogicURL: 'https://ssp.example/decision-logic.js',
    interestGroupBuyers: ['https://dsp.example'],
    resolveToConfig: true // FencedFrameConfig statt URN anfordern
  };

  const config = await navigator.runAdAuction(auctionConfig);

  if (config === null) {
    console.log('Keine Anzeige hat die Auktion gewonnen.');
    return;
  }

  const frame = document.createElement('fencedframe');
  frame.width = 300;
  frame.height = 250;
  frame.config = config; // Navigation starten
  document.querySelector('#ad-slot').append(frame);
  console.log(config instanceof FencedFrameConfig);
};

showAd();

true

A/B-Test mit Shared Storage und selectURL()

const runExperiment = async () => {
  // Das Worklet registriert die Operation 'ab-testing'
  await window.sharedStorage.worklet.addModule('/ab-testing-worklet.js');

  const config = await window.sharedStorage.selectURL(
    'ab-testing',
    [
      { url: 'https://content.example/variante-a.html' },
      { url: 'https://content.example/variante-b.html' }
    ],
    { resolveToConfig: true }
  );

  // Welche Variante gewählt wurde, bleibt für diese Seite verborgen
  document.querySelector('#experiment-frame').config = config;
};

runExperiment();

Kontextdaten mit setSharedStorageContext() übergeben

const config = await navigator.runAdAuction({
  seller: 'https://ssp.example',
  decisionLogicURL: 'https://ssp.example/decision-logic.js',
  interestGroupBuyers: ['https://dsp.example'],
  resolveToConfig: true
});

if (config) {
  // Nur in Shared-Storage-Worklets im Fenced Frame lesbar
  config.setSharedStorageContext('kampagne-2024-herbst');
  document.querySelector('fencedframe').config = config;
}

// Im Worklet innerhalb des Fenced Frames:
// console.log(sharedStorage.context); // 'kampagne-2024-herbst'

Feature-Erkennung mit Ausweichlösung

const supportsFencedFrames =
  'FencedFrameConfig' in window &&
  'HTMLFencedFrameElement' in window;

if (supportsFencedFrames) {
  console.log('Fenced Frames verfügbar');
} else {
  console.log('Keine Fenced Frames, Ausweichlösung wird geladen');
  // z. B. kontextbezogene Anzeige in einem <iframe> ohne Nutzerdaten
}

Fenced Frames verfügbar (in Chromium mit aktivierter Privacy Sandbox)

// Wichtig · Fallstricke

Browser-Unterstützung: Experimentell und nur in Chromium-Browsern verfügbar (ab etwa Chrome 115). Die Privacy-Sandbox-APIs müssen aktiviert sein, und die Website braucht teils eine Anmeldung (Enrollment). Firefox und Safari unterstützen die API nicht. Deshalb immer eine Feature-Erkennung verwenden.
Undurchsichtig: Werte wie URL, Breite und Höhe sind intern gespeichert und lassen sich nicht auslesen. Das ist so gewollt. Wer versucht, die Ziel-URL zu ermitteln, bekommt nichts.
Nicht selbst erzeugen: Das Objekt kommt normalerweise nur aus runAdAuction() oder selectURL() mit resolveToConfig: true. Ohne diese Option liefern die APIs stattdessen eine urn:uuid:-URN, die für <iframe> gedacht ist. Ein öffentlicher Konstruktor new FencedFrameConfig(url) ist nur in manchen Entwurfs- und Browserversionen vorhanden und bietet dann nicht denselben Datenschutz.
Kommunikation eingeschränkt: Zwischen Fenced Frame und einbettender Seite gibt es kein postMessage. setSharedStorageContext() ist der einzige vorgesehene Weg, Kontextdaten in den Frame zu geben, und sie sind nur in Shared-Storage-Worklets lesbar.
Sicherheit: Inhalte in einem Fenced Frame müssen den Response-Header Supports-Loading-Mode: fenced-frame senden, sonst werden sie nicht geladen. Eine CSP-Direktive fenced-frame-src regelt, welche Quellen erlaubt sind.

Siehe auch

NDEFRecord SanitizerConfig WebGLFramebuffer CSSKeyframeRule CSSKeyframesRule