Panoramica dell'API Private Aggregation

Genera report di dati aggregati utilizzando i dati di Protected Audience e i dati cross-site da Shared Storage.

Punto chiave: la prova dell'origine di Pertinenza e Misurazione dell'origine di Privacy Sandbox è terminata il 20 settembre 2023 e le API sono ora disponibili per il 99% degli utenti di Chrome e la registrazione alla prova dell'origine è stata chiusa. Per stare al passo con la percentuale di utenti per cui è abilitata ogni API, consulta i grafici di stato di Chrome.

Per fornire funzionalità critiche utilizzate dal web, l'API Private Aggregation è stata creata per aggregare e generare report sui dati tra siti nel rispetto 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 i dati cross-site da Shared Storage.

Questa API attualmente fornisce un'operazione, sendHistogramReport(), ma potrebbe essere supportata in futuro in futuro. L'operazione con 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 a 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 aver riscontrato un bug nello script di terze parti. Questa operazione viene eseguita all'interno del worklet di un'altra API.

Termine chiave: worklet consente di eseguire funzioni JavaScript specifiche e restituire informazioni al richiedente. All'interno di un worklet puoi eseguire JavaScript, ma non puoi interagire o comunicare con la pagina esterna.

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

Concetti fondamentali

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. I report raggruppati vengono elaborati successivamente dal Servizio di aggregazione e viene generato un report di riepilogo.

Consulta il documento sui concetti fondamentali dell'API Private Aggregation per saperne di più sui concetti chiave 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 è creata per le misurazioni tra siti in combinazione con API come l'API Protected Audience e Shared Storage. Entrambe le API producono report aggregabili che vengono utilizzati dal back-end del servizio di aggregazione per generare report di riepilogo.

I report sull'attribuzione associano i dati raccolti da un evento di impressione e da un evento di conversione, che si verificano in momenti diversi. L'aggregazione privata misura un singolo evento tra siti.

Testa questa API

L'API Private Aggregation può essere testata in locale attivando il flag dell'esperimento sulle API degli annunci di Privacy Sandbox all'indirizzo chrome://flags/#privacy-sandbox-ads-apis.

Imposta l'esperimento sulle API degli annunci di Privacy Sandbox su abilitato per utilizzare queste API

Scopri di più sui test nell'esperimento e partecipare.

Utilizza la demo

La demo dell'API Private Aggregation per l'archiviazione condivisa è disponibile 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 generica per la misurazione tra siti ed è disponibile per l'utilizzo nei worklet Shared Storage e Protected Audience. Il primo passaggio consiste nel decidere quali informazioni raccogliere. Questi punti dati sono la base delle chiavi di aggregazione.

Con spazio di archiviazione condiviso

Lo spazio di archiviazione condiviso ti consente di leggere e scrivere dati tra siti in un ambiente sicuro per evitare fughe di dati, mentre l'API Private Aggregation ti consente di misurare i dati tra siti archiviati nello spazio di archiviazione condiviso.

Misurazione della copertura unica

Ti consigliamo di misurare il numero di utenti unici che hanno visto i loro contenuti. L'API Private Aggregation può fornire una risposta come "Circa 317 utenti unici hanno visualizzato l'ID Content ID 861".

In Archiviazione condivisa puoi impostare un flag per indicare se l'utente ha già visto i contenuti o meno. Durante la prima visita in cui il flag non esiste, viene effettuata una chiamata all'aggregazione privata e poi viene impostato il flag. Nelle visite successive dell'utente, comprese le visite tra siti, puoi controllare lo spazio di archiviazione condiviso 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.

L'aggregazione privata può fornire una risposta, ad esempio: "Circa 317 utenti unici provengono da età compresa tra i 18 e i 45 anni e provengono dalla Germania". Utilizza lo spazio di archiviazione condiviso per accedere ai dati demografici da un contesto di terze parti. In un secondo momento, puoi generare un report con l'aggregazione privata codificando le dimensioni età e paese nella chiave di aggregazione.

Misurazione della frequenza K+

Ti consigliamo di misurare il numero di utenti che hanno visto un contenuto o un annuncio almeno K volte su un determinato browser, per ottenere il valore K prescelto.

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 Archiviazione condivisa da siti diversi e può essere letto all'interno di un worklet. Quando il conteggio ha raggiunto K, è possibile inviare un report tramite l'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 ti 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 nelle aste.

Da un worklet dell'API Protected Audience, puoi aggregare i dati direttamente utilizzando sendHistogramReport() e generare report sui dati in base a un attivatore utilizzando reportContributionForEvent(), che è un'estensione speciale per l'API Protected Audience.

Funzioni disponibili

Le seguenti funzioni sono disponibili nell'oggetto privateAggregation disponibili nei worklet dell'API Shared Storage e Protected Audience.

contributeToHistogram()

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

Ecco un esempio di come può essere chiamato nello 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);

L'esempio di codice sopra riportato chiama Private Aggregation ogni volta che vengono caricati i contenuti iframe tra siti. Il codice iframe carica il worklet e il worklet 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 l'invio di un report solo se si verifica un determinato evento. Inoltre, questa funzione fa sì che il bucket e il valore dipendano da indicatori non ancora disponibili in quel momento dell'asta.

Il metodo privateAggregation.reportContributionForEvent(eventType, contribution) utilizza un eventType che specifica l'evento di attivazione e il 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 perdita dell'asta, oppure può provenire da un frame isolato che ha visualizzato l'annuncio. Per inviare un report sugli eventi di asta, puoi utilizzare due parole chiave riservate, reserved.win, reserved.loss e reserved.always. Per inviare un report attivato da un evento da un frame isolato, definisci un tipo di evento personalizzato. Per attivare l'evento da un frame isolato, 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 vincita dell'asta e un report sui clic se viene attivato un evento click dal frame recintato che ha 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 il video esplicativo sui report estesi sull'aggregazione privata.

enableDebugMode()

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

La chiamata di privateAggregation.enableDebugMode() nel worklet consente di attivare la modalità di debug, il 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 di Aggregation Service.

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

Importante: la modalità di debug è disponibile temporaneamente per i browser in modalità B in cui i cookie di terze parti sono disabilitati, al fine di facilitare i test e la preparazione al ritiro dei cookie di terze parti. Per i browser in Modalità B, le chiamate a enableDebugMode() attiveranno correttamente i report di debug.

Puoi anche impostare la chiave di debug chiamando privateAggregation.enableDebugMode({ <debugKey: debugKey> }), dove 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 e i dati di una misurazione di aggregazione privata. Queste possono essere chiamate una sola volta per contesto. Eventuali chiamate successive verranno ignorate.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Segnalare la verifica

Per l'archiviazione condivisa, puoi verificare la legittimità dei report aggregabili che hai ricevuto aggiungendo un ID contesto alla chiamata dell'operazione di archiviazione condivisa. L'ID verrà allegato al report inviato e, in un secondo momento, potrai utilizzarlo per verificare che il report sia stato inviato dall'operazione di spazio di archiviazione condiviso.

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 il spiegazione esplicativa sulla verifica della segnalazione.

Interagisci e condividi feedback

L'API Private Aggregation è in fase di discussione attiva ed è soggetta a modifiche in futuro. Se provi questa API e vuoi fornire un feedback, ci farebbe piacere conoscere la tua opinione.

• GitHub: leggi il spiegatore, poni domande e partecipa alla discussione.
• Assistenza per gli sviluppatori: poni domande e partecipa alle discussioni sul repository dell'assistenza per gli sviluppatori di Privacy Sandbox.
• Unisciti al gruppo di API Shared Storage e al gruppo di API Protected Audience per gli ultimi annunci relativi all'aggregazione privata.