Report sulle aste dell'API Protected Audience

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

Questo articolo fornisce una panoramica generale dei vari meccanismi disponibili per segnalare i dati dell'asta dell'API Protected Audience al tuo server, nonché dei meccanismi di transizione disponibili al momento da utilizzare durante la migrazione fino a quando non saranno pronte soluzioni alternative.

Per generare report sulle metriche importanti che raccogli da un'asta dell'annuncio, l'API Protected Audience funziona con:

• Private Aggregation, che raccoglie i segnali e i risultati dell'asta per generare report di riepilogo.
• API Ads Reporting per Fenced Frame 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 ai segnali dell'asta. I report a livello di evento dell'API Google Ads Reporting sono un meccanismo di transizione in attesa della progettazione di un meccanismo di generazione di report più privato.
• Report sull'attribuzione, che ti consente di associare i dati sulle conversioni ai segnali dell'asta.
• Shared Storage, che consente di scrivere indicatori dell'asta in uno spazio di archiviazione multiorigine, per poi consentire di generare report su questi dati in un secondo momento utilizzando Private Aggregation.

Panoramica dei report dell'API Protected Audience

Esistono tre periodi di tempo principali in cui i dati del flusso dell'asta dell'API Protected Audience possono essere inviati al tuo server: il momento dell'asta, quando l'asta viene eseguita dal sito del publisher, il momento del rendering, quando l'annuncio viene visualizzato in un frame isolato o in un iframe sul sito del publisher, e il momento della conversione, quando l'utente esegue un'azione su un altro sito che può essere attribuita all'asta.

Durante il periodo dell'asta, puoi generare report sui dati dell'asta utilizzando i worklet di reporting. Durante il rendering, puoi generare report sui dati di coinvolgimento da un iframe o un fenced frame. Durante il periodo di conversione, puoi generare report sui dati di attribuzione dalla pagina di destinazione utilizzando l'API Attribution Reporting.

Posizioni dei report

All'interno 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, gli acquirenti e i venditori possono segnalare i dati di un frame che ha visualizzato l'annuncio e del 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 quali indicatori dell'asta, dati a livello di evento e dati sulle conversioni.

Dati disponibili in un'asta dell'API Protected Audience

I seguenti dati possono essere inclusi in un report di 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 del 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 auction config è la principale fonte di dati forniti per diventare disponibili come indicatori nei worklet. Il publisher e il venditore possono fornire dati contestuali e proprietari nella configurazione dell'asta e questi indicatori possono essere arricchiti con i dati dei gruppi di interesse dell'acquirente, i dati a livello di evento del frame di rendering dell'annuncio e i dati di attribuzione della pagina di clickthrough. I dati riportati possono essere utilizzati per report di acquirenti/venditori, fatturazione, definizione del budget, addestramento di modelli ML e altro ancora.

Altri dati disponibili

• Dati sui risultati relativi ai dati sulle aste vinte e perse, come il prezzo dell'offerta vincente e il motivo del rifiuto dell'offerta.
• Dati sul rendimento che contengono informazioni sulla latenza, ad esempio il tempo impiegato 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 la generazione di report.

Durante il 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 dell'asta dell'API Protected Audience e inviati al tuo server. I dati a livello di evento di esempio includono impressioni dell'annuncio, clickthrough, passaggi del mouse e qualsiasi altro evento che si verifica all'interno del frame.

Durante il periodo di conversione, quando un utente esegue un'azione nella pagina di destinazione che viene attribuita all'asta, i dati a livello di evento della pagina di conversione possono essere associati ai dati dell'asta dell'API Protected Audience e inviati al 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 all'asta, un'impressione dell'annuncio o una conversione. Almeno fino al 2026, i report sulle aste vinte a livello di evento rimarranno in vigore, i fenced frame non saranno necessari per il rendering di un annuncio Protected Audience e per i report a livello di evento potrà essere utilizzato un iframe con accesso alla rete senza limitazioni. Inoltre, l'API Ads Reporting è disponibile in fenced frame e iframe per consentirti di associare i dati di aste e conversioni ai dati a livello di evento del frame. In questo modo, l'ecosistema avrà un percorso di migrazione più semplice, poiché potrai continuare a utilizzare l'infrastruttura di generazione dei report esistente almeno fino al 2026 durante la migrazione del sistema a Protected Audience.

Report sulle vittorie all'asta a livello di evento con sendReportTo()

Un meccanismo disponibile per la generazione di report sui dati a livello di evento all'interno di un'asta Protected Audience è sendReportTo() function in caso di vittoria dell'asta. La funzione è disponibile nei worklet per i report di acquirenti e venditori e il browser effettua una richiesta GET alla stringa URL fornita quando inizia il rendering dell'annuncio. Puoi codificare qualsiasi indicatore disponibile nei 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 chiamata da reportResult() e un report sulle vittorie per l'acquirente quando viene chiamata da reportWin(). La funzione sendReportTo() è disponibile almeno fino al 2026,

Report Coinvolgimento

Un report sul coinvolgimento contiene dati a livello di evento di una creatività dell'annuncio, ad esempio dati su impressioni o clic, associati agli indicatori dell'asta dell'API Protected Audience che ha eseguito il rendering dell'annuncio. Poiché l'annuncio viene visualizzato dopo la conclusione dell'asta, gli indicatori dell'asta non sono disponibili all'interno del frame che esegue il rendering dell'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 sopra può essere utilizzata per associare i dati dell'asta ai dati a livello di evento di un iframe, ma non funziona per un frame isolato, poiché non è possibile passare un ID univoco dall'incorporatore perché la comunicazione tra l'incorporatore e il frame isolato è limitata. Per associare i dati delle aste ai dati a livello di evento di un annuncio in un frame isolato, puoi utilizzare l'API Ads Reporting.

API Ads Reporting per frame recintati e iframe

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

In un worklet di generazione di report dell'API Protected Audience, puoi registrare un beacon annuncio con la funzione registerAdBeacon() e trasmettere l'URL di generazione di report con i segnali aggiunti come parametri di query. Specifichi anche l'evento personalizzato che vuoi associare all'URL dei report. Successivamente, quando l'annuncio viene visualizzato in un frame isolato, 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 reporting e non nella logica di offerta dell'acquirente e nella logica di assegnazione del punteggio 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 recintati consentiranno il caricamento delle risorse di rete nello stesso modo di un iframe e potrai inviare dati a livello di evento all'interno dei frame recintati al tuo server. Puoi generare report a livello di evento sul lato server in un secondo momento associando i dati a livello di evento di un frame isolato ai dati dell'asta inviati con sendReportTo(), come descritto nella sezione Meccanismo di generazione di report a livello di evento dell'asta riportata sopra.

L'accesso alla rete sarà limitato in futuro.

Report sull'attribuzione

Un report sull'attribuzione ti 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 prodotto che pubblichi, essere reindirizzato al sito dell'inserzionista, effettuare un acquisto e tu sei interessato ad attribuire l'acquisto all'annuncio visualizzato. L'API Attribution Reporting verrà integrata con l'API Protected Audience per combinare i dati dell'asta del sito del publisher e i dati di conversione del sito dell'inserzionista.

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

Meccanismo transitorio

Quando registri un beacon annuncio, puoi utilizzare la parola chiave reserved.top_navigation, che aggiungerà automaticamente l'intestazione Attribution-Reporting-Eligible per consentire al beacon di registrarsi come origine attribuzione.

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

Per allegare 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 della spiegazione dell'API Ads Reporting.

Esempio di report sul coinvolgimento e sulle conversioni

In questo esempio, esamineremo la situazione 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 all'asta. Durante l'asta, l'acquirente invia questo ID univoco con i dati dell'asta. Durante il rendering e il tempo di conversione, i dati del frame recintato o dell'iframe vengono inviati anche con lo stesso ID univoco. In un secondo momento, 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 nell'ambito della risposta all'offerta di offerte in tempo reale ("RTB") programmatiche. L'ID può essere impostato come variabile, ad esempio auctionId. L'ID viene trasmesso come perBuyerSignals in auctionConfig e diventa disponibile nei worklet dell'acquirente.
2. Durante il periodo dell'asta, l'acquirente può registrare un beacon annuncio da attivare durante il rendering dell'annuncio e il periodo di conversione (registerAdBeacon()).
   1. Per associare gli indicatori dell'asta a un evento frame dell'annuncio, imposta auctionId come parametro di ricerca dell'URL beacon.
   2. Per associare gli indicatori dell'asta a un evento di conversione, imposta auctionId nell'URL del beacon.
3. Durante il rendering dell'annuncio, i beacon registrati durante l'asta possono essere attivati o migliorati con dati a livello di evento.
   1. Attiva l'evento frame con reportEvent() e passa i dati a livello di evento.
   2. Aggiungi il 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 annuncio con l'intestazione Attribution-Reporting-Register-Source.
4. Durante il periodo di conversione, puoi attivare l'origine che hai registrato durante il periodo dell'asta.

Al termine della procedura descritta sopra, l'acquirente avrà un report sull'asta, un report sul coinvolgimento e un report sulle conversioni, tutti collegati da una singola chiave univoca che può essere utilizzata per associarli 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 la SSP deve essere presente anche nella pagina di destinazione affinché l'attivazione venga attribuita alla fonte.

Aggregazione dei dati Protected Audience

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

Ad esempio, un evento di impressione dell'annuncio può essere conteggiato in bucket diversi, dove ogni bucket rappresenta una campagna pubblicitaria diversa. Un report di riepilogo si differenzia 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 visualizzato la campagna 123. Con i report di riepilogo, puoi misurare il numero di utenti che hanno visualizzato la campagna 123 e viene aggiunto rumore per proteggere la privacy degli utenti.

Per saperne di più sull'API, consulta l'articolo Private Aggregation.

Aggregazione degli indicatori dell'asta

Puoi aggregare gli indicatori disponibili all'interno dei worklet al tuo server utilizzando Private Aggregation. Per l'aggregazione dei segnali, puoi utilizzare il metodo privateAggregation.contributeToHistogram() disponibile nel worklet per le offerte dell'acquirente, nel worklet per l'assegnazione del punteggio al venditore e nei worklet per i report di acquirenti e venditori.

In questo esempio, l'offerta vincente viene aggregata nel bucket del proprietario del gruppo basato sugli interessi:

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 al di fuori dell'asta. Per scoprire di più sui report sugli indicatori dell'asta, consulta la spiegazione.

Aggregazione degli indicatori dell'asta con i 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 per una campagna creando un bucket che rappresenti la campagna e l'evento di clic. Tieni presente che, dal frame dell'annuncio, puoi specificare l'evento che si è verificato, ma non puoi allegare un payload a livello di evento.

Per aggregare gli indicatori dell'asta in base agli eventi, puoi utilizzare privateAggregation.contributeToHistogramOnEvent(eventType, contribution), che accetta una stringa che specifica il tipo di evento e il contributo da segnalare quando viene attivato l'evento. Puoi chiamare il metodo con un tipo di evento personalizzato, quindi 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 per 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 delle offerte, puoi definire un bucket come combinazione dell'ID campagna e dell'evento di clic, quindi aumentare il valore di questo bucket di 1 ogni volta che viene attivato l'evento.

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

Successivamente, dal frame dell'annuncio, puoi attivare l'invio della segnalazione chiamando reportEvent(eventType):

Scopri di più sull'attivazione dei contributi di Private Aggregation da un frame nella spiegazione.

Report sui risultati e sul rendimento dell'asta

Puoi anche aggregare i risultati dell'asta quando vengono attivati da un evento di vittoria o perdita dell'asta con contributeToHistogramOnEvent(eventType, contribution) quando inserisci parole chiave di tipo di evento riservato (reserved.win, reserved.loss e reserved.always).

L'aggregazione privata fornisce un elenco di valori di 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 che ha ottenuto il secondo punteggio più alto e il motivo per cui un'offerta è stata rifiutata dall'asta.

Quando viene fornito un valore di base, ad esempio l'importo dell'offerta vincente, puoi impostare l'importo da aggiungere o sottrarre a questo valore, quindi segnalare il valore finale. Ad esempio, se l'offerta vincente di 5 $viene fornita come valore di base, puoi sottrarre la tua offerta di 2 $per calcolare il valore effettivo di 3 $di quanto hai perso l'asta.

Report sui risultati dell'asta

Vediamo un esempio in cui hai perso un'asta e vuoi sapere quanto la tua offerta si discosta dal prezzo di aggiudicazione dell'asta.

Per scoprire di quanto hai perso l'asta, puoi sottrarre il prezzo della tua 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 
    }
  });
}

Quando il report viene inviato, il valore effettivo segnalato sarà il valore 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 impiegato per l'esecuzione di uno script e per il recupero degli indicatori attendibili. I venditori possono raccogliere l'ora di generazione dell'offerta e l'ora dell'indicatore di offerta attendibile di ogni acquirente con il suo permesso.

Per saperne di più, consulta la spiegazione.

Memorizzazione degli indicatori dell'asta in Shared Storage

Lo spazio di archiviazione condiviso è uno spazio di archiviazione non partizionato e multiorigine in cui puoi scrivere liberamente, ma è protetto da porte quando leggi ed elabori i valori archiviati. Uno dei gate 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, assegnazione del punteggio e generazione di report dell'API Protected Audience. In un secondo momento, puoi segnalare questi valori nello spazio di archiviazione condiviso al tuo server utilizzando Private Aggregation . Puoi anche utilizzare i valori memorizzati per l'operazione Selezione URL.

Da un worklet dell'API Protected Audience, puoi scrivere qualsiasi chiave e valore nello spazio di archiviazione condiviso:

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

In un secondo momento, puoi caricare un worklet Shared Storage per leggere e inviare quel valore con l'aggregazione privata:

// 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 saperne di più su Shared Storage, consulta la sezione relativa all'archiviazione condivisa della guida per gli sviluppatori del report dell'API Protected Audience, la spiegazione, la demo live e il codice 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.