Berichte zu Protected Audience API-Auktionsergebnissen

Leitfaden für Verkäufer und Käufer zum Generieren von Protected Audience API-Auktionsberichten

Dieser Artikel ist eine technische Referenz zum Erstellen von Berichten für Protected Audience API-Auktionsgewinne, die in der aktuellen Iteration der experimentellen Protected Audience API verwendet werden.

Im Entwicklerleitfaden finden Sie Informationen zum gesamten Lebenszyklus der Protected Audience API. In der Erläuterung zur Protected Audience API finden Sie eine ausführliche Erläuterung der Berichterstellung auf Ereignisebene (temporär).

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

Was ist der Bericht über die Protected Audience API?

Es gibt zwei Protected Audience API-Berichte:

  • Verkäuferbericht: Der Verkäufer wird über den Gewinner der Anzeigenauktion informiert.
  • Käuferbericht: Dieser Bericht ist nur für erfolgreiche Käufer verfügbar, damit sie wissen, dass sie eine Auktion gewonnen haben.

Der langfristige Plan sieht vor, dass der Browser über die Private Aggregation API Berichte zu Auktionsergebnissen für Verkäufer und Käufer erstellen kann. Als vorübergehende Methode zur Berichterstellung auf Ereignisebene kann der Code, mit dem reportResult() für den Verkäufer und reportWin() für den erfolgreichen Bieter implementiert wird, die Funktion sendReportTo() aufrufen. Dafür wird ein einziges Argument verwendet: ein String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird. Die zu meldenden Informationen auf Ereignisebene werden codiert.

API-Funktionen

Verkäufer: reportResult()

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

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

Folgende Argumente werden an diese Funktion übergeben:

auctionConfig

Das an navigator.runAdAuction() übergebene Objekt zur Auktionskonfiguration.

browserSignals

Ein vom Browser erstelltes Objekt, das Informationen zur Auktion liefert. 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() zur Verfügung gestellt hat, kann eine reportWin()-Funktion enthalten, um das Auktionsergebnis zu melden.

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

Folgende Argumente werden an diese Funktion übergeben:

auctionSignals und perBuyerSignals

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

sellerSignals

Der Rückgabewert von reportResult(), mit dem der Verkäufer die Informationen an den Käufer weitergeben kann.

browserSignals

Ein vom Browser erstelltes Objekt, das Informationen zur Auktion liefert. Beispiel:

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

Vorübergehende Implementierung der Berichterstellung

In Chrome stehen Ihnen vorübergehend zwei Methoden für Auktionsberichte zur Verfügung:

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

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

Chrome sendet nur dann Berichte zu Verlusten/Gewinnen bei der Fehlerbehebung, wenn eine Auktion abgeschlossen wurde. Wenn eine Auktion abgebrochen wird (z. B. aufgrund einer neuen Navigation), werden keine Berichte generiert.

Diese Methoden sind standardmäßig in Chrome verfügbar, wenn chrome://flags/#privacy-sandbox-ads-apis aktiviert ist. Wenn Sie Chrome jedoch 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, werden aber nicht ausgeführt.

Alle Protected Audience API-Referenzen

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.