Verkäuferleitfaden: Anzeigenauktionen durchführen

Seller API-Leitfaden und Referenzen für die Anzeigenauktion der Protected Audience API

In diesem Artikel finden Sie die technische Referenz für die Anzeigenauktion, die in der aktuellen Version der Protected Audience API-Testversion verwendet wird.

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

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

Was ist die Protected Audience API-Anzeigenauktion?

Eine Protected Audience API-Anzeigenauktion ist eine Sammlung kleiner JavaScript-Programme, die der Browser auf dem Gerät des Nutzers ausführt, um eine Anzeige auszuwählen. Aus Datenschutzgründen wird der gesamte Auktionscode des Verkäufers und Käufers in isolierten JavaScript-Workstations ausgeführt, die nicht mit der Außenwelt kommunizieren können.

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.

Wann findet die Auktion statt?

Die Protected Audience API kann allein oder mit programmatischen Auktionen ausgeführt werden. Bei einer programmatischen Auktion mit mehreren Verkäufern gilt Folgendes:

  1. Der Nutzer besucht eine teilnehmende Website.
  2. Eine programmatische Auktion wird von einem anderen Verkäufer durchgeführt, um eine kontextbezogene Anzeige für eine verfügbare Anzeigenfläche zu finden.
  3. Die Protected Audience API-Auktion wird ausgeführt.
  4. scoreAd()Die Gebote des Käufers werden mit den Ergebnissen der ersten Auktion verglichen.

Gebote, die den kontextbezogenen Gewinner nicht übertreffen können, werden abgelehnt.

Wer führt die Protected Audience API-Anzeigenauktion durch?

Es gibt mehrere Parteien, die eine Auktion zum Verkauf von Werbeflächen durchführen.

Beispiel:

  • Content-Publisher: Hostet Anzeigeninhalte auf seiner Website für sich selbst.
  • Supply-Side-Plattform (SSP): Zusammenarbeit mit dem Publisher und Bereitstellung anderer Dienste
  • Drittanbieter-Script: Aktion für einen Publisher, um die Teilnahme an Anzeigenauktionen zu ermöglichen

Mit der Protected Audience API haben Verkäufer drei Aufgaben:

  • Publisher-Regeln durchsetzen, um festzulegen, welche Käufer und welche Gebote infrage kommen
  • Auktionslogik ausführen: JavaScript wird in Worklets ausgeführt, um für jedes Gebot einen gewünschten Wert zu berechnen.
  • Melden Sie das Auktionsergebnis.

Diese Jobs werden programmatisch in Code ausgeführt, der vom Verkäufer beim Initiieren einer Anzeigenauktion durch Aufrufen der JavaScript-Funktion navigator.runAdAuction() bereitgestellt wird.

API-Funktionen

runAdAuction()

Der Verkäufer sendet durch Aufrufen von navigator.runAdAuction() eine Anfrage an den Browser des Nutzers, um eine Anzeigenauktion zu starten.

Beispiel:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() gibt ein Promise zurück, das zu einer URN (urn:uuid:<something>) aufgelöst wird, die das Ergebnis der Anzeigenauktion darstellt. Es kann vom Browser nur decodiert werden, wenn es zum Rendern an einen Fenced Frame übergeben wird. Die Publisher-Seite kann die erfolgreiche Anzeige nicht untersuchen.

Das Skript decisionLogicUrl betrachtet jede einzelne Anzeige zusammen mit dem zugehörigen Gebot und den zugehörigen Metadaten nacheinander und weist ihr dann einen numerischen Wunschwert zu.

auctionConfig Unterkünfte

seller
Erforderlich
Beispiel: 'https://ssp.example'
Rolle: Ursprung des Verkäufers.
decisionLogicUrl
Erforderlich
Beispiel: 'https://ssp.example/auction-decision-logic.js'
Rolle: URL für Auktions-Worklet-JavaScript.
trustedScoringSignalsUrl
Optional
Beispiel: 'https://ssp.example/scoring-signals'
Rolle: URL des vertrauenswürdigen Servers des Verkäufers.
interestGroupBuyers
Erforderlich
Beispiel: ['https://dsp.example', 'https://buyer2.example', ...]
Rolle: Ursprünge aller Interessengruppeninhaber, die in der Auktion Gebote abgeben sollen
Hinweis: Der Verkäufer kann interestGroupBuyers: angeben, damit alle Interessengruppen Gebote abgeben können. Die Anzeigen werden dann basierend auf anderen Kriterien als der Aufnahme des Inhabers der Interessengruppe akzeptiert oder abgelehnt. Beispielsweise kann der Verkäufer Creatives überprüfen, um sicherzustellen, dass seine Richtlinien eingehalten werden.
auctionSignals
Optional
Beispiel: {...}
Rolle: Verkäuferinformationen über Seitenkontext, Auktionstyp usw.
sellerSignals
Optional
Beispiel: {...}
Rolle: Informationen basierend auf Publisher-Einstellungen, Erstellen einer kontextbezogenen Anzeigenanfrage usw.
sellerTimeout
Optional
Beispiel: 100
Rolle: Maximale Laufzeit (ms) des Skripts scoreAd() des Verkäufers.
perBuyerSignals
Optional
Beispiel: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Rolle: Kontextsignale zur Seite für jeden einzelnen Käufer von seinem Server.
perBuyerTimeouts
Optional
Beispiel: 50
Rolle: Maximale Laufzeit (ms) der generateBid()-Skripts eines bestimmten Käufers.
componentAuctions
Optional
Beispiel: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
Rolle: Zusätzliche Konfigurationen für Komponentenauktionen.

decisionLogicUrl

decisionLogicUrl ist eine Eigenschaft des Auktionskonfigurationsobjekts, die an runAdAuction() übergeben wird. Diese URL muss ein Skript für die Funktion scoreAd() enthalten. Diese Logik wird einmal für jede Anzeige ausgeführt, um ihre gewünschte Eigenschaft zu bestimmen.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals ist ein vom Browser erstelltes Objekt, einschließlich Informationen, die dem Browser bekannt sind und die das Auktionsskript des Verkäufers überprüfen möchte:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

Vor Beginn einer Auktion findet der Verkäufer die beste kontextbezogene Anzeige für die verfügbare Anzeigenfläche. Ein Teil der scoreAd()-Logik lehnt alle Anzeigen ab, die den kontextbezogenen Gewinner nicht übertreffen können.

scoreAd()

scoreAd() verwendet die folgenden Argumente:

Argument Rolle
adMetadata Beliebige Metadaten, die vom Käufer bereitgestellt werden.
auctionConfig Das an navigator.runAdAuction() übergebene Objekt für die Auktionskonfiguration.
bid Ein numerischer Gebotswert
trustedScoringSignals Werte, die zum Zeitpunkt der Auktion vom vertrauenswürdigen Server des Verkäufers abgerufen werden und die Meinung des Verkäufers zur Anzeige darstellen.

Häufig gestellte Fragen

Wie wird der Auktionsgewinner ermittelt und wer wählt ihn aus?

Der Verkäufer stellt die Bewertungslogik bereit, um den Wunschwert jeder Anzeige zu bestimmen, und der Browser wählt den höchsten Wert als erfolgreiche Anzeige aus.

Der Verkäufer fügt eine Logik in die scoreAd()-Funktion ein, und der Browser führt die Funktion in einem Worklet aus, das nur begrenzte Kommunikation mit externem Code hat. Der Browser selbst bewertet die Anzeigen nicht. Der Browser ist allein dafür verantwortlich, die Bewertungslogik auszuführen und das Gebot mit dem höchsten Wert auszuwählen.

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.