Fence.reportEvent() — Methode · JavaScript-Referenz

Signatur

Fence.prototype.reportEvent(event)

Beschreibung

reportEvent() ist eine Methode des Fence-Objekts, das in einem <fencedframe> (oder in einem iframe, der über eine FencedFrameConfig geladen wurde) als window.fence verfügbar ist. Die Werbung im Frame kann damit Ereignisse wie Klicks, Sichtbarkeit oder Videowiedergabe an die Beteiligten einer Protected Audience-Auktion melden, z. B. an Käufer (buyer) oder Verkäufer (seller).

Wohin ein Bericht geht, wird nicht im Frame festgelegt. Die Ziel-URLs werden vorher in den Worklet-Funktionen reportWin() bzw. reportResult() mit registerAdBeacon({ click: 'https://…' }) einem Ereignistyp zugeordnet. reportEvent() gibt nur den Ereignistyp, die Nutzdaten und die Zielgruppen an. Der Browser schlägt die passende URL nach und schickt die Daten dann als POST-Beacon.

Es gibt auch eine zweite Form: Mit destinationURL gibt man eine eigene URL an. Darin werden Makros wie ${PUBLISHER_ID} ersetzt, die vorher mit registerAdMacro() registriert wurden. Diese Variante sendet einen GET-Request ohne Nutzdaten im Request-Body.

Die Methode wird vor allem für Messung und Abrechnung in datenschutzfreundlicher Werbung verwendet. Außerhalb eines Fenced-Frame-Kontexts ist window.fence null, deshalb sollte man vor dem Aufruf immer prüfen, ob das Objekt vorhanden ist.

Parameter

Name	Typ	Default	Beschreibung
$event Pflicht	FenceEvent (Object)		Objekt, das den Bericht beschreibt. Für vorregistrierte Beacons: `eventType` (`string`): Ereignistyp, der mit `registerAdBeacon()` registriert wurde, z. B. `"click"`. `eventData` (`string`): Nutzdaten, die als Request-Body per `POST` gesendet werden. `destination` (`string[]`): Empfänger, möglich sind `"buyer"`, `"seller"`, `"component-seller"`, `"direct-seller"` und `"shared-storage-select-url"`. `once` (`boolean`, optional, Standard `false`): Bei `true` wird der Bericht pro Frame höchstens einmal gesendet. `crossOriginExposed` (`boolean`, optional): Erlaubt den Aufruf aus Cross-Origin-Unterframes innerhalb des Fenced Frames. Alternativ ein Objekt mit `destinationURL` (`string`): eigene HTTPS-URL mit Makros, die per `GET` aufgerufen wird.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Der Beacon wird asynchron im Hintergrund gesendet. Ob er zugestellt wurde, lässt sich im Frame nicht feststellen.

Beispiele

Beacon im Worklet registrieren (Voraussetzung)

// In reportWin() des Käufer-Worklets (buyer.js)
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  registerAdBeacon({
    click: 'https://dsp.example/report/click',
    view: 'https://dsp.example/report/view'
  });
}

// In reportResult() des Verkäufer-Worklets (seller.js)
function reportResult(auctionConfig, browserSignals) {
  registerAdBeacon({
    click: 'https://ssp.example/report/click'
  });
}

Klick aus dem Fenced Frame an Käufer und Verkäufer melden

// Im Werbemittel, das im <fencedframe> läuft
const adButton = document.querySelector('#cta');

adButton.addEventListener('click', () => {
  if (!window.fence) return; // nicht in einem Fenced Frame

  window.fence.reportEvent({
    eventType: 'click',
    eventData: JSON.stringify({ ts: Date.now(), element: 'cta' }),
    destination: ['buyer', 'seller']
  });
});

// POST an https://dsp.example/report/click und https://ssp.example/report/click // Body: {"ts":1718000000000,"element":"cta"}

Sichtbarkeit nur einmal melden (once)

const observer = new IntersectionObserver((entries) => {
  const visible = entries.some((e) => e.intersectionRatio >= 0.5);
  if (visible && window.fence) {
    window.fence.reportEvent({
      eventType: 'view',
      eventData: 'viewable-50',
      destination: ['buyer'],
      once: true // weitere Aufrufe werden ignoriert
    });
    observer.disconnect();
  }
}, { threshold: [0.5] });

observer.observe(document.body);

Eigene Ziel-URL mit Makros

// Vorher im Worklet: registerAdMacro('PUBLISHER_ID', '123a');
window.fence?.reportEvent({
  destinationURL: 'https://adtech.example/impression?pub=${PUBLISHER_ID}'
});

// GET https://adtech.example/impression?pub=123a

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist experimentell und nur in Chromium-Browsern im Rahmen der Privacy Sandbox verfügbar. Firefox und Safari unterstützen sie nicht. Google hat angekündigt, Teile der Privacy Sandbox zurückzufahren. Vor produktivem Einsatz den aktuellen Stand prüfen.
window.fence ist nur in Fenced Frames bzw. in Frames verfügbar, die über eine FencedFrameConfig geladen wurden. Sonst ist es null, deshalb immer mit window.fence?.reportEvent(...) absichern.
Wenn für einen eventType bei einer Zielgruppe kein Beacon registriert wurde, wird für diese Zielgruppe stillschweigend nichts gesendet. Es gibt keinen Fehler.
Die Ziel-URLs müssen HTTPS verwenden und die Bedingungen für Privacy-Sandbox-Registrierung und -Attestierung erfüllen.
eventData ist ein String mit begrenzter Größe. Objekte vorher mit JSON.stringify() umwandeln.
Datenschutz: Nutzdaten dürfen keine Identifikatoren enthalten, mit denen sich Nutzer über Websites hinweg verfolgen lassen. Das würde den Zweck von Protected Audience untergraben.
Für Berichte bei der Navigation der obersten Ebene (reserved.top_navigation_start/_commit) gibt es automatische Beacons. Deren Daten legt man mit Fence.setReportEventDataForAutomaticBeacons() fest.

Siehe auch

Fence.getNestedConfigs() Fence.setReportEventDataForAutomaticBeacons() new ErrorEvent() Event.initEvent() Window.reportError() FileSystemDirectoryHandle.values() new InputEvent()