Report sulle aste dell'API Protected Audience

bookmark_border Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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 delle aste dell'API Protected Audience al tuo server, oltre ai meccanismi di transizione che puoi utilizzare immediatamente durante la migrazione finché non saranno disponibili soluzioni alternative.

Per generare report sulle metriche importanti raccolte da un'asta di annunci, l'API Protected Audience è compatibile con:

• Aggregazione privata, che raccoglie gli indicatori e i risultati delle aste per generare report di riepilogo.
• API Ads Reporting per frame delimitati 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. I report a livello di evento dell'API Ads Reporting sono un meccanismo transitorio fino a quando non verrà progettato un meccanismo di generazione di report più privato.
• Report sull'attribuzione, che ti consente di associare i dati sulle conversioni agli indicatori delle aste.
• Archiviazione condivisa, che ti consente di scrivere indicatori di asta in un'area di archiviazione cross-origin, per poi generare report su questi dati utilizzando l'aggregazione privata.

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 registrati sul tuo server: l'ora dell'asta quando l'asta viene eseguita dal sito del publisher, l'ora di rendering quando l'annuncio viene visualizzato in un frame delimitato o in un iframe sul sito del publisher e l'ora di conversione quando l'utente esegue un'azione su un altro sito che può essere attribuita all'asta.

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

Località 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 registrare 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 generazione di report disponibili per generare report su dati quali indicatori delle aste, dati a livello di evento e dati sulle conversioni.

Dati disponibili in un'asta dell'API Protected Audience

I seguenti dati possono essere registrati 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 del browser disponibili per gli acquirenti e i venditori all'interno di un worklet per generare un'offerta, assegnare un punteggio a un annuncio e generare report sui risultati di un'asta.

L'oggetto auction config è la fonte principale dei dati forniti per essere resi 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 del gruppo di interesse dell'acquirente, i dati a livello di evento del frame di rendering dell'annuncio e i dati di attribuzione della pagina di clic. I dati registrati possono essere utilizzati per i report acquirenti/venditori, la fatturazione, il budget, l'addestramento dei modelli ML e altro ancora.

Altri dati disponibili

• Dati sui risultati relativi ai dati sulle offerte 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 necessario per recuperare ed eseguire il worklet per le offerte.

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 delimitato possono essere associati ai dati dell'asta dell'API Protected Audience e registrati sul tuo server. Alcuni esempi di dati a livello di evento sono impressioni dell'annuncio, clic indiretti, passaggio del mouse e qualsiasi altro evento che si verifica all'interno del frame.

Durante il momento di conversione, quando un utente esegue un'azione nella pagina di clicthrough 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 registrati 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 all'asta, un'impressione dell'annuncio o una conversione. Fino ad almeno il 2026, i report sulle aste vinte a livello di evento rimarranno in vigore, i frame delimitati non saranno necessari per il rendering di un annuncio Protected Audience e un iframe con accesso alla rete senza restrizioni potrà essere utilizzato per i report a livello di evento. Inoltre, l'API Ads Reporting è disponibile nei frame delimitati e negli iframe per consentirti di associare i dati delle aste e delle conversioni ai dati a livello di evento del frame. Questo approccio è progettato per consentire all'ecosistema di seguire un percorso di migrazione più semplice, poiché puoi continuare a utilizzare l'infrastruttura di generazione di report esistente almeno fino al 2026 durante la migrazione del sistema a Protected Audience.

Report sulle aste vinte 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 è sendReportTo() function in caso di vittoria dell'asta. La funzione è disponibile nei worklet dei report per acquirenti e venditori e il browser invia una richiesta GET alla stringa URL fornita all'inizio del 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() a fini di 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 offerte vinte per il venditore quando viene chiamata da reportResult() e un report sulle offerte vinte 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, come i dati sulle impressioni o sui clic, associati agli indicatori dell'asta dell'API Protected Audience che ha visualizzato l'annuncio. Poiché l'annuncio viene visualizzato al termine dell'asta, gli indicatori dell'asta non sono disponibili all'interno del frame che lo mostra. Per associare questi dati di periodi di tempo diversi, ti offriamo 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 delimitato perché non è possibile trasmettere un ID univoco dall'inserzionista a causa della limitazione della comunicazione tra l'inserzionista e il frame delimitato. Per associare i dati dell'asta ai dati a livello di evento di un annuncio in un riquadro recintato, puoi utilizzare l'API Ads Reporting.

API Ads Reporting per frame delimitati e iframe

L'API Ads Reporting per frame delimitati e iframe fornisce un meccanismo per associare i dati a livello di evento utente di un frame dell'annuncio agli indicatori 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 passare l'URL dei report con gli indicatori aggiunti come parametri di query. Specifica anche l'evento personalizzato da associare all'URL dei report. In un secondo momento, quando l'annuncio viene visualizzato in un frame delimitato, 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 di report e non nella logica di offerta dell'acquirente e nella logica di 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 di generazione di report sugli annunci con frame delimitati sarà disponibile anche fino ad almeno il 2026 per gli stessi motivi dei report sulle vittorie.

Per un approfondimento, consulta la spiegazione.

Accesso alla rete senza restrizioni

I frame delimitati consentono di caricare le risorse di rete nello stesso modo in cui lo farebbe un iframe e puoi inviare dati a livello di evento all'interno di frame delimitati al tuo server. In un secondo momento, puoi generare report a livello di evento lato server associando i dati a livello di evento di un frame recintato ai dati dell'asta inviati con sendReportTo(), come descritto nella sezione Meccanismo di generazione di report a livello di evento dell'asta 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 di prodotto che pubblichi, essere reindirizzato al sito dell'inserzionista, effettuare un acquisto e tu vorresti attribuire l'acquisto all'annuncio mostrato. L'API Attribution Reporting verrà integrata con l'API Protected Audience per combinare i dati dell'asta del sito del publisher e i dati sulle conversioni del sito dell'inserzionista.

Mentre sviluppiamo una soluzione più permanente, puoi utilizzare l'API Ads Reporting per i frame delimitati come meccanismo di transizione per generare un report aggregabile a livello di evento con Attribution Reporting. Tieni presente che questi report sono destinati alla misurazione delle conversioni e sono separati dai report sul coinvolgimento aggregabili e a livello di evento generati dall'asta e dal frame dell'annuncio. Quando sarà tutto pronto, pubblicheremo una spiegazione di 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 essere registrato come origine di attribuzione.

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

Per associare 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 Report sull'attribuzione della 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 all'asta. Durante l'asta, l'acquirente invia questo ID univoco con i dati dell'asta. Durante il rendering e il momento della conversione, anche i dati del frame o dell'iframe recintato vengono inviati 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 al venditore un ID univoco nell'ambito della risposta all'offerta di offerte in tempo reale ("RTB") programmatiche. L'ID può essere impostato come una variabile come auctionId. L'ID viene passato come perBuyerSignals in auctionConfig e diventa disponibile nei worklet dell'acquirente.
2. Durante l'asta, l'acquirente può registrare un beacon annuncio da attivare al momento del rendering dell'annuncio e al momento della conversione (registerAdBeacon()).
   1. Per associare gli indicatori dell'asta per un evento frame dell'annuncio, imposta auctionId come parametro di query dell'URL del beacon.
   2. Per associare gli indicatori di asta per 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 degli annunci con l'intestazione Attribution-Reporting-Register-Source.
4. Al momento della conversione, puoi attivare l'origine che hai registrato durante l'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 un'unica chiave univoca che può essere utilizzata per l'associazione.

Un flusso di lavoro simile si applica a un venditore se ha bisogno di accedere ai dati di attribuzione e 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 nella pagina di destinazione affinché l'attivatore venga attribuito all'origine.

Aggregare i 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 con 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 diversi bucket, dove ogni bucket rappresenta una campagna pubblicitaria diversa. 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 stabilire 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 vengono aggiunti dati non significativi per proteggere la privacy degli utenti.

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

Aggregare gli indicatori delle aste

Puoi aggregare gli indicatori disponibili all'interno dei worklet sul tuo server utilizzando l'aggregazione privata. Per l'aggregazione degli indicatori, puoi utilizzare il metodo privateAggregation.contributeToHistogram() disponibile nel worklet per le offerte degli acquirenti, nel worklet per il calcolo del punteggio dei venditori e nei worklet per i report per acquirenti/venditori.

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 da aggregare non sono associati ai dati a livello di evento e non vengono attivati da un evento esterno all'asta. Per scoprire di più sugli indicatori delle aste nei report, consulta la spiegazione.

Aggregare gli indicatori delle aste con i dati sugli eventi

Puoi aggregare gli indicatori di asta con informazioni limitate su un evento che si verifica in un frame dell'annuncio. Ad esempio, puoi misurare in modo aggregato il numero di clic ricevuti da 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 quale evento si è verificato, ma non puoi allegare un payload a livello di evento.

Per aggregare gli indicatori delle aste per eventi, puoi utilizzare privateAggregation.contributeToHistogramOnEvent(eventType, contribution) che accetta una stringa che specifica il tipo di evento e il contributo da segnalare quando si verifica 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 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 delle offerte, puoi definire un bucket come la combinazione dell'ID campagna e dell'evento di clic, quindi aumentare il valore del bucket di 1 ogni volta che viene attivato l'evento.

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

In un secondo momento, dal frame dell'annuncio, puoi attivare l'invio della segnalazione chiamando reportEvent(eventType):

Scopri di più sull'attivazione dei contributi di aggregazione privata da un frame nel documento esplicativo.

Report sui risultati e sul rendimento delle aste

Puoi anche aggregare i risultati dell'asta quando vengono attivati da un evento di vittoria o perdita dell'asta con contributeToHistogramOnEvent(eventType, contribution) quando passi parole chiave di tipo di evento riservate (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 ricevuto il punteggio di secondo valore 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 quel valore, quindi indicare 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 $della perdita dell'asta.

Report sui risultati dell'asta

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

Per scoprire 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 
    }
  });
}

Quando il report viene inviato, il valore effettivo registrato sarà il valore baseValue scalato spostato dal valore offset. Per scoprire di più, consulta la spiegazione.

Creazione di report sul rendimento

Gli acquirenti e i venditori possono segnalare il tempo impiegato per l'esecuzione di uno script e il tempo impiegato per recuperare gli indicatori attendibili. I venditori possono raccogliere la data e l'ora di generazione dell'offerta e l'ora dell'indicatore di offerte attendibili di ogni acquirente con la sua autorizzazione.

Per saperne di più, consulta la spiegazione.

Memorizzare gli indicatori delle aste nello spazio di archiviazione condiviso

Lo spazio di archiviazione condiviso è uno spazio di archiviazione non partizionato e cross-origin in cui puoi scrivere liberamente, ma è protetto da cancelli durante la lettura e l'elaborazione dei 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 generare report su questi valori utilizzando l'aggregazione privata dal worklet.

Puoi anche scrivere nello spazio di archiviazione condiviso dai worklet di offerta, di punteggio e di generazione di report dell'API Protected Audience. In un secondo momento, puoi registrare questi valori nello spazio di archiviazione condiviso sul tuo server utilizzando l'aggregazione privata . 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 di archiviazione condivisa per leggere e inviare il 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 scoprire di più su Shared Storage, consulta la sezione relativa a questo servizio nella guida per gli sviluppatori relativa ai report dell'API Protected Audience, la spiegazione, la demo in tempo reale 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.