Hier erfahren Sie, wie Sie eine Protected Audience API-Auktion konfigurieren.
Auktionen auf Geräten, die von Verkäufern durchgeführt werden
Eine Protected Audience-Auktion auf dem Gerät wird auf einer Website ausgeführt, auf der Werbeflächen verkauft werden. Die Partei, die die Auktion durchführt, wird als Verkäufer bezeichnet. Viele Parteien können als Verkäufer fungieren: Eine Website kann ihre eigene Anzeigenauktion durchführen oder ein Drittanbieter-Script einbinden, um die Auktion für sie durchzuführen, oder eine SSP verwenden, die die Durchführung einer On-Device-Auktion mit anderen serverseitigen Anzeigenauktionsaktivitäten kombiniert. Verkäufer haben drei grundlegende Aufgaben in der On-Device-Anzeigenauktion:
- Verkäufer entscheiden (a), welche Käufer teilnehmen dürfen, und (b), welche Gebote aus den Interessengruppen dieser Käufer für die Auktion infrage kommen. So kann der Verkäufer die Regeln der Website für Anzeigen durchsetzen, die auf der Seite erscheinen dürfen.
- Verkäufer sind für die Geschäftslogik der Auktion verantwortlich: JavaScript-Code, in dem der Preis und die Metadaten jedes Gebots berücksichtigt und eine „Attraktivitäts“-Punktzahl berechnet wird. Das Gebot mit dem höchsten Desirability-Wert gewinnt die Auktion.
- Verkäufer erstellen Berichte zum Auktionsergebnis, einschließlich Informationen zum Abrechnungspreis und zu allen anderen Auszahlungen. Die Käufer, die die Auktion gewonnen oder verloren haben, können ebenfalls eigene Berichte erstellen.
In diesem Dokument wird beschrieben, wie Sie eine Auktion auf dem Gerät konfigurieren und starten.
Protected Audience API-Werbeauktion konfigurieren
Um eine Anzeigenauktion mit der Protected Audience API durchzuführen, müssen Sie zuerst die Auktion konfigurieren. Dazu wird ein auctionConfig-Objekt erstellt.
Hier sehen Sie ein Beispiel für eine solche Konfiguration:
const auctionConfig = {
seller: 'https://seller.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://buyer-1.example': {...},
'https://buyer-2.example': {...},
...
},
perBuyerTimeouts: {
'https://buyer-1.example': 50,
'https://buyer-2.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://component-seller.example',
'decisionLogicUrl': ...,
...
},
...
],
resolveToConfig: [true|false],
};
AuctionConfig Unterkünfte
Erforderliche Properties
Die einzigen erforderlichen Properties für auctionConfigs sind seller, decisionLogicUrl und interestGroupBuyers.
| Attribut | Beispiel | Rolle |
|---|---|---|
| seller | https://seller.example | Herkunft des Verkäufers. |
| decisionLogicUrl | https://seller.example/decision-logic.js | URL für das Worklet für die Entscheidungslogik für die JavaScript-Auktion. Dieses Feld muss denselben Ursprung wie das Verkäuferfeld haben. |
| interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Ursprünge aller Interessengruppeninhaber, die aufgefordert wurden, in der Auktion zu bieten |
Optionale Attribute
Die verbleibenden Attribute für auctionConfigs sind optional.
| Attribut | Beispiel | Rolle |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | URL des Key/Value-Servers des Verkäufers. Sie wird während der Anzeigenbewertung mit der Render-URL des Creatives als Schlüssel abgefragt. Dieses Feld muss denselben Ursprung wie das Verkäuferfeld haben. |
| auctionSignals | {"category":"news"} | JSON-serialisierbares Objekt, das die Signale darstellt, die allen Käufern und Verkäufern zur Verfügung stehen, die an der Auktion teilnehmen. |
| sellerSignals | {...} | JSON-serialisierbares Objekt, das Signale darstellt, die nur für Verkäufer verfügbar sind. |
| perBuyerSignals | {https://dsp.beispiel: {...}, https://another-buyer.beispiel: {...}, ... } |
Signale, die einem bestimmten Käufer zur Verfügung stehen. Die Signale können von den Verkäufern und auch von den Käufern selbst stammen. |
| perBuyerTimeouts | {https://www.beispiel-dsp.de: 50, https://www.anderer-kaeufer.de: 200, *: 150, ...}, |
Maximale Laufzeit in Millisekunden für das generateBid()-Skript eines bestimmten Käufers. Ein Platzhaltersymbol wird auf jeden Käufer angewendet, für den kein bestimmtes Zeitlimit definiert ist. |
| sellerTimeout | 100 | Maximale Laufzeit in Millisekunden für das scoreAd()-Skript eines Verkäufers. |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Zusätzliche Konfigurationen für Komponentenauktionen. |
| resolveToConfig | true|false | Ein boolescher Wert, der angibt, ob das von runAdAuction() zurückgegebene Promise in eine FencedFrameConfig aufgelöst werden soll, wenn „true“ (zur Verwendung in einem <fencedframe>) oder in eine undurchsichtige urn:uuid-URL, wenn „false“ (zur Verwendung in einem <iframe>). Der Standardwert ist „false“. |
Signale asynchron bereitstellen
Die Werte einiger Signale (die durch die Felder auctionSignals, sellerSignals, perBuyerSignals und perBuyerTimeouts konfiguriert werden) können optional nicht als konkrete Werte, sondern als Promises angegeben werden. Dadurch können sich einige Teile der Auktion, z. B. das Laden von Skripts und vertrauenswürdigen Signalen sowie das Starten isolierter Worklet-Prozesse, mit der Berechnung (oder dem Abrufen über das Netzwerk) dieser Werte überschneiden. In den Worklet-Skripts werden nur die aufgelösten Werte angezeigt. Wenn ein solches Promise abgelehnt wird, wird die Auktion abgebrochen, sofern sie nicht bereits fehlgeschlagen oder auf andere Weise abgebrochen wurde.
Auktion mit mehreren Verkäufern konfigurieren
In einigen Fällen möchten mehrere Verkäufer an einer Auktion teilnehmen, wobei die Gewinner separater Auktionen an eine andere Auktion weitergeleitet werden, die von einem anderen Verkäufer durchgeführt wird. Diese separaten Auktionen werden als Komponentenauktionen bezeichnet.
Um diese Komponentenauktionen zu ermöglichen, kann das componentAuctions-Objekt zusätzliche Auktionskonfigurationen für die Komponentenauktion jedes Verkäufers enthalten. Das Gewinnergebot jeder dieser Komponentenauktionen wird an die Auktion auf höchster Ebene weitergeleitet, in der die endgültige Entscheidung über die Auktion getroffen wird. Die auctionConfig von Komponentenauktionen haben möglicherweise keine eigene componentAuctions. Wenn componentAuctions nicht leer ist, muss interestGroupBuyers leer sein. Das heißt, bei einer bestimmten Protected Audience-Auktion gibt es entweder einen einzelnen Verkäufer und keine untergeordneten Auktionen oder alle Gebote stammen aus untergeordneten Auktionen und bei der Auktion auf höchster Ebene kann nur zwischen den Gewinnern der untergeordneten Auktionen ausgewählt werden.
Auktion durchführen
Der Verkäufer sendet eine Anfrage an den Browser des Nutzers, um eine Anzeigenauktion zu starten, indem er navigator.runAdAuction() aufruft.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
Der runAdAuction()-Aufruf gibt ein Promise zurück, das in der Anzeige aufgelöst wird. Es ist nicht möglich, dass Code auf der Publisher-Seite die Gewinneranzeige untersucht oder auf andere Weise aus dem Ergebnis von runAdAuction() etwas über ihren Inhalt erfährt. Wenn das Flag resolveToConfig in der AuctionConfig auf „true“ gesetzt wurde, wird ein FencedFrameConfig-Objekt zurückgegeben, das nur in einem umzäunten Frame gerendert werden kann. Wenn das Flag auf „false“ gesetzt wurde, wird eine undurchsichtige URN zurückgegeben, die in einem iFrame gerendert werden kann. Es ist möglich, dass „runAdAuction“ einen Nullwert zurückgibt, was bedeutet, dass keine Anzeige ausgewählt wurde. In diesem Fall kann der Verkäufer eine kontextbezogene Anzeige schalten.