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 utiliser Shared Storage et Private Aggregation. Vous devez comprendre les deux API, car Shared Storage stocke les valeurs et Private Aggregation crée les rapports agrégables.

Audience cible : fournisseurs de technologies publicitaires et de mesure.

API Shared Storage

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

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

Le stockage partagé est limité en capacité par origine, chaque entrée étant limitée à un nombre maximal de caractères. Si la limite est atteinte, aucune autre saisie n'est stockée. Les limites de stockage des données sont décrites dans l'explication sur le stockage partagé.

Appeler Shared Storage

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

• Utiliser JavaScript : les technologies publicitaires peuvent effectuer des fonctions de stockage partagé spécifiques, telles que définir, ajouter et supprimer des 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 qui peuvent être utilisées en dehors d'un worklet JavaScript sont disponibles dans Proposed API Surface – Outside the worklet.

  Les méthodes utilisées dans le worklet lors d'une opération sont disponibles dans Proposed API Surface - In the worklet.

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

  Comme pour JavaScript, seules certaines fonctions telles que la définition, l'ajout et la suppression de valeurs dans le stockage partagé peuvent être effectuées à l'aide d'en-têtes de réponse. Pour utiliser le stockage partagé 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 depuis le client, exécutez le code suivant, en fonction de la méthode choisie :

  • Utiliser fetch()

    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>
    

  • Utiliser 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: Response Headers (Stockage partagé : en-têtes de réponse).

Écrire dans Shared Storage

Pour écrire dans Shared Storage, appelez sharedStorage.set() depuis l'intérieur ou l'extérieur d'un worklet JavaScript. Si elle est appelée en dehors du worklet, les données sont écrites dans 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 dans l'origine du contexte de navigation qui a chargé le worklet. Les clés définies expirent 30 jours après la dernière mise à jour.

Le champ ignoreIfPresent est facultatif. Si elle est présente et définie sur true, la clé n'est pas mise à jour si elle existe déjà. La date d'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 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'}
  

  De même, à l'intérieur du worklet :

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

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

  Vous pouvez également écrire dans 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
  

  Plusieurs éléments peuvent être séparés par une virgule et peuvent 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 "append". Si la clé n'existe pas, l'appel de append() crée la clé et définit la valeur. Pour ce faire, vous pouvez utiliser JavaScript ou un en-tête de réponse.

• Utiliser JavaScript

  Pour mettre à jour les valeurs des 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 éléments dans le worklet :

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

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

  Comme pour définir une valeur dans le stockage partagé, 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"
  

Mise à jour groupée des valeurs

Vous pouvez appeler sharedStorage.batchUpdate() depuis ou en dehors d'un worklet JavaScript et transmettre un tableau ordonné de méthodes qui spécifient les opérations choisies. Chaque constructeur de méthode accepte les mêmes paramètres que la méthode individuelle correspondante pour set, append, delete et clear.

Vous pouvez appeler batchUpdate() à partir de JavaScript ou utiliser un en-tête de réponse :

• Utiliser JavaScript

  Voici quelques méthodes JavaScript qui peuvent être utilisées avec batchUpdate() :

  • SharedStorageSetMethod() : écrit une paire clé-valeur dans le stockage partagé.
  • SharedStorageAppendMethod() : ajoute une valeur à une clé existante dans le stockage partagé ou écrit une paire clé-valeur si la clé n'existe pas encore.
  • SharedStorageDeleteMethod() : supprime une paire clé-valeur du stockage partagé.
  • SharedStorageClearMethod() : efface toutes les clés du stockage partagé.

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

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

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

L'utilisation d'en-têtes de réponse effectue batchUpdate() pour toutes les méthodes de l'en-tête.

Lire à partir de Shared Storage

Vous ne pouvez lire les données du stockage partagé que depuis un worklet.

await sharedStorage.get('mykey');

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

Supprimer des données de Shared Storage

Vous pouvez effectuer des suppressions à partir du stockage partagé à l'aide de JavaScript, à 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 à la fois, utilisez clear() depuis l'une ou l'autre des interfaces.

• Utiliser JavaScript

  Pour supprimer des données du stockage partagé en dehors du worklet :

  window.sharedStorage.delete('myKey');
  

  Pour supprimer des données du stockage partagé depuis le worklet :

  sharedStorage.delete('myKey');
  

  Pour supprimer toutes les clés à la fois en dehors du worklet :

  window.sharedStorage.clear();
  

  Pour supprimer toutes les clés à la fois depuis le worklet :

  sharedStorage.clear();
  

• Utiliser les 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 des en-têtes de réponse :

  clear;
  

Lire les groupes d'intérêt Protected Audience à partir de Shared Storage

Vous pouvez lire les groupes d'intérêt Protected Audience à partir d'un worklet Shared Storage. La méthode interestGroups() renvoie un tableau d'objets StorageInterestGroup, y compris les attributs AuctionInterestGroup et GenerateBidInterestGroup.

L'exemple suivant montre comment lire les groupes d'intérêt du contexte de navigation et certaines opérations possibles qui peuvent être effectuées sur les groupes d'intérêt récupérés. Deux opérations possibles sont utilisées : trouver le nombre de groupes d'intérêt et trouver le groupe d'intérêt avec le nombre d'enchères le plus élevé.

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 du contexte de navigation à partir duquel le module de worklet a été chargé détermine l'origine des groupes d'intérêt lus par défaut. Pour en savoir plus sur l'origine du worklet par défaut et sur la façon de la modifier, consultez la section Exécuter Shared Storage et Private Aggregation dans le tutoriel sur l'API Shared Storage.

Options

Toutes les méthodes de modificateur Shared Storage acceptent un objet d'options facultatif comme dernier argument.

withLock

L'option withLock est facultative. Si cette option est spécifiée, la méthode est invitée à acquérir un verrou pour la ressource définie à l'aide de l'API Web Locks avant de continuer. Un nom de verrouillage est transmis lors de la demande de verrouillage. Le nom représente une ressource dont l'utilisation est coordonnée dans plusieurs onglets,workers ou codes au sein de l'origine.

L'option withLock peut être utilisée avec les méthodes de modification Shared Storage suivantes :

• set
• append
• supprimer
• effacer
• mise à jour groupée

Vous pouvez définir le verrouillage à l'aide de JavaScript ou d'un en-tête de réponse :

• Utiliser JavaScript

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

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

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

Les verrous de stockage partagé sont partitionnés par origine des données. Les verrous sont indépendants de ceux obtenus à l'aide de la méthode LockManager de LockManager, qu'ils se trouvent dans un contexte window ou worker. Néanmoins, ils partagent le même champ d'application que les verrous obtenus à l'aide de request() dans le contexte SharedStorageWorklet.

Bien que la méthode request() offre diverses options de configuration, les verrous acquis dans le stockage partagé respectent toujours les paramètres par défaut suivants :

• mode: "exclusive" : aucun autre verrou du même nom ne peut être détenu simultanément.
• steal: false : les verrous existants portant le même nom ne sont pas libérés pour répondre à d'autres demandes.
• ifAvailable: false : les requêtes attendent indéfiniment jusqu'à ce que le verrou devienne disponible.

Dans quel contexte utiliser withLock ?

Les verrous sont utiles dans les scénarios où plusieurs worklets peuvent s'exécuter simultanément (par exemple, plusieurs worklets sur une page ou plusieurs worklets dans différents onglets), chacun d'eux examinant les mêmes données. Dans ce scénario, il est judicieux d'encapsuler le code du worklet concerné avec un verrou pour s'assurer qu'un seul worklet traite les rapports à la fois.

Les verrous sont également utiles lorsqu'un worklet doit lire plusieurs clés ensemble et que leur état doit être synchronisé. Dans ce cas, il convient d'encapsuler les appels get avec un verrou et de s'assurer d'acquérir le même verrou lors de l'écriture dans ces clés.

Ordre des verrous

En raison de la nature des verrous Web, il est possible que les méthodes de modification ne s'exécutent pas dans l'ordre que vous avez défini. Si la première opération nécessite un verrou et qu'elle est retardée, la deuxième opération peut commencer avant la fin de la première.

Par exemple :

// 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');

Exemple de modification de plusieurs clés

L'option withLock avec batchUpdate() assure l'exclusion mutuelle avec d'autres opérations simultanées acquérant le même verrou. Vous ne pouvez appliquer l'option withLock pour batchUpdate() qu'à l'ensemble du lot. L'application de withLock à un objet de méthode individuel dans le lot génère une exception.

Cet exemple utilise un verrou pour s'assurer que les opérations de lecture et de suppression au sein du worklet se produisent ensemble, ce qui empêche toute interférence en dehors du worklet.

L'exemple modify-multiple-keys.js suivant définit de nouvelles valeurs pour keyOne et keyTwo avec modify-lock, puis exécute l'opération modify-multiple-keys à partir du 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');

Ensuite, dans modify-multiple-keys-worklet.js, vous pouvez demander le verrouillage à l'aide de navigator.locks.request() pour lire et modifier les clés si nécessaire.

// 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);

Changement de contexte

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

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 le stockage partagé de l'intégrateur. Lorsque vous chargez le code tiers dans un iframe, le code reçoit un nouveau contexte de navigation et son origine est celle de l'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 a intégré 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 d'un tiers en créant un 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. Elle ne peut être déchiffrée et agrégée qu'à l'aide du service d'agrégation.

Le navigateur limitera é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é dans 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

Par défaut, lorsque vous utilisez le stockage partagé avec createWorklet(), l'origine de la partition de données est celle du contexte de navigation appelant, et non celle 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 appelant.
• dataOrigin: "script-origin" : les données sont stockées dans l'espace de stockage partagé de l'origine du script du worklet. Vous devez activer ce mode.
• dataOrigin: "https://custom-data-origin.example" : les données sont stockées dans l'espace de stockage partagé d'une origine de données personnalisée. Pour activer ce mode, vous devez l'activer et obtenir le consentement du propriétaire de l'origine de données personnalisée, comme indiqué dans Origine de données personnalisée.

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

Pour activer cette fonctionnalité, lorsque vous utilisez "script-origin" ou une origine personnalisée, le point de terminaison du script doit répondre avec l'en-tête Shared-Storage-Cross-Origin-Worklet-Allowed. Pour les requêtes multi-origines, le CORS doit également être activé.

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

Vous pouvez également exécuter des scripts cross-origin à l'aide d'un iFrame tiers. Dans ce cas, les actions Shared Storage se trouveront dans le contexte de navigation tiers.

Utiliser un iFrame inter-origines

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

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

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 devrez créer une classe avec une méthode run asynchrone et l'register pour qu'elle s'exécute dans l'iFrame de l'annonce. À l'intérieur 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-origines

Shared Storage et Private Aggregation permettent de créer des worklets multi-origines sans avoir besoin d'iFrames multi-origines.

La page propriétaire peut également appeler createWorklet() au point de terminaison JavaScript d'origine croisée. Lorsque vous créez le worklet, vous devez définir l'origine de la partition de données du worklet sur celle de l'origine du 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();

Le point de terminaison JavaScript d'origine croisée devra répondre avec les en-têtes Shared-Storage-Cross-Origin-Worklet-Allowed et noter que 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.

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

Origine de données personnalisée

Lorsque dataOrigin est défini sur une origine valide, le propriétaire de dataOrigin doit consentir au traitement du stockage partagé pour ce dataOrigin en hébergeant un fichier JSON listant l'origine du script du worklet au chemin d'accès /.well-known/shared-storage/trusted-origins. Le fichier doit être un tableau d'objets avec les clés scriptOrigin et contextOrigin. Les valeurs de ces clés peuvent être une chaîne ou un tableau de chaînes.

Créez le fichier trusted-origins à l'aide des informations suivantes :

• Contexte de l'appelant
• URL et origine du script du worklet
• Origine et propriétaire des données

Le tableau suivant montre comment construire le fichier trusted-origins en fonction de ces informations :

[{
  "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"
}]
      

Par exemple, le code JSON suivant peut être hébergé sur https://custom-data-origin.example/.well-known/shared-storage/trusted-origins et combiner tous les processeurs autorisés de données Shared Storage pour 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"
    ]
}]

Étapes suivantes

Les pages suivantes expliquent des aspects importants des API Shared Storage et Private Aggregation.

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

Une fois que vous vous êtes familiarisé avec les API, vous pouvez commencer à collecter les rapports, qui sont envoyés sous la forme d'une 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 le Trusted Execution Environment for Aggregation Service pour obtenir les rapports agrégés.

Envoyer des commentaires

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

• Shared Storage
• Private Aggregation