Panoramica dell'API Private Aggregation

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 dell'implementazione

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 di siti su cui ogni utente ha visualizzato i tuoi contenuti o rilevare 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 hanno visto 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 sull'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 costituiscono 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 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.

L'aggregazione privata può fornire una risposta, ad esempio "Circa 317 utenti unici hanno un'età compresa tra 18 e 45 anni e risiedono 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 l'aggregazione privata.

Attribuzione multi-touch

Queste linee guida devono essere pubblicate sul sito per sviluppatori, in modo che i tecnici pubblicitari possano capire come implementare MTA all'interno dell'archiviazione condivisa + 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 nelle aste.

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 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 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 a privateAggregation.enableDebugMode() nel worklet attiva la modalità di debug, che fa sì che i report aggregabili includano il payload non criptato (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 spazio di archiviazione condiviso. L'ID verrà allegato al report inviato e in un secondo momento potrai utilizzarlo per verificare che il report sia stato inviato dalla tua 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.