Panoramica dell'API Private Aggregation

Genera report sui dati aggregati utilizzando i dati di Protected Audience e i dati tra siti di Shared Storage.

Per fornire funzionalità essenziali su cui si basa il web, l'API Private Aggregation è stata creata per aggregare e generare report sui dati cross-site in modo da tutelare la privacy.

Stato dell'implementazione

Che cos'è l'API Private Aggregation

L'API Private Aggregation consente agli sviluppatori di generare report di dati aggregati con i dati dell'API Protected Audience e i dati tra siti di Shared Storage.

La funzione principale di questa API è nota come contributeToHistogram(). L'operazione dell'istogramma ti consente di aggregare i dati tra gli utenti in ogni bucket (noto nell'API come chiave di aggregazione) che definisci. La chiamata all'istogramma accumula i valori e restituisce un risultato aggregato con rumore sotto forma di report riepilogativo. Ad esempio, il report potrebbe mostrare il numero di siti su cui ogni utente ha visualizzato i tuoi contenuti o riscontrato un bug nello 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 Shared Storage, puoi utilizzare l'API Private Aggregation per creare un istogramma che ti indichi approssimativamente quanti utenti di New York City hanno visto i tuoi contenuti su più siti. Per l'aggregazione di 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 aggregabili 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.

Consulta il documento Nozioni di base dell'API Private Aggregation per scoprire di più sui concetti chiave coinvolti nell'API Private Aggregation.

Differenze rispetto ad Attribution Reporting

L'API Private Aggregation presenta molte somiglianze con l'API Attribution Reporting. Attribution Reporting è un'API autonoma progettata per misurare le conversioni, mentre Private Aggregation è pensata per le misurazioni cross-site in combinazione con API come l'API Protected Audience e Shared Storage. Entrambe le API producono report aggregabili che vengono utilizzati dal backend del servizio di aggregazione per generare report di riepilogo.

I report sull'attribuzione associano i dati raccolti da un evento impressione e da un evento di conversione, che si verificano in momenti diversi. L'aggregazione privata misura un singolo evento cross-site.

Testa questa API

Per testare l'API Private Aggregation localmente, attiva tutte le API per la privacy degli annunci in chrome://settings/adPrivacy.

Scopri di più sui test in Esperimenti e partecipa.

Utilizzare la demo

La demo dell'API Private Aggregation per Shared Storage è disponibile 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 cross-site ed è disponibile per l'utilizzo nei worklet Shared Storage e Protected Audience API. Il primo passo consiste nel decidere quali informazioni vuoi raccogliere. Questi punti dati sono la base delle chiavi di aggregazione.

Con Shared Storage

Shared Storage consente di leggere e scrivere dati tra siti in un ambiente sicuro per evitare la fuga di dati, mentre l'API Private Aggregation consente di misurare i dati tra siti archiviati in Shared Storage.

Misura della copertura unica

Potresti voler misurare quanti utenti unici hanno visto i tuoi contenuti. L'API Private Aggregation può fornire una risposta come "Circa 317 utenti unici hanno visto l'ID contenuto 861".

Puoi impostare un flag in Shared Storage per indicare se l'utente ha già visto o meno i contenuti. Alla prima visita in cui il flag non esiste, viene effettuata una chiamata all'aggregazione privata e poi viene impostato il flag. Nelle visite successive dell'utente, comprese le visite cross-site, puoi controllare Shared Storage e saltare l'invio di un report all'aggregazione privata se il flag è impostato. Per scoprire di più sui metodi per implementare queste misurazioni, consulta il nostro white paper sulla copertura.

Misurazione dei dati demografici

Potresti voler misurare i dati demografici degli utenti che hanno visualizzato i tuoi contenuti su diversi siti.

L'aggregazione privata può fornire una risposta, ad esempio "Circa 317 utenti unici hanno un'età compresa tra 18 e 45 anni e provengono dalla Germania". Utilizza Shared Storage per accedere ai dati demografici da un contesto di terze parti. In un secondo momento, puoi generare un report con l'API Private Aggregation codificando le dimensioni del gruppo di età e del paese nella chiave di aggregazione.

Misurazione della frequenza K+

Potresti voler misurare il numero di utenti che hanno visualizzato un contenuto o un annuncio almeno K volte su un determinato browser, per un valore di K predefinito.

L'aggregazione privata può fornire una risposta come "Circa 89 utenti hanno visto l'ID contenuto 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 raggiunge K, è possibile inviare un report utilizzando Private Aggregation.

Attribuzione multi-touch

L'attribuzione marketing è un metodo utilizzato dagli inserzionisti per determinare il contributo delle tattiche di marketing e delle successive interazioni con gli annunci alle vendite o alle conversioni.

Con l'API Protected Audience

L'API Protected Audience consente i casi d'uso del retargeting e dei segmenti di pubblico personalizzati, mentre Private Aggregation consente di generare report sugli eventi dai worklet di acquirenti e venditori. L'API può essere utilizzata per attività come la misurazione della distribuzione delle offerte all'asta.

Da un worklet dell'API Protected Audience, puoi aggregare i dati direttamente utilizzando contributeToHistogram() e generare report sui dati in base a un trigger utilizzando contributeToHistogramOnEvent(), un'estensione speciale per l'API Protected Audience.

Funzioni disponibili

Le seguenti funzioni sono disponibili nell'oggetto privateAggregation disponibile nei worklet dell'API Shared Storage e Protected Audience.

contributeToHistogram()

Puoi chiamare privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), dove la chiave di aggregazione è bucket e il valore aggregabile è value. Per il parametro bucket è richiesto un BigInt. Per il parametro value è richiesto un numero intero.

Ecco un esempio di come potrebbe essere chiamato in Shared Storage 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 sharedStorage.get(key) === 'true';

    // Don't 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

L'esempio di codice precedente chiamerà l'API Private Aggregation ogni volta che vengono caricati i contenuti iframe cross-site. Il codice iframe carica il worklet e il worklet 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 un report solo se si verifica un determinato evento. Questa funzione consente inoltre di fare in modo che il bucket e il valore dipendano da indicatori non ancora disponibili in quel momento dell'asta.

Il metodo privateAggregation.contributeToHistogramOnEvent(eventType, contribution) accetta un eventType che specifica l'evento di attivazione e il contribution da inviare quando l'evento viene attivato. L'evento di attivazione può provenire dall'asta stessa dopo la sua conclusione, ad esempio un evento di vittoria o perdita dell'asta, oppure da un frame recintato che ha eseguito il rendering dell'annuncio.

Per inviare un report per gli eventi asta, puoi utilizzare due parole chiave riservate: reserved.win, reserved.loss e reserved.always. Per inviare un report attivato da un evento 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 vincita dell'asta e un report sui clic se viene attivato un evento click dal frame recintato che ha eseguito il rendering dell'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 la spiegazione del report Private Aggregation esteso.

enableDebugMode()

Sebbene i cookie di terze parti siano ancora disponibili, forniremo un meccanismo temporaneo che consente di eseguire più facilmente il debug e i test attivando la modalità di debug. Un report di debug è utile per confrontare le misurazioni basate sui cookie con quelle di Private Aggregation e consente anche di convalidare rapidamente l'integrazione dell'API.

La chiamata a privateAggregation.enableDebugMode() nel worklet attiva la modalità di debug, che fa sì che i report aggregabili includano il payload non criptato (in testo non criptato). 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 ai cookie di terze parti. Se il chiamante non ha accesso ai cookie di terze parti, enableDebugMode() non andrà a buon fine.

Puoi anche impostare la chiave di debug chiamando privateAggregation.enableDebugMode({ <debugKey: debugKey> }), dove BigInt può essere utilizzata come chiave di debug. La chiave di debug può essere utilizzata per associare i dati di una misurazione basata sui cookie e i dati della misurazione di Private Aggregation.

Questi possono essere chiamati solo una volta per contesto. Le 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

L'API Private Aggregation consente la misurazione tra siti proteggendo al contempo la privacy degli utenti. Tuttavia, i malintenzionati potrebbero tentare di manipolare l'accuratezza di queste misurazioni. Per evitare questo problema, puoi utilizzare un ID contesto per verificare l'autenticità dei report.

L'impostazione di un ID contesto contribuisce a garantire l'accuratezza dei dati quando contribuiscono ai risultati aggregati finali. Ciò si ottiene:

• Prevenzione di report illegittimi o non autentici: verifica che i report siano generati tramite chiamate API legittime e autentiche, rendendo difficile la fabbricazione di report per i malintenzionati.
• Impedire la riproduzione dei report:rileva e rifiuta qualsiasi tentativo di riutilizzare report precedenti, assicurando che ogni report contribuisca una sola volta ai risultati aggregati.

Shared Storage

Quando utilizzi Shared Storage per eseguire un'operazione che può inviare un report aggregabile, puoi impostare un ID imprevedibile al di fuori del worklet.

Questo ID è incorporato nel report creato dal worklet. Puoi specificarlo quando chiami i metodi di archiviazione condivisa run() o selectURL(), all'interno dell'oggetto delle opzioni sotto la chiave privateAggregationConfig.

Ad esempio:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Una volta impostato questo ID, puoi utilizzarlo per verificare che il report sia stato inviato dall'operazione Shared Storage. Per evitare la divulgazione di informazioni, viene inviato esattamente un report per operazione di Shared Storage (anche se non vengono apportati contributi), indipendentemente dal numero di chiamate contributeToHistogram().

L'API Private Aggregation invia report aggregabili con un ritardo casuale fino a un'ora. Tuttavia, l'impostazione di un ID contesto per verificare un report riduce questo ritardo. In questo caso, si verifica un ritardo fisso e più breve di 5 secondi dall'inizio dell'operazione di archiviazione condivisa.

Un esempio di flusso di lavoro (come mostrato nel diagramma precedente):

1. L'operazione Shared Storage viene eseguita con una configurazione di Private Aggregation che specifica un ID contesto e viene generato un report aggregabile.
2. L'ID contesto è incorporato nel report aggregabile generato inviato al tuo server.
3. Il server raccoglie i report aggregabili generati.
4. I processi sul server controllano l'ID contesto in ogni report aggregabile rispetto agli ID contesto archiviati per verificarne la validità prima di raggruppare i report e inviarli al servizio di aggregazione.

Verifica dell'ID contesto

I report in entrata al server di raccolta possono essere verificati in diversi modi prima di essere inviati al servizio di aggregazione. I report con ID contesto non validi possono essere rifiutati quando l'ID contesto è:

• Sconosciuto:se ricevi una segnalazione con un ID contesto non creato dal tuo sistema, puoi ignorarla. In questo modo, si impedisce a malintenzionati sconosciuti o dannosi di inserire dati nella pipeline di aggregazione.
• Un duplicato:se ricevi due o più report con lo stesso ID contesto, significa che devi scegliere quale report eliminare.
• Segnalato nel rilevamento dello spam:
  • Se rilevi attività sospette da parte di un utente, ad esempio un cambiamento improvviso nella sua attività, durante l'elaborazione della segnalazione, puoi ignorarla.
  • Puoi archiviare i report insieme ai relativi ID contesto e a eventuali indicatori pertinenti (ad esempio, user agent, origine referral e così via). In seguito, man mano che analizzi il comportamento degli utenti e identifichi nuovi indicatori di spam, puoi rivalutare i report archiviati in base agli ID contesto e ai segnali associati. In questo modo puoi ignorare i report degli utenti che mostrano attività sospetta, anche se inizialmente non sono stati segnalati.

Partecipare e condividere feedback

L'API Private Aggregation è in fase di discussione e sarà 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 API Shared Storage e al gruppo API Protected Audience per ricevere gli ultimi annunci relativi all'aggregazione privata.