Report sulle aste dell'API Protected Audience

Misurare i dati e i risultati delle aste dell'API Protected Audience

In questo articolo troverai una panoramica generale dei vari meccanismi disponibili per segnalare i dati delle aste dell'API Protected Audience al tuo server. Inoltre, troverai i meccanismi di transizione attualmente disponibili e utilizzabili durante la migrazione finché non saranno pronte soluzioni alternative.

Per generare report su metriche importanti raccolte da un'asta dell'annuncio, l'API Protected Audience utilizza:

• Aggregazione privata che raccoglie indicatori e risultati delle aste per generare report di riepilogo.
• L'API Ads Reporting per frame schermati e iframe, che è un canale all'interno dei frame per comunicare con i worklet dell'API Protected Audience. L'API consente di associare i dati a livello di evento agli indicatori delle aste. Il reporting a livello di evento dell'API Ads Reporting è un meccanismo di transizione fino a quando non viene progettato un meccanismo di reporting più privato.
• Attribution Reporting ti consente di associare i dati sulle conversioni agli indicatori delle aste.
• Spazio di archiviazione condiviso, che consente di scrivere segnali di asta in uno spazio di archiviazione multiorigine e poi di registrare i dati in un secondo momento utilizzando l'aggregazione privata.

Panoramica dei report dell'API Protected Audience

Sono tre i periodi di tempo principali in cui i dati del flusso di asta dell'API Protected Audience possono essere segnalati al server: il momento dell'asta, quando l'asta viene eseguita dal sito del publisher, il tempo di rendering, quando l'annuncio viene visualizzato in un frame recintato o un iframe sul sito del publisher, e la data e l'ora della conversione, quando l'utente esegue un'azione su un altro sito attribuibile all'asta.

Durante il momento dell'asta, puoi generare report sui dati dell'asta utilizzando i worklet di reporting. Durante il tempo di rendering, puoi registrare i dati sul coinvolgimento da un iframe o un frame recintato. Durante il momento della conversione, puoi generare report sui dati sull'attribuzione dalla pagina di destinazione utilizzando l'API Attribution Reporting.

Segnalare località

Nell'ambito di un'asta, gli acquirenti possono segnalare gli indicatori disponibili nei worklet generateBid() e reportWin(), mentre i venditori possono segnalare gli indicatori disponibili in scoreAd() e reportResult(). Al di fuori di un'asta, acquirenti e venditori possono registrare i dati provenienti da un frame in cui è stato visualizzato l'annuncio e dal sito da cui è stata effettuata la conversione.

Durante ciascuno dei periodi di tempo elencati, acquirenti e venditori avranno accesso a varie API di reporting disponibili per generare report su dati come indicatori delle aste, dati a livello di evento e dati sulle conversioni.

Dati disponibili in un'asta dell'API Protected Audience

I seguenti dati sono disponibili per essere inclusi nei report da un worklet dell'API Protected Audience durante l'asta.

Indicatori

Gli indicatori sono i dati contestuali dell'asta, i dati utente, i dati in tempo reale e i dati sui browser disponibili per acquirenti e venditori all'interno di un worklet per generare un'offerta, assegnare un punteggio a un annuncio e segnalare i risultati di un'asta.

L'oggetto configurazione delle aste è l'origine principale dei dati forniti per diventare disponibili come indicatori nei worklet. Il publisher e il venditore possono fornire dati contestuali e proprietari nella configurazione dell'asta; questi indicatori possono essere arricchiti con i dati sul gruppo di interesse dell'acquirente, i dati a livello di evento dal frame di rendering dell'annuncio e i dati di attribuzione dalla pagina clickthrough. I dati riportati possono essere utilizzati per la generazione di report su acquirenti/venditori, la fatturazione, la definizione del budget, l'addestramento dei modelli ML e altro ancora.

Altri dati disponibili

• Dati sui risultati relativi ai dati sulla vittoria e sulla perdita dell'asta, ad esempio il prezzo dell'offerta vincente e il motivo del rifiuto dell'offerta.
• Dati sul rendimento che contengono informazioni sulla latenza, come il tempo necessario per recuperare ed eseguire il worklet di offerta.

Dati disponibili al di fuori di un'asta dell'API Protected Audience

Al di fuori di un'asta dell'API Protected Audience, esistono due periodi di tempo in cui i dati sono disponibili per essere registrati.

Durante il tempo di rendering, quando l'annuncio viene visualizzato sul sito del publisher, i dati a livello di evento all'interno dell'iframe o del frame recintato possono essere associati ai dati di asta dell'API Protected Audience e segnalati al tuo server. Esempi di dati a livello di evento includono impressioni dell'annuncio, clickthrough, passaggio del mouse e qualsiasi altro evento che si verifica all'interno del frame.

Durante il momento della conversione, quando un utente esegue sulla pagina di clickthrough un'azione che viene attribuita nuovamente all'asta, i dati a livello di evento della pagina di conversione possono essere associati ai dati delle aste dell'API Protected Audience e riportati sul tuo server.

Report a livello di evento

I report a livello di evento forniscono informazioni dettagliate su uno o più eventi. Un evento può essere una vittoria in un'asta, un'impressione dell'annuncio o una conversione. Fino al 2026, i report sulle vittorie dell'asta a livello di evento rimarranno attivi, non saranno necessari frame protetti per visualizzare un annuncio Protected Audience e un iframe con accesso alla rete non vincolato può essere utilizzato per i report a livello di evento. Inoltre, l'API Ads Reporting è disponibile in frame e iframe recintati per consentirti di associare i dati su aste e conversioni ai dati a livello di evento del frame. Questa soluzione è stata concepita per consentire all'ecosistema di avere un percorso di migrazione più semplice, dal momento che puoi continuare a utilizzare la tua infrastruttura di generazione di report esistente almeno fino al 2026 durante la migrazione del sistema a Protected Audience.

Report sulle vincite dell'asta a livello di evento con sendReportTo()

Un meccanismo disponibile per generare report sui dati a livello di evento all'interno di un'asta Protected Audience è il sendReportTo() function in caso di vincita di un'asta. La funzione è disponibile nei worklet per i report per acquirente e venditore e il browser invia una richiesta GET alla stringa dell'URL fornita quando inizia il rendering dell'annuncio. Puoi codificare qualsiasi indicatore disponibile nei tuoi worklet come parametri di query dell'URL.

Ad esempio, un acquirente può segnalare l'importo dell'offerta vincente dal worklet reportWin() ai fini della fatturazione:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

La funzione sendReportTo() può essere utilizzata per generare un report sulle vittorie per il venditore quando viene chiamato da reportResult() e un report sulle vittorie per l'acquirente quando viene chiamato da reportWin(). La funzione sendReportTo() è disponibile almeno fino al 2026,

Report Coinvolgimento

Un report sul coinvolgimento contiene dati a livello di evento provenienti da una creatività dell'annuncio, ad esempio i dati sulle impressioni o sui clic associati agli indicatori dell'asta dell'API Protected Audience che hanno visualizzato l'annuncio. Poiché l'annuncio viene visualizzato al termine dell'asta, gli indicatori dell'asta non sono disponibili all'interno del frame che mostra l'annuncio. Per associare questi dati di periodi di tempo diversi, ti forniamo due meccanismi di transizione per generare report sul coinvolgimento.

La funzione sendReportTo() descritta in precedenza può essere utilizzata per associare i dati dell'asta a dati a livello di evento provenienti da un iframe, ma non funziona per un frame protetto perché non è possibile passare un ID univoco dall'incorporamento perché la comunicazione tra quest'ultimo e il frame protetto è limitata. Per associare i dati dell'asta ai dati a livello di evento di un annuncio frame recintato, è possibile utilizzare l'API Ads Reporting.

API Ads Reporting per frame e iframe recintati

L'API Ads Reporting per iframe e frame recintati fornisce un meccanismo per associare i dati a livello di evento utente di un frame dell'annuncio a indicatori all'interno di un'asta Protected Audience.

In un worklet di reporting dell'API Protected Audience, puoi registrare un beacon degli annunci con la funzione registerAdBeacon() e trasmettere l'URL del report con gli indicatori aggiunti come parametri di query. Devi anche specificare l'evento personalizzato da associare all'URL del report. Quindi, in un secondo momento, quando l'annuncio viene visualizzato in un frame recintato, puoi attivare l'evento personalizzato chiamando la funzione window.fence.reportEvent(). I dati disponibili all'interno del frame recintato possono essere aggiunti come payload.

La funzione registerAdBeacon() è disponibile solo nelle funzioni di generazione dei report e non è disponibile nella logica di offerta dell'acquirente e in quella di valutazione del venditore.

Nell'esempio seguente, un ID campagna è associato a un payload a livello di evento con le coordinate del clic:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

L'API Fenced Frames Ads Reporting sarà disponibile almeno fino al 2026 per gli stessi motivi dei report sulle vittorie.

Per un approfondimento più dettagliato, consulta la spiegazione.

Accesso alla rete senza limitazioni

I frame protetti consentono di caricare le risorse di rete come farebbe un iframe, inoltre potrai inviare al tuo server dati a livello di evento all'interno di frame recintati. Puoi generare report a livello di evento sul lato server in un secondo momento associando i dati a livello di evento di un frame protetto con i dati dell'asta inviati con sendReportTo() discussi nella sezione precedente meccanismo di generazione di report a livello di evento dell'asta.

L'accesso alla rete sarà limitato in futuro.

Report sull'attribuzione

Un report sull'attribuzione consente di associare una conversione su un sito web a un annuncio scelto da un'asta dell'API Protected Audience. Ad esempio, un utente potrebbe fare clic su un annuncio di prodotto che pubblichi, essere reindirizzato al sito dell'inserzionista, effettuare un acquisto sul sito in questione e tu vorresti attribuire l'acquisto all'annuncio che è stato mostrato. L'API Attribution Reporting verrà integrata con l'API Protected Audience per combinare i dati dell'asta provenienti dal sito del publisher con i dati sulle conversioni provenienti dal sito dell'inserzionista.

Anche se progettiamo una soluzione più permanente, puoi utilizzare l'API Ads Reporting per i frame protetti come meccanismo transitorio per generare un report aggregabile a livello di evento con Attribution Reporting. Tieni presente che questi report servono a misurare le conversioni e sono separati dai report sul coinvolgimento aggregabili a livello di evento generati dall'asta e dal frame dell'annuncio. Quando sarà pronta, pubblicheremo una spiegazione per una soluzione più definitiva.

Meccanismo di transizione

Quando registri un beacon degli annunci, puoi utilizzare la parola chiave reserved.top_navigation che aggiungerà automaticamente l'intestazione Attribution-Reporting-Eligible affinché il beacon risulti idoneo alla registrazione come origine di attribuzione.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

Per collegare i dati a livello di evento al beacon che hai registrato, puoi chiamare setReportEventDataForAutomaticBeacons() dal frame recintato con il payload dell'evento.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

Per saperne di più, consulta la sezione Attribution Reporting nella spiegazione dell'API Ads Reporting.

Esempio di report sul coinvolgimento e sulle conversioni

In questo esempio, lo esamineremo dal punto di vista dell'acquirente interessato ad associare i dati dell'asta, del frame dell'annuncio e del sito di conversione.

In questo flusso di lavoro, l'acquirente si coordina con il venditore per inviare un ID univoco nell'asta. Durante l'asta, l'acquirente invia questo ID univoco con i dati dell'asta. Durante i tempi di rendering e di conversione, anche i dati del frame recintato o dell'iframe vengono inviati con lo stesso ID univoco. In seguito, l'ID univoco può essere utilizzato per associare questi report.

Flusso di lavoro:

1. Prima dell'inizio dell'asta, l'acquirente invia un ID univoco al venditore come parte della risposta all'offerta programmatica per le offerte in tempo reale ("RTB"). L'ID può essere impostato come variabile, ad esempio auctionId. L'ID viene trasmesso come perBuyerSignals nel auctionConfig e diventa disponibile nei worklet dell'acquirente.
2. Al momento dell'asta, l'acquirente può registrare un beacon dell'annuncio da attivare durante il tempo di rendering e il momento della conversione dell'annuncio (registerAdBeacon()).
   1. Per associare gli indicatori di asta a un evento del frame dell'annuncio, imposta auctionId come parametro di query dell'URL di beaconing.
   2. Per associare gli indicatori delle aste a un evento di conversione, imposta auctionId nell'URL di beaconing.
3. Durante il rendering dell'annuncio, i beacon registrati al momento dell'asta possono essere attivati o migliorati con i dati a livello di evento.
   1. Attiva l'evento frame con reportEvent() e passa i dati a livello di evento.
   2. Aggiungi payload a livello di evento al beacon di attribuzione con setReportEventDataForAutomaticBeacons()
   3. Registra l'annuncio con l'API Attribution Reporting rispondendo alle richieste di beacon degli annunci con l'intestazione Attribution-Reporting-Register-Source.
4. Al momento della conversione, puoi attivare l'origine che hai registrato al momento dell'asta.

Al termine della procedura descritta sopra, l'acquirente avrà un report sulle aste, un report sul coinvolgimento e un report sulle conversioni, tutti associati da un'unica chiave univoca che può essere utilizzata per essere associate tra loro.

Un flusso di lavoro simile si applica a un venditore se ha bisogno di accedere ai dati di attribuzione e il venditore può anche utilizzare un ID univoco da inviare con registerAdBeacon(). Dal frame, la chiamata reportEvent() contiene una proprietà di destinazione che può essere utilizzata per inviare il report sia all'acquirente sia al venditore. Tieni presente che l'SSP deve essere presente anche sulla pagina di destinazione affinché l'attivatore possa essere attribuito all'origine.

Aggregazione dei dati di Protected Audience

L'API Private Aggregation è il meccanismo utilizzato per segnalare i dati di Protected Audience al fine di generare un report di riepilogo, ovvero un report aggregato e non disturbato dei dati raccolti nei bucket. Un bucket è rappresentato da una chiave di aggregazione e alcune informazioni possono essere codificate nella chiave.

Ad esempio, un evento relativo a un'impressione dell'annuncio può essere conteggiato in diversi bucket, dove ogni bucket rappresenta una diversa campagna pubblicitaria. Un report di riepilogo è diverso da un report a livello di evento in quanto non rivela informazioni su ogni singolo evento. Con un report a livello di evento, puoi determinare che gli utenti A, B e C hanno visto la campagna 123. Con i report di riepilogo, puoi misurare il numero di utenti che hanno visualizzato la campagna 123 e aggiungere rumore per proteggere la privacy degli utenti.

Per saperne di più sull'API, consulta l'articolo sull'aggregazione privata.

Aggregazione degli indicatori delle aste

Puoi aggregare gli indicatori disponibili all'interno dei worklet con il tuo server utilizzando Private Aggregation. Per l'aggregazione degli indicatori, puoi utilizzare il metodo privateAggregation.contributeToHistogram() disponibile nel worklet delle offerte dell'acquirente, nel worklet di valutazione del venditore e nei worklet dei report acquirente/venditore.

In questo esempio, l'offerta vincente viene aggregata nel bucket del proprietario del gruppo di interesse:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

Questo è il meccanismo generale da utilizzare quando gli indicatori che vuoi aggregare non sono associati a dati a livello di evento e non vengono attivati da un evento esterno all'asta. Per scoprire di più sulla generazione di report sugli indicatori delle aste, consulta la documentazione.

Aggregazione di indicatori di asta con dati sugli eventi

Puoi aggregare gli indicatori dell'asta con informazioni limitate su un evento che si verifica in un frame dell'annuncio. Ad esempio, puoi misurare in modo aggregato quanti clic ha ricevuto un annuncio di una campagna creando un bucket che rappresenta la campagna e l'evento clic. Tieni presente che, dal frame dell'annuncio, puoi specificare quale evento si è verificato, ma non puoi collegare un payload a livello di evento.

Per aggregare gli indicatori dell'asta in base agli eventi, puoi utilizzare privateAggregation.contributeToHistogramOnEvent(eventType, contribution), che prende una stringa che specifica il tipo di evento e il contributo da segnalare quando viene attivato questo evento. Puoi chiamare il metodo con un tipo di evento personalizzato, poi chiamare window.fence.reportEvent(eventType) dal frame dell'annuncio per attivare l'invio del report.

Supponiamo che tu voglia misurare il numero di clic ricevuti da un annuncio di una campagna.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

Nella funzione di generazione dell'offerta, puoi definire un bucket come combinazione di ID campagna e evento clic, quindi aumentare il valore del bucket di 1 ogni volta che viene attivato l'evento.

// Ad frame
window.fence.reportEvent('click');

Poi, in un secondo momento, dal frame dell'annuncio, puoi attivare l'invio del report chiamando reportEvent(eventType):

Scopri di più sull'attivazione di contributi all'aggregazione privata da un frame nella spiegazione.

Generare report sui risultati delle aste e sul rendimento

Puoi anche aggregare i risultati delle aste quando attivati da un evento di vittoria o perdita di asta con contributeToHistogramOnEvent(eventType, contribution), quando trasmetti parole chiave di tipo di evento prenotato (reserved.win, reserved.loss e reserved.always).

L'aggregazione privata fornisce un elenco di valori base da cui puoi calcolare il bucket e il valore del tuo contributo. I valori di base disponibili per i risultati dell'asta sono il valore dell'offerta dell'annuncio vincente, il valore dell'offerta a cui è stato assegnato il secondo punteggio più alto e il motivo per cui un'offerta è stata rifiutata dall'asta.

Quando viene fornito un valore base, come l'importo dell'offerta vincente, puoi impostare l'importo da aggiungere o sottrarre da quel valore e poi registrare il valore finale. Ad esempio, se come valore base viene fornita l'offerta vincente di 5 €, puoi sottrarre questa offerta di 2 € per calcolare il valore effettivo di 3 €, equivalente a quanto hai perso l'asta.

Report sui risultati delle aste

Esaminiamo un esempio in cui hai perso un'asta e vuoi sapere quanto la tua offerta era distante dal prezzo di aggiudicazione dell'asta.

Per sapere di quanto hai perso l'asta, puoi sottrarre il prezzo dell'offerta dal prezzo dell'offerta vincente:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

Una volta inviato il report, il valore effettivo del report sarà il baseValue scalato spostato del valore offset. Per scoprire di più, consulta la spiegazione.

Creazione di report sul rendimento

Acquirenti e venditori possono segnalare il tempo necessario per l'esecuzione di uno script e il tempo necessario per recuperare gli indicatori attendibili. I venditori possono raccogliere il tempo per la generazione dell'offerta e l'ora dell'indicatore di offerta attendibile di ciascun acquirente con la loro autorizzazione.

Per saperne di più, consulta la spiegazione.

Archiviazione dei segnali di asta nello spazio di archiviazione condiviso

L'archivio condiviso è uno spazio di archiviazione non partizionato e multiorigine in cui puoi scrivere liberamente, ma è sorvegliato da porte durante la lettura e l'elaborazione dei valori archiviati. Una delle porte disponibili per l'API Shared Storage è Private Aggregation. Puoi leggere i valori nello spazio di archiviazione condiviso solo dall'interno di un worklet e puoi segnalarli utilizzando l'aggregazione privata dal worklet.

Puoi anche scrivere nello spazio di archiviazione condiviso dai worklet di offerta, della valutazione e dei report dell'API Protected Audience. Potrai segnalare questi valori nello spazio di archiviazione condiviso al tuo server in un secondo momento utilizzando l'aggregazione privata . Puoi anche utilizzare i valori memorizzati per l'operazione di selezione dell'URL.

Da un worklet dell'API Protected Audience, puoi scrivere chiavi e valori nello spazio di archiviazione condiviso:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

In un secondo momento puoi caricare un worklet dello spazio di archiviazione condiviso per leggere e inviare il valore con Private Aggregation:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

Per scoprire di più sull'archiviazione condivisa, consulta la sezione dedicata allo spazio di archiviazione condiviso della guida per gli sviluppatori dei report dell'API Protected Audience, il video esplicativo, la demo dal vivo e il codice della demo su GitHub.

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.