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

Questo documento è una guida rapida per l'utilizzo di Shared Storage e Private Aggregation. Devi conoscere entrambe le API perché Shared Storage memorizza i valori e Private Aggregation crea i report aggregabili.

Pubblico di destinazione:fornitori di tecnologia pubblicitaria e misurazione.

API Shared Storage

Per impedire il monitoraggio cross-site, i browser hanno iniziato a partizionare tutte le forme di archiviazione, inclusi l'archiviazione locale, i cookie e così via. Tuttavia, esistono casi d'uso in cui è necessario uno spazio di archiviazione non partizionato. L'API Shared Storage fornisce accesso in scrittura illimitato a diversi siti di primo livello con accesso in lettura che tutela la privacy.

Shared Storage è limitato all'origine del contesto (il chiamante di sharedStorage).

Shared Storage ha un limite di capacità per origine e ogni voce è limitata a un numero massimo di caratteri. Se il limite viene raggiunto, non vengono memorizzati ulteriori input. I limiti di spazio di archiviazione dei dati sono descritti nella spiegazione dello spazio di archiviazione condiviso.

Richiamare Shared Storage

Le tecnologie pubblicitarie possono scrivere nello spazio di archiviazione condiviso utilizzando JavaScript o un'intestazione della risposta. La lettura dallo spazio di archiviazione condiviso avviene solo all'interno di un ambiente JavaScript isolato chiamato worklet.

• Utilizzo di JavaScript: le tecnologie pubblicitarie possono eseguire funzioni di Shared Storage specifiche, come impostare, aggiungere ed eliminare valori al di fuori di un worklet JavaScript. Tuttavia, funzioni come la lettura di Shared Storage 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 Superficie API proposta - Al di fuori del worklet.

  I metodi utilizzati nel worklet durante un'operazione sono disponibili in Superficie API proposta - In worklet.

• Utilizzo delle intestazioni di risposta

  Analogamente a JavaScript, solo funzioni specifiche come l'impostazione, l'aggiunta e l'eliminazione di valori in Shared Storage possono essere eseguite utilizzando le intestazioni di risposta. Per utilizzare Shared Storage in un'intestazione di risposta, Shared-Storage-Writable: ?1 deve essere incluso nell'intestazione della richiesta.

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

  • In uso: fetch()

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

  • Utilizzare 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";
    

Per ulteriori informazioni, consulta Shared Storage: Response Headers.

Scrittura in Shared Storage

Per scrivere in Shared Storage, chiama sharedStorage.set() dall'interno o dall'esterno di un worklet JavaScript. Se viene chiamato dall'esterno del worklet, i dati vengono scritti nell'origine del contesto di navigazione da cui è stata effettuata la chiamata. Se viene chiamato 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 impostato 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 più volte a Shared Storage nel caricamento della stessa 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

  Al di fuori 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 });
  

• Utilizzo delle intestazioni di risposta

  Puoi anche scrivere nello spazio di archiviazione condiviso utilizzando le intestazioni di risposta. Per farlo, 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
  

  È possibile separare più elementi con una virgola e 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 append. Se la chiave non esiste, la chiamata di append() crea la chiave e imposta il valore. Questa operazione può essere eseguita utilizzando JavaScript o un'intestazione della risposta.

• Utilizzo di JavaScript

  Per aggiornare i valori delle chiavi esistenti, utilizza 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 all'interno del worklet:

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

• Utilizzo delle intestazioni di risposta

  Analogamente all'impostazione di un valore in Shared Storage, puoi utilizzare Shared-Storage-Write nell'intestazione della risposta per passare la coppia chiave-valore.

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

Aggiornamento batch dei valori

Puoi chiamare sharedStorage.batchUpdate() dall'interno o dall'esterno di un worklet JavaScript e passare un array ordinato di metodi che specificano le operazioni scelte. Ogni costruttore di metodi accetta gli stessi parametri del metodo individuale corrispondente per impostare, aggiungere, eliminare e cancellare.

Puoi chiamare batchUpdate() da JavaScript o utilizzare un'intestazione della risposta:

• Utilizzo di JavaScript

  I metodi JavaScript che possono essere utilizzati con batchUpdate() includono:

  • SharedStorageSetMethod(): scrive una coppia chiave-valore in Shared Storage.
  • SharedStorageAppendMethod(): aggiunge un valore a una chiave esistente nello spazio di archiviazione condiviso o scrive una coppia chiave-valore se la chiave non esiste ancora.
  • SharedStorageDeleteMethod(): elimina una coppia chiave-valore da Shared Storage.
  • SharedStorageClearMethod(): cancella tutte le chiavi in Shared Storage.

  sharedStorage.batchUpdate([
  new SharedStorageSetMethod('keyOne', 'valueOne'),
  new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
  new SharedStorageDeleteMethod('keyThree'),
  new SharedStorageClearMethod()
  ]);
  

• Utilizzo delle intestazioni di risposta

  Shared-Storage-Write : set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear
  

L'utilizzo delle intestazioni della risposta esegue batchUpdate() per tutti i metodi nell'intestazione.

Lettura da Shared Storage

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 worklet determina di chi viene letto lo spazio di archiviazione condiviso.

Eliminazione da Shared Storage

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

• Utilizzo di JavaScript

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

  window.sharedStorage.delete('myKey');
  

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

  sharedStorage.delete('myKey');
  

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

  window.sharedStorage.clear();
  

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

  sharedStorage.clear();
  

• Utilizzo delle intestazioni di risposta

  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 della risposta:

  clear;
  

Lettura dei gruppi basati sugli interessi di Protected Audience dallo spazio di archiviazione condiviso

Puoi leggere i gruppi basati sugli interessi di Protected Audience da un worklet Shared Storage. Il metodo interestGroups() restituisce un array di oggetti StorageInterestGroup, inclusi gli attributi AuctionInterestGroup e GenerateBidInterestGroup.

Il seguente esempio mostra come leggere i gruppi di interesse del contesto di navigazione e alcune possibili operazioni che potrebbero essere eseguite sui gruppi di interesse recuperati. Due possibili operazioni utilizzate sono la ricerca del numero di gruppi di interesse e la ricerca del gruppo di interesse con il conteggio delle offerte più alto.

async function analyzeInterestGroups() {
  const interestGroups = await interestGroups();
  numIGs = interestGroups.length;
  maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
  console.log("The IG that bid the most has name " + maxBidCountIG.name);
}

L'origine del contesto di navigazione da cui è stato caricato il modulo worklet determina l'origine dei gruppi di interesse letti per impostazione predefinita. Per scoprire di più sull'origine del worklet predefinita e su come modificarla, consulta la sezione Esecuzione di Shared Storage e Private Aggregation nella procedura dettagliata dell'API Shared Storage.

Opzioni

Tutti i metodi di modifica di Shared Storage supportano un oggetto options facoltativo come ultimo argomento.

withLock

L'opzione withLock è facoltativa. Se specificata, questa opzione indica al metodo di acquisire un blocco per la risorsa definita utilizzando l'API Web Locks prima di procedere. Quando viene richiesta la serratura, viene passato un nome. Il nome rappresenta una risorsa per la quale l'utilizzo è coordinato in più schede,worker o codice all'interno dell'origine.

L'opzione withLock può essere utilizzata con i seguenti metodi di modifica dell'archiviazione condivisa:

• imposta
• Aggiunta
• elimina
• cancella
• aggiornamento batch

Puoi impostare il blocco utilizzando JavaScript o un'intestazione della risposta:

• Utilizzo di JavaScript

  sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });
  

• Utilizzo delle intestazioni di risposta

  Shared-Storage-Write : set;key="myKey";value="myValue",options;with_lock="myResource"
  

I blocchi di Shared Storage sono partizionati in base all'origine dei dati. I blocchi sono indipendenti da quelli ottenuti utilizzando il metodo LockManager request(), indipendentemente dal fatto che si trovino in un contesto window o worker. Tuttavia, condividono lo stesso ambito dei blocchi ottenuti utilizzando request() nel contesto di SharedStorageWorklet.

Sebbene il metodo request() consenta varie opzioni di configurazione, i blocchi acquisiti all'interno dello spazio di archiviazione condiviso rispettano sempre le seguenti impostazioni predefinite:

• mode: "exclusive": Non è possibile mantenere contemporaneamente altri blocchi con lo stesso nome.
• steal: false: I blocchi esistenti con lo stesso nome non vengono rilasciati per soddisfare altre richieste.
• ifAvailable: false: le richieste attendono a tempo indeterminato finché il blocco non diventa disponibile.

Quando utilizzarli withLock

I blocchi sono utili in scenari in cui potrebbero essere in esecuzione più worklet contemporaneamente (ad esempio, più worklet in una pagina o più worklet in schede diverse), ognuno dei quali esamina gli stessi dati. In questo scenario, è consigliabile racchiudere il codice del worklet pertinente in un blocco per garantire che un solo worklet elabori i report alla volta.

Un'altra situazione in cui i blocchi sono utili è quando in un worklet devono essere lette più chiavi insieme e il loro stato deve essere sincronizzato. In questo caso, è necessario racchiudere le chiamate get con un blocco e assicurarsi di acquisire lo stesso blocco quando si scrive su queste chiavi.

Ordine delle serrature

A causa della natura dei blocchi web, i metodi di modifica potrebbero non essere eseguiti nell'ordine che hai definito. Se la prima operazione richiede un blocco ed è ritardata, la seconda operazione potrebbe iniziare prima del completamento della prima.

Ad esempio:

// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });

// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');

Esempio di modifica di più chiavi

L'opzione withLock con batchUpdate() garantisce l'esclusione reciproca con altre operazioni simultanee che acquisiscono lo stesso blocco. Puoi applicare l'opzione withLock per batchUpdate() all'intero batch. L'applicazione di withLock a qualsiasi singolo oggetto metodo all'interno del batch genera un'eccezione.

Questo esempio utilizza un blocco per garantire che le operazioni di lettura ed eliminazione all'interno del worklet avvengano insieme, impedendo interferenze esterne al worklet.

Il seguente esempio di modify-multiple-keys.js imposta nuovi valori per keyOne e keyTwo con modify-lock, quindi esegue l'operazione modify-multiple-keys dal worklet:

// modify-multiple-keys.js
sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
    new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });

const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');

Poi, all'interno di modify-multiple-keys-worklet.js puoi richiedere il blocco utilizzando navigator.locks.request() per leggere e modificare le chiavi in base alle necessità.

// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
  async run(data) {
    await navigator.locks.request('modify-lock', async (lock) => {
      const value1 = await sharedStorage.get('keyOne');
      const value2 = await sharedStorage.get('keyTwo');

      // Do something with `value1` and `value2` here.

      await sharedStorage.delete('keyOne');
      await sharedStorage.delete('keyTwo');
    });
  }
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);

Commutazione di contesto

I dati di Shared Storage 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'incorporatore. Pertanto, quando il codice di terze parti chiama sharedStorage.set(), i dati vengono scritti nello spazio di archiviazione condiviso dell'incorporatore. 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 archivia i dati nell'archivio condiviso dell'origine dell'iframe.

Contesto proprietario

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

Contesto di terze parti

La coppia chiave-valore può essere memorizzata nel contesto della tecnologia pubblicitaria o di terze parti creando un iframe e chiamando set() o delete() nel codice JavaScript all'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() all'interno di un worklet con un bucket e un valore. Il bucket è rappresentato da un numero intero non firmato a 128 bit che deve essere passato 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 durante il transito e può essere decriptato e aggregato solo utilizzando il servizio di aggregazione.

Il browser limiterà anche i contributi che un sito può apportare a una query di output. Nello specifico, il budget di contributo limita il totale di tutti i report di un singolo sito per un determinato browser in una determinata finestra temporale in tutti i bucket. Se il budget attuale viene superato, non verrà generato un report.

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

Esecuzione di Shared Storage e Private Aggregation

Per impostazione predefinita, quando utilizzi l'archiviazione condivisa con createWorklet(), l'origine della partizione dei dati sarà l'origine del contesto di navigazione di chiamata, non l'origine dello script del worklet stesso.

Per modificare il comportamento predefinito, imposta la proprietà dataOrigin quando chiami createWorklet.

• dataOrigin: "context-origin": (valore predefinito) i dati vengono archiviati nello spazio di archiviazione condiviso dell'origine del contesto di navigazione chiamante.
• dataOrigin: "script-origin": i dati vengono archiviati nello spazio di archiviazione condiviso dell'origine dello script del worklet. Per attivare questa modalità è necessario eseguire l'attivazione.
• dataOrigin: "https://custom-data-origin.example": i dati vengono archiviati nello spazio di archiviazione condiviso di un'origine dati personalizzata. Per attivare questa modalità è necessario il consenso e l'approvazione del proprietario dell'origine dati personalizzata, come descritto in Origine dati personalizzata.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

Per attivare la funzionalità, quando utilizzi "script-origin" o un'origine personalizzata, l'endpoint dello script deve rispondere con l'intestazione Shared-Storage-Cross-Origin-Worklet-Allowed. Per le richieste multiorigine, deve essere abilitata anche la CORS.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin: *

Puoi anche eseguire script multiorigine utilizzando un iframe di terze parti, nel qual caso le azioni di Shared Storage si troveranno nel contesto di navigazione di terze parti.

Utilizzo di iframe multiorigine

È necessario un iframe per richiamare il worklet dello spazio di archiviazione condiviso.

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Nello script del worklet, dovrai creare una classe con un metodo run asincrono e register per eseguirlo 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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

Utilizzo della richiesta multiorigine

Shared Storage e Private Aggregation consentono la creazione di worklet multiorigine senza la necessità di iframe multiorigine.

La pagina proprietaria può anche richiamare una chiamata createWorklet() all'endpoint JavaScript multiorigine. Quando crei il worklet, devi impostare l'origine della partizione dei dati del worklet in modo che corrisponda a quella dell'origine dello script.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

L'endpoint JavaScript multiorigine dovrà rispondere con le intestazioni Shared-Storage-Cross-Origin-Worklet-Allowed e notare che CORS è abilitato per la richiesta.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

I worklet creati utilizzando createWorklet() avranno selectURL e run(). addModule() non è disponibile per questa operazione.

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

Origine dati personalizzata

Quando dataOrigin è impostato su un'origine valida, il proprietario di dataOrigin deve acconsentire al trattamento di Shared Storage per dataOrigin ospitando un file JSON che elenca l'origine dello script del worklet nel percorso /.well-known/shared-storage/trusted-origins. Il file deve essere un array di oggetti con chiavi scriptOrigin e contextOrigin. I valori di queste chiavi possono essere una stringa o un array di stringhe.

Crea il file trusted-origins utilizzando le seguenti informazioni:

• Contesto del chiamante
• Origine e URL dello script del worklet
• Origine e proprietario dei dati

La seguente tabella mostra come potresti creare il file trusted-origins in base a queste informazioni:

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "https://publisher.example"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": "*"
}]
      

[{
  "scriptOrigin": "https://cdn-ad.example",
  "contextOrigin": [
      "https://publisher-a.example",
      "https://publisher-b.example"
  ]
}]
      

[{
  "scriptOrigin": [
    "https://cdn-a-ad.example",
    "https://cdn-b-ad.example"
  ],
  "contextOrigin": "https://publisher.example"
}]
      

Ad esempio, il seguente JSON può essere ospitato all'indirizzo https://custom-data-origin.example/.well-known/shared-storage/trusted-origins e combinare tutti i processori consentiti dei dati di Shared Storage per l'origine https://custom-data-origin.example.

[
  {
    "scriptOrigin": "https://script-origin.a.example",
    "contextOrigin": "https://context-origin.a.example"
  },
  {
    "scriptOrigin": "https://script-origin.b.example",
    "contextOrigin": [
      "https://context-origin.a.example",
      "https://context-origin.b.example"
    ]
}]

Passaggi successivi

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

• Introduzione a Shared Storage (Chrome per sviluppatori)
• Casi d'uso di Shared Storage (Developer Chrome)
• Introduzione all'aggregazione privata (Chrome per sviluppatori)
• Spiegazione di Shared Storage (GitHub)
• Messaggio esplicativo sull'aggregazione privata (GitHub)
• Demo di Shared Storage e Private Aggregation

Una volta acquisita familiarità con le API, puoi iniziare a raccogliere i report, che vengono inviati come richiesta POST ai seguenti endpoint in formato 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 il test utilizzando lo strumento di test locale o configurare l'ambiente di esecuzione attendibile per il servizio di aggregazione per ottenere i report aggregati.

Condividi il tuo feedback

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

• Shared Storage
• Private Aggregation