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.
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
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
oimg
<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
Utilizzo di un attributo IDL con un tag
iframe
oimg
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
eclear
.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.