Guida rapida all'implementazione dell'archiviazione condivisa e dell'aggregazione privata

Questo documento è una guida rapida per l'utilizzo dello spazio di archiviazione condiviso e dell'aggregazione privata. Devi comprendere entrambe le API, perché l'archiviazione condivisa archivia i valori e l'aggregazione privata crea i report aggregabili.

Pubblico di destinazione:fornitori di tecnologie pubblicitarie e servizi di misurazione.

Prova la demo

Prova la demo dal vivo. Segui i passaggi nelle istruzioni della demo per abilitare le API Privacy Sandbox. L'apertura di Chrome DevTools consente di visualizzare i risultati di diversi casi d'uso. Casi d'uso disponibili nella demo:

• Aggregazione privata
  • Misurazione della unique reach
  • Misurazione dei dati demografici
  • Misurazione della frequenza K+
• Utilizzo generale
  • Misurare l'evento al passaggio del mouse all'interno di frame delimitati
  • Navigazione di primo livello
  • Stabilire dove terze parti possono scrivere

Come visualizzare lo spazio di archiviazione condiviso

Per visualizzare i dati archiviati nello spazio di archiviazione condiviso, utilizza Chrome DevTools. I dati archiviati sono disponibili in Application -> Shared Storage.

Visualizza report per l'aggregazione privata

Per visualizzare i report aggregabili inviati, vai alla pagina chrome://private-aggregation-internals. Quando la modalità di debug è attivata, un report viene inviato immediatamente (senza ritardo) all'[[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage insieme al report con ritardo da inviare a [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

Per attivare il debug, segui le istruzioni riportate nella sezione debug.

API Shared Storage

Per impedire il monitoraggio tra siti, i browser hanno iniziato a partizionare tutte le forme di archiviazione, tra cui spazio di archiviazione locale, cookie e così via. Ma ci sono casi d'uso in cui è richiesta archiviazione non partizionata. L'API Shared Storage fornisce accesso in scrittura illimitato su diversi siti di primo livello con un accesso in lettura incentrato sulla tutela della privacy.

Lo spazio di archiviazione condiviso è limitato all'origine del contesto (il chiamante di sharedStorage).

Lo spazio di archiviazione condiviso prevede un limite di capacità per origine, con un limite massimo di caratteri per ogni voce. Se viene raggiunto il limite, non vengono archiviati ulteriori input. I limiti di spazio di archiviazione dei dati sono descritti nel messaggio esplicativo sull'archiviazione condivisa.

Richiamo dello spazio di archiviazione condiviso

Gli ad tech possono scrivere nello spazio di archiviazione condiviso utilizzando JavaScript o le intestazioni di risposta. La lettura dallo spazio di archiviazione condiviso avviene solo in un ambiente JavaScript isolato chiamato worklet.

Un worklet consente di eseguire funzioni JavaScript specifiche e restituire le informazioni al richiedente. All'interno di un worklet puoi eseguire JavaScript, ma non puoi interagire o comunicare con la pagina esterna.

I worklet vengono utilizzati per archiviare ed estrarre i dati con l'API Shared Storage.

• Utilizzo di JavaScript Gli ad tech possono eseguire funzioni specifiche dell'archiviazione condivisa come l'impostazione, l'aggiunta e l'eliminazione di valori al di fuori di un worklet JavaScript. Tuttavia, funzioni come la lettura dell'archiviazione condivisa e l'esecuzione dell'aggregazione privata devono essere completate tramite un worklet JavaScript. I metodi che possono essere utilizzati al di fuori di un worklet JavaScript sono disponibili in Surface API Proposed API Surface - Outside the worklet.

  I metodi utilizzati nel worklet durante un'operazione sono disponibili in Surface API Proposed API - Nel worklet.

• Utilizzare le intestazioni delle risposte

  Questa funzionalità è stata resa disponibile nella versione M119.

  Analogamente a JavaScript, solo funzioni specifiche come l'impostazione, l'aggiunta e l'eliminazione di valori nello spazio di archiviazione condiviso possono essere eseguite utilizzando le intestazioni delle risposte. Per lavorare con lo spazio di archiviazione condiviso nell'intestazione della risposta, Shared-Storage-Writable: ?1 deve essere incluso nell'intestazione della richiesta.

  Per avviare una richiesta dal client, esegui il codice seguente, a seconda del metodo scelto:

  • In uso: fetch()

    fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    

  • Utilizzo di un tag iframe o img

    <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
    

  • Utilizzo di un attributo IDL con un tag iframe o img

    let iframe = document.getElementById("my-iframe");
    iframe.sharedStorageWritable = true;
    iframe.src = "https://a.example/path/for/updates";
    

Ulteriori informazioni sono disponibili in Spazio di archiviazione condiviso: intestazioni delle risposte.

Scrittura nello spazio di archiviazione condiviso

Per scrivere nello spazio di archiviazione condiviso, chiama sharedStorage.set() dall'interno o dall'esterno di un worklet JavaScript. Se chiamati dall'esterno del worklet, i dati vengono scritti nell'origine del contesto di navigazione da cui è stata effettuata la chiamata. Se chiamati dall'interno del worklet, i dati vengono scritti nell'origine del contesto di navigazione che ha caricato il worklet. Le chiavi impostate hanno una data di scadenza di 30 giorni dall'ultimo aggiornamento.

Il campo ignoreIfPresent è facoltativo. Se presente e impostata su true, la chiave non viene aggiornata se esiste già. La scadenza della chiave viene rinnovata a 30 giorni dalla chiamata set() anche se la chiave non viene aggiornata.

Se si accede all'Archivio condiviso più volte nello stesso caricamento della pagina con la stessa chiave, il valore della chiave viene sovrascritto. È consigliabile utilizzare sharedStorage.append() se la chiave deve mantenere il valore precedente.

• Utilizzo di JavaScript

  All'esterno del worklet:

  window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
  // Shared Storage: {'myKey': 'myValue2'}
  

  Analogamente, all'interno del worklet:

  sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  

• Utilizzare le intestazioni delle risposte

  Puoi anche scrivere nello spazio di archiviazione condiviso utilizzando le intestazioni di risposta. A tale scopo, utilizza Shared-Storage-Write nell'intestazione della risposta insieme ai seguenti comandi:

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  Più elementi possono essere separati da virgole e possono combinare set, append, delete e clear.

  Shared-Storage-Write : 
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

Aggiunta di un valore

Puoi aggiungere un valore a una chiave esistente utilizzando il metodo di aggiunta. Se la chiave non esiste, la chiamata a append() crea la chiave e imposta il valore. Questa operazione può essere eseguita utilizzando JavaScript o le intestazioni di risposta.

• Utilizzo di JavaScript

  Per aggiornare i valori delle chiavi esistenti, usa sharedStorage.append() dall'interno o dall'esterno del worklet.

  window.sharedStorage.append('myKey', 'myValue1');
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.append('myKey', 'myValue2');
  // Shared Storage: {'myKey': 'myValue1myValue2'}
  window.sharedStorage.append('anotherKey', 'hello');
  // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
  

  Per aggiungere elementi all'interno del worklet:

  sharedStorage.append('myKey', 'myValue1');
  

• Utilizzare le intestazioni delle risposte

  Analogamente all'impostazione di un valore nello spazio di archiviazione condiviso, puoi utilizzare Shared-Storage-Write nell'intestazione della risposta per trasmettere la coppia chiave-valore.

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

Lettura dallo spazio di archiviazione condiviso

Puoi leggere dallo spazio di archiviazione condiviso solo dall'interno di un worklet.

await sharedStorage.get('mykey');

L'origine del contesto di navigazione da cui è stato caricato il modulo di worklet determina la quantità di spazio di archiviazione condiviso letto.

Eliminazione dallo spazio di archiviazione condiviso

Puoi eseguire eliminazioni dall'archiviazione condivisa utilizzando JavaScript dall'interno o dall'esterno del worklet oppure utilizzando le intestazioni di risposta con delete(). Per eliminare tutte le chiavi contemporaneamente, usa il criterio clear() da una delle due.

• Utilizzo di JavaScript

  Per eliminare dallo spazio di archiviazione condiviso dall'esterno del worklet:

  window.sharedStorage.delete('myKey');
  

  Per eliminare dallo spazio di archiviazione condiviso dall'interno del worklet:

  sharedStorage.delete('myKey');
  

  Per eliminare contemporaneamente tutte le chiavi dall'esterno del worklet:

  window.sharedStorage.clear();
  

  Per eliminare tutte le chiavi contemporaneamente dall'interno del worklet:

  sharedStorage.clear();
  

• Utilizzare le intestazioni delle risposte

  Per eliminare i valori utilizzando le intestazioni della risposta, puoi anche utilizzare Shared-Storage-Write nell'intestazione della risposta per passare la chiave da eliminare.

  delete;key="myKey"
  

  Per eliminare tutte le chiavi utilizzando le intestazioni delle risposte:

  clear;
  

Cambio di contesto

I dati dello spazio di archiviazione condiviso vengono scritti nell'origine, ad esempio https://example.adtech.com, del contesto di navigazione da cui ha avuto origine la chiamata.

Quando carichi il codice di terze parti utilizzando un tag <script>, il codice viene eseguito nel contesto di navigazione dell'incorporamento. Pertanto, quando il codice di terze parti chiama sharedStorage.set(), i dati vengono scritti nello spazio di archiviazione condiviso dell'incorporamento. Quando carichi il codice di terze parti all'interno di un iframe, il codice riceve un nuovo contesto di navigazione e la sua origine è l'origine dell'iframe. Pertanto, la chiamata sharedStorage.set() effettuata dall'iframe memorizza i dati nello spazio di archiviazione condiviso dell'origine dell'iframe.

Contesto proprietario

Se una pagina proprietaria ha incorporato un codice JavaScript di terze parti che chiama sharedStorage.set() o sharedStorage.delete(), la coppia chiave-valore viene archiviata nel contesto proprietario.

Contesto di terze parti

La coppia chiave-valore può essere archiviata in un contesto di ad tech o di terze parti creando un iframe e chiamando set() o delete() nel codice JavaScript dall'interno dell'iframe.

API Private Aggregation

Per misurare i dati aggregabili archiviati in Shared Storage, puoi utilizzare l'API Private Aggregation.

Per creare un report, chiama contributeToHistogram() in un worklet con un bucket e un valore. Il bucket è rappresentato da un numero intero a 128 bit senza firma che deve essere trasmesso alla funzione come BigInt. Il valore è un numero intero positivo.

Per proteggere la privacy, il payload del report, che contiene il bucket e il valore, viene criptato in transito e può essere decriptato e aggregato solo mediante Aggregation Service.

Il browser limiterà anche i contributi di un sito a una query di output. In particolare, il budget di contributo limita il totale di tutti i report di un singolo sito per un determinato browser in un determinato periodo di tempo in tutti i bucket. Se il budget attuale viene superato, non verrà generato un report.

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

Esecuzione dell'archiviazione condivisa e dell'aggregazione privata

Nell'iframe dell'annuncio, carica il modulo di worklet chiamando addModule(). Per eseguire il metodo registrato nel file di lavoro sharedStorageWorklet.js, nello stesso codice JavaScript iframe dell'annuncio, chiama sharedStorage.run().

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Nello script di lavoro, devi creare una classe con un metodo run asinc. register questa classe da pubblicare nell'iframe dell'annuncio. All'interno di sharedStorageWorklet.js:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

Debug

Per attivare il debug, chiama il metodo JavaScript enableDebugMode() nello stesso contesto in cui vengono utilizzati lo spazio di archiviazione condiviso e l'aggregazione privata. Verrà applicata per i report futuri nello stesso contesto.

privateAggregation.enableDebugMode();

Per associare i report ai contesti che li hanno attivati, puoi impostare una chiave di debug con un numero intero senza firma a 64 bit che viene passata alla chiamata JavaScript. Il debugKey è un BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Debug dell'archiviazione condivisa

Lo spazio di archiviazione condiviso restituisce un messaggio di errore generico:

Promise is rejected without and explicit error message

Puoi eseguire il debug dello spazio di archiviazione condiviso eseguendo il wrapping delle chiamate con blocchi try-catch.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Debug dell'aggregazione privata

I report vengono inviati a /.well-known/private-aggregation/report-shared-storage e /.well-known/private-aggregation/debug/report-shared-storage. I report di debug ricevono un payload simile al seguente JSON. Questo payload definisce il campo api come "shared-storage".

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

Debug payload in chiaro

debug_cleartext_payload ha una codifica Base64 CBOR. Puoi visualizzare il bucket e il valore utilizzando il decoder o utilizzare il codice JavaScript trovato nel decoder Storage condiviso.

Passaggi successivi

Le pagine seguenti illustrano aspetti importanti delle API Shared Storage e Private Aggregation.

• Introduzione allo spazio di archiviazione condiviso (Chrome per sviluppatori)
• Casi d'uso dello spazio di archiviazione condiviso (Chrome per sviluppatori)
• Introduzione all'aggregazione privata (Chrome per sviluppatori)
• Spiegazione dello spazio di archiviazione condiviso (GitHub)
• Explainer sull'aggregazione privata (GitHub)
• Demo di spazio di archiviazione condiviso e aggregazione privata

Dopo aver acquisito familiarità con le API, puoi iniziare a raccogliere i report, che vengono inviati come richiesta POST ai seguenti endpoint come JSON nel corpo della richiesta.

• Report di debug - context-origin/.well-known/private-aggregation/debug/report-shared-storage
• Report - context-origin/.well-known/private-aggregation/report-shared-storage

Una volta raccolti i report, puoi eseguire i test utilizzando lo strumento di test locale o configurare il Trusted Execution Environment per Aggregation Service per ricevere i report aggregati.

Condividi il tuo feedback

Puoi condividere il tuo feedback sulle API e sulla documentazione su GitHub.

• Spazio di archiviazione condiviso
• Aggregazione privata