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">![Sechs Phasen einer Protected Audience API-Anzeigenauktion](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=19&hl=de)
- Ein Nutzer besucht eine Website, auf der Anzeigen ausgeliefert werden.
- 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()
. - 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.
- Ü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
- 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.
- 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:
- Der Nutzer besucht eine teilnehmende Website.
- Eine programmatische Auktion wird von einem anderen Verkäufer durchgeführt, um eine kontextbezogene Anzeige für eine verfügbare Anzeigenfläche zu finden.
- Die Protected Audience API-Auktion wird durchgeführt.
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:
- 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.