Verkäuferleitfaden: Anzeigenauktionen durchführen

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

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

Entwicklerleitfaden der Protected Audience API. In der Erläuterung der Protected Audience API finden Sie ausführliche Informationen zu On-Device-Auktionen von Verkäufern.

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

Was ist die Anzeigenauktion der Protected Audience API?

Eine Protected Audience API-Anzeigenauktion besteht aus einer auf dem Gerät des Nutzers ausgeführt wird, um eine Anzeige auszuwählen. Um den Datenschutz zu wahren, wird der Auktionscode von Verkäufer und Käufer in isoliertem JavaScript ausgeführt. Worklets, die nicht mit dem auf der Erde.

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder"></ph> Sechs Phasen einer Protected Audience API-Anzeigenauktion
In diesem Diagramm werden die einzelnen Phasen einer Protected Audience API-Anzeigenauktion dargestellt.
  1. Ein Nutzer besucht eine Website, auf der Anzeigen ausgeliefert werden.
  2. Mit dem Verkäufercode wird navigator.runAdAuction() ausgeführt. Damit wird angegeben, Werbefläche zum Verkauf steht und wer Gebote abgeben kann. Verkäufer müssen außerdem ein Skript für jedes Gebot, scoreAd().
  3. Mit dem Code des eingeladenen Käufers wird ein Gebot und die URL für eine relevante Anzeige generiert. Creative und andere Daten. Das Gebotsskript kann Echtzeitdaten abfragen, etwa das verbleibende Kampagnenbudget, Schlüssel/Wert-Dienst.
  4. Über den Code des Verkäufers wird jedes Gebot bewertet und das erfolgreiche Gebot ermittelt. Diese Logik verwendet die Gebotswert und andere Daten geben Aufschluss darüber, wie wichtig ein Gebot ist. Anzeigen, die unschlagbar sind wird der kontextbezogene Gewinner abgelehnt. Der Verkäufer kann eine eigene Schlüssel/Wert-Dienst für Echtzeitdaten
  5. Die erfolgreiche Anzeige wird als opaker Wert zurückgegeben, der in einer Fened Frame Sowohl der Verkäufer als auch kann der Publisher diesen Wert nicht sehen.
  6. Die Auktion wird dem Verkäufer und den erfolgreichen Käufern gemeldet.

Wann findet die Auktion statt?

Die Protected Audience API kann eigenständig oder mit programmatischen Auktionen ausgeführt werden. In einem Mehrfachkundenkonto programmatische Auktion:

  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 durchgeführt.
  4. scoreAd()Die Gebote des Käufers werden mit den Ergebnissen der ersten Auktion verglichen.

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

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

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

Beispiel:

  • Content-Publisher: Das Hosten von Anzeigeninhalten auf seiner Website ist selbstständig.
  • Supply-Side-Plattform (SSP): Zusammenarbeit mit dem Publisher und Bereitstellung anderer Dienste
  • Drittanbieter-Skript: Handeln für einen Publisher, um die Teilnahme an Anzeigenauktionen zu ermöglichen

Mit der Protected Audience API hat ein Verkäufer drei Jobs:

  • Publisher-Regeln erzwingen, um festzulegen, welche Käufer und welche Gebote infrage kommen
  • Auktionslogik ausführen: JavaScript-Ausführung in worklets zum Berechnen eines Wunschwert für jedes Gebot.
  • Melden Sie das Auktionsergebnis.

Diese Aufträge werden programmatisch in Code ausgeführt, der vom Verkäufer bereitgestellt wird, wenn eine Anzeigenauktion durch Aufrufen der JavaScript-Funktion navigator.runAdAuction()

API-Funktionen

runAdAuction()

Der Verkäufer sendet eine Anfrage zum Starten einer Anzeigenauktion an den Browser des Nutzers, 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 in eine URN (urn:uuid:<something>) aufgelöst wird, die den das Ergebnis der Anzeigenauktion. Dieser Code kann nur vom Browser decodiert werden, wenn er an einen Fenced Frame übergeben wird. Rendering: Die Publisher-Seite kann die erfolgreiche Anzeige nicht prüfen.

Das Skript decisionLogicUrl berücksichtigt jede einzelne Anzeige samt zugehörigem Gebot und den zugehörigen Metadaten nacheinander ab und weist ihm ein numerisches Erwünschtheit.

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 ein Gebot abgeben möchten.
Hinweis: Der Verkäufer kann interestGroupBuyers: angeben, damit alle Interessengruppen Gebote abgeben dürfen. Die Anzeigen werden dann basierend auf anderen Kriterien als der Einbeziehung des Interessengruppeninhabers angenommen oder abgelehnt. Verkäufer haben beispielsweise die Möglichkeit, ihre Creatives auf die Einhaltung der Richtlinien zu überprüfen.
auctionSignals
Optional
Beispiel: {...}
Rolle: Verkäuferinformationen zum Seitenkontext, zur Art der Auktion usw.
sellerSignals
Optional
Beispiel: {...}
Rolle: Informationen basierend auf den Publisher-Einstellungen, einer kontextbezogenen Anzeigenanfrage usw.
sellerTimeout
Optional
Beispiel: 100
Rolle: Maximale Laufzeit (ms) des scoreAd()-Skripts des Verkäufers.
perBuyerSignals
Optional
Beispiel: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Rolle: Kontextsignale zur Seite für die einzelnen Käufer vom jeweiligen 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. an runAdAuction() übergeben. Diese URL muss ein Skript für den scoreAd()-Funktion. Diese Logik wird für jede Anzeige einmal ausgeführt, um seine Bedürfnisse zu ermitteln.

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

browserSignals

browserSignals ist ein Objekt, das vom Browser erstellt wird und Informationen enthält, die der Browser kennt und über das Auktionsskript des Verkäufers Bestätigen:

{
  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 sucht der Verkäufer die am besten geeignete kontextbezogene Anzeige für den verfügbare Anzeigenfläche. Durch die scoreAd()-Logik werden alle Anzeigen abgelehnt, schlug den kontextbezogenen Gewinner.

scoreAd()

scoreAd() verwendet die folgenden Argumente:

Argument Rolle
adMetadata Beliebige Metadaten, die vom Käufer bereitgestellt werden.
auctionConfig Das an navigator.runAdAuction() übergebene Auktionskonfigurationsobjekt.
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 bezüglich der Anzeige widerspiegeln.

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 Gewinner der Anzeige 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 davon kommunizieren kann. Der Browser selbst bewertet die Anzeigen nicht. Der Browser ist allein für die Ausführung der Bewertungslogik und die Auswahl des Gebots mit der höchsten Punktzahl verantwortlich.

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.