Concetti fondamentali dell'API Private Aggregation

Concetti chiave dell'API Private Aggregation

A chi è destinato questo documento?

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

• Se sei uno sviluppatore che sta creando un sistema di generazione di report per la misurazione tra siti.
• Se sei un professionista del 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, sarà utile acquisire familiarità con i termini e i concetti chiave. Ognuno 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 località in cui il browser riporta il nome del paese. Una chiave di aggregazione può contenere più di una dimensione (ad esempio, paese e ID del widget dei contenuti).
• Un valore aggregabile è un singolo punto dati raccolto in una chiave di aggregazione. Se vuoi misurare quanti utenti provenienti dalla Francia hanno visto i tuoi contenuti, France è una dimensione nella chiave di aggregazione, mentre viewCount di 1 è il valore aggregabile.
• I report aggregati vengono generati e criptati all'interno di un browser. Per l'API Private Aggregation, contiene i dati su un singolo evento.
• Il servizio di aggregazione elabora i dati provenienti dai report aggregabili per creare un report di riepilogo.
• Un report di riepilogo è l'output finale dell'Aggregation Service e contiene dati utente aggregati sul rumore e dati dettagliati sulle conversioni.
• Un worklet è un'infrastruttura che 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 aggregazione privata

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 server che raggruppa i report. I report raggruppati vengono elaborati successivamente da Aggregation Service 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 da raccogliere.
2. Il tuo server raccoglie i report dai client e li raggruppa in modo che vengano inviati al servizio di aggregazione.
3. Quando hai raccolto un numero sufficiente di report, puoi raggrupparli e inviarli al servizio di aggregazione, in esecuzione in un ambiente di esecuzione attendibile, per generare un report di riepilogo.

Termine chiave: l'ambiente di esecuzione affidabile è una configurazione speciale di hardware e software per computer che consente a parti esterne di verificare le versioni esatte del software in esecuzione sul computer. I TEE consentono a parti esterne di verificare che il software faccia esattamente ciò che afferma il produttore del software, nulla di più o meno.

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 di impressione e un evento di conversione, che si verificano in momenti diversi. L'aggregazione privata misura un singolo evento tra siti.

Chiave di aggregazione

Una chiave di aggregazione ("chiave" in breve) rappresenta il bucket in cui verranno accumulati i valori aggregati. Una o più dimensioni possono essere codificate nella chiave. Una dimensione rappresenta alcuni aspetti su cui vuoi ottenere maggiori informazioni, come l'età degli utenti o il numero di impressioni di una campagna pubblicitaria.

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

La chiave fornita all'API Private Aggregation è un BigInt, che consiste in diverse 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 sarebbe di 7 cifre, dove i primi 4 caratteri sono riservati per WidgetID e gli ultimi 3 caratteri sono riservati per CountryID.

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

Chiave di aggregazione
ID widget	ID paese
3276	061

Esempio: se una dimensione ha uno spazio per le chiavi disponibile per più cifre, ma il valore ne ha di meno, aggiungi gli zeri iniziali. Ad esempio, se l'ID paese consente 3 cifre, l'ID paese per l'Algeria è 003.

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

All'interno di un worklet Archiviazione condivisa, 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.

Nell'esempio seguente viene descritto come generare una chiave bucket da un valore sottoposto ad hashing:

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

Nota: sebbene i concetti siano simili, la chiave viene creata in modo diverso per l'API Private Aggregation rispetto all'API Attribution Reporting. Per l'aggregazione privata, la chiave completa viene specificata contemporaneamente nella chiamata JavaScript.

Valore aggregato

I valori aggregati vengono sommati per chiave per più utenti per generare approfondimenti aggregati sotto forma di valori di riepilogo nei report di riepilogo.

Ora torniamo all'esempio di domanda precedente: "Quanti 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 provengono dalla Francia". Il valore aggregato è 1 per ogni utente e "4881 utenti" è il valore aggregato che corrisponde alla somma di tutti i valori aggregati per la chiave di aggregazione in questione.

Chiave di aggregazione		Valore aggregato
ID widget	ID paese	Numero di visualizzazioni
3276	061	1

Per questo esempio, aumentiamo il valore di 1 per ogni utente che vede il widget. In pratica, il valore aggregabile può essere scalato per migliorare il rapporto indicatore-rumore.

Budget per il contributo

Ogni chiamata all'API Private Aggregation è denominata contributo. Per proteggere la privacy degli utenti, il numero di contributi che è possibile raccogliere da un privato è limitato.

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

Il budget di contributo è rappresentato dal parametro L₁ ed è impostato su 2¹⁶ (65.536) ogni dieci minuti al giorno con un backstop di 2²⁰

(1.048.576). Per scoprire di più su questi parametri, consulta la spiegazione.

Il valore del budget per il contributo è arbitrario, ma viene adattato il rumore. Puoi utilizzare questo budget per massimizzare il rapporto segnale-rumore nei valori di riepilogo (esaminati ulteriormente nella sezione Rumore e scalabilità).

Per scoprire di più sui budget per i contributi, consulta questo spiegazione. Per ulteriori indicazioni, consulta anche la pagina Budget per il contributo.

Report aggregati

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

I contributi sono criptati e illeggibili al di fuori del servizio di aggregazione. Aggregation Service 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 Key Management Service. Il coordinatore conserva un elenco di hash binari dell'immagine del servizio per verificare che il chiamante possa ricevere la chiave di decrittografia.

Un 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 consultati dalla pagina di 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 report aggregabili

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

• Per lo spazio di archiviazione condiviso: /.well-known/private-aggregation/report-shared-storage
• Per Protected Audience: /.well-known/private-aggregation/report-protected-audience

In questi endpoint, dovrai utilizzare un server, che funga da raccoglitore, che riceve i report aggregabili inviati dai clienti.

Il server deve quindi inviare report in batch e inviare il batch al servizio di aggregazione. Crea batch basati sulle informazioni disponibili nel payload non criptato del report aggregabile, ad esempio il campo shared_info. Idealmente, i batch dovrebbero contenere 100 o più report per batch.

Puoi decidere di eseguire il raggruppamento su base giornaliera o settimanale. Questa strategia è flessibile e puoi modificarla 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 con la stessa versione dell'API, la stessa origine di reporting e pianificare la data del report.

Servizio di aggregazione

Il servizio di aggregazione riceve report aggregabili criptati dal raccoglitore e genera report di riepilogo.

Per decriptare il payload del report, Aggregation Service recupera una chiave di decrittografia dal coordinatore. Il servizio viene eseguito in un ambiente di esecuzione affidabile (TEE, Trusted Execution Environment), che garantisce un livello di garanzia relativo all'integrità e alla riservatezza dei dati e all'integrità del codice. Anche se possiedi e gestisci il servizio, non hai visibilità sui dati in fase di elaborazione all'interno del TEE.

Report di riepilogo

I report di riepilogo ti consentono di visualizzare i dati raccolti con l'aggiunta del rumore. Puoi richiedere report di riepilogo per un determinato set di chiavi.

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

• bucket: la chiave di aggregazione come stringa di numero binario. 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 l'aggiunta del rumore.

Ad esempio:

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

Rumore e scalabilità

Per tutelare la privacy degli utenti, il servizio di aggregazione aggiunge il 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 delle modalità di aggiunta del rumore, puoi influenzare l'impatto del rumore sui suoi dati di misurazione.

La distribuzione del rumore è la stessa indipendentemente dalla somma dei valori aggregabili. Pertanto, maggiore è il numero di valori aggregabili, minore sarà l'impatto che il rumore potrebbe avere.

Ad esempio, supponiamo che la distribuzione del rumore abbia una deviazione standard di 100 ed sia centrata su zero. Se il valore del report aggregabile raccolto (o "valore aggregato") è 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 dello 0, 5% del valore aggregato. Pertanto, il valore aggregato di 20.000 avrebbe un rapporto segnale-rumore molto più elevato.

Pertanto, moltiplicando il valore aggregabile per un fattore di scalabilità può contribuire a ridurre il rumore di fondo. Il fattore di scalabilità rappresenta di quanto vuoi scalare un determinato valore aggregabile.

Fare lo scale up dei valori scegliendo un fattore di scalabilità più grande riduce il rumore relativo. Tuttavia, ciò fa sì che la somma di tutti i contributi in tutti i bucket raggiunga più velocemente il limite del budget per i contributi. La scalabilità dei valori scegliendo una costante minore del fattore di scalabilità aumenta il rumore relativo, ma riduce il rischio di raggiungere il limite del budget.

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

Per scoprire di più, consulta la documentazione sul budget di contributo.

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 l'spiegazione, fai 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.