Concetti fondamentali dell'API Private Aggregation

Concetti chiave dell'API Private Aggregation

A chi è destinato questo documento?

L'API Private Aggregation consente la raccolta di dati aggregati dai worklet con accesso a dati cross-site. I concetti condivisi qui sono importanti per gli sviluppatori che creano disponibili all'interno di Archiviazione condivisa e API Protected Audience.

  • Se sei uno sviluppatore e stai creando un sistema di generazione di report per più siti misurazione.
  • 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 è 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 paese nome. 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 aggregati vengono generati e criptati all'interno di un browser. Per API Private Aggregation, che 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 e 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 in batch vengono elaborati in seguito dal servizio di aggregazione; 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 in modo che vengano inviate al servizio di aggregazione.
  3. Una volta raccolti un numero sufficiente di report, li invii in batch e li invii al di aggregazione, in esecuzione in un ambiente di esecuzione attendibile, per generare un report di riepilogo.
di Gemini Advanced.

Il flusso di lavoro descritto in questa sezione è simile a quello della sezione Attribution Reporting tramite Google Cloud. Tuttavia, l'attribuzione I report associano i dati raccolti da un evento impressione a una 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. Una o più dimensioni possono essere codificate 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 contenere fino a 4 cifre ad esempio 1234, e ogni paese è associato a un numero in ordine alfabetico come l'Afghanistan è 1, la Francia è 61 e lo Zimbabwe è "195". Di conseguenza, la chiave aggregabile sarebbe di 7 cifre, dove le prime 4 sono riservati per WidgetID e gli ultimi 3 caratteri sono riservato 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

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 hash ha più di 128 bit, puoi troncarlo per assicurarti che non venga supera il valore massimo consentito del bucket di 2^128−1.

All'interno di un worklet dello spazio di archiviazione condiviso, puoi accedere crypto e TextEncoder moduli che può 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 bucket da un bucket con hash valore:

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 più utenti al fine di generare e approfondimenti sotto forma di valori di riepilogo nei report di riepilogo.

A questo punto, torna alla domanda di esempio posta in precedenza: "Quanti degli utenti chi ha visto il mio widget proviene 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" sono Il valore aggregato che corrisponde alla somma di tutti i valori aggregabili per l'elemento chiave di aggregazione.

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

Per questo esempio, aumenteremo 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 di contributo

Ogni chiamata all'API Private Aggregation è denominata contributo. Per proteggere privacy dell'utente, il numero di contributi che possono essere raccolti da un individuali sono limitate.

Quando si sommano tutti i valori aggregabili in tutte le chiavi di aggregazione, la somma deve essere inferiore al budget di contributo. L'ambito del budget è limitato a ciascun worklet origin, al giorno, ed è separate per i worklet API Protected Audience e Archiviazione condivisa. Un rotolante finestra di conversione all'incirca delle ultime 24 ore viene utilizzata per la giornata. Se un nuovo un report aggregabile potrebbe 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 le spiegazione per saperne di più su questi parametri.

Il valore del budget per il contributo è arbitrario, ma viene adeguato il rumore. Puoi utilizzare questo budget per massimizzare il rapporto tra indicatori e rumore nei valori di riepilogo (trattata più avanti nella sezione Rumore e scalabilità).

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

Report aggregati

Quando l'utente richiama l'API Private Aggregation, il browser genera i report aggregabili affinché possano essere elaborati dal servizio di aggregazione in un secondo momento. in tempo per generare un riepilogo report. Un aggregabile è in formato JSON e contiene un elenco criptato contributi, ognuno dei quali è una coppia di {aggregation key, aggregatable value}. I report aggregati vengono inviati con un ritardo casuale di massimo 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 da verificare che il chiamante possa 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 aggregare report in blocco

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

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

Su questi endpoint, dovrai far funzionare un server, fungendo da raccoglitore, che riceve i report aggregabili inviati dai clienti.

Il server deve quindi generare report in batch e inviare il batch all'aggregazione assistenza. Crea batch basati sulle informazioni disponibili nel file payload del report aggregabile, come il campo shared_info. L'ideale è devono contenere 100 o più report per batch.

Puoi decidere di raggruppare le foto 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 API, della stessa origine report e Pianificare le tempistiche del 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 i 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 sono estratta in modo casuale da una probabilità di Laplace la distribuzione dei contenuti. Mentre sei non controlla direttamente il modo in cui si aggiunge il rumore, si può influenzare l'impatto di rumore sui suoi dati di misurazione.

La distribuzione del rumore è la stessa indipendentemente dalla somma degli aggregabili e i relativi valori. Pertanto, più elevati sono i valori aggregabili, minore è l'impatto che potrebbe avere.

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 l'entità della scalabilità di un determinato aggregabile.

Il rumore è costante indipendentemente dal valore aggregato.

L'aumento dei valori scegliendo un fattore di scala maggiore riduce la relazione il rumore. Tuttavia, questo determina anche la somma di tutti i contributi in tutti i bucket raggiungere più rapidamente il limite del budget di contributo. Ridimensionamento dei valori di scegliendo una costante del fattore di scala più piccolo aumenta il rumore relativo, ma riduce il rischio di raggiungere il limite del budget.

Adatta il valore aggregabile al budget per i contributi.

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

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

Interagisci e condividi il 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.