Scopri come configurare un'asta dell'API Protected Audience.
Aste on-device gestite da venditori
Un'asta Protected Audience viene eseguita su un sito che vende spazi pubblicitari e noi si riferisce alla parte che gestisce l'asta come il venditore. Molte parti possono agire venditori: un sito potrebbe eseguire la propria asta dell'annuncio o includere una terza parte uno script per eseguire l'asta o utilizzare una SSP che combina l'esecuzione asta on-device con altre attività di asta dell'annuncio lato server. I venditori hanno tre attività di base nell'asta degli annunci on-device:
- Sono i venditori a decidere (a) quali acquirenti possono partecipare e (b) quali offerte dagli acquirenti gruppi basati sugli interessi sono idonei a partecipare all'asta. Ciò consente il venditore applica le regole del sito relative a quali annunci possono essere pubblicati .
- I venditori sono responsabili della logica di business dell'asta: JavaScript che tiene conto del prezzo e dei metadati di ciascuna offerta e calcola un "desiderabilità" punteggio. L'offerta con il punteggio di desiderabilità più alto vince il in un'asta.
- I venditori eseguono report sul risultato dell'asta, incluse informazioni su prezzo di liquidazione ed eventuali altri pagamenti. Anche gli acquirenti vincenti e perdenti ottengono a svolgere i propri report.
Questo documento spiega come configurare e avviare un'asta on-device.
Configurare un'asta dell'annuncio con l'API Protected Audience
Per eseguire un'asta dell'annuncio con l'API Protected Audience, la prima cosa da fare è
configurare l'asta. Per farlo, occorre creare 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 del worklet della logica decisionale JavaScript per l'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 offerte 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à eseguita una query 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 serializzabile 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. Un carattere jolly viene applicato a tutti gli acquirenti per i quali non è stato definito un timeout specifico. |
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 le aste dei componenti. |
resolveToConfig | vero | Un valore booleano che indirizza la promessa restituita da runAdauction() per risolverla in un FencedFrameConfig se true (per l'utilizzo in un <fencedframe>) o a un URL urn:uuid opaco se false (per l'utilizzo in un <iframe>). Il valore predefinito è false. |
Fornisci indicatori in modo asincrono
I valori di alcuni indicatori (quelli configurati da auctionSignals
,
sellerSignals
, perBuyerSignals
e perBuyerTimeouts
) può
facoltativamente essere forniti non come valori concreti, ma come Promises. Ciò consente
alcune parti dell'asta, come il caricamento di script e indicatori attendibili, e
di processi isolati di worklet, per sovrapporsi al calcolo (o
recupero) di questi valori. Gli script di worklet vedranno solo
valori; se una tale Promessa viene rifiutata, l'asta verrà interrotta a meno che
già fallito o viene interrotto in altri modi.
Configurare un'asta con più venditori
In alcuni casi, più venditori potrebbero voler partecipare a un'asta, con i
vincitori di aste separate che vengono passate 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
configurazioni dell'asta aggiuntive per l'asta dei componenti di ciascun venditore. La
l'offerta vincente di ciascuna di queste aste verrà trasmessa
"di primo livello" che determina l'asta. La
Il auctionConfig
delle aste dei componenti potrebbe non avere una propria
componentAuctions
. Quando il campo componentAuctions
non è vuoto,
Il campo interestGroupBuyers
deve essere vuoto. Vale a dire, per ogni particolare
Asta per pubblico, in presenza di un singolo venditore e senza aste di componenti oppure
altrimenti tutte le offerte provengono da aste dei componenti e l'asta di primo livello può
scegliere tra le aste dei componenti vincitori.
Eseguire l'asta
Il venditore invia una richiesta al browser dell'utente per avviare un'asta dell'annuncio
chiamata navigator.runAdAuction()
.
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
La chiamata runAdAuction()
restituisce una promessa che si risolve nell'annuncio. Non è
possibile che qualsiasi codice sulla pagina del publisher esamini l'annuncio vincente o
altrimenti scoprirne i contenuti dal risultato di runAdAuction()
. Se
Il flag resolveToConfig
è stato impostato su true in AuctionConfig
, un
Viene restituito un oggetto FencedFrameConfig
che può essere visualizzato solo in un ambiente recintato
frame. Se il flag è stato impostato su false, viene restituito un URN opaco che può essere
visualizzato in un iframe. È possibile che runAdauction restituisca un valore nullo,
per indicare che non è stato selezionato alcun annuncio. In questo caso, il venditore potrebbe decidere di
un annuncio con targeting contestuale.