Eseguire un'asta basata su browser con un singolo venditore

bookmark_border Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

In questo documento troverai una panoramica generale per l'esecuzione di un'asta con i dati di Protected Audience per un singolo venditore, come utilizzato nell'attuale iterazione dell'API Protected Audience. Un'asta con un singolo venditore può essere eseguita nell'ambito di un'asta più complessa che coinvolge più venditori. In questo caso, l'asta con un singolo venditore è indicata come "asta di componenti", che può fornire annunci candidati all'"asta di primo livello" con più venditori partecipanti.

Leggi la guida per gli sviluppatori per conoscere l'intero ciclo di vita dell'API Protected Audience e consulta l'articolo esplicativo sull'API Protected Audience per una discussione approfondita su come i venditori gestiscono le aste on-device.

Sei fasi di un'asta di annunci dell'API Protected Audience

1. Un utente visita un sito che mostra annunci.
2. Il codice del venditore esegue navigator.runAdAuction(). In questo modo viene specificato quale spazio pubblicitario è in vendita e chi può fare offerte. I venditori devono includere anche uno script che assegna un punteggio a ogni offerta, scoreAd().
3. Il codice dell'acquirente invitato viene eseguito per generare un'offerta, l'URL di una creatività dell'annuncio pertinente e altri dati. Lo script di offerta può eseguire query per dati in tempo reale, come il budget rimanente della campagna pubblicitaria, dal servizio Key/Value dell'acquirente.
4. Il codice del venditore assegna un punteggio a ogni offerta e seleziona un'offerta vincente. Questa logica utilizza il valore dell'offerta e altri dati per restituire la desiderabilità di un'offerta. Gli annunci che non riescono a battere l'annuncio di tipo contestuale migliore vengono rifiutati. Il venditore può utilizzare il proprio servizio Key/Value per i dati in tempo reale.
5. L'annuncio vincente viene restituito come valore opaco, che viene visualizzato in un frame delimitato. Né il venditore né l'editore potranno visualizzare questo valore.
6. L'asta viene segnalata al venditore e agli acquirenti vincitori.

Un'asta può essere eseguita quando un utente visita una pagina che mostra un annuncio. Le aste possono essere eseguite in anticipo in modo che la creatività dell'annuncio sia pronta quando lo slot dell'annuncio viene visualizzato.

I venditori avviano l'asta di annunci, assegnano un punteggio agli annunci candidati utilizzando una logica personalizzata fornita come funzione scoreAd() e sono responsabili di segnalare i risultati dell'asta a se stessi e all'acquirente vincente. I venditori possono anche applicare le regole del publisher e filtrare in base alla qualità dell'annuncio utilizzando la loro funzione scoreAd().

Un venditore può fare riferimento a:

• Editori di contenuti che agiscono per conto proprio per ospitare contenuti degli annunci sul proprio sito web
• Supply-Side Platform (SSP), che collaborano con il publisher dell'annuncio e forniscono altri servizi
• Script di terze parti che agiscono per conto di un publisher per consentire la partecipazione alle aste di annunci.

Prerequisiti per l'organizzazione di un'asta

Per poter eseguire un'asta, un venditore deve definire due funzioni JavaScript:

• scoreAd(), che assegna un punteggio a un annuncio candidato
• reportResult(), che si occupa di segnalare il risultato dell'asta al venditore stesso

Questi script devono essere pubblicati da un unico endpoint di proprietà del venditore.

scoreAd()

Un venditore deve definire una funzione scoreAd() pubblicata da un endpoint di sua proprietà. L'endpoint viene specificato nella configurazione dell'asta come decisionLogicUrl. La funzione scoreAd() ha la seguente firma:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

I parametri scoreAd() sono:

• adMetaData, ovvero metadati arbitrari sulla creatività dell'annuncio forniti dall'acquirente. Si tratta di un oggetto JSON serializzabile che venditori e acquirenti dovranno definire e concordare sulla struttura.
• bid, che è un valore numerico che rappresenta l'offerta.
• auctionConfig, ovvero la configurazione dell'asta utilizzata per eseguirla.
• trustedScoringSignals, ovvero indicatori letti al momento dell'asta dal server Key/Value del venditore. La piattaforma utilizzerà il valore renderUrl dell'annuncio candidato come chiave per questa ricerca.
• browserSignals, che è un oggetto creato dal browser, incluse informazioni che il browser conosce e che lo script dell'asta del venditore potrebbe voler verificare.
• directFromSellerSignals è un oggetto che può contenere i seguenti campi: ** sellerSignals: come auctionConfig.sellerSignals, ma passato utilizzando il meccanismo directFromSellerSignals. ** auctionSignals: come auctionConfig.auctionSignals, ma passato utilizzando il meccanismo directFromSellerSignals.

Di seguito è riportato un esempio di browserSignals. Tieni presente che il renderUrl dell'annuncio candidato è disponibile tramite questi indicatori:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Un venditore deve definire una funzione reportResult() pubblicata da un endpoint di sua proprietà. L'endpoint viene specificato nella configurazione dell'asta come decisionLogicUrl. La funzione reportResult() ha la seguente firma:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

I parametri reportResult() sono:

• auctionConfig, ovvero la configurazione dell'asta utilizzata per eseguirla.
• browserSignals, che è un oggetto creato dal browser, incluse informazioni che il browser conosce e che lo script dell'asta del venditore potrebbe voler verificare. Si tratta dello stesso oggetto passato alla funzione scoreAds().

reportResult() restituisce signalsForWinner, un oggetto JSON arbitrario che viene passato alla funzione di generazione di report dell'acquirente vincente. Deve includere tutte le informazioni pertinenti che il venditore può fornire sull'asta e che l'acquirente richiede per i report.

Eseguire un'asta con l'API Protected Audience

Un venditore deve seguire quattro passaggi principali per gestire un'asta. Tieni presente che questi passaggi presuppongono che il venditore abbia configurato un endpoint per restituire il codice JavaScript richiesto precedentemente menzionato in questa guida.

1. Configura l'asta. Questo passaggio include la creazione di un oggetto auctionConfig. In questo modo, il venditore può specificare quali acquirenti devono partecipare all'asta, nonché fornire eventuali indicatori che potrebbero essere pertinenti durante la generazione delle offerte o la valutazione degli annunci.
2. Esegui l'asta chiamando navigator.runAdAuction(), passando la configurazione creata nel passaggio precedente. Viene così avviata la catena di acquirenti che generano offerte e poi vengono assegnati i punteggi. Il risultato finale di questo passaggio è un annuncio candidato che può essere visualizzato per mostrare un annuncio.
3. Esegui il rendering dell'annuncio vincente in un frame o in un iframe delimitato.
4. Segnala il risultato dell'asta. Esiste una funzione, navigator.sendReportTo(), che avvia la generazione di report. Il venditore riceverà sempre un report sui risultati dell'asta. Solo l'acquirente che ha vinto l'asta riceverà un report. Per inviare i report al server, viene utilizzato il reportResult() del venditore descritto in precedenza in questa guida.