Berichte zu Protected Audience API-Auktionsergebnissen

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

Dieser Artikel ist eine technische Referenz zum Generieren von Berichten zu Auktionsgewinnen der Protected Audience API, die in der aktuellen Version der experimentellen Protected Audience API verwendet wird.

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

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

Was wird in der Protected Audience API gemeldet?

Es gibt zwei verfügbare 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, um zu erfahren, dass sie eine Auktion gewonnen haben.

Langfristig planen Sie, dass der Browser über die Private Aggregation API APIs Berichte zu Auktionsergebnissen für den Verkäufer und Käufer erstellen kann. Als temporäres Berichtsmechanismus auf Ereignisebene kann der Code, der reportResult() für den Verkäufer und reportWin() für den erfolgreichen Bieter implementiert, die sendReportTo()-Funktion aufrufen. Dafür wird ein einzelnes Argument verwendet: ein String, der eine URL darstellt, die nach Abschluss der Auktion abgerufen wird und die Informationen auf Ereignisebene codiert, die gemeldet werden sollen.

API-Funktionen

Verkäufer: reportResult()

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

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

Folgende Argumente werden an diese Funktion übergeben:

auctionConfig

Das an navigator.runAdAuction() übergebene Auktionskonfigurationsobjekt.

browserSignals

Ein Objekt, das vom Browser erstellt wird und 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()

Der JavaScript-Code des erfolgreichen Bieters, der auch generateBid() bereitgestellt 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 werden für den erfolgreichen Bieter an generateBid() übergeben.

sellerSignals

Der Rückgabewert von reportResult(), der dem Verkäufer die Möglichkeit gibt, Informationen an den Käufer zu senden.

browserSignals

Ein Objekt, das vom Browser erstellt wird und 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>
}

Temporäre Implementierung von Berichten

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

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

Diese Methoden verwenden jeweils ein einzelnes 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 und Gewinnen zur Fehlerbehebung, wenn eine Auktion abgeschlossen ist. 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 Sie unter chrome://settings/adPrivacy alle APIs zum Datenschutz bei Werbung aktivieren. Wenn Sie Chrome mit Befehlszeilen-Flags zum Aktivieren der Protected Audience API ausführen, müssen Sie die Methoden explizit aktivieren, indem Sie das Flag BiddingAndScoringDebugReportingAPI einfügen. Wenn das Flag nicht aktiviert ist, sind die Methoden zwar verfügbar, führen aber nichts aus.

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.