Panoramica dell'API Private Aggregation

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Genera report sui dati aggregati utilizzando i dati di Protected Audience e i dati cross-site di Shared Storage.

Per fornire funzionalità fondamentali su cui si basa il web, l'API Private Aggregation è stata creata per aggregare e generare report sui dati cross-site in modo da preservare 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 i dati dell'API Protected Audience e i dati cross-site di Shared Storage.

La funzione principale di questa API è nota come contributeToHistogram(). L'operazione di istogramma consente di aggregare i dati tra gli utenti di ogni bucket (chiamato nell'API chiave di aggregazione) che definisci. La chiamata dell'istogramma accumula i 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 eseguire l'aggregazione per questa misurazione, puoi codificare la dimensione Geografia 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 l'aggregazione. I report raggruppati vengono elaborati in un secondo momento dal servizio di aggregazione e viene generato un report di riepilogo.

Consulta il documento Concetti fondamentali dell'API Private Aggregation per saperne di più sui concetti chiave dell'API Private Aggregation.

Differenze rispetto a Attribution Reporting

L'API Private Aggregation condivide molte somiglianze con l'API Attribution Reporting. Attribution Reporting è un'API autonoma progettata per misurare le conversioni, mentre l'aggregazione privata è progettata per le misurazioni su più siti in combinazione con API come 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 di impressione e da un evento di conversione che si verificano in momenti diversi. L'aggregazione privata misura un singolo evento cross-site.

Prova questa API

Per testare l'API Private Aggregation localmente, abilita tutte le API Privacy per gli annunci in chrome://settings/adPrivacy.

Scopri di più sui test in Eseguire esperimenti e partecipare.

Utilizzare 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 generica per la misurazione su più siti ed è disponibile per l'utilizzo 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

Shared Storage ti consente di leggere e scrivere dati cross-site in un ambiente sicuro per evitare fughe di dati, mentre l'API Private Aggregation ti consente di misurare i dati cross-site archiviati in Shared Storage.

Misura della copertura unica

Potresti voler misurare il numero di utenti unici che hanno visto i tuoi contenuti. L'API Private Aggregation può fornire una risposta come "Circa 317 utenti unici hanno visto il Content ID 861".

Puoi impostare un flag in Spazio di archiviazione condiviso 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 il flag viene impostato. Nelle visite successive dell'utente, incluse quelle su più siti, puoi controllare lo spazio di archiviazione condiviso 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 siti diversi.

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. In un secondo momento, puoi generare un report con l'aggregazione privata codificando le dimensioni fascia d'età e paese nella chiave di aggregazione.

Misurazione della frequenza per valori superiori a 1000

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

L'aggregazione privata può fornire una risposta come "Circa 89 utenti hanno visto il 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 utilizzando l'aggregazione privata.

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 di retargeting e segmenti di pubblico personalizzati, mentre l'aggregazione privata ti consente di registrare gli eventi 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 generare report 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 dell'API Protected Audience e dello spazio di archiviazione condiviso.

contributeToHistogram()

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

Ecco un esempio di come potrebbe essere chiamato nello 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';

    // 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'aggregazione privata ogni volta che vengono caricati i contenuti iframe cross-site. Il codice iframe carica il worklet, che a sua volta 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 l'invio di un report solo se si verifica un determinato evento. Questa funzione consente inoltre al bucket e al valore di dipendere 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 al termine dell'asta, ad esempio un evento di vittoria o perdita dell'asta, oppure da un frame recintato che ha visualizzato l'annuncio.

Per inviare un report per gli eventi di 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 delimitato, utilizza il metodo fence.reportEvent() disponibile nell'API di reporting sugli annunci con frame delimitati.

L'esempio seguente invia un report sulle impressioni quando viene attivato l'evento di aggiudicazione dell'asta e un report sui clic se viene attivato un evento click dal frame recintato che ha visualizzato l'annuncio. Questi due valori possono essere utilizzati per calcolare il tasso 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 dei report di aggregazione privata estesa.

enableDebugMode()

Anche se i cookie di terze parti sono ancora disponibili, forniremo un meccanismo temporaneo che consente di semplificare 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 aggregazione privata e ti 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 gli utenti che hanno l'autorizzazione ad accedere ai cookie di terze parti. Se chi chiama non ha accesso ai cookie di terze parti, enableDebugMode() non avrà esito.

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 su cookie e i dati della misurazione dell'aggregazione privata.

Questi metodi possono essere chiamati una sola 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 del report

L'API Private Aggregation consente la misurazione su più siti proteggendo al contempo la privacy degli utenti. Tuttavia, i malintenzionati potrebbero tentare di manipolare la precisione di queste misurazioni. Per evitare che ciò accada, 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 vengono generati i risultati aggregati finali. Ciò viene ottenuto:

• Prevenzione di report illegittimi o non autentici: assicurati che i report vengano generati tramite chiamate API legittime e autentiche, rendendo difficile la loro falsificazione da parte di malintenzionati.
• Impedire la riproduzione dei report: rileva e rifiuta qualsiasi tentativo di riutilizzare i vecchi report, assicurandoti che ogni report venga conteggiato una sola volta nei risultati aggregati.

Spazio di archiviazione condiviso

Quando utilizzi lo spazio di archiviazione condiviso per eseguire un'operazione che può inviare un report aggregabile, puoi impostare un ID imprevedibile all'esterno 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 options sotto la chiave privateAggregationConfig.

Ad esempio:

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

Una volta impostato, puoi utilizzare questo ID per verificare che il report sia stato inviato dalla tua operazione di archiviazione condivisa. Per evitare la fuga di informazioni, viene inviato esattamente un report per operazione di archiviazione condivisa (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, è presente un ritardo fisso più breve di 5 secondi dall'avvio dell'operazione di archiviazione condivisa.

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

1. L'operazione di archiviazione condivisa viene eseguita con una configurazione di aggregazione privata che specifica un ID contesto e viene generato un report aggregabile.
2. L'ID contesto è incorporato nel report aggregabile generato e 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 arrivo sul 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 se l'ID contesto è:

• Sconosciuto:se un report arriva con un ID contesto non creato dal tuo sistema, puoi ignorarlo. In questo modo, gli utenti malintenzionati o sconosciuti non possono iniettare dati nella pipeline di aggregazione.
• Un duplicato: se ricevi due o più report con lo stesso ID contesto, devi scegliere quale eliminare.
• Segnalato nel rilevamento dello spam:
  • Se durante l'elaborazione del report rilevi attività sospette da parte di un utente, ad esempio un cambiamento improvviso nell'attività, puoi ignorarlo.
  • Puoi archiviare i report insieme ai relativi ID contesto e a eventuali indicatori pertinenti (ad esempio user agent, sorgente 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 agli indicatori associati. In questo modo puoi eliminare i report degli utenti che mostrano attività sospette, anche se inizialmente non sono stati segnalati.

Coinvolgere e condividere feedback

L'API Private Aggregation è in discussione attiva ed è soggetta a modifiche in futuro. Se provi questa API e hai un feedback, ci farebbe piacere conoscerlo.

• 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.
• Partecipa al gruppo API Shared Storage e al gruppo API Protected Audience per ricevere gli ultimi annunci relativi all'aggregazione privata.