Verkäuferleitfaden: Anzeigenauktionen durchführen

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

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

In diesem Artikel finden Sie eine technische Referenz für die Anzeigenauktion, wie sie 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 erfahren Sie außerdem, wie Verkäufer On-Device-Auktionen durchführen.

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

Was ist die Protected Audience API-Anzeigenauktion?

Eine Protected Audience API-Anzeigenauktion besteht aus einer Reihe kleiner JavaScript-Programme, die der Browser auf dem Gerät des Nutzers ausführt, um eine Anzeige auszuwählen. Zum Schutz der Daten werden alle Anzeigenauktionen-Codes von Verkäufern und Käufern in isolierten JavaScript-Worklets ausgeführt, die nicht mit der Außenwelt kommunizieren können.

1. Ein Nutzer besucht eine Website mit Anzeigen.
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.

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. Ein anderer Verkäufer führt eine programmatische Auktion durch, um eine kontextbezogene Anzeige für einen verfügbaren Anzeigenblock zu finden.
3. Die Protected Audience API-Auktion wird ausgeführt.
4. scoreAd()vergleicht die Gebote des Käufers mit den Ergebnissen der ersten Auktion.

Gebote, die das kontextbezogene Gewinnergebot 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 abhalten können.

Beispiel:

• Content-Publisher: Er hostet Anzeigeninhalte auf seiner Website.
• Supply-Side-Plattform (SSP): Arbeitet mit dem Publisher zusammen und erbringt andere Dienstleistungen.
• Script eines Drittanbieters: Script, das für einen Publisher ausgeführt wird, um die Teilnahme an Anzeigenauktionen zu ermöglichen.

Bei der Protected Audience API hat ein Verkäufer drei Aufgaben:

• Publisher-Regeln erzwingen: Welche Käufer und Gebote sind zulässig?
• Auktionslogik ausführen: JavaScript wird in Worklets ausgeführt, um für jedes Gebot einen Wert für die Attraktivität zu berechnen.
• Melden Sie das Auktionsergebnis.

Diese Jobs werden programmatisch in Code ausgeführt, den der Verkäufer bereitstellt, wenn er eine Anzeigenauktion durch Aufrufen der JavaScript-Funktion navigator.runAdAuction() initiiert.

API-Funktionen

runAdAuction()

Der Verkäufer sendet eine Anfrage an den Browser des Nutzers, um eine Anzeigenauktion zu starten, indem er navigator.runAdAuction() aufruft.

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 Versprechen zurück, das zu einer URN (urn:uuid:<something>) führt, die das Ergebnis der Anzeigenauktion darstellt. Diese kann nur vom Browser decodiert werden, wenn sie zum Rendern an einen begrenzten Frame übergeben wird. Die Anzeige, die den Zuschlag erhalten hat, kann nicht auf der Publisher-Seite geprüft werden.

Im decisionLogicUrl-Script wird jede einzelne Anzeige zusammen mit dem zugehörigen Gebot und den zugehörigen Metadaten einzeln berücksichtigt und dann eine numerische Bewertung der Eignung zugewiesen.

auctionConfig Unterkünfte

seller

Erforderlich

Beispiel: 'https://ssp.example'

Rolle: Herkunft des Verkäufers.

decisionLogicUrl

Erforderlich

Beispiel: 'https://ssp.example/auction-decision-logic.js'

Rolle: URL für das JavaScript des Auktions-Worklets.

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: Herkunft aller Inhaber von Interessengruppen, die aufgefordert wurden, in der Auktion zu bieten.

Hinweise: Der Verkäufer kann interestGroupBuyers: angeben, um allen Interessengruppen das Abgeben von Geboten zu ermöglichen. Anzeigen werden dann anhand anderer Kriterien als der Aufnahme des Eigentümers der Interessengruppe akzeptiert oder abgelehnt. So kann der Verkäufer beispielsweise Creatives prüfen, um die Einhaltung seiner Richtlinien zu bestätigen.

auctionSignals

Optional

Beispiel: {...}

Rolle: Verkäuferinformationen zum Seitenkontext, zur Auktionsart usw.

sellerSignals

Optional

Beispiel: {...}

Rolle: Informationen basierend auf den Einstellungen des Publishers, Abgabe einer Anfrage für kontextbezogene Anzeigen usw.

sellerTimeout

Optional

Beispiel: 100

Rolle: Maximale Laufzeit (ms) des scoreAd()-Scripts des Verkäufers.

perBuyerSignals

Optional

Beispiel:

{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }

Rolle: Kontextsignale zur Seite für jeden einzelnen Käufer, die von seinem Server stammen.

perBuyerTimeouts

Optional

Beispiel: 50

Rolle: Maximale Laufzeit (ms) der generateBid()-Scripts 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 ein Attribut des Auktionskonfiguratiobjekts, das an runAdAuction() übergeben wird. Diese URL muss ein Script für die Funktion scoreAd() enthalten. Diese Logik wird einmal für jede Anzeige ausgeführt, um ihre Attraktivität zu bestimmen.

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

browserSignals

browserSignals ist ein vom Browser erstelltes Objekt, das Informationen enthält, die dem Browser bekannt sind und die vom Auktions-Script des Verkäufers möglicherweise überprüft werden sollen:

{
  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. */
}

Bevor eine Auktion beginnt, sucht der Verkäufer die beste kontextbezogene Anzeige für den verfügbaren Anzeigenblock. Im Rahmen der scoreAd()-Logik werden alle Anzeigen abgelehnt, die den kontextbezogenen Gewinner nicht übertreffen können.

scoreAd()

scoreAd() verwendet die folgenden Argumente:

Häufig gestellte Fragen

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

Der Verkäufer stellt die Bewertungslogik bereit, um den Wählbarkeitsfaktor jeder Anzeige zu bestimmen. Der Browser wählt die Anzeige mit der höchsten Punktzahl als Gewinner aus.

Der Verkäufer fügt der scoreAd()-Funktion Logik hinzu und der Browser führt die Funktion in einem Worklet aus, das nur eingeschränkt mit Code außerhalb kommunizieren kann. Die Anzeigen werden nicht vom Browser selbst bewertet. Der Browser ist ausschließlich dafür verantwortlich, die Bewertungslogik auszuführen und das Gebot mit der höchsten Punktzahl auszuwählen.

Alle Protected Audience API-Referenzen

API-Referenzleitfäden sind verfügbar:

• Entwicklerleitfaden für die Protected Audience API
• Käuferleitfaden für Protected Audience zu Interessengruppen und Gebotserstellung.
• Leitfaden für Anzeigenverkäufer zu Protected Audience-Anzeigenauktionen
• Leitfaden zur Berichterstellung für Auktionsergebnisse
• Best Practices für die Latenz bei der Anzeigenauktion von Protected Audience
• Fehlerbehebung bei Protected Audience

In der Erläuterung der Protected Audience API finden Sie auch Details zur Funktionsunterstützung und zu den Einschränkungen.