Hier erfahren Sie, wie Sie eine Protected Audience API-Auktion konfigurieren.
On-Device-Auktionen von Verkäufern
Eine Protected Audience-Auktion auf dem Gerät wird auf einer Website durchgeführt, auf der Werbeflächen verkauft werden. Der Auktionsanbieter ist dabei der Verkäufer. Viele Anbieter agieren als Verkäufer: Eine Website kann eine eigene Anzeigenauktion durchführen, ein Drittanbieter-Script für die Auktion verwenden oder eine SSP nutzen, die eine On-Device-Auktion mit anderen serverseitigen Anzeigenauktionen kombiniert. Verkäufer haben in der On-Device-Anzeigenauktion drei grundlegende Jobs:
- Verkäufer entscheiden, (a) welche Käufer teilnehmen können und (b) welche Gebote aus den Interessengruppen dieser Käufer an der Auktion teilnehmen. So kann der Verkäufer auf der Website selbst festlegen, welche Anzeigen auf der Seite präsentiert werden dürfen.
- Verkäufer sind für die Geschäftslogik der Auktion verantwortlich: der JavaScript-Code, der den Preis und die Metadaten jedes Gebots berücksichtigt und einen Wunschwert für die Auktion berechnet. Das Gebot mit dem höchsten Wunschwert gewinnt die Auktion.
- Die Verkäufer erstellen Berichte zum Auktionsergebnis, einschließlich Informationen über den Tiefstpreis und andere Auszahlungen. Die erfolgreichen und unterlegenen Käufer erhalten ihre eigenen Berichte.
In diesem Dokument wird erläutert, wie Sie eine On-Device-Auktion konfigurieren und initiieren.
Protected Audience API-Anzeigenauktion konfigurieren
Wenn Sie eine Protected Audience API-Anzeigenauktion durchführen möchten, müssen Sie zuerst die Auktion konfigurieren. Dazu wird ein auctionConfig-Objekt erstellt.
Hier ist 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 Attribute für auctionConfigs sind seller, decisionLogicUrl und interestGroupBuyers.
| Property | Beispiel | Rolle |
|---|---|---|
| seller | https://seller.example | Der Ursprung des Verkäufers. |
| decisionLogicUrl | https://seller.example/decision-logic.js | URL für das Worklet für die JavaScript-Entscheidungslogik bei Auktionen. Dieses Feld muss denselben Ursprung wie das Feld „Verkäufer“ haben. |
| interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Ursprünge aller Inhaber einer Interessengruppe, die in der Auktion Gebote abgeben möchten |
Optionale Attribute
Die verbleibenden Attribute für auctionConfigs sind optional.
| Property | Beispiel | Rolle |
|---|---|---|
| trustedScoringSignalsUrl | https://seller.example/scoring-signals | URL des Schlüssel-/Wert-Servers des Verkäufers. Diese wird während der Anzeigenbewertung abgefragt, wobei die Rendering-URL des Creatives als Schlüssel verwendet wird. Dieses Feld muss denselben Ursprung wie das Feld „Verkäufer“ haben. |
| auctionSignals | {"category":"news"} | Serialisierbares JSON-Objekt, das die Signale darstellt, die allen an der Auktion teilnehmenden Käufern und Verkäufern zur Verfügung stehen. |
| sellerSignals | {...} | Serialisierbares JSON-Objekt, das Signale darstellt, die nur für Verkäufer verfügbar sind. |
| perBuyerSignals | {https://dsp.beispiel: {...}, https://anderer-käufer.beispiel: {...}, ... } |
Signale, die für einen bestimmten Käufer verfügbar sind. Diese Signale können von den Verkäufern und auch von den Käufern selbst stammen. |
| perBuyerTimeouts | {https://www.beispiel-dsp.de: 50, https://www.andere-käufer.de: 200, *: 150, ...}, |
Maximale Laufzeit des „generateBid()“-Skripts eines bestimmten Käufers in Millisekunden. Für jeden Käufer, für den kein bestimmtes Zeitlimit festgelegt ist, wird ein Platzhaltersymbol verwendet. |
| sellerTimeout | 100 | Maximale Laufzeit des ScoreAd()-Skripts eines Verkäufers in Millisekunden. |
| componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Zusätzliche Konfigurationen für Komponentenauktionen. |
| resolveToConfig | wahr|falsch | Ein boolescher Wert, der das von runAdAuction() zurückgegebene Versprechen anweist, in ein FencedFrameConfig-Objekt aufzulösen, wenn es wahr ist (zur Verwendung in einem <fencedframe>), oder in eine intransparente urn:uuid-URL, wenn es falsch ist (zur Verwendung in einem <iframe>). Der Standardwert ist „falsch“. |
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 Promise-Werte 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 Netzwerkabruf) dieser Werte überschneiden. Die Worklet-Skripts sehen nur die aufgelösten Werte. Wird ein Promise abgelehnt, wird die Auktion abgebrochen, sofern es nicht erfolgreich war oder anderweitig abgebrochen wird.
Auktion mit mehreren Verkäufern konfigurieren
In einigen Fällen möchten vielleicht mehrere Verkäufer an einer Auktion teilnehmen, wobei die Gewinner separater Auktionen an eine andere Auktion übergeben werden, die von einem anderen Verkäufer durchgeführt wird. Diese separaten Auktionen, die ignoriert werden, werden als Komponentenauktionen bezeichnet.
Um diese Komponentenauktionen zu erleichtern, kann das componentAuctions-Objekt zusätzliche Auktionskonfigurationen für die einzelnen Komponentenauktionen der einzelnen Verkäufer enthalten. Das erfolgreiche Gebot jeder dieser Komponentenauktionen wird an die Auktion der obersten Ebene übergeben. Damit wird die Auktion endgültig festgelegt. Die auctionConfig der Auktionen mit Komponenten hat möglicherweise keinen eigenen 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 Auktionen mit Komponenten oder alle Gebote stammen aus Auktionen mit Komponenten und die Auktion der obersten Ebene kann nur unter den Gewinnern der einzelnen Auktionen auswählen.
Auktion durchführen
Der Verkäufer sendet durch Aufrufen von navigator.runAdAuction() eine Anfrage an den Browser des Nutzers, um eine Anzeigenauktion zu starten.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
Der Aufruf runAdAuction() gibt ein Promise zurück, das in die Anzeige aufgelöst wird. Es ist nicht möglich, mit Code auf der Publisher-Seite die erfolgreiche Anzeige zu prüfen oder anhand des Ergebnisses von runAdAuction() mehr über ihren Inhalt zu erfahren. Wenn das Flag resolveToConfig in AuctionConfig auf „true“ gesetzt wurde, wird ein FencedFrameConfig-Objekt zurückgegeben, das nur in einem Fenced Frame gerendert werden kann. Wenn das Flag auf „false“ gesetzt ist, wird eine intransparente URN zurückgegeben, die in einem iFrame gerendert werden kann. Unter Umständen gibt „runAdAuction“ einen Nullwert zurück, was bedeutet, dass keine Anzeige ausgewählt wurde. In diesem Fall kann der Verkäufer eine kontextbezogene Anzeige rendern.