Imposta un'asta dell'annuncio sulla pagina del publisher

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:

1. 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.
2. 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.
3. 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

Nota: additionalBids non è supportato nell'attuale implementazione dell'API Protected Audience. Per saperne di più, leggi la sezione Partecipanti all'asta nel messaggio esplicativo dell'API Protected Audience.

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.