Report sui risultati dell'asta dell'API Protected Audience

Guida per venditori e acquirenti per generare report sulle aste dell'API Protected Audience.

Questo articolo è un riferimento tecnico per la generazione di report sulle vittorie delle aste dell'API Protected Audience, come utilizzato nell'iterazione attuale dell'API Protected Audience sperimentale.

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 sui report a livello di evento (temporanei).

Non sei uno sviluppatore? Consulta la panoramica dell'API Protected Audience.

Che cosa segnala l'API Protected Audience?

Sono disponibili due report sull'API Protected Audience:

  • Report sul venditore: informa il venditore del vincitore dell'asta dell'annuncio.
  • Report per l'acquirente: disponibile solo per gli acquirenti vincenti, per informarli che hanno vinto un'asta.

Il piano a lungo termine è quello di consentire al browser di generare report sui risultati dell'asta per il venditore e gli acquirenti con le API Private Aggregation. Come meccanismo temporaneo di generazione di report a livello di evento, il codice che implementa reportResult() per il venditore e reportWin() per l'offerente vincente può chiamare la funzione sendReportTo(). Questo accetta un singolo argomento: una stringa che rappresenta un URL recuperato al termine dell'asta, che codifica le informazioni a livello di evento da segnalare.

Funzioni API

Venditore: reportResult()

Il codice JavaScript del venditore fornito in decisionLogicUrl (che fornisce anche scoreAd()) può includere una funzione reportResult() per segnalare il risultato dell'asta.

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

Gli argomenti passati a questa funzione sono:

auctionConfig

L'oggetto di configurazione dell'asta passato a navigator.runAdAuction().

browserSignals

Un oggetto creato dal browser che fornisce informazioni sull'asta. Ad esempio:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

Il valore restituito di questa funzione viene utilizzato come argomento sellerSignals per la funzione reportWin() dell'offerente vincente.

Acquirente: reportWin()

Il JavaScript dell'offerente vincente (che ha fornito anche generateBid()) può includere una funzione reportWin() per segnalare l'esito dell'asta.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Gli argomenti passati a questa funzione sono:

auctionSignals e perBuyerSignals

Gli stessi valori trasmessi a generateBid() per l'offerente vincente.

sellerSignals

Il valore di ritorno di reportResult(), che offre al venditore l'opportunità di trasmettere informazioni all'acquirente.

browserSignals

Un oggetto creato dal browser che fornisce informazioni sull'asta. Ad esempio:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

Implementazione temporanea dei report

In Chrome sono temporaneamente disponibili due metodi per la generazione di report sulle aste:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Questi metodi accettano un solo argomento: un URL da recuperare al termine dell'asta. Possono essere chiamati più volte, sia in scoreAd() che in generateBid(), con argomenti URL diversi.

Chrome invia report di debug di perdita/vittoria solo quando un'asta viene completata. Se un'asta viene annullata (ad esempio a causa di una nuova navigazione), non verranno generati report.

Questi metodi sono disponibili per impostazione predefinita in Chrome quando abiliti tutte le API di privacy per gli annunci in chrome://settings/adPrivacy. Se esegui Chrome con flag della riga di comando per abilitare l'API Protected Audience, devi abilitare esplicitamente i metodi includendo il flag BiddingAndScoringDebugReportingAPI. Se il flag non è attivato, i metodi saranno comunque disponibili, ma non faranno nulla.

Tutti i riferimenti API dell'API Protected Audience

Sono disponibili guide di riferimento API:

Il messaggio esplicativo dell'API Protected Audience fornisce anche dettagli sul supporto e sui vincoli delle funzionalità.

Passaggi successivi

Vogliamo interagire con te per assicurarci di creare un'API che funzioni per tutti.

Informazioni sull'API

Come altre API di Privacy Sandbox, questa API è documentata e spiegata pubblicamente.

Sperimenta con l'API

Puoi sperimentare e partecipare alla conversazione sull'API Protected Audience.