Scopri come configurare un'asta dell'API Protected Audience.
Aste on-device condotte dai venditori
Un'asta Protected Audience on-device viene eseguita su un sito che vende spazi pubblicitari e ci riferiamo alla parte che esegue l'asta come venditore. Molte parti potrebbero agire come venditori: un sito potrebbe eseguire la propria asta dell'annuncio o includere uno script di terze parti per eseguire l'asta oppure utilizzare una SSP che combina l'esecuzione di un'asta on-device con altre attività di asta dell'annuncio lato server. I venditori svolgono tre attività di base nell'asta dell'annuncio on-device:
- I venditori decidono (a) quali acquirenti possono partecipare e (b) quali offerte provenienti dai gruppi di interesse di tali acquirenti sono idonee a partecipare all'asta. Questo consente al venditore di applicare le regole del sito relative a quali annunci possono essere pubblicati sulla pagina.
- I venditori sono responsabili della logica di business dell'asta: codice JavaScript che considera il prezzo e i metadati di ogni offerta e calcola il punteggio di "desiderabilità". L'offerta con il punteggio di desiderabilità più alto vince l'asta.
- I venditori eseguono report sul risultato dell'asta, incluse informazioni sul prezzo di compensazione ed eventuali altri pagamenti. Anche gli acquirenti vincenti e perdenti possono generare i propri report.
Questo documento spiega come configurare e avviare un'asta on-device.
Configurare un'asta dell'annuncio dell'API Protected Audience
Per eseguire un'asta dell'annuncio dell'API Protected Audience, il primo passaggio consiste
nel configurarla. A questo scopo, crea un oggetto auctionConfig
.
Ecco un esempio di una di queste configurazioni:
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
strutture
Proprietà obbligatorie
Le uniche proprietà obbligatorie per auctionConfigs
sono seller
,
decisionLogicUrl
e interestGroupBuyers
.
Proprietà | Esempio | Ruolo |
---|---|---|
seller | https://seller.example | Origine del venditore. |
decisionLogicUrl | https://seller.example/decision-logic.js | URL per il worklet della logica decisionale JavaScript dell'asta. Questo campo deve avere la stessa origine del campo del venditore. |
interestGroupBuyers | [https://buyer-1.example, https://buyer-2.example, ...] |
Origini di tutti i proprietari di gruppi di interesse a cui è stato chiesto di fare un'offerta nell'asta |
Proprietà facoltative
Le restanti proprietà per auctionConfigs
sono facoltative.
Proprietà | Esempio | Ruolo |
---|---|---|
trustedScoringSignalsUrl | https://seller.example/scoring-signals | URL del server chiave/valore del venditore. Verrà effettuata una query su questo aspetto durante il processo di valutazione degli annunci, utilizzando l'URL di rendering della creatività come chiave. Questo campo deve avere la stessa origine del campo del venditore. |
auctionSignals | {"category":"news"} | Oggetto seriale JSON che rappresenta gli indicatori disponibili per tutti gli acquirenti e i venditori che partecipano all'asta. |
sellerSignals | {...} | Oggetto serializzabile JSON che rappresenta gli indicatori disponibili solo per i venditori. |
perBuyerSignals | {https://dsp.example: {...}, https://another-buyer.example: {...}, ... } |
Indicatori disponibili per un acquirente specifico. Gli indicatori possono provenire dai venditori e anche dagli acquirenti stessi. |
perBuyerTimeouts | {https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...}, |
Tempo di esecuzione massimo in millisecondi dello script generateBid() di un determinato acquirente. A ogni acquirente per cui non è stato definito un timeout specifico verrà applicato un carattere jolly. |
sellerTimeout | 100 | Tempo di esecuzione massimo in millisecondi dello script scoreAd() di un venditore. |
componentAuctions | [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] | Configurazioni aggiuntive per aste di componenti. |
resolveToConfig | vero|falso | Un valore booleano che indirizza la promessa restituita da runAdauction() a FencedFrameConfig se true (per l'uso in un <fencedframe>) o a un URL urn:uuid opaco se false (per l'uso in un <iframe>). Il valore predefinito è false. |
Fornisci indicatori in modo asincrono
Facoltativamente, i valori di alcuni indicatori (configurati dai campi auctionSignals
, sellerSignals
, perBuyerSignals
e perBuyerTimeouts
) possono essere forniti non come valori concreti, ma come Promise. Ciò consente ad alcune parti dell'asta, come il caricamento di script e indicatori attendibili, e l'avvio di processi di worklet isolati, di sovrapporsi al calcolo (o al recupero della rete) di questi valori. Gli script di worklet vedranno solo i valori risolti; se una promessa di questo tipo viene rifiutata, l'asta verrà interrotta a meno che non risulti già fallita o venga interrotta in altri modi.
Configurare un'asta con più venditori
In alcuni casi, più venditori potrebbero voler partecipare a un'asta. I vincitori di aste separate vengono superati a un'altra asta gestita da un altro venditore. Queste aste separate che vengono ignorate sono chiamate aste dei componenti.
Per facilitare queste aste dei componenti, l'oggetto componentAuctions
può contenere
ulteriori configurazioni per l'asta dei componenti di ogni venditore. L'offerta vincente di ciascuna di queste aste componenti viene passata all'asta di "primo livello" che determina l'asta finale. L'elemento
auctionConfig
delle aste dei componenti potrebbe non avere un
componentAuctions
proprio. Se componentAuctions
non è vuoto,
interestGroupBuyers
deve essere vuoto. In altre parole, per ogni asta di Protected Audience esiste un unico venditore e non esistono aste dei componenti, oppure tutte le offerte provengono da aste dei componenti e l'asta di primo livello può scegliere solo tra i vincitori delle aste dei componenti.
Eseguire l'asta
Il venditore invia una richiesta al browser dell'utente per iniziare un'asta dell'annuncio
chiamando navigator.runAdAuction()
.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
La chiamata runAdAuction()
restituisce una promessa che si risolve nell'annuncio. Nessun codice nella pagina del publisher consente di esaminare l'annuncio vincente o di scoprire in altro modo i suoi contenuti a partire dal risultato di runAdAuction()
. Se il flag resolveToConfig
è stato impostato su true in AuctionConfig
, viene restituito un oggetto FencedFrameConfig
che può essere visualizzato solo in un frame isolato. Se il flag è impostato su false, viene restituito un URN opaco che può essere visualizzato in un iframe. È possibile che runAdauction restituisca un valore null, che indica che non è stato selezionato alcun annuncio. In questo caso, il venditore può scegliere di
visualizzare un annuncio con targeting contestuale.