Fence.setReportEventDataForAutomaticBeacons() — Methode · JavaScript-Referenz

Signatur

Fence.prototype.setReportEventDataForAutomaticBeacons(event)

Beschreibung

setReportEventDataForAutomaticBeacons() gehört zur Fence-Schnittstelle, die in einem <fencedframe> (oder einem per Protected Audience geladenen <iframe>) über window.fence verfügbar ist. Damit hinterlegt die Werbeanzeige Daten, die der Browser automatisch als Beacon (HTTP-POST) verschickt, sobald der Rahmen eine Navigation der obersten Ebene auslöst, typischerweise wenn jemand auf die Anzeige klickt und die Zielseite in einem neuen Tab oder im Hauptfenster geöffnet wird.

Das ist vor allem für die Klickmessung in der Privacy Sandbox (Protected Audience API) gedacht. Ein manueller Aufruf von reportEvent() im Klick-Handler geht verloren, wenn die Seite bereits wegnavigiert. Automatische Beacons verschickt der Browser dagegen zuverlässig, auch wenn der Rahmen danach zerstört wird. Die Ziel-URLs für die reservierten Ereignistypen (z. B. reserved.top_navigation_start) werden vorher im Worklet über registerAdBeacon() in reportWin() bzw. reportResult() registriert.

Die Methode rufst du am besten auf, bevor der Nutzer klickt, etwa beim Laden der Anzeige oder in einem pointerdown-Handler. Die Navigation selbst muss durch eine echte Nutzeraktivierung ausgelöst werden, zum Beispiel über window.open() oder einen Link mit target="_blank"/_top.

Parameter

Name	Typ	Default	Beschreibung
$event Pflicht	Object		Konfigurationsobjekt für den automatischen Beacon mit folgenden Eigenschaften: `eventType` (`string`, Pflicht): reservierter Ereignistyp, `"reserved.top_navigation_start"` (Navigation beginnt) oder `"reserved.top_navigation_commit"` (Navigation abgeschlossen). Das ältere `"reserved.top_navigation"` ist veraltet. `eventData` (`string`, Pflicht): Nutzdaten, die als Body des POST-Beacons gesendet werden (maximal 64 KB). `destination` (`string[]`, Pflicht): Empfänger, möglich sind `"buyer"`, `"seller"`, `"component-seller"`, `"direct-seller"` und `"shared-storage-select-url"`. `once` (`boolean`, optional, Standard `false`): Bei `true` werden die Daten nur für den nächsten Beacon verwendet und danach verworfen. `crossOriginExposed` (`boolean`, optional, Standard `false`): Bei `true` dürfen die Daten auch für Navigationen verwendet werden, die ein ursprungsfremder Unterrahmen der Anzeige auslöst. Voraussetzung ist, dass dieser Unterrahmen mit dem Header `Allow-Cross-Origin-Event-Reporting: true` zustimmt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Daten werden intern gespeichert und beim nächsten passenden Navigationsereignis gesendet.

Beispiele

Klickdaten vor der Navigation hinterlegen

// Code innerhalb der Anzeige (im fencedframe)
const ctaButton = document.querySelector('#cta');

window.fence?.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation_start',
  eventData: JSON.stringify({ adId: 'sommer-2024', creative: 'banner-a' }),
  destination: ['buyer', 'seller']
});

ctaButton.addEventListener('click', () => {
  // Top-Level-Navigation mit Nutzeraktivierung löst den Beacon aus
  window.open('https://shop.example/angebot', '_blank');
});

Daten nur einmalig und für mehrere Phasen senden

const reportClick = (position) => {
  const payload = JSON.stringify({ position, ts: Date.now() });

  // Beim Start der Navigation (nur einmal verwenden)
  window.fence.setReportEventDataForAutomaticBeacons({
    eventType: 'reserved.top_navigation_start',
    eventData: payload,
    destination: ['buyer'],
    once: true
  });

  // Nach erfolgreichem Commit der Navigation
  window.fence.setReportEventDataForAutomaticBeacons({
    eventType: 'reserved.top_navigation_commit',
    eventData: payload,
    destination: ['buyer', 'seller'],
    once: true
  });
};

document.querySelectorAll('a[target="_blank"]').forEach((link, i) => {
  // pointerdown feuert vor click, also vor der Navigation
  link.addEventListener('pointerdown', () => reportClick(i));
});

Beacon-Ziel im Worklet registrieren (Gegenstück)

// Im Protected-Audience-Worklet des Käufers (reportWin)
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  registerAdBeacon({
    'reserved.top_navigation_start': 'https://dsp.example/beacon/nav-start',
    'reserved.top_navigation_commit': 'https://dsp.example/beacon/nav-commit'
  });
}

// Wichtig · Fallstricke

Experimentell und nur in Chromium verfügbar: Firefox und Safari unterstützen die Methode nicht. window.fence gibt es nur innerhalb eines Fenced Frames bzw. eines per Protected Audience geladenen iframes, sonst ist es null. Prüfe den Zugriff deshalb immer mit optionaler Verkettung (window.fence?.…). Google hat die Zukunft mehrerer Privacy-Sandbox-APIs neu bewertet. Prüfe den aktuellen Status, bevor du die Methode produktiv einsetzt.
Ein Beacon wird nur gesendet, wenn für den eventType vorher per registerAdBeacon() eine URL registriert wurde. Andernfalls gehen die Daten stillschweigend verloren.
Die Navigation braucht eine Nutzeraktivierung (Klick, Tastendruck). Programmatische Navigationen ohne Nutzergeste lösen keinen automatischen Beacon aus.
Ein erneuter Aufruf mit demselben eventType überschreibt die vorher gesetzten Daten.
Ungültige Werte für eventType oder destination sowie zu große eventData führen zu einer Ausnahme (z. B. SecurityError oder TypeError).
Datenschutz: eventData darf keine Nutzerkennungen enthalten, die über Kontexte hinweg verknüpfbar sind. Das würde dem Zweck der Fenced Frames widersprechen.

Siehe auch

Fence.reportEvent() Fence.getNestedConfigs() XRFrame.getDepthInformation() CrashReportContext.initialize() Event.preventDefault()