Browserbasierte Auktion mit einem einzelnen Verkäufer durchführen

In diesem Dokument erhalten Sie einen allgemeinen Überblick über die Durchführung einer Auktion mit Protected Audience-Daten für einen einzelnen Verkäufer, der in der aktuellen Iteration der Protected Audience API verwendet wird. Eine Auktion mit einem einzelnen Verkäufer kann im Rahmen einer komplexeren Auktion mit mehreren Verkäufern durchgeführt werden. In diesem Fall wird die Auktion mit einem Verkäufer als „Komponentenauktion“ bezeichnet, bei der Anzeigenkandidaten für die „Top-Level-Auktion“ mit mehreren Verkäufern teilnehmen können.

Der Entwicklerleitfaden enthält Informationen zum gesamten Lebenszyklus der Protected Audience API. In der Erläuterung der Protected Audience API wird ausführlich beschrieben, wie Verkäufer On-Device-Auktionen ausführen.

Sechs Phasen einer Protected Audience API-Anzeigenauktion

In diesem Diagramm werden die einzelnen Phasen einer Protected Audience API-Anzeigenauktion veranschaulicht.

1. Ein Nutzer besucht eine Website, auf der Anzeigen geschaltet werden.
2. Mit dem Verkäufercode wird navigator.runAdAuction() ausgeführt. Damit wird festgelegt, welche Werbefläche zum Verkauf steht und wer Gebote abgeben darf. Verkäufer müssen außerdem ein Skript hinzufügen, mit dem für jedes Gebot der Wert scoreAd() bewertet wird.
3. Der Code des eingeladenen Käufers wird ausgeführt, um unter anderem ein Gebot und eine URL für ein relevantes Creative zu generieren. Mit dem Gebotsskript können Echtzeitdaten vom Schlüssel/Wert-Dienst des Käufers abgefragt werden, etwa zum verbleibenden Budget für Werbekampagnen.
4. Der Verkäufercode bewertet jedes Gebot und wählt den Gewinner. Bei dieser Logik wird der Gebotswert verwendet und andere Daten geben den gewünschten Gebotswert zurück. Anzeigen, die den kontextabhängigen Gewinner nicht übertreffen können, werden abgelehnt. Der Verkäufer kann seinen eigenen Schlüssel/Wert-Dienst für Echtzeitdaten verwenden.
5. Die erfolgreiche Anzeige wird als opaker Wert zurückgegeben und in einem Fenced Frame angezeigt. Weder der Verkäufer noch der Publisher können diesen Wert sehen.
6. Die Auktion wird für den Verkäufer und die gewinnenden Käufer erfasst.

Eine Auktion kann stattfinden, wenn ein Nutzer eine Seite mit einer Anzeige aufruft. Auktionen können im Voraus ausgeführt werden, damit die Anzeige bereit ist, wenn die Anzeigenfläche eingeblendet wird.

Verkäufer initiieren die Anzeigenauktion, bewerten mögliche Anzeigen mithilfe der benutzerdefinierten Logik, die als scoreAd()-Funktion bereitgestellt wird, und sind dafür verantwortlich, die Ergebnisse der Auktion sowohl an sich selbst als auch an den gewinnenden Käufer zu melden. Außerdem können Verkäufer mithilfe der Funktion scoreAd() Publisher-Regeln durchsetzen und nach Anzeigenqualität filtern.

Mögliche Bezeichnungen für Verkäufer sind:

• Content-Publisher, die für sich selbst agieren, um Anzeigeninhalte auf ihrer Website zu hosten
• Supply-Side-Plattformen (SSPs), die mit dem Anzeigen-Publisher zusammenarbeiten und weitere Dienstleistungen anbieten
• Drittanbieterskripts, die Publishern die Teilnahme an Anzeigenauktionen ermöglichen

Voraussetzungen für die Durchführung einer Auktion

Ein Verkäufer benötigt zwei JavaScript-Funktionen, die definiert sind, um eine Auktion durchzuführen:

• scoreAd(), wodurch eine mögliche Anzeige bewertet wird
• reportResult(), über die das Ergebnis der Auktion an den Verkäufer selbst gemeldet wird

Diese Skripts müssen von einem einzigen Endpunkt bereitgestellt werden, der dem Verkäufer gehört.

scoreAd()

Ein Verkäufer muss eine scoreAd()-Funktion definieren, die von einem ihm gehörenden Endpunkt bereitgestellt wird. Der Endpunkt wird in der Auktionskonfiguration als decisionLogicUrl angegeben. Die Funktion scoreAd() hat die folgende Signatur:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Die scoreAd()-Parameter sind:

• adMetaData: willkürliche Metadaten zur Anzeige, die vom Käufer zur Verfügung gestellt werden. Dies ist ein serielles JSON-Objekt, das Verkäufer und Käufer definieren und sich auf eine Struktur einigen müssen.
• bid: ein numerischer Wert für das Gebot
• auctionConfig – die Auktionskonfiguration, die zum Ausführen der Auktion verwendet wird.
• trustedScoringSignals – Signale, die zum Zeitpunkt der Auktion vom Schlüssel/Wert-Server des Verkäufers gelesen werden. Die Plattform verwendet den renderUrl der Kandidatenanzeige als Schlüssel für diese Suche.
• browserSignals, ein vom Browser erstelltes Objekt, einschließlich Informationen, die dem Browser bekannt sind und welche das Auktionsskript des Verkäufers überprüfen möchte.
• directFromSellerSignals ist ein Objekt, das die folgenden Felder enthalten kann: ** sellerSignals: wie auctionConfig.sellerSignals, wird aber mit dem Mechanismus directFromSellerSignals übergeben. ** auctionSignals: Wie auctionConfig.auctionSignals, wird aber mit dem Mechanismus directFromSellerSignals übergeben.

Im Folgenden finden Sie ein Beispiel für browserSignals. Die renderUrl der Kandidatenanzeige ist über folgende Signale verfügbar:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Ein Verkäufer muss eine reportResult()-Funktion definieren, die von einem eigenen Endpunkt bereitgestellt wird. Der Endpunkt wird in der Auktionskonfiguration als decisionLogicUrl angegeben. Die Funktion reportResult() hat die folgende Signatur:

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

Die reportResult()-Parameter sind:

• auctionConfig – die Auktionskonfiguration, die zum Ausführen der Auktion verwendet wird.
• browserSignals, ein vom Browser erstelltes Objekt, einschließlich Informationen, die dem Browser bekannt sind und welche das Auktionsskript des Verkäufers überprüfen möchte. Dies ist dasselbe Objekt, das an die Funktion scoreAds() übergeben wird.

reportResult() gibt signalsForWinner zurück. Dies ist ein beliebiges JSON-Objekt, das an die Berichtsfunktion des erfolgreichen Käufers übergeben wird. Hier sollten alle relevanten Informationen enthalten sein, die der Verkäufer zur Auktion bereitstellen kann, die der Käufer für seine Berichte benötigt.

Protected Audience API-Auktionen durchführen

Verkäufer müssen vier Hauptschritte ausführen, um eine Auktion durchzuführen. Bei diesen Schritten wird vorausgesetzt, dass der Verkäufer einen Endpunkt eingerichtet hat, um den zuvor in diesem Leitfaden genannten erforderlichen JavaScript-Code zurückzugeben.

1. Konfigurieren Sie die Auktion. Dieser Schritt umfasst das Erstellen eines auctionConfig-Objekts. So kann der Verkäufer angeben, welche Käufer an der Auktion teilnehmen sollen. Außerdem können sie alle Signale bereitstellen, die bei der Gebotserstellung oder Anzeigenbewertung relevant sein könnten.
2. Führen Sie die Auktion aus, indem Sie navigator.runAdAuction() aufrufen und die im vorherigen Schritt erstellte Konfiguration übergeben. Dadurch wird die Käuferkette gestartet, die Gebote generiert und dann bewertet. Das Endergebnis dieses Schritts ist ein Anzeigenkandidat, der gerendert werden kann, um eine Anzeige zu präsentieren.
3. Rendering Sie die erfolgreichste Anzeige in einem abgegrenzten Frame oder iFrame.
4. Melden Sie das Ergebnis der Auktion. Die Funktion navigator.sendReportTo() löst die Berichterstellung aus. Der Verkäufer erhält immer einen Bericht mit den Auktionsergebnissen. Nur der Käufer, der die Auktion gewonnen hat, erhält einen Bericht. Dabei wird das zuvor in diesem Leitfaden beschriebene reportResult() des Verkäufers verwendet, um einen Bericht an seinen Server zu senden.