Berichte zu Protected Audience API-Auktionsergebnissen

Anleitung für Verkäufer und Käufer zum Erstellen von Berichten zu Protected Audience API-Auktionen.

Dieser Artikel ist eine technische Referenz zum Generieren von Berichten zu Auktionsgewinnen der Protected Audience API, wie sie in der aktuellen Iteration der experimentellen Protected Audience API verwendet werden.

Im Entwicklerleitfaden finden Sie Informationen zum gesamten Lebenszyklus der Protected Audience API. Eine ausführliche Erläuterung der Berichterstellung auf Ereignisebene (vorübergehend) finden Sie im Explainer zur Protected Audience API.

Sie sind kein Entwickler? Weitere Informationen finden Sie in der Übersicht zur Protected Audience API.

Was wird in der Protected Audience API gemeldet?

Es sind zwei Protected Audience API-Berichte verfügbar:

  • Verkäuferbericht: Der Verkäufer wird über den Gewinner der Anzeigenauktion informiert.
  • Käuferbericht: Nur für erfolgreiche Käufer verfügbar, um zu erfahren, dass sie eine Auktion gewonnen haben.

Langfristig soll der Browser mit den Private Aggregation APIs Auktionsergebnisse für den Verkäufer und die Käufer melden können. Als temporärer Berichtsmechanismus auf Ereignisebene kann der Code, der reportResult() für den Verkäufer und reportWin() für den erfolgreichen Bieter implementiert, die Funktion sendReportTo() aufrufen. Dafür ist ein einzelnes Argument erforderlich: ein String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird. In dieser URL sind Informationen auf Ereignisebene enthalten, die gemeldet werden sollen.

API-Funktionen

Verkäufer: reportResult()

Das vom Verkäufer in decisionLogicUrl bereitgestellte JavaScript (das auch scoreAd() bereitstellt) kann eine reportResult()-Funktion enthalten, um das Auktionsergebnis zu melden.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Die an diese Funktion übergebenen Argumente sind:

auctionConfig

Das Auktionskonfigurationsobjekt, das an navigator.runAdAuction() übergeben wurde.

browserSignals

Ein vom Browser erstelltes Objekt mit Informationen zur Auktion. Beispiel:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

Der Rückgabewert dieser Funktion wird als sellerSignals-Argument für die reportWin()-Funktion des erfolgreichen Bieters verwendet.

Käufer: reportWin()

Das JavaScript des erfolgreichen Bieters (das auch generateBid() bereitgestellt hat) kann eine reportWin()-Funktion enthalten, um das Auktionsergebnis zu melden.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Die an diese Funktion übergebenen Argumente sind:

auctionSignals und perBuyerSignals

Dieselben Werte, die für den erfolgreichen Bieter an generateBid() übergeben wurden.

sellerSignals

Der Rückgabewert von reportResult() bietet dem Verkäufer die Möglichkeit, Informationen an den Käufer weiterzugeben.

browserSignals

Ein vom Browser erstelltes Objekt mit Informationen zur Auktion. Beispiel:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

Temporäre Implementierung der Berichterstellung

In Chrome sind vorübergehend zwei Methoden für Auktionsberichte verfügbar:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Jede dieser Methoden verwendet ein einzelnes Argument: eine URL, die nach Abschluss der Auktion abgerufen werden soll. Sie können sowohl in scoreAd() als auch in generateBid() mit unterschiedlichen URL-Argumenten mehrmals aufgerufen werden.

Chrome sendet nur dann Debug-Berichte zu Verlusten/Gewinnen, wenn eine Auktion abgeschlossen wird. Wenn eine Auktion abgebrochen wird (z. B. aufgrund einer neuen Navigation), werden keine Berichte erstellt.

Diese Methoden sind in Chrome standardmäßig verfügbar, wenn Sie alle APIs für Datenschutz bei Werbung unter chrome://settings/adPrivacy aktivieren. Wenn Sie Chrome mit Befehlszeilen-Flags ausführen, um die Protected Audience API zu aktivieren, müssen Sie die Methoden explizit aktivieren, indem Sie das Flag BiddingAndScoringDebugReportingAPI einfügen. Wenn das Flag nicht aktiviert ist, sind die Methoden weiterhin verfügbar, führen aber zu keiner Aktion.

Alle API-Referenzen für die Protected Audience API

API-Referenzleitfäden sind verfügbar:

In der Erläuterung der Protected Audience API finden Sie auch Details zur Funktionsunterstützung und zu den Einschränkungen.

Nächste Schritte

Wir möchten mit Ihnen ins Gespräch kommen, um eine API zu entwickeln, die für alle funktioniert.

Über die API diskutieren

Wie andere Privacy Sandbox APIs wird auch diese API dokumentiert und öffentlich diskutiert.

Mit der API experimentieren

Sie können Tests zur Protected Audience API durchführen und sich an Diskussionen beteiligen.