Guide de démarrage rapide pour l'implémentation du stockage partagé et de l'agrégation privée

Ce document est un guide de démarrage rapide pour l'utilisation du stockage partagé et de l'agrégation privée. Vous devez connaître les deux API, car Shared Storage stocke les valeurs et Private Aggregation crée les rapports agrégables.

Cible:technologies publicitaires et fournisseurs de solutions de mesure.

API Shared Storage

Pour empêcher le suivi intersites, les navigateurs ont commencé à partitionner toutes les formes de stockage, y compris le stockage local, les cookies, etc. Mais il existe des cas d'utilisation où un stockage non partitionné est nécessaire. L'API Shared Storage fournit un accès en écriture illimité sur différents sites de premier niveau avec un accès en lecture protégeant la confidentialité.

Le stockage partagé est limité à l'origine du contexte (l'appelant de sharedStorage).

Le stockage partagé est limité en termes de capacité par origine, et chaque entrée est limitée à un nombre maximal de caractères. Si la limite est atteinte, aucune autre entrée n'est stockée. Les limites de stockage des données sont décrites dans la présentation de Shared Storage.

Appeler le stockage partagé

Les technologies publicitaires peuvent écrire dans le stockage partagé à l'aide de JavaScript ou d'en-têtes de réponse. La lecture à partir du stockage partagé ne se produit que dans un environnement JavaScript isolé appelé "worklet".

Un worklet vous permet d'exécuter des fonctions JavaScript spécifiques et de renvoyer des informations au demandeur. Dans un worklet, vous pouvez exécuter JavaScript, mais vous ne pouvez pas interagir ni communiquer avec la page externe.

Les Worklets sont utilisés pour stocker et extraire des données avec l'API Shared Storage.

• À l'aide de JavaScript Les technologies publicitaires peuvent effectuer des fonctions de stockage partagé spécifiques, telles que le paramétrage, l'ajout et la suppression de valeurs en dehors d'un worklet JavaScript. Toutefois, les fonctions telles que la lecture du stockage partagé et l'agrégation privée doivent être effectuées via un Worklet JavaScript. Les méthodes pouvant être utilisées en dehors d'un worklet JavaScript sont disponibles dans la section Proposed API Surface - Outside the worklet (Surface de l'API proposée – En dehors du worklet).

  Les méthodes utilisées dans le worklet lors d'une opération se trouvent dans la section Proposed API Surface - In the worklet (Surface de l'API proposée : dans le worklet).

• Utiliser des en-têtes de réponse

  Comme en JavaScript, seules des fonctions spécifiques telles que la définition, l'ajout et la suppression de valeurs dans Shared Storage peuvent être effectuées à l'aide d'en-têtes de réponse. Pour utiliser Shared Storage dans un en-tête de réponse, Shared-Storage-Writable: ?1 doit être inclus dans l'en-tête de la requête.

  Pour lancer une requête à partir du client, exécutez le code suivant, en fonction de la méthode choisie:

  • fetch() utilisé(s)

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

  • Utiliser une balise iframe ou img

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

  • Utilisation d'un attribut IDL avec une balise iframe ou img

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

Pour en savoir plus, consultez Shared Storage: en-têtes de réponse.

Écrire dans Shared Storage

Pour écrire dans le stockage partagé, appelez sharedStorage.set() depuis ou depuis un Worklet JavaScript. Si appelé en dehors du worklet, les données sont écrites à l'origine du contexte de navigation à partir duquel l'appel a été effectué. Si elle est appelée depuis le worklet, les données sont écrites à l'origine du contexte de navigation qui a chargé le worklet. Les clés définies ont une date d'expiration de 30 jours à compter de la dernière mise à jour.

Le champ ignoreIfPresent est facultatif. Si cette clé est présente et définie sur true, elle n'est pas mise à jour si elle existe déjà. L'expiration de la clé est renouvelée pour 30 jours à compter de l'appel set(), même si la clé n'est pas mise à jour.

Si le stockage partagé est consulté plusieurs fois lors du même chargement de page avec la même clé, la valeur de la clé est écrasée. Il est conseillé d'utiliser sharedStorage.append() si la clé doit conserver la valeur précédente.

• Utiliser JavaScript

  En dehors du widget de travail:

  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'}
  

  De même, dans le worklet:

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

• Utiliser des en-têtes de réponse

  Vous pouvez également écrire sur le stockage partagé à l'aide d'en-têtes de réponse. Pour ce faire, utilisez Shared-Storage-Write dans l'en-tête de réponse avec les commandes suivantes:

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

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

  Vous pouvez séparer plusieurs éléments par une virgule et combiner set, append, delete et clear.

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

Ajouter une valeur

Vous pouvez ajouter une valeur à une clé existante à l'aide de la méthode d'ajout. Si la clé n'existe pas, l'appel de append() crée la clé et définit la valeur. Pour ce faire, utilisez JavaScript ou des en-têtes de réponse.

• Utiliser JavaScript

  Pour mettre à jour les valeurs de clés existantes, utilisez sharedStorage.append() à l'intérieur ou à l'extérieur du 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'}
  

  Pour ajouter des données dans le worklet:

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

• Utiliser des en-têtes de réponse

  Comme pour définir une valeur dans Shared Storage, vous pouvez utiliser Shared-Storage-Write dans l'en-tête de réponse pour transmettre la paire clé-valeur.

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

Lire à partir de l'espace de stockage partagé

Vous ne pouvez lire le stockage partagé qu'à partir d'un worklet.

await sharedStorage.get('mykey');

L'origine du contexte de navigation à partir duquel le module de worklet a été chargé détermine le stockage partagé qui est lu.

Supprimer de l'espace de stockage partagé

Vous pouvez effectuer des suppressions à partir de Shared Storage à l'aide de JavaScript, que ce soit à l'intérieur ou à l'extérieur du worklet, ou en utilisant des en-têtes de réponse avec delete(). Pour supprimer toutes les clés en même temps, utilisez clear() dans l'une ou l'autre des applications.

• À l'aide de JavaScript

  Pour supprimer des éléments du stockage partagé en dehors du worklet:

  window.sharedStorage.delete('myKey');
  

  Pour supprimer des éléments du stockage partagé depuis le worklet:

  sharedStorage.delete('myKey');
  

  Pour supprimer toutes les clés en même temps en dehors du worklet:

  window.sharedStorage.clear();
  

  Pour supprimer toutes les clés en une seule fois depuis le worklet:

  sharedStorage.clear();
  

• Utiliser des en-têtes de réponse

  Pour supprimer des valeurs à l'aide d'en-têtes de réponse, vous pouvez également utiliser Shared-Storage-Write dans l'en-tête de réponse pour transmettre la clé à supprimer.

  delete;key="myKey"
  

  Pour supprimer toutes les clés à l'aide d'en-têtes de réponse:

  clear;
  

Changement de contexte

Les données de stockage partagé sont écrites dans l'origine (par exemple, https://example.adtech.com) du contexte de navigation à partir duquel l'appel a été effectué.

Lorsque vous chargez le code tiers à l'aide d'une balise <script>, le code est exécuté dans le contexte de navigation de l'intégrateur. Par conséquent, lorsque le code tiers appelle sharedStorage.set(), les données sont écrites dans l'espace de stockage partagé de l'intégrateur. Lorsque vous chargez le code tiers dans un élément iFrame, le code reçoit un nouveau contexte de navigation et son origine est celle de l'élément iFrame. Par conséquent, l'appel sharedStorage.set() effectué à partir de l'iFrame stocke les données dans le stockage partagé de l'origine de l'iFrame.

Contexte first party

Si une page propriétaire intègre du code JavaScript tiers qui appelle sharedStorage.set() ou sharedStorage.delete(), la paire clé-valeur est stockée dans le contexte propriétaire.

Contexte tiers

La paire clé-valeur peut être stockée dans le contexte de la technologie publicitaire ou tiers en créant une iFrame et en appelant set() ou delete() dans le code JavaScript à partir de l'iFrame.

API Private Aggregation

Pour mesurer les données agrégables stockées dans Shared Storage, vous pouvez utiliser l'API Private Aggregation.

Pour créer un rapport, appelez contributeToHistogram() dans un worklet avec un bucket et une valeur. Le bucket est représenté par un entier non signé de 128 bits qui doit être transmis à la fonction en tant que BigInt. La valeur est un entier positif.

Pour protéger la confidentialité, la charge utile du rapport, qui contient le bucket et la valeur, est chiffrée en transit et ne peut être déchiffrée et agrégée qu'à l'aide du service d'agrégation.

Le navigateur limite également les contributions qu'un site peut apporter à une requête de sortie. Plus précisément, le budget de contribution limite le total de tous les rapports d'un même site pour un navigateur donné au cours d'une période donnée pour tous les buckets. Si le budget actuel est dépassé, aucun rapport ne sera généré.

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

Exécuter Shared Storage et Private Aggregation

Vous devez créer un worklet pour accéder aux données du stockage partagé. Pour ce faire, appelez createWorklet() avec l'URL du worklet. Par défaut, lorsque vous utilisez le stockage partagé avec createWorklet(), l'origine de la partition de données est l'origine du contexte de navigation qui appelle, et non l'origine du script du Worklet lui-même.

Pour modifier le comportement par défaut, définissez la propriété dataOrigin lorsque vous appelez createWorklet.

• dataOrigin: "context-origin": (par défaut) les données sont stockées dans l'espace de stockage partagé de l'origine du contexte de navigation appelé.
• dataOrigin: "script-origin": les données sont stockées dans l'espace de stockage partagé de l'origine du script de travail. Notez que vous devez activer ce mode.

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

Pour l'activer, lorsque vous utilisez "script-origin", le point de terminaison du script doit répondre avec l'en-tête Shared-Storage-Cross-Origin-Worklet-Allowed. Notez que CORS doit être activé pour les requêtes multi-origines.

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

La définition de "dataOrigin" sur "createWorklet()" et la création de Worklets multi-origines avec "addModule()" sont disponibles dans M130.

Utiliser un iFrame multi-origine

Un iFrame est nécessaire pour appeler le Worklet de stockage partagé.

Dans l'iframe de l'annonce, chargez le module de travaillet en appelant addModule(). Pour exécuter la méthode enregistrée dans le fichier de worklet sharedStorageWorklet.js, dans le même code JavaScript de l'iFrame d'annonce, appelez sharedStorage.run().

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

Dans le script du worklet, vous devez créer une classe avec une méthode run asynchrone et register pour l'exécuter dans l'iframe de l'annonce. Dans sharedStorageWorklet.js:

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

Utiliser une requête multi-origine

Le stockage partagé et l'agrégation privée permettent de créer des worklets multi-origines sans avoir besoin d'iFrames multi-origines.

La page propriétaire peut également appeler un appel createWorklet() au point de terminaison JavaScript inter-origine. Vous devez définir l'origine de la partition de données du worklet sur celle de l'origine du script lorsque vous créez le worklet.

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

Le point de terminaison JavaScript inter-origines doit répondre avec les en-têtes Shared-Storage-Cross-Origin-Worklet-Allowed et noter que le CORS est activé pour la requête.

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

Les worklets créés à l'aide de createWorklet() auront selectURL et run(). addModule() n'est pas disponible pour cela.

Remarque :addModule() peut être utilisé pour créer des worklets inter-origines. Cependant, il est préférable d'utiliser createWorklet(), car cela permet de créer une partition de données multi-origines et peut créer plusieurs Worklets, contrairement à addModule().

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

Étapes suivantes

Les pages suivantes décrivent des aspects importants des API Shared Storage et Private Aggregation.

• Présentation de l'espace de stockage partagé (Chrome pour les développeurs)
• Cas d'utilisation du stockage partagé (Chrome pour les développeurs)
• Présentation de l'agrégation privée (Chrome pour les développeurs)
• Présentation du stockage partagé (GitHub)
• Explication de l'agrégation privée (GitHub)
• Démonstration du stockage partagé et de l'agrégation privée

Une fois que vous avez pris connaissance des API, vous pouvez commencer à collecter les rapports, qui sont envoyés sous forme de requête POST aux points de terminaison suivants au format JSON dans le corps de la requête.

• Rapports de débogage - context-origin/.well-known/private-aggregation/debug/report-shared-storage
• Rapports - context-origin/.well-known/private-aggregation/report-shared-storage

Une fois les rapports collectés, vous pouvez effectuer des tests à l'aide de l'outil de test local ou configurer l'environnement d'exécution sécurisé pour le service d'agrégation afin d'obtenir les rapports agrégés.

Envoyer des commentaires

Vous pouvez partager vos commentaires sur les API et la documentation sur GitHub.

• Stockage partagé
• Agrégation privée