Browserbasierte Auktion mit einem einzelnen Verkäufer durchführen

In diesem Dokument finden Sie einen allgemeinen Überblick über die Durchführung einer Auktion mit Protected Audience-Daten für einen einzelnen Verkäufer, wie sie in der aktuellen Version der Protected Audience API verwendet wird. Eine Auktion mit einem einzelnen Verkäufer kann als Teil einer komplexeren Auktion mit mehreren Verkäufern durchgeführt werden. In diesem Fall wird die Auktion mit einem einzelnen Verkäufer als „Komponentenauktion“ bezeichnet, die Anzeigenkandidaten für die „Auktion auf oberster Ebene“ mit mehreren teilnehmenden Verkäufern liefern kann.

Im Entwicklerleitfaden finden Sie Informationen zum gesamten Lebenszyklus der Protected Audience API. Im Protected Audience API-Explainer wird ausführlich erläutert, wie Verkäufer On-Device-Auktionen durchführen.

Sechs Phasen einer Anzeigenauktion mit der Protected Audience API

1. Ein Nutzer besucht eine Website, auf der Anzeigen ausgeliefert werden.
2. Der Code des Verkäufers wird ausgeführt. navigator.runAdAuction() Hier wird angegeben, welche Werbefläche zum Verkauf steht und wer Gebote abgeben kann. Verkäufer müssen auch ein Skript einfügen, mit dem jedes Gebot bewertet wird: scoreAd().
3. Der Code des eingeladenen Käufers wird ausgeführt, um ein Gebot, eine URL für ein relevantes Anzeigen-Creative und andere Daten zu generieren. Das Gebotsscript 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 nicht besser als die kontextbezogene Gewinneranzeige abschneiden, werden abgelehnt. Der Verkäufer kann seinen eigenen Schlüssel/Wert-Dienst für Echtzeitdaten verwenden.
5. Die Gewinneranzeige wird als undurchsichtiger Wert zurückgegeben, der in einem Fenced 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 die Auktion 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 Anzeigen-Creative bereit ist, wenn der Anzeigen-Slot in den Blick kommt.

Verkäufer starten die Anzeigenauktion, bewerten infrage kommende Anzeigen mithilfe einer benutzerdefinierten Logik, die als scoreAd()-Funktion bereitgestellt wird, und sind dafür verantwortlich, die Ergebnisse der Auktion an sich selbst und an den erfolgreichen Käufer zu melden. Verkäufer können auch Publisher-Regeln erzwingen und mithilfe der Funktion scoreAd() nach Anzeigenqualität filtern.

Ein Verkäufer kann sich auf Folgendes beziehen:

• Content-Publisher, die in eigener Verantwortung Werbeinhalte auf ihrer Website hosten
• Supply-Side-Plattformen (SSPs), die mit dem Anzeigen-Publisher zusammenarbeiten und andere Dienste anbieten
• Drittanbieterskripts, die im Namen eines Publishers die Teilnahme an Anzeigenauktionen ermöglichen.

Voraussetzungen für die Durchführung einer Auktion

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

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

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

scoreAd()

Ein Verkäufer muss eine scoreAd()-Funktion definieren, die von einem Endpunkt bereitgestellt 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: Beliebige Metadaten zum Anzeigen-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 zum Ausführen der Auktion verwendet wird.
• trustedScoringSignals. Das sind Signale, die zum Zeitpunkt der Auktion vom Schlüssel/Wert-Server des Verkäufers gelesen werden. Die Plattform verwendet die renderUrl der infrage kommenden Anzeige als Schlüssel für diese Suche.
• browserSignals ist ein vom Browser erstelltes Objekt, das Informationen enthält, die der Browser kennt und die das Auktionsskript des Verkäufers möglicherweise überprüfen möchte.
• directFromSellerSignals ist ein Objekt, das die folgenden Felder enthalten kann: ** sellerSignals: Wie auctionConfig.sellerSignals, aber über den Mechanismus directFromSellerSignals übergeben. ** auctionSignals: Wie auctionConfig.auctionSignals, aber über den Mechanismus directFromSellerSignals übergeben.

Im Folgenden finden Sie ein Beispiel für browserSignals. Die renderUrl der infrage kommenden 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 bereitgestellt 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 zum Ausführen der Auktion verwendet wird.
• browserSignals ist ein vom Browser erstelltes Objekt, das Informationen enthält, die der Browser kennt und die das Auktionsskript des Verkäufers möglicherweise überprüfen möchte. Dies ist dasselbe Objekt, das an die Funktion scoreAds() übergeben wurde.

reportResult() gibt signalsForWinner zurück. Das ist ein beliebiges JSON-Objekt, das an die Berichtsfunktion des erfolgreichen Käufers übergeben wird. Dazu sollten alle relevanten Informationen gehören, die der Verkäufer zur Auktion bereitstellen kann und die der Käufer für seine Berichterstellung benötigt.

Protected Audience API-Auktion durchführen

Ein Verkäufer muss vier Hauptschritte ausführen, um eine Auktion durchzuführen. Bei diesen Schritten wird davon ausgegangen, dass der Verkäufer einen Endpunkt eingerichtet hat, über den das in dieser Anleitung erwähnte erforderliche JavaScript zurückgegeben wird.

1. Konfigurieren Sie die Auktion. In diesem Schritt erstellen Sie ein auctionConfig-Objekt. So kann der Verkäufer festlegen, welche Käufer an der Auktion teilnehmen sollen, und 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 Kette von Käufern ausgelöst, 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 Fenced Frame oder Iframe.
4. Ergebnis der Auktion melden Mit der Funktion navigator.sendReportTo() wird die Berichterstellung initiiert. 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 die reportResult() des Verkäufers verwendet, die weiter oben in dieser Anleitung beschrieben wurde, um Daten an den Server des Verkäufers zu senden.