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 generare report sulle vittorie delle aste dell'API Protected Audience, come utilizzato nell'iterazione corrente dell'API Protected Audience sperimentale.

Leggi la guida per gli sviluppatori per informazioni sull'intero ciclo di vita dell'API Protected Audience e fai riferimento al messaggio esplicativo 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 indica l'API Protected Audience?

Sono disponibili due report dell'API Protected Audience:

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

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

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

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 codice JavaScript dell'offerente vincente (che forniva anche generateBid()) può includere una funzione reportWin() per segnalare il risultato dell'asta.

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

Gli argomenti passati a questa funzione sono:

auctionSignals e perBuyerSignals

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

sellerSignals

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

browserSignals

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 disponibili temporaneamente due metodi per i report sulle aste:

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

Ciascun metodo prevede un singolo argomento: un URL da recuperare al termine dell'asta. Possono essere richiamate più volte, in scoreAd() e generateBid(), con argomenti URL diversi.

Chrome invia report su vittoria/perdita di debug solo quando un'asta viene eseguita fino al completamento. 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 se chrome://flags/#privacy-sandbox-ads-apis è abilitato. Tuttavia, se esegui Chrome con flag della riga di comando per abilitare l'API Protected Audience, dovrai abilitare esplicitamente i metodi includendo il flag BiddingAndScoringDebugReportingAPI. Se il flag non è abilitato, i metodi saranno comunque disponibili, ma non fare nulla.

Tutti i riferimenti 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.