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

Questo documento è una guida rapida all'utilizzo di Shared Storage e Private Aggregation. Devi conoscere entrambe le API perché lo spazio di archiviazione condiviso immagazzina i valori e l'aggregazione privata crea i report aggregabili.

Pubblico di destinazione:fornitori di tecnologia pubblicitaria e fornitori di servizi di misurazione.

API Shared Storage

Per impedire il monitoraggio tra siti, i browser hanno iniziato a suddividere tutte le forme di archiviazione, inclusi lo spazio di 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.

L'archiviazione condivisa è limitata all'origine del contesto (il chiamante di sharedStorage).

Lo spazio di archiviazione condiviso ha un limite di capacità per origine, con ogni voce limitata a un numero massimo di caratteri. Se viene raggiunto il limite, non vengono memorizzati ulteriori input. I limiti di archiviazione dei dati sono descritti nell'articolo esplicativo su Archiviazione condivisa.

Richiamo dello spazio di archiviazione condiviso

Gli esperti di tecnologia pubblicitaria possono scrivere in Shared Storage utilizzando JavaScript o le intestazioni di risposta. La lettura da Archiviazione condivisa avviene solo all'interno di 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.

• Utilizzando JavaScript, gli esperti di tecnologia pubblicitaria possono eseguire funzioni specifiche di archiviazione condivisa, come l'impostazione, l'aggiunta e l'eliminazione di valori al di fuori di un worklet JavaScript. Tuttavia, funzioni come la lettura dello spazio di archiviazione condiviso 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 API Proposed Surface - Outside the worklet.

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

• Utilizzo delle intestazioni delle risposte

  Analogamente a JavaScript, solo funzioni specifiche come l'impostazione, l'aggiunta e l'eliminazione di valori in Archiviazione condivisa possono essere eseguite utilizzando le intestazioni delle risposte. Per lavorare con lo spazio di archiviazione condiviso 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});
    

  • Utilizzo di un tag iframe o img

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

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

Puoi trovare ulteriori informazioni in Spazio di archiviazione condiviso: intestazioni di risposta.

Scrittura nello spazio di archiviazione condiviso

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 impostata su true, la chiave non viene aggiornata se esiste già. La scadenza della chiave viene rinnovata per 30 giorni dalla chiamata set() anche se la chiave non viene aggiornata.

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

• Utilizzare 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 });
  

• Utilizzare le intestazioni di risposta

  Puoi anche scrivere in Shared Storage utilizzando le intestazioni di risposta. A tale scopo, utilizzaShared-Storage-Write nell'intestazione di 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 di aggiunta. Se la chiave non esiste, la chiamata a append() crea la chiave e imposta il valore. Questo può essere ottenuto utilizzando JavaScript o le intestazioni di risposta.

• Utilizzare 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 accodare all'interno del worklet:

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

• Utilizzare le intestazioni di risposta

  Come per l'impostazione di un valore in Shared Storage, puoi utilizzare Shared-Storage-Write nell'intestazione di risposta per passare 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 da un worklet.

await sharedStorage.get('mykey');

L'origine del contesto di navigazione da cui è stato caricato il modulo del worklet determina lo spazio di archiviazione condiviso di chi viene letto.

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.

• Utilizzare JavaScript

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

  window.sharedStorage.delete('myKey');
  

  Per eliminare lo 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();
  

• Utilizzare le intestazioni di risposta

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

  delete;key="myKey"
  

  Per eliminare tutte le chiavi utilizzando le intestazioni di risposta:

  clear;
  

Cambio di contesto

I dati di Shared Storage vengono scritti nell'origine (ad es. 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'embedder. Pertanto, quando il codice di terze parti chiama sharedStorage.set(), i dati vengono scritti nello spazio di archiviazione condiviso dell'utente che ha eseguito l'embed. Quando carichi il codice di terze parti all'interno di un iframe, il codice riceve un nuovo contesto di navigazione e la relativa origine è l'origine dell'iframe. Pertanto, la chiamata sharedStorage.set() effettuata dall'iframe archivia i dati nello stoccaggio 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 archiviata nel contesto 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 nello spazio di archiviazione condiviso, puoi utilizzare l'API PrivateAggregation.

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 in transito e può essere decriptato e aggregato solo utilizzando il servizio di aggregazione.

Il browser limiterà anche i contributi che un sito può dare a una query di output. Nello specifico, il budget per i contributi 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)
});

Eseguire lo spazio di archiviazione condiviso e l'aggregazione privata

Devi creare un worklet per accedere ai dati dallo spazio di archiviazione condiviso. Per farlo, chiama createWorklet() con l'URL del worklet. Per impostazione predefinita, quando utilizzi lo spazio di archiviazione condiviso con createWorklet(), l'origine della partizione di dati sarà l'origine del contesto di navigazione invocante, non l'origine dello script del worklet stesso.

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

• dataOrigin: "context-origin" (impostazione predefinita): i dati vengono archiviati nello spazio di archiviazione condiviso dell'origine del contesto di navigazione richiamato.
• dataOrigin: "script-origin": i dati vengono archiviati nello spazio di archiviazione condiviso dell'origine dello script del worklet. Tieni presente che per attivare questa modalità è richiesta un'attivazione.

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

Per attivare questa funzionalità, quando utilizzi "script-origin", l'endpoint dello script dovrà rispondere con l'intestazione Shared-Storage-Cross-Origin-Worklet-Allowed. Tieni presente che CORS deve essere abilitato per le richieste cross-origin.

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

L'impostazione di "dataOrigin" su "createWorklet()" e la creazione di worklet cross-origin con "addModule()" sono diventate disponibili in M130.

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 di worklet sharedStorageWorklet.js, nello stesso codice JavaScript dell'iframe dell'annuncio, chiama sharedStorage.run().

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 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 di una richiesta cross-origin

L'archiviazione condivisa e l'aggregazione privata consentono di creare worklet multiorigine senza bisogno di iframe multiorigine.

La pagina proprietaria può anche invocare una chiamata createWorklet() all'endpoint JavaScript cross-origin. Quando crei il worklet, devi impostare l'origine della partizione di dati del worklet su quella dell'origine 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 cross-origin dovrà rispondere con le intestazioniShared-Storage-Cross-Origin-Worklet-Allowed e tenere presente 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.

Nota: addModule() può essere utilizzato per creare worklet cross-origin. Tuttavia, è preferibile utilizzare createWorklet() in quanto consente la creazione di una partizione di dati cross-origin e può creare più worklet, a differenza di addModule().

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

Passaggi successivi

Le pagine seguenti spiegano aspetti importanti delle API di archiviazione condivisa e aggregazione privata.

• Introduzione allo spazio di archiviazione condiviso (Chrome per sviluppatori)
• Caso d'uso dello spazio di archiviazione condiviso (Chrome per sviluppatori)
• Introduzione all'aggregazione privata (Chrome per sviluppatori)
• Documentazione dello spazio di archiviazione condiviso (GitHub)
• Spiegazione dell'aggregazione privata (GitHub)
• Demo di spazio di archiviazione condiviso e aggregazione privata

Una volta acquisita 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 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.

• Spazio di archiviazione condiviso
• Aggregazione privata