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.
- Ein Nutzer besucht eine Website, auf der Anzeigen geschaltet werden.
- 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 WertscoreAd()
bewertet wird. - 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.
- 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.
- 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.
- 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:
- 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 ausgeführt.
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:
- 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.