Verkäuferleitfaden: Anzeigenauktionen durchführen

Leitfaden und Referenzen für die Verkäufer-API für die Anzeigenauktion mit der Protected Audience API.

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. Im Protected Audience API-Explainer wird ausführlich erläutert, 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. Um den Datenschutz zu wahren, wird der gesamte Auktionscode 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, 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.

Wann findet die Auktion statt?

Die Protected Audience API kann eigenständig oder zusammen mit programmatischen Auktionen ausgeführt werden. In einer programmatischen Auktion mit mehreren Verkäufern:

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 Anzeigefläche 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 Anzeigenauktion der Protected Audience API durch?

Es gibt mehrere Parteien, die eine Auktion durchführen können, um Werbeflächen zu verkaufen.

Beispiel:

• Content-Publisher: handelt für sich selbst, um Anzeigeninhalte auf seiner Website zu hosten.
• Supply-Side-Plattform (SSP): Zusammenarbeit mit dem Publisher und Bereitstellung anderer Dienste.
• Drittanbieterskript: Wird im Auftrag eines Publishers verwendet, um die Teilnahme an Anzeigenauktionen zu ermöglichen.

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

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

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

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 Promise zurück, das in einen URN (urn:uuid:<something>) aufgelöst wird, der das Ergebnis der Anzeigenauktion darstellt. Sie kann nur vom Browser decodiert werden, wenn sie an einen eingezäunten Frame zur Darstellung übergeben wird. Die Publisher-Seite kann die Gewinneranzeige nicht prüfen.

Im decisionLogicUrl-Script wird jede einzelne Anzeige mit dem zugehörigen Gebot und den Metadaten einzeln berücksichtigt und dann ein numerischer Wert für die Attraktivität 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, im Rahmen der Auktion Gebote abzugeben.

Hinweise: Der Verkäufer kann interestGroupBuyers: angeben, um Gebote für alle Interessengruppen zuzulassen. Anzeigen werden dann auf Grundlage anderer Kriterien als der Einbeziehung des Eigentümers der Interessengruppe akzeptiert oder abgelehnt. Der Verkäufer kann beispielsweise Anzeigen-Creatives überprüfen, um die Einhaltung seiner Richtlinien zu bestätigen.

auctionSignals

Optional

Beispiel: {...}

Rolle: Verkäuferinformationen zum Seitenkontext, zur Art der Auktion usw.

sellerSignals

Optional

Beispiel: {...}

Rolle: Informationen basierend auf Publisher-Einstellungen, einer kontextbezogenen Anzeigenanfrage usw.

sellerTimeout

Optional

Beispiel: 100

Rolle: Maximale Laufzeit (in Millisekunden) des scoreAd()-Skripts des Verkäufers.

perBuyerSignals

Optional

Beispiel:

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

Rolle: Kontextbezogene Signale zur Seite für jeden einzelnen Käufer von seinem Server.

perBuyerTimeouts

Optional

Beispiel: 50

Rolle: Maximale Laufzeit (in Millisekunden) 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 Auktionskonfigurationsobjekts, 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 ermitteln.

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

browserSignals

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:

{
  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 nach der besten kontextbezogenen Anzeige für den verfügbaren Anzeigenblock. Im Rahmen der scoreAd()-Logik wird jede Anzeige abgelehnt, die nicht besser als die kontextbezogene Gewinneranzeige ist.

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 Scoring-Logik bereit, um den Attraktivitätswert jeder Anzeige zu ermitteln. Der Browser wählt die Anzeige mit dem höchsten Wert aus.

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

Alle Verweise auf die Protected Audience API

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.