Genera report di dati aggregati utilizzando i dati di Protected Audience e i dati cross-site di Archiviazione condivisa.
Per fornire funzionalità fondamentali su cui si basa il web, Private Aggregation L'API è stata creata per l'aggregazione e la generazione di report su dati cross-site in una che tutela la privacy.
Stato implementazione
Proposta | Stato |
---|---|
Evita report dell'API Private Aggregation non validi con la verifica dei report per lo spazio di archiviazione condiviso Spiegazione |
Disponibile in Chrome |
La disponibilità della modalità di debug di aggregazione privata dipende dall'idoneità di terze parti Problema GitHub |
Disponibile in Chrome M119 |
Riduzione del ritardo della segnalazione Spiegazione |
Disponibile in Chrome M119 |
Supporto per l'API Private Aggregation e il servizio di aggregazione per Google Cloud Spiegazione |
Disponibile in Chrome M121 |
Spaziatura interna per payload dei report aggregabili Spiegazione |
Disponibile in Chrome M119 |
Modalità di debug di aggregazione privata disponibile per i report di AuctionReportBuyers Spiegazione |
Previste in Chrome M123 |
Supporto dell'ID filtro Spiegazione |
Previste in Chrome M128 |
Che cos'è l'API Private Aggregation
L'API Private Aggregation consente agli sviluppatori di generare report sui dati aggregati con dati dell'API Protected Audience e dati cross-site da Spazio di archiviazione condiviso.
La funzione principale di questa API è nota come contributeToHistogram()
. L'operazione sull'istogramma ti consente di aggregare i dati
tra gli utenti di ciascun bucket (noto nell'API come chiave di aggregazione) che definisci.
La chiamata dell'istogramma accumula valori e restituisce un risultato aggregato con rumore.
sotto forma di report di riepilogo. Ad esempio, il report potrebbe mostrare il numero
siti su cui ciascun utente ha visto i tuoi contenuti o ha rilevato un bug nel tuo script di terze parti. Questa operazione viene eseguita all'interno del worklet di un'altra API.
Ad esempio, se in precedenza hai registrato dati demografici e geografici in Archiviazione condivisa, puoi utilizzare l'API Private Aggregation per creare un istogramma che indichi approssimativamente quanti utenti di New York hanno visualizzato i tuoi contenuti su più siti. Per aggregare 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 in batch. I report in batch vengono elaborati in un secondo momento dal servizio di aggregazione e viene generato un report di riepilogo.
Per saperne di più sui concetti chiave dell'API Private Aggregation, consulta il documento sui concetti fondamentali dell'API Private Aggregation.
Differenze rispetto ai report di 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 è pensata per le misurazioni tra siti in combinazione con API come l'API Protected Audience e l'archiviazione condivisa. Entrambe le API producono report aggregabili che vengono utilizzati dal backend del servizio di aggregazione per generare report di riepilogo.
Attribution Reporting associa i dati raccolti da un evento di impressione a un evento di conversione, che si verificano in momenti diversi. L'aggregazione privata misura un singolo evento tra siti.
Testa questa API
Per testare l'API Private Aggregation localmente, abilita tutte le API di privacy per gli annunci in chrome://settings/adPrivacy
.
Scopri di più sui test in Esperimento e partecipazione.
Usa la demo
Puoi accedere alla demo dell'API Private Aggregation per lo spazio di archiviazione condiviso 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 per uso generico per la misurazione tra siti e può essere utilizzata nei worklet Shared Storage e Protected Audience. Il primo passaggio consiste nel decidere esattamente quali informazioni vuoi raccogliere. Questi punti dati sono la base delle chiavi di aggregazione.
Con spazio di archiviazione condiviso
Spazio di archiviazione condiviso consente di leggere e scrivere dati tra siti in un ambiente sicuro per evitare perdite, mentre l'API Private Aggregation consente di misurare i dati tra siti archiviati in Archiviazione condivisa.
Misurazione della copertura unica
Può essere utile calcolare quanti utenti unici hanno visto i loro contenuti. L'API Private Aggregation può fornire una risposta come "Circa 317 utenti unici hanno visualizzato Content ID 861".
Puoi impostare un flag in Archiviazione condivisa per indicare se l'utente ha già visto i contenuti o meno. Alla prima visita in cui il flag non esiste, viene effettuata una chiamata alla funzione Private Aggregation e poi viene impostato il flag. Per le visite successive dell'utente, comprese quelle tra siti, puoi controllare l'archiviazione condivisa e saltare l'invio di un report all'aggregazione privata se il flag è impostato. Per ulteriori informazioni sui metodi per implementare queste misurazioni, consulta il nostro white paper sulla copertura.
Misurazione dei dati demografici
Ti consigliamo di misurare i dati demografici degli utenti che hanno visto i tuoi contenuti su diversi siti.
Private Aggregation può fornire una risposta come "Circa 317 utenti unici di età compresa tra i 18 e i 45 anni sono residenti in Germania". Utilizza lo spazio di archiviazione condiviso per accedere ai dati demografici da un contesto di terze parti. Potrai generare un report con aggregazione privata in un secondo momento codificando le dimensioni relative all'età e al paese nella chiave di aggregazione.
Misurazione della frequenza K+
Può essere utile misurare il numero di utenti che hanno visualizzato un contenuto o un annuncio almeno K volte su un determinato browser, per ottenere un valore preselezionato di K.
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 Shared Storage da siti diversi e può essere letto all'interno di un worklet. Quando il conteggio ha raggiunto K, è possibile inviare un report tramite 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 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 dell'asta.
Da un worklet dell'API Protected Audience, puoi aggregare i dati direttamente utilizzando contributeToHistogram()
e segnalarli in base a un attivatore utilizzando contributeToHistogramOnEvent()
, un'estensione speciale per l'API Protected Audience.
Funzioni disponibili
Le seguenti funzioni sono disponibili nell'oggetto privateAggregation
disponibile nei worklet dello spazio di archiviazione condiviso e dell'API Protected Audience.
contributeToHistogram()
Puoi chiamare privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
, dove la chiave di aggregazione è bucket
e il valore aggregabile come value
. Il BigInt
è obbligatorio per il parametro bucket
. Per il parametro value
, è richiesto un numero intero.
Di seguito è riportato un esempio di come potrebbe essere chiamato in 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);
Il codice di esempio riportato sopra chiama Aggregazione privata ogni volta che vengono caricati i contenuti degli iframe tra siti. Il codice iframe carica il worklet, che 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 inviare una segnalazione solo se si verifica un determinato evento. Questa funzione consente inoltre al bucket e al valore di dipendere da indicatori che non sono ancora disponibili in quel momento dell'asta.
Il metodo privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
richiede un eventType
che specifica l'evento di attivazione e l'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 sconfitta dell'asta, oppure può provenire da un frame chiuso in cui è stato visualizzato l'annuncio.
Per inviare un report sugli eventi di asta, puoi utilizzare due parole chiave prenotate, reserved.win
, reserved.loss
e reserved.always
. Per inviare un report attivato da un evento proveniente da un frame recintato, definisci un tipo di evento personalizzato. Per attivare l'evento da un frame recintato, 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 vittoria dell'asta e un report sui clic se viene attivato un evento click
dal frame recintato in cui è stato 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 l'articolo esplicativo sui report sull'aggregazione privata estesa.
enableDebugMode()
Sebbene i cookie di terze parti siano ancora disponibili, offriremo un meccanismo temporaneo che semplifica il debug e i test attivando la modalità di debug. Un report di debug è utile per confrontare le misurazioni basate sui cookie con quelle dell'aggregazione privata e consente anche di convalidare rapidamente l'integrazione dell'API.
La chiamata di privateAggregation.enableDebugMode()
nel worklet consente la modalità di debug 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 del servizio di aggregazione.
La modalità di debug è disponibile solo per i chiamanti autorizzati ad accedere
cookie di terze parti. Se il chiamante non ha accesso a cookie di terze parti,
L'app enableDebugMode()
interromperà automaticamente l'accesso. Ciò significa che quando
i cookie sono deprecati, la modalità di debug non sarà più disponibile.
Puoi anche impostare la chiave di debug chiamando privateAggregation.enableDebugMode({ <debugKey: debugKey> })
, dove un 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 a quelli della misurazione dell'aggregazione privata.
Queste possono essere chiamate solo una volta per contesto. Eventuali chiamate successive genereranno un'eccezione.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Verifica report
Per lo spazio di archiviazione condiviso, puoi verificare che i report aggregabili che hai ricevuto siano legittimi aggiungendo un ID contesto alla chiamata dell'operazione di archiviazione condivisa. L'ID verrà allegato al report inviato e, successivamente, potrai utilizzarlo per verificare che il report sia stato inviato dall'operazione di archiviazione condivisa.
Per scoprire di più, consulta la spiegazione della verifica della segnalazione.
Interagisci e condividi il feedback
L'API Private Aggregation è attualmente in fase di discussione ed è soggetta a modifiche in futuro. Se provi questa API e hai feedback, ci piacerebbe conoscere la tua opinione.
- GitHub: leggi l'spiegatore, solleva le domande e partecipa alla discussione.
- Assistenza per gli sviluppatori: poni domande e partecipa alle discussioni nel 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.