Eseguire un'asta basata su browser con un singolo venditore

In questo documento troverai una panoramica di alto livello per l'esecuzione di un'asta con dati Protected Audience per un singolo venditore, come utilizzato nell'iterazione attuale 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 con un solo venditore viene definita "asta componente", che può fornire candidati annuncio all'"asta di primo livello" a cui partecipano più venditori.

Leggi la guida per gli sviluppatori per l'intero ciclo di vita dell'API Protected Audience e consulta la spiegazione dell'API Protected Audience per una discussione approfondita su come i venditori eseguono 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 viene eseguito navigator.runAdAuction(). Specifica 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 i dati in tempo reale, come 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 per restituire l'utilità di un'offerta. Gli annunci che non possono battere il vincitore contestuale 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 recintato. Né il venditore né l'editore potranno visualizzare questo valore.
6. L'asta viene segnalata al venditore e agli acquirenti vincitori.

Un'asta può svolgersi 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 spazio pubblicitario diventa visibile.

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

Un venditore può fare riferimento a:

• Editori di contenuti, che agiscono in prima persona per ospitare contenuti pubblicitari sul proprio sito web
• Supply-Side Platform (SSP), che collaborano con l'editore di annunci e forniscono altri servizi
• Script di terze parti che agiscono per conto di un publisher per consentire la partecipazione alle aste pubblicitarie.

Prerequisiti per l'esecuzione di un'asta

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

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

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 è 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 serializzabile JSON che venditori e acquirenti dovranno definire e concordare la struttura.
• bid, un valore numerico che rappresenta l'offerta.
• auctionConfig, ovvero la configurazione dell'asta utilizzata per eseguire l'asta.
• trustedScoringSignals, ovvero indicatori letti al momento dell'asta dal server Key/Value del venditore. La piattaforma utilizzerà il renderUrl dell'annuncio candidato come chiave per questa ricerca.
• browserSignals, un oggetto creato dal browser, che include informazioni note al browser 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 è 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 eseguire l'asta.
• browserSignals, un oggetto creato dal browser, che include informazioni note al browser e che lo script dell'asta del venditore potrebbe voler verificare. Si tratta dello stesso oggetto passato alla funzione scoreAds().

reportResult() restituisce signalsForWinner, che è un oggetto JSON arbitrario che viene passato alla funzione di generazione dei report dell'acquirente vincente. Devono essere incluse tutte le informazioni pertinenti che il venditore può fornire sull'asta di cui l'acquirente ha bisogno per i suoi report.

Esegui un'asta dell'API Protected Audience

Un venditore deve eseguire quattro passaggi principali per organizzare un'asta. Tieni presente che questi passaggi presuppongono che il venditore abbia configurato un endpoint per restituire il codice JavaScript richiesto menzionato in precedenza 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 e fornire eventuali indicatori che potrebbero essere pertinenti durante la generazione delle offerte o l'assegnazione del punteggio agli annunci.
2. Esegui l'asta chiamando navigator.runAdAuction(), passando la configurazione creata nel passaggio precedente. Inizia la catena di acquirenti che generano offerte, poi punteggi. Il risultato finale di questo passaggio è un candidato annuncio che può essere visualizzato per mostrare un annuncio.
3. Esegui il rendering dell'annuncio vincente in un frame recintato o in un iframe.
4. Report the result of the auction. Esiste 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 riceverà un report. Utilizza reportResult() del venditore descritto in precedenza in questa guida per inviare report al server.