Browserbasierte Auktion mit einem einzelnen Verkäufer durchführen

bookmark_border Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

In diesem Dokument finden Sie einen allgemeinen Überblick zum Ausführen einer Auktion mit Protected Audience-Daten für einen einzelnen Verkäufer, wie in der aktuellen Version der Protected Audience API verwendet. Eine Auktion mit einem einzelnen Verkäufer kann als Teil einer komplexeren Auktion mit mehreren Verkäufern ausgeführt werden. In diesem Fall wird die Auktion mit einem einzelnen Verkäufer als „Komponenten-Auktion“ bezeichnet. Sie kann Anzeigenkandidaten für die „Auktion der obersten Ebene“ bereitstellen, an der mehrere Verkäufer teilnehmen.

Im Entwicklerleitfaden finden Sie Informationen zum gesamten Lebenszyklus der Protected Audience API. In der Erläuterung zur Protected Audience API erfahren Sie, wie Verkäufer On-Device-Auktionen durchführen.

Sechs Phasen einer Protected Audience API-Anzeigenauktion

1. Ein Nutzer besucht eine Website, auf der Anzeigen ausgeliefert werden.
2. Der Code des Verkäufers führt navigator.runAdAuction() aus. Hier wird festgelegt, welche Anzeigenfläche zum Verkauf steht und wer bieten kann. Verkäufer müssen außerdem ein Script angeben, mit dem jedes Gebot bewertet wird, scoreAd().
3. Der Code des eingeladenen Käufers wird ausgeführt, um ein Gebot, die URL eines relevanten Creatives und andere Daten zu generieren. Das Gebotsskript kann Echtzeitdaten wie das verbleibende Budget der Werbekampagne vom Schlüssel/Wert-Dienst des Käufers abfragen.
4. Der Code des Verkäufers bewertet jedes Gebot und wählt einen Gewinner aus. Bei dieser Logik wird der Gebotswert und andere Daten verwendet, um die Attraktivität eines Gebots zu ermitteln. Anzeigen, die den kontextbezogenen Gewinner nicht übertreffen können, werden abgelehnt. Der Verkäufer kann seinen eigenen Schlüssel/Wert-Dienst für Echtzeitdaten verwenden.
5. Die ausgewählte Anzeige wird als undurchsichtiger Wert zurückgegeben, der in einem begrenzten Frame angezeigt wird. Sowohl der Verkäufer als auch der Publisher können diesen Wert nicht sehen.
6. Die Auktion wird dem Verkäufer und den Käufern, die sie gewonnen haben, gemeldet.

Eine Auktion kann stattfinden, wenn ein Nutzer eine Seite aufruft, auf der eine Anzeige ausgeliefert wird. Auktionen können vorab durchgeführt werden, damit das Creative bereit ist, wenn der Anzeigen-Slot sichtbar wird.

Verkäufer initiieren die Anzeigenauktion, bewerten Anzeigenkandidaten anhand benutzerdefinierter Logik, die als scoreAd()-Funktion bereitgestellt wird, und sind dafür verantwortlich, die Ergebnisse der Auktion sowohl für sich selbst als auch für den Gewinner zu erfassen. Verkäufer können außerdem mithilfe der Funktion scoreAd() die Regeln von Publishern erzwingen und nach Anzeigenqualität filtern.

Ein Verkäufer kann sich auf Folgendes beziehen:

• Contentanbieter, die in eigenem Namen Anzeigeninhalte auf ihrer Website hosten
• Supply-Side-Plattformen (SSPs), die mit dem Anzeigenpublisher zusammenarbeiten und andere Dienstleistungen anbieten
• Scripts von Drittanbietern, die für einen Publisher die Teilnahme an Anzeigenauktionen ermöglichen.

Voraussetzungen für die Durchführung einer Auktion

Für die Durchführung einer Auktion müssen zwei JavaScript-Funktionen definiert sein:

• scoreAd(), mit dem ein Anzeigenkandidat bewertet wird
• reportResult(), das das Ergebnis der Auktion dem Verkäufer meldet

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

scoreAd()

Ein Verkäufer muss eine scoreAd()-Funktion definieren, die von einem Endpunkt ausgeliefert wird, der ihm gehört. 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: Benutzerdefinierte Metadaten zum Creative, die vom Käufer bereitgestellt werden. Dies ist ein JSON-serialisierbares Objekt, dessen Struktur von Verkäufern und Käufern definiert und vereinbart werden muss.
• bid, ein numerischer Wert, der das Gebot darstellt.
• auctionConfig, die Auktionskonfiguration, die für die Durchführung der Auktion verwendet wird.
• trustedScoringSignals, d. h. Signale, die zur Auktion vom Schlüssel/Wert-Server des Verkäufers gelesen werden. Die Plattform verwendet die renderUrl der ausgewählten Anzeige als Schlüssel für diese Suche.
• browserSignals, ein vom Browser erstelltes Objekt, das Informationen enthält, die dem Browser bekannt sind und die vom Auktionsskript des Verkäufers möglicherweise überprüft werden sollen.
• directFromSellerSignals ist ein Objekt, das die folgenden Felder enthalten kann: ** sellerSignals: Ähnlich wie auctionConfig.sellerSignals, wird aber mit dem Mechanismus directFromSellerSignals übergeben. ** auctionSignals: Ähnlich wie auctionConfig.auctionSignals, wird aber mit dem Mechanismus directFromSellerSignals übergeben.

Das folgende Beispiel zeigt browserSignals. Die renderUrl der ausgewählten Anzeige ist über diese 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 Endpunkt ausgeliefert wird, der ihm gehört. 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 für die Durchführung der Auktion verwendet wird.
• browserSignals, ein vom Browser erstelltes Objekt, das Informationen enthält, die dem Browser bekannt sind und die vom Auktionsskript des Verkäufers möglicherweise überprüft werden sollen. Dies ist dasselbe Objekt, das an die scoreAds()-Funktion übergeben wird.

reportResult() gibt signalsForWinner zurück, ein beliebiges JSON-Objekt, das an die Berichtsfunktion des Gewinners übergeben wird. Dazu gehören alle relevanten Informationen, die der Verkäufer über die Auktion zur Verfügung stellen kann und die der Käufer für seine Berichte benötigt.

Protected Audience API-Auktion durchführen

Es gibt vier Hauptschritte, die ein Verkäufer ausführen muss, um eine Auktion durchzuführen. Beachten Sie, dass bei diesen Schritten davon ausgegangen wird, dass der Verkäufer einen Endpunkt eingerichtet hat, um das erforderliche JavaScript zurückzugeben, das bereits in diesem Leitfaden erwähnt wurde.

1. Konfigurieren Sie die Auktion. Dazu gehört das Erstellen eines auctionConfig-Objekts. So kann der Verkäufer angeben, welche Käufer an der Auktion teilnehmen sollen, und alle Signale angeben, die bei der Gebotsgenerierung oder Anzeigenbewertung relevant sein könnten.
2. Führen Sie die Auktion durch, indem Sie navigator.runAdAuction() aufrufen und die im vorherigen Schritt erstellte Konfiguration übergeben. Dadurch wird die Kette von Käufern initiiert, die Gebote generieren und dann bewerten. Das Endergebnis dieses Schritts ist ein Anzeigenkandidat, der gerendert werden kann, um eine Anzeige zu präsentieren.
3. Rendern Sie die Gewinneranzeige in einem abgegrenzten Frame oder Iframe.
4. Melden Sie das Ergebnis der Auktion. Mit der Funktion navigator.sendReportTo() werden Berichte erstellt. Der Verkäufer erhält immer einen Bericht zu den Auktionsergebnissen. Nur der Käufer, der die Auktion gewonnen hat, erhält einen Bericht. Dabei wird die reportResult() des Verkäufers verwendet, die bereits in diesem Leitfaden beschrieben wurde, um Berichte an seinen Server zu senden.