Panoramica dell'API Private Aggregation

Genera report di dati aggregati utilizzando i dati di Protected Audience e i dati cross-site di Archiviazione condivisa.

Per fornire funzionalità fondamentali su cui si basa il web, l'API Private Aggregation è stata creata per l'aggregazione e la generazione di report sui dati tra siti in modo incentrato sulla tutela della privacy.

Stato implementazione

Proposta Stato
Previeni report dell'API Private Aggregation non validi con la verifica dei report per Shared Storage
Explainer		 Disponibile in Chrome
Disponibilità della modalità di debug di aggregazione privata in base all'idoneità di 3PC
Problema GitHub		 Disponibile in Chrome M119
Riduzione del ritardo nei report
Spiegazione		 Disponibile in Chrome M119
Supporto per l'API Private Aggregation e il servizio Aggregation Service per Google Cloud
Explainer		 Disponibile in Chrome M121
Riempimento per i payload dei report aggregabili
Explainer		 Disponibile in Chrome M119
Modalità di debug dell'aggregazione privata disponibile per i reportauctionReportBuyers
Spiegazione		 Previsto in Chrome M123
Supporto degli ID filtro
Spiegazione		 Lancio iniziale previsto in Chrome nel secondo trimestre del 2024.

Che cos'è l'API Private Aggregation

L'API Private Aggregation consente agli sviluppatori di generare report di dati aggregati con i dati dell'API Protected Audience e dati cross-site da Spazio di archiviazione condiviso.

Al momento questa API fornisce un'operazione, contributeToHistogram(), ma in futuro potrebbero essere supportate altre. L'operazione relativa all'istogramma ti consente di aggregare i dati di tutti gli utenti in ciascun bucket (noto nell'API come chiave di aggregazione) che definisci. La chiamata dell'istogramma accumula valori e restituisce un risultato aggregato con rumore sotto forma di report di riepilogo. Ad esempio, il report potrebbe mostrare il numero di siti su cui ogni utente ha visto i tuoi contenuti o rilevare un bug nello script di terze parti. Questa operazione viene eseguita all'interno del worklet di un'altra API.

Ad esempio, se in precedenza hai registrato dati demografici e geografici in Archiviazione condivisa, puoi utilizzare l'API Private Aggregation per creare un istogramma che indichi approssimativamente quanti utenti di New York hanno visualizzato i tuoi contenuti su più siti. Per aggregare questa misurazione, puoi codificare la dimensione geografica nella chiave di aggregazione e conteggiare gli utenti nel valore aggregabile.

Concetti principali

Quando chiami l'API Private Aggregation con una chiave di aggregazione e un valore aggregabile, il browser genera un report aggregabile.

I report aggregati vengono inviati al tuo server per la raccolta e il raggruppamento in batch. I report in batch vengono elaborati in un secondo momento dal servizio di aggregazione e viene generato un report di riepilogo.

Per saperne di più sui concetti chiave dell'API Private Aggregation, consulta il documento sui concetti fondamentali dell'API Private Aggregation.

Differenze rispetto ai report sull'attribuzione

L'API Private Aggregation condivide molte somiglianze con l'API Attribution Reporting. Attribution Reporting è un'API autonoma progettata per misurare le conversioni, mentre Private Aggregation è pensata per le misurazioni tra siti in combinazione con API come l'API Protected Audience e l'archiviazione condivisa. Entrambe le API producono report aggregabili che vengono utilizzati dal backend del servizio di aggregazione per generare report di riepilogo.

Attribution Reporting associa i dati raccolti da un evento di impressione a un evento di conversione, che si verificano in momenti diversi. L'aggregazione privata misura un singolo evento tra siti.

Testa questa API

Per testare l'API Private Aggregation localmente, abilita tutte le API di privacy per gli annunci in chrome://settings/adPrivacy.

Scopri di più sui test in Esperimento e partecipazione.

Usa la demo

Puoi accedere alla demo dell'API Private Aggregation per lo spazio di archiviazione condiviso all'indirizzo goo.gle/shared-storage-demo e il codice è disponibile su GitHub. La demo implementa le operazioni lato client e produce un report aggregabile che viene inviato al tuo server.

In futuro verrà pubblicata una demo dell'API Private Aggregation per l'API Protected Audience.

Casi d'uso

Private Aggregation è un'API per uso generico per la misurazione tra siti e può essere utilizzata nei worklet Shared Storage e Protected Audience. Il primo passaggio consiste nel decidere esattamente quali informazioni vuoi raccogliere. Questi punti dati sono la base delle chiavi di aggregazione.

Con spazio di archiviazione condiviso

L'archiviazione condivisa ti consente di leggere e scrivere dati tra siti in un ambiente sicuro per evitare perdite, mentre l'API Private Aggregation ti consente di misurare i dati tra siti archiviati in Archiviazione condivisa.

Misurazione della copertura unica

Può essere utile calcolare quanti utenti unici hanno visto i contenuti. L'API Private Aggregation può fornire una risposta come "Circa 317 utenti unici hanno visualizzato Content ID 861".

Puoi impostare un flag in Archiviazione condivisa per indicare se l'utente ha già visto i contenuti o meno. Alla prima visita in cui il flag non esiste, viene effettuata una chiamata alla funzione Private Aggregation e poi viene impostato il flag. Per le visite successive dell'utente, comprese quelle tra siti, puoi controllare l'archiviazione condivisa e saltare l'invio di un report all'aggregazione privata se il flag è impostato.

Misurazione dei dati demografici

Ti consigliamo di misurare i dati demografici degli utenti che hanno visto i tuoi contenuti su diversi siti.

Private Aggregation può fornire una risposta come "Circa 317 utenti unici di età compresa tra i 18 e i 45 anni sono residenti in Germania". Utilizza lo spazio di archiviazione condiviso per accedere ai dati demografici da un contesto di terze parti. Potrai generare un report con aggregazione privata in un secondo momento codificando le dimensioni relative all'età e al paese nella chiave di aggregazione.

Misurazione della frequenza K+

Può essere utile misurare il numero di utenti che hanno visualizzato un contenuto o un annuncio almeno K volte su un determinato browser, per ottenere un valore preselezionato di K.

L'aggregazione privata può fornire una risposta come "Circa 89 utenti hanno visualizzato Content ID 581 almeno 3 volte". Un contatore può essere incrementato in Shared Storage da siti diversi e può essere letto all'interno di un worklet. Quando il conteggio ha raggiunto K, è possibile inviare un report tramite aggregazione privata.

Con l'API Protected Audience

L'API Protected Audience consente casi d'uso di retargeting e segmenti di pubblico personalizzati, mentre Private Aggregation consente di generare report sugli eventi provenienti dai worklet di acquirenti e venditori. L'API può essere utilizzata per attività come la misurazione della distribuzione delle offerte dell'asta.

Da un worklet dell'API Protected Audience, puoi aggregare i dati direttamente utilizzando contributeToHistogram() e segnalarli in base a un attivatore utilizzando contributeToHistogramOnEvent(), un'estensione speciale per l'API Protected Audience.

Funzioni disponibili

Le seguenti funzioni sono disponibili nell'oggetto privateAggregation disponibile nei worklet dello spazio di archiviazione condiviso e dell'API Protected Audience.

contributeToHistogram()

Puoi chiamare privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), dove la chiave di aggregazione è bucket e il valore aggregabile come value. Il BigInt è obbligatorio per il parametro bucket. Per il parametro value, è richiesto un numero intero.

Di seguito è riportato un esempio di come potrebbe essere chiamato in Spazio di archiviazione condiviso per la misurazione della copertura:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Il codice di esempio riportato sopra chiama Aggregazione privata ogni volta che vengono caricati i contenuti degli iframe tra siti. Il codice iframe carica il worklet, che chiama l'API Private Aggregation con l'ID contenuto convertito in una chiave di aggregazione (bucket).

contributeToHistogramOnEvent()

Solo all'interno dei worklet dell'API Protected Audience, forniamo un meccanismo basato su trigger per inviare una segnalazione solo se si verifica un determinato evento. Questa funzione consente inoltre al bucket e al valore di dipendere da indicatori che non sono ancora disponibili in quel momento dell'asta.

Il metodo privateAggregation.contributeToHistogramOnEvent(eventType, contribution) richiede un eventType che specifica l'evento di attivazione e l'contribution da inviare quando l'evento viene attivato. L'evento di attivazione può provenire dall'asta stessa al termine dell'asta, ad esempio un evento di vittoria o sconfitta dell'asta, oppure può provenire da un frame chiuso in cui è stato visualizzato l'annuncio. Per inviare un report sugli eventi di asta, puoi utilizzare due parole chiave prenotate, reserved.win, reserved.loss e reserved.always. Per inviare un report attivato da un evento proveniente da un frame recintato, definisci un tipo di evento personalizzato. Per attivare l'evento da un frame recintato, utilizza il metodo fence.reportEvent() disponibile nell'API Fenced Frames Ads Reporting.

L'esempio seguente invia un report sulle impressioni quando viene attivato l'evento di vittoria dell'asta e un report sui clic se viene attivato un evento click dal frame recintato in cui è stato visualizzato l'annuncio. Questi due valori possono essere utilizzati per calcolare la percentuale di clic. 

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Per saperne di più, consulta l'articolo esplicativo sui report sull'aggregazione privata estesa.

enableDebugMode()

Sebbene i cookie di terze parti siano ancora disponibili, offriremo un meccanismo temporaneo che semplifica il debug e i test attivando la modalità di debug. Un report di debug è utile per confrontare le misurazioni basate sui cookie con quelle dell'aggregazione privata e consente anche di convalidare rapidamente l'integrazione dell'API.

La chiamata di privateAggregation.enableDebugMode() nel worklet consente la modalità di debug che fa sì che i report aggregabili includano il payload non criptato (testo in chiaro). Puoi quindi elaborare questi payload con lo strumento di test locale del servizio di aggregazione.

La modalità di debug è disponibile solo per i chiamanti autorizzati ad accedere ai cookie di terze parti. Se il chiamante non ha accesso a cookie di terze parti, l'app enableDebugMode() non avrà accesso. Ciò significa che quando i cookie di terze parti verranno ritirati, la modalità di debug non sarà più disponibile.

Puoi anche impostare la chiave di debug chiamando privateAggregation.enableDebugMode({ <debugKey: debugKey> }), dove un BigInt può essere utilizzato come chiave di debug. La chiave di debug può essere utilizzata per associare i dati di una misurazione basata sui cookie a quelli della misurazione dell'aggregazione privata.

Queste possono essere chiamate solo una volta per contesto. Eventuali chiamate successive genereranno un'eccezione.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Verifica report

Per lo spazio di archiviazione condiviso, puoi verificare che i report aggregabili che hai ricevuto siano legittimi aggiungendo un ID contesto alla chiamata dell'operazione di archiviazione condivisa. L'ID verrà allegato al report inviato e, successivamente, potrai utilizzarlo per verificare che il report sia stato inviato dall'operazione di archiviazione condivisa.

La funzionalità è disponibile per i test in Chrome M114 e versioni successive. La verifica dei report per l'API Protected Audience non è ancora disponibile per i test.

Per scoprire di più, consulta la spiegazione della verifica della segnalazione.

Interagisci e condividi il feedback

L'API Private Aggregation è attualmente in fase di discussione ed è soggetta a modifiche in futuro. Se provi questa API e hai feedback, ci piacerebbe conoscere la tua opinione.