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 crea un sistema di generazione di report per la misurazione tra siti.
  • Se sei un professionista del marketing, un data scientist o un altro report di riepilogo consumatore, comprendere questi meccanismi ti aiuterà a fare progettazione per recuperare un report di riepilogo ottimizzato.

Termini chiave

Prima di leggere questo documento, ti consigliamo di 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 posizione 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 in una chiave di aggregazione. Se vuoi misurare il numero di utenti della Francia hanno visto i tuoi contenuti, allora France è una dimensione chiave di aggregazione e viewCount di 1 è il valore aggregabile.
  • I report aggregabili vengono generati e criptati in un browser. Per l'API Private Aggregation, contiene i dati relativi a un singolo evento.
  • Il servizio di aggregazione elabora i dati di report aggregabili per creare un report di riepilogo.
  • Un report di riepilogo è l'output finale del servizio di aggregazione. Contengono dati utente aggregati sul rumore e dati dettagliati sulle conversioni.
  • Un worklet è un elemento che ti consente di eseguire funzioni JavaScript specifiche per restituire le informazioni al richiedente. All'interno di un worklet puoi eseguire JavaScript, ma non puoi interagire o comunicare con la pagina esterna.

Flusso di lavoro dell'aggregazione privata

Quando chiami l'API Private Aggregation con una chiave di aggregazione e un aggregabile, il browser genera un report aggregabile. I report vengono inviati al tuo server che raggruppa i report. I report raggruppati vengono successivamente elaborati dal servizio di aggregazione e viene generato un report di riepilogo.

I dati passano dal client al raccoglitore e poi all'aggregazione Servizio per generare un report di riepilogo.
  1. Quando chiami l'API Private Aggregation, il client (browser) genera e invia il report aggregabile al tuo server affinché venga raccolto.
  2. Il server raccoglie i report dai client e li raggruppa per inviarli al servizio di aggregazione.
  3. Una volta raccolti report sufficienti, li raggruppi e li invii 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 a quello della sezione Attribution Reporting tramite Google Cloud. 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 ("chiave" in breve) rappresenta il bucket in cui vengono accumulati valori aggregabili. È possibile codificare una o più dimensioni nella chiave. Una dimensione rappresenta alcuni aspetti che vuoi acquisire di più approfondimenti, ad esempio l'età degli utenti o il numero di impressioni di un annuncio campagna.

Ad esempio, potresti avere un widget incorporato in più siti e vuoi analizzare il paese degli utenti che hanno visto il tuo widget. Stai cercando per rispondere a domande come "Quanti degli utenti che hanno visto il mio widget sono dal 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 è una 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 essere lungo fino a 4 cifre, ad esempio 1234, e che ogni paese sia associato 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 per WidgetID e gli ultimi 3 caratteri sono riservati per CountryID.

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

Chiave di aggregazione
ID widget ID paese
3276 061

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 sottoposto ad hashing e poi convertito in un BigInt valore di 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Se il valore dell'hash ha più di 128 bit, puoi troncarlo per assicurarti che non superi il valore massimo consentito del bucket, ovvero 2^128−1.

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

L'esempio seguente descrive come generare una chiave del 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

Valore aggregato

I valori aggregabili vengono sommati per chiave tra molti utenti per generare informazioni aggregate sotto forma di valori di riepilogo nei report di riepilogo.

A questo punto, torna alla domanda di esempio posta in precedenza: "Quanti degli utenti che hanno visto il mio widget sono dalla Francia?" La risposta a questa domanda sarà ad esempio: "Circa 4881 utenti che hanno visto il mio ID widget 3276 sono dalla Francia". 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.

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

Per questo esempio, incrementiamo il valore di 1 per ogni utente che vede il widget. In pratica, il valore aggregabile può essere scalato per migliorare il rapporto tra indicatori e rumore rapporto.

Budget contributivo

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

Quando si sommano tutti i valori aggregabili in tutte le chiavi di aggregazione, la somma deve essere inferiore al budget di contributo. Il budget è definito in base all'origine del worklet, al giorno ed è distinto per l'API Protected Audience e i worklet dello spazio di archiviazione condiviso. Un rotolante finestra di conversione all'incirca delle ultime 24 ore viene utilizzata per la giornata. Se un nuovo un report aggregabile può causare il superamento del budget, il report non è stato creato.

Il budget di contributo è rappresentato dal parametro L1 ed è impostato su 216 (65.536) per dieci minuti al giorno con un backstop di 220

(1.048.576). Consulta la spiegazione per scoprire di più su questi parametri.

Il valore del budget dei contributi è 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 (discututo ulteriormente nella sezione Rumore e scalabilità).

Per scoprire di più sui budget dei contributi, consulta la spiegazione. Consulta anche la sezione Contributo Budget per ulteriori indicazioni.

Limite di contributi per report

A seconda dell'utente che effettua la chiamata, il limite di contributo può variare. Al momento, i report generati per i chiamanti dell'API Shared Storage hanno un limite di 20 contributi per report. Al contrario, i chiamanti dell'API Protected Audience sono limitati a 100 contributi. per ogni report. Questi limiti sono stati scelti per bilanciare il numero di contributi che può essere incorporato con le dimensioni del payload.

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

Contributi con spaziatura interna

I contributi vengono ulteriormente modificati con una funzionalità di spaziatura interna. L'operazione di padding del payload protegge le informazioni sul numero effettivo di contributi incorporati nel report aggregabile. Il padding aumenta il payload con contributi null (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 in un secondo momento dal servizio di aggregazione 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 aggregabili vengono inviati con un ritardo casuale massimo di un'ora.

I contributi sono criptati e illeggibili al di fuori del servizio di aggregazione. Il servizio di aggregazione decripta i report e genera un report di riepilogo. La la chiave di crittografia per il browser e la chiave di decrittografia per l'aggregazione Il servizio viene emesso 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 chi chiama sia autorizzato a ricevere la chiave di decrittografia.

Un report aggregabile di esempio con il report debug attiva:

  "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 Pagina chrome://private-aggregation-internals:

screenshot della pagina dei dati interni dell'API Private Aggregation

A scopo di test, la casella di controllo "Invia report selezionati" può essere utilizzato per inviare immediatamente 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 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 utilizzare un server che agisce come raccoglitore e riceve i report aggregabili inviati dai client.

Il server deve quindi generare report in batch e inviare il batch all'aggregazione assistenza. Crea batch in base alle informazioni disponibili nel payload non criptato del report aggregabile, ad esempio il campo shared_info. Idealmente, i batch devono contenere almeno 100 report.

Puoi decidere di eseguire il batch su base giornaliera o settimanale. Questa strategia è flessibile, e modificare la strategia di raggruppamento per eventi specifici in cui si prevede maggiore volume, 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 report e con lo stesso orario di pianificazione dei report.

Servizio di aggregazione

Il servizio viene eseguito in un TEE, decripta i report aggregabili e aggiunge per creare il report di riepilogo finale.

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

Per decriptare il payload del report, il servizio di aggregazione recupera una chiave di decriptazione dal coordinatore. Il servizio viene eseguito in un ambiente di esecuzione affidabile (Trusted Execution Environment, TEE), che fornisce un livello di garanzia per l'integrità e la riservatezza dei dati e l'integrità del codice. Sebbene tu possieda e gestisci il servizio, non dovrai visibilità sui dati elaborati all'interno del TEE.

Report di riepilogo

Report riepilogativi ti permettono di vedere i dati che hai raccolto con l'aggiunta di rumore. Puoi richiedere report di riepilogo per un determinato insieme di chiavi.

Un report di riepilogo contiene un insieme di coppie chiave-valore in stile dizionario JSON. Ciascuna 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 l'aggiunta di 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 ogni volta che viene richiesto un report di riepilogo. I valori del rumore vengono ricavati in modo casuale da una distribuzione di probabilità di Laplace. Anche se non hai il controllo diretto sui modi in cui viene aggiunto il rumore, puoi influire sull'impatto del rumore sui dati di misurazione.

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

Ad esempio, supponiamo che la distribuzione del rumore abbia una deviazione standard di 100 ed è centrato su zero. Se il valore del report aggregabile (o "aggregatable value") è solo 200, la deviazione standard del rumore sarà pari al 50% del valore aggregato. Ma se il valore aggregabile è 20.000, la deviazione standard del rumore sarà solo lo 0,5% del valore aggregato. Quindi, un valore aggregabile di 20.000 avrebbe un rapporto indicatore-rumore molto più elevato.

Pertanto, moltiplicare il valore aggregabile per un fattore di scala può aiutare e ridurre il rumore. Il fattore di scala rappresenta il grado di scalatura di un determinato valore aggregabile.

Il rumore è costante indipendentemente dal valore aggregato.

Lo scale up dei valori scegliendo un fattore di scala maggiore riduce la relazione il rumore. Tuttavia, questo fa sì che anche la somma di tutti i contributi in tutti i bucket raggiunga più velocemente il limite di budget dei contributi. La riduzione dei valori scegliendo una costante del fattore di scala più piccola aumenta il rumore relativo, ma riduce il rischio di raggiungere il limite di budget.

Adatta il valore aggregabile al budget per i contributi.

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

Consulta la sezione Budget contributivo documentazione per saperne di più.

Coinvolgere e condividere feedback

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