Eseguire un'asta basata su browser con un singolo venditore

In questo documento troverai una panoramica generale sull'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 solo venditore può essere eseguita nell'ambito di un'asta più complessa che coinvolge più venditori. In questo caso, l'asta per singolo venditore è definita "asta di componenti", che può fornire candidati degli annunci all'"asta di primo livello" a cui partecipano più venditori.

Leggi la guida per gli sviluppatori per informazioni sull'intero ciclo di vita dell'API Protected Audience e consulta la sezione esplicativa dell'API Protected Audience per un'analisi approfondita su come i venditori eseguono le aste on-device.

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

Questo diagramma illustra ogni fase dell'asta dell'annuncio dell'API Protected Audience.

1. Un utente visita un sito che pubblica annunci.
2. Il codice del venditore esegue il giorno navigator.runAdAuction(). che specifica quale spazio pubblicitario è in vendita e chi può fare offerte. I venditori devono anche includere uno script che attribuisca un punteggio a ogni offerta, scoreAd().
3. Il codice dell'acquirente invitato viene eseguito per generare un'offerta, l'URL per una creatività dell'annuncio pertinente e altri dati. Lo script di offerta può eseguire query su dati in tempo reale, ad esempio il budget rimanente della campagna pubblicitaria, dal servizio chiave/valore dell'acquirente.
4. Il codice del venditore assegna un punteggio a ogni offerta e seleziona un vincitore. Questa logica utilizza il valore dell'offerta e altri dati restituiscono l'opportunità di un'offerta. Gli annunci che non possono battere il vincitore contestuale vengono rifiutati. Il venditore può utilizzare il proprio servizio chiave/valore per ottenere dati in tempo reale.
5. L'annuncio vincente viene restituito sotto forma di valore opaco, che viene mostrato in un frame recintato. Sia il venditore sia l'editore non saranno in grado di visualizzare questo valore.
6. L'asta viene segnalata al venditore e agli acquirenti vincenti.

Un'asta può avvenire quando un utente accede a una pagina in cui è pubblicato un annuncio. Le aste possono essere eseguite in anticipo in modo che la creatività dell'annuncio sia pronta quando viene visualizzata l'area annuncio.

I venditori avviano l'asta dell'annuncio, 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 per i publisher e filtrare i dati in base alla qualità degli annunci utilizzando la funzione scoreAd().

Un venditore può fare riferimento a:

• Publisher di contenuti, che agiscono autonomamente per ospitare i contenuti degli annunci sul proprio sito web
• Supply-Side Platform (SSP), collaborazione con il publisher dell'annuncio e fornitura di altri servizi
• Script di terze parti che fungono da publisher per consentire la partecipazione alle aste dell'annuncio.

Prerequisiti per l'esecuzione di un'asta

Un venditore deve definire due funzioni JavaScript per poter eseguire un'asta:

• scoreAd(), che assegna un punteggio a un candidato dell'annuncio
• reportResult(), che gestisce la segnalazione del risultato dell'asta al venditore stesso

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

scoreAd()

Un venditore deve definire una funzione scoreAd() che viene 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, che sono metadati arbitrari relativi alla creatività dell'annuncio fornita dall'acquirente. Si tratta di un oggetto serializzabile JSON che venditori e acquirenti dovranno definire e concordare la struttura.
• bid, che è un valore numerico che rappresenta l'offerta.
• auctionConfig, che è la configurazione utilizzata per eseguirla.
• trustedScoringSignals, che sono indicatori letti al momento dell'asta dal server chiave/valore del venditore. La piattaforma utilizzerà il renderUrl dell'annuncio del candidato come chiave per questa ricerca.
• browserSignals, che è un oggetto creato dal browser, che include informazioni note al browser e quali lo script di asta del venditore potrebbe voler verificare.
• directFromSellerSignals è un oggetto che può contenere i seguenti campi: ** sellerSignals: come auctionConfig.sellerSignals, ma trasmesso utilizzando il meccanismo directFromSellerSignals. ** auctionSignals: come auctionConfig.auctionSignals, ma viene superato utilizzando il meccanismo directFromSellerSignals.

Di seguito è riportato un esempio di browserSignals. Tieni presente che il valore renderUrl dell'annuncio del 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() che viene pubblicata da un endpoint di sua proprietà. L'endpoint è specificato nella configurazione dell'asta come decisionLogicUrl. La funzione reportResult() ha la seguente firma:

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

I parametri reportResult() sono:

• auctionConfig, che è la configurazione utilizzata per eseguirla.
• browserSignals, che è un oggetto creato dal browser, che include informazioni note al browser e quali lo script di asta del venditore potrebbe voler verificare. Si tratta dello stesso oggetto passato alla funzione scoreAds().

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

Eseguire un'asta dell'API Protected Audience

Sono quattro i passaggi principali che un venditore deve eseguire per poter eseguire un'asta. Tieni presente che questi passaggi presuppongono che il venditore abbia un endpoint configurato per restituire il codice JavaScript richiesto in precedenza menzionato in questa guida.

1. Configurare l'asta. Questo passaggio include la creazione di un oggetto auctionConfig. Ciò consente al venditore di specificare quali acquirenti devono partecipare all'asta, oltre a fornire eventuali indicatori che potrebbero essere pertinenti durante la generazione dell'offerta o il punteggio degli annunci.
2. Esegui l'asta chiamando navigator.runAdAuction(), passando la configurazione creata nel passaggio precedente. Questo avvia la catena di acquirenti che genera le offerte e poi assegna un punteggio. Il risultato finale di questo passaggio è un candidato che può essere visualizzato in modo da visualizzare un annuncio.
3. Esegui il rendering dell'annuncio vincente in un frame o iframe recintato.
4. Segnala il risultato dell'asta. È presente una funzione, navigator.sendReportTo(), che avvierà la generazione di report. Il venditore riceverà sempre un report sui risultati dell'asta. Solo l'acquirente che ha vinto l'asta riceve un report. Vengono utilizzati i reportResult() del venditore descritti in precedenza in questa guida per la segnalazione al server.