Concetti fondamentali dell'API Private Aggregation

Concetti chiave dell'API Private Aggregation

A chi è rivolto questo documento?

L'API Private Aggregation consente la raccolta di dati aggregati dai worklet con accesso ai dati cross-site. I concetti condivisi qui sono importanti per gli sviluppatori che creano funzioni di generazione di report all'interno dell'API Shared Storage e Protected Audience.

• Se sei uno sviluppatore che sta creando un sistema di reporting per la misurazione cross-site.
• Se sei un esperto di marketing, un data scientist o un altro consumatore di report di riepilogo, comprendere questi meccanismi ti aiuterà a prendere decisioni di progettazione per recuperare un report di riepilogo ottimizzato.

Termini chiave

Prima di leggere questo documento, è utile acquisire familiarità con termini e concetti chiave. Ciascuno di questi termini verrà descritto in dettaglio qui.

• Una chiave di aggregazione (nota anche come bucket) è una raccolta predeterminata di punti dati. Ad esempio, potresti voler raccogliere un bucket di dati sulla posizione in cui il browser segnala il nome del paese. Una chiave di aggregazione può contenere più di una dimensione (ad esempio, il paese e l'ID del widget dei contenuti).
• Un valore aggregabile è un singolo punto dati raccolto in una chiave di aggregazione. Se vuoi misurare quanti utenti della Francia hanno visto i tuoi contenuti, France è una dimensione nella chiave di aggregazione e viewCount di 1 è il valore aggregabile.
• I report aggregabili vengono generati e criptati all'interno di un browser. Per l'API Private Aggregation, contiene dati su un singolo evento.
• Il servizio di aggregazione elabora i dati dei report aggregabili per creare un report di riepilogo.
• Un report di riepilogo è l'output finale di Aggregation Service e contiene dati utente aggregati con rumore e dati dettagliati sulle conversioni.
• Un worklet è un componente dell'infrastruttura che ti 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.

Flusso di lavoro di Private Aggregation

Quando chiami l'API Private Aggregation con una chiave di aggregazione e un valore aggregabile, il browser genera un report aggregabile. I report vengono inviati al tuo server che li raggruppa in batch. I report in batch vengono elaborati in un secondo momento dal servizio di aggregazione e viene generato un report di riepilogo.

1. Quando chiami l'API Private Aggregation, il client (browser) genera e invia il report aggregabile al tuo server per essere raccolto.
2. Il server raccoglie i report dai client e li raggruppa in batch da inviare al servizio di aggregazione.
3. Una volta raccolti un numero sufficiente di report, li raggrupperai e li invierai al servizio di aggregazione, in esecuzione in un ambiente di esecuzione attendibile, per generare un report di riepilogo.

Il flusso di lavoro descritto in questa sezione è simile all'API Attribution Reporting. Tuttavia, i report sull'attribuzione associano i dati raccolti da un evento impressione e da un evento conversione, che si verificano in momenti diversi. L'aggregazione privata misura un singolo evento cross-site.

Chiave di aggregazione

Una chiave di aggregazione (o semplicemente "chiave") rappresenta il bucket in cui verranno accumulati i valori aggregabili. Una o più dimensioni possono essere codificate nella chiave. Una dimensione rappresenta un aspetto su cui vuoi ottenere maggiori informazioni, ad esempio la fascia d'età degli utenti o il conteggio delle impressioni di una campagna pubblicitaria.

Ad esempio, potresti avere un widget incorporato in più siti e voler analizzare il paese degli utenti che lo hanno visualizzato. Vuoi rispondere a domande come "Quanti degli utenti che hanno visto il mio widget provengono dal paese X?" Per generare report su questa domanda, puoi configurare una chiave di aggregazione che codifica due dimensioni: ID widget e ID paese.

La chiave fornita all'API Private Aggregation è un BigInt, che è composto da più dimensioni. In questo esempio, le dimensioni sono l'ID widget e l'ID paese. Supponiamo che l'ID widget possa contenere fino a 4 cifre, ad esempio 1234, e che ogni paese sia mappato a un numero in ordine alfabetico, ad esempio l'Afghanistan è 1, la Francia è 61 e lo Zimbabwe è 195. Pertanto, la chiave aggregabile sarà lunga 7 cifre, dove i primi 4 caratteri sono riservati al WidgetID e gli ultimi 3 caratteri sono riservati al CountryID.

Supponiamo che la chiave rappresenti il conteggio degli utenti provenienti dalla Francia (ID paese 061) che hanno visualizzato l'ID widget 3276. La chiave di aggregazione è 3276061.

La chiave di aggregazione può essere generata anche con un meccanismo di hashing, ad esempio SHA-256. Ad esempio, la stringa {"WidgetId":3276,"CountryID":67} può essere sottoposta ad hashing e poi convertita in un valore BigInt pari a 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Se il valore hash ha più di 128 bit, puoi troncarlo per assicurarti che non superi il valore bucket massimo consentito di 2^128−1.

All'interno di un worklet Shared Storage, puoi accedere ai moduli crypto e TextEncoder che possono aiutarti a generare un hash. Per scoprire di più sulla generazione di un hash, consulta SubtleCrypto.digest() su MDN.

Il seguente esempio descrive come generare una chiave bucket da un valore con hash:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

Valore aggregabile

I valori aggregabili vengono sommati per chiave in molti utenti per generare approfondimenti aggregati sotto forma di valori di riepilogo nei report di riepilogo.

Ora torniamo alla domanda di esempio posta in precedenza: "Quanti degli utenti che hanno visto il mio widget provengono dalla Francia?" La risposta a questa domanda sarà simile a "Circa 4881 utenti che hanno visto il mio ID widget 3276 sono francesi". Il valore aggregabile è 1 per ogni utente e "4881 utenti" è il valore aggregato, ovvero la somma di tutti i valori aggregabili per quella chiave di aggregazione.

Per questo esempio, incrementiamo il valore di 1 per ogni utente che visualizza il widget. In pratica, il valore aggregabile può essere scalato per migliorare il rapporto segnale/rumore.

Budget per i contributi

Ogni chiamata all'API Private Aggregation è chiamata contributo. Per proteggere la privacy degli utenti, il numero di contributi che possono essere raccolti da un singolo utente è limitato.

Quando sommi tutti i valori aggregabili in tutte le chiavi di aggregazione, la somma deve essere inferiore al budget di contributo. Il budget è definito per worklet origine, per giorno ed è separato per i worklet dell'API Protected Audience e di Shared Storage. Per il giorno viene utilizzata una finestra mobile di circa le ultime 24 ore. Se un nuovo report aggregabile causerebbe il superamento del budget, il report non viene creato.

Il budget per i contributi è rappresentato dal parametro L₁ ed è impostato su 2¹⁶ (65.536) ogni 10 minuti al giorno con un limite di 2²⁰ (1.048.576). Per scoprire di più su questi parametri, consulta la spiegazione.

Il valore del budget di contribuzione è arbitrario, ma il rumore viene scalato in base a questo valore. Puoi utilizzare questo budget per massimizzare il rapporto segnale/rumore sui valori di riepilogo (approfondito nella sezione Rumore e scalabilità).

Per saperne di più sui budget per i contributi, consulta la spiegazione. Consulta anche il budget per i contributi per maggiori informazioni.

Limite di contributi per report

A seconda di chi chiama, il limite di contributo può variare e, per l'archiviazione condivisa, questi limiti sono predefiniti e possono essere ignorati. Al momento, i report generati per i chiamanti dell'API Shared Storage sono limitati a 20 contributi per report. D'altra parte, i chiamanti dell'API Protected Audience hanno un limite di 100 contributi per report. Questi limiti sono stati scelti per bilanciare il numero di contributi che possono essere incorporati con le dimensioni del payload.

Per lo spazio di archiviazione condiviso, i contributi apportati in una singola operazione run() o selectURL() vengono raggruppati in un unico report. Per Protected Audience, i contributi apportati da una singola origine all'interno di un'asta vengono raggruppati.

Contributi con spaziatura interna

I contributi vengono ulteriormente modificati con una funzionalità di padding. L'operazione di padding del payload protegge le informazioni sul numero effettivo di contributi incorporati nel report aggregabile. Il padding aumenta il payload con null contributi (ovvero con valore 0) per raggiungere una lunghezza fissa.

Report aggregabili

Una volta che l'utente richiama l'API Private Aggregation, il browser genera report aggregabili da elaborare dal servizio di aggregazione in un secondo momento per generare report di riepilogo. Un report aggregabile è in formato JSON e contiene un elenco criptato di contributi, ognuno dei quali è una coppia {aggregation key, aggregatable value}. I report aggregabili vengono inviati con un ritardo casuale fino a un'ora.

I contributi sono criptati e non leggibili al di fuori del servizio di aggregazione. Il servizio di aggregazione decripta i report e genera un report di riepilogo. La chiave di crittografia per il browser e la chiave di decrittografia per il servizio di aggregazione vengono emesse dal coordinatore, che funge da servizio di gestione delle chiavi. Il coordinatore mantiene un elenco di hash binari dell'immagine del servizio per verificare che il chiamante sia autorizzato a ricevere la chiave di decrittografia.

Esempio di report aggregabile con la modalità di debug attivata:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

I report aggregabili possono essere esaminati dalla pagina chrome://private-aggregation-internals:

A scopo di test, il pulsante "Invia report selezionati" può essere utilizzato per inviare immediatamente il report al server.

Raccogliere e raggruppare i report aggregabili

Il browser invia i report aggregabili all'origine del worklet contenente la chiamata all'API Private Aggregation, utilizzando il percorso ben noto elencato:

• Per Shared Storage: /.well-known/private-aggregation/report-shared-storage
• Per Protected Audience: /.well-known/private-aggregation/report-protected-audience

In questi endpoint, dovrai gestire un server che funge da raccoglitore e riceve i report aggregabili inviati dai client.

Il server deve quindi raggruppare i report in batch e inviarli al servizio di aggregazione. Crea batch in base alle informazioni disponibili nel payload non criptato del report aggregabile, ad esempio il campo shared_info. Idealmente, i batch dovrebbero contenere almeno 100 report ciascuno.

Puoi decidere di raggruppare i dati su base giornaliera o settimanale. Questa strategia è flessibile e puoi modificare la strategia di raggruppamento per eventi specifici in cui prevedi un volume maggiore, ad esempio i giorni dell'anno in cui sono previste più impressioni. I batch devono includere report della stessa versione dell'API, della stessa origine di reporting e dello stesso orario di generazione del report.

ID filtro

L'API Private Aggregation e il servizio di aggregazione consentono l'utilizzo di ID di filtro per elaborare le misurazioni a un livello più granulare, ad esempio per campagna pubblicitaria, anziché elaborare i risultati in query più grandi.

Per iniziare a utilizzarlo oggi, ecco alcuni passaggi approssimativi da applicare all'implementazione attuale.

Passaggi di Shared Storage

Se utilizzi l'API Shared Storage nel tuo flusso:

1. Definisci dove dichiarare ed eseguire il nuovo modulo Shared Storage. Nell'esempio seguente, abbiamo denominato il file del modulo filtering-worklet.js, registrato in filtering-example.

   (async function runFilteringIdsExample () {
   await window.sharedStorage.worklet.addModule('filtering-worklet.js');
   await window.sharedStorage.run('filtering-example', {
     keepAlive: true,
     privateAggregationConfig: {
       contextId: 'example-id',
       filteringIdMaxBytes: 8 // optional
     }
   }});
   })();
   

   Tieni presente che filteringIdMaxBytes è configurabile per report e, se non impostato, il valore predefinito è 1. Questo valore predefinito serve a evitare di aumentare inutilmente le dimensioni del payload e quindi i costi di archiviazione ed elaborazione. Scopri di più nella spiegazione del contributo flessibile.

2. In filtering-worklet.js, quando trasferisci un contributo a privateAggregation.contributeToHistogram(...) all'interno del worklet Shared Storage, puoi specificare un ID filtro.

   // Within  filtering-worklet.js
   class FilterOperation {
     async run() {
       let contributions = [{
         bucket: 1234n,
         value: 56,
         filteringId: 3n // defaults to 0n if not assigned, type bigint
       }];
   
       for (const c of contributions) {
         privateAggregation.contributeToHistogram(c);
       }
       …
   }
   });
   
   register('filtering-example', FilterOperation);
   

3. I report aggregabili verranno inviati all'endpoint che hai definito /.well-known/private-aggregation/report-shared-storage. Continua a leggere la guida al filtraggio degli ID per scoprire le modifiche necessarie nei parametri del job del servizio di aggregazione.

Una volta completato il batch e inviato al servizio di aggregazione di cui è stato eseguito il deployment, i risultati filtrati devono essere riportati nel report di riepilogo finale.

Passaggi di Protected Audience

Se utilizzi l'API Protected Audience nel tuo flusso:

1. Nell'implementazione attuale di Protected Audience, puoi impostare quanto segue per l'integrazione con Private Aggregation. A differenza dello spazio di archiviazione condiviso, non è ancora possibile configurare le dimensioni massime degli ID di filtraggio. Per impostazione predefinita, la dimensione massima dell'ID filtro è 1 byte e verrà impostata su 0n. Tieni presente che questi valori verranno impostati nelle funzioni di generazione di report Protected Audience (ad es.reportResult() o generateBid()).

   const contribution = {
     ...
     filteringId: 0n
   };
   
   privateAggregation.contributeToHistogram(contribution);
   

2. I report aggregabili verranno inviati all'endpoint che hai definito /.well-known/private-aggregation/report-protected-audience. Una volta completato il batch e inviato al servizio di aggregazione di cui è stato eseguito il deployment, i risultati filtrati devono essere riportati nel report di riepilogo finale. Di seguito sono disponibili le spiegazioni dell'API Attribution Reporting e dell'API Private Aggregation, nonché la proposta iniziale.

Continua a leggere la nostra guida all'applicazione di filtri agli ID nel servizio di aggregazione o vai alle sezioni dell'API Attribution Reporting per una descrizione più dettagliata.

Servizio di aggregazione

Il servizio di aggregazione riceve report aggregabili criptati dal raccoglitore e genera report di riepilogo. Per ulteriori strategie su come creare report aggregabili in batch nel tuo raccoglitore, consulta la nostra guida al batch.

Il servizio viene eseguito in un Trusted Execution Environment (TEE), che fornisce un livello di garanzia per l'integrità dei dati, la riservatezza dei dati e l'integrità del codice. Se vuoi esaminare più da vicino come vengono utilizzati i coordinatori insieme agli ambienti di esecuzione attendibili, scopri di più sul loro ruolo e scopo.

Report di riepilogo

I report di riepilogo ti consentono di visualizzare i dati che hai raccolto con l'aggiunta di rumore. Puoi richiedere report riepilogativi per un determinato insieme di chiavi.

Un report di riepilogo contiene un insieme di coppie chiave-valore in stile dizionario JSON. Ogni coppia contiene:

• bucket: la chiave di aggregazione come stringa di numeri binari. Se la chiave di aggregazione utilizzata è "123", il bucket è "1111011".
• value: il valore di riepilogo per un determinato obiettivo di misurazione, sommato da tutti i report aggregabili disponibili con rumore aggiunto.

Ad esempio:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Rumore e scalabilità

Per preservare la privacy degli utenti, il servizio di aggregazione aggiunge rumore una volta a ogni valore di riepilogo ogni volta che viene richiesto un report di riepilogo. I valori del rumore vengono estratti in modo casuale da una distribuzione di probabilità di Laplace. Anche se non hai il controllo diretto sulle modalità di aggiunta del rumore, puoi influenzarne l'impatto sui dati di misurazione.

La distribuzione del rumore è la stessa indipendentemente dalla somma di tutti i valori aggregabili. Pertanto, più alti sono i valori aggregabili, minore è l'impatto che il rumore potrebbe avere.

Ad esempio, supponiamo che la distribuzione del rumore abbia una deviazione standard di 100 e sia centrata sullo zero. Se il valore del report aggregabile raccolto (o "valore aggregabile") è solo 200, la deviazione standard del rumore sarebbe il 50% del valore aggregato. Tuttavia, se il valore aggregabile è 20.000,la deviazione standard del rumore sarebbe solo lo 0, 5% del valore aggregato. Pertanto, il valore aggregabile di 20.000 avrebbe un rapporto segnale/rumore molto più elevato.

Pertanto, moltiplicare il valore aggregabile per un fattore di scalabilità può contribuire a ridurre il rumore. Il fattore di scalabilità rappresenta la quantità di scalabilità che vuoi applicare a un determinato valore aggregabile.

Aumentando i valori scegliendo un fattore di scalabilità maggiore si riduce il rumore relativo. Tuttavia, in questo modo la somma di tutti i contributi in tutti i bucket raggiunge più rapidamente il limite di budget per i contributi. Ridurre i valori scegliendo una costante del fattore di scalabilità più piccola aumenta il rumore relativo, ma riduce il rischio di raggiungere il limite di budget.

Per calcolare un fattore di scalabilità appropriato, dividi il budget del contributo per la somma massima dei valori aggregabili in tutte le chiavi.

Per saperne di più, consulta la documentazione sul budget per i contributi.

Partecipare e condividere feedback

L'API Private Aggregation è in fase di discussione e soggetta a modifiche in futuro. Se provi questa API e hai un feedback, ci farebbe piacere riceverlo.

• GitHub: leggi l'explainer, poni domande e partecipa alla discussione.
  • Assistenza per gli sviluppatori: fai domande e partecipa alle discussioni nel repository Privacy Sandbox Developer Support.
• Unisciti al gruppo dell'API Shared Storage e al gruppo dell'API Protected Audience per ricevere gli ultimi annunci relativi all'aggregazione privata.