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

API reference guides are available:

• Developer guide for the Protected Audience API.
• Ad buyer guide to Protected Audience interest groups and bid generation.
• Ad seller guide to Protected Audience ad auctions.
• Guide to reporting auction results
• Best practices for Protected Audience ad auction latency
• Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.