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 des Agrégation. Vous devez connaître les deux API, car Shared Storage stocke les valeurs, et Private Aggregation crée des rapports agrégables.

Audience cible:technologies publicitaires et fournisseurs de solutions de mesure.

Essayer la démo

Essayez la démonstration en direct. Suivre la procédure dans les instructions de démonstration pour activer les API Privacy Sandbox. Ouverture de Chrome Les outils de développement vous permettent de visualiser les résultats de différents cas d'utilisation. Cas d'utilisation dans la démonstration:

• Agrégation privée
  • Mesure Unique Reach
  • Mesure des données démographiques
  • Mesure de la fréquence K+
• Utilisation générale
  • Mesurer l'événement de survol dans des cadres cloisonnés
  • Navigation de premier niveau
  • Contrôle des emplacements où les tiers peuvent écrire

Afficher le stockage partagé

Pour afficher les données stockées dans le stockage partagé, utilisez les outils pour les développeurs Chrome. Les données stockées peuvent sont disponibles dans Application -> Shared Storage.

Afficher les rapports sur l'agrégation privée

Pour afficher les rapports agrégables envoyés, accédez à chrome://private-aggregation-internals Lorsque le mode débogage est activé, un rapport est envoyé immédiatement (sans délai) au [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage ainsi que le rapport différé à envoyer à [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage

Pour activer le débogage, suivez les instructions de la section Débogage. .

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 requis. L'API Shared Storage fournit Accès en écriture illimité sur différents sites de premier niveau avec protection de la confidentialité un accès en lecture.

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

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

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 de Shared Storage ne s'effectue que dans un fichier JavaScript isolé un environnement de travail 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.

• Utiliser JavaScript : les technologies publicitaires peuvent exécuter des fonctions de stockage partagé spécifiques. telles que la définition, l'ajout et la suppression de valeurs en dehors d'un fichier JavaScript Worklet de VM. Toutefois, des fonctions telles que la lecture du stockage partagé et l'exécution L'agrégation privée doit être effectuée à l'aide d'un Worklet JavaScript. Les méthodes utilisables en dehors d'un Worklet JavaScript sont disponibles dans Surface d'API proposée - À l'extérieur de la Worklet de travail.

  Les méthodes utilisées dans le Worklet lors d'une opération se trouvent dans Surface d'API proposée - Dans le Worklet de travail.

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

  Cette fonctionnalité est disponible dans M119.

  Comme pour JavaScript, seules des fonctions spécifiques telles que la définition, l'ajout, et supprimer des valeurs dans le stockage partagé à l'aide d'en-têtes de réponse. À travailler avec 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>
  

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

Vous trouverez plus d'informations dans Stockage partagé: réponse En-têtes :

Écrire dans le stockage partagé

Pour écrire dans le stockage partagé, appelez sharedStorage.set() depuis ou depuis l'intérieur ou l'extérieur d'un Worklet JavaScript. En cas d'appel depuis l'extérieur du Worklet, les données sont écrites dans L'origine du contexte de navigation à partir duquel l'appel a été effectué En cas d'appel depuis dans 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 elle est présente et définie sur true, la clé n'est pas mis à jour s'il existe déjà. L'expiration de la clé est renouvelée pour 30 jours l'appel set() même si la clé n'est pas mise à jour.

Si Shared Storage est consulté plusieurs fois au cours d'un même chargement de page avec le même clé, la valeur de la clé est remplacée. C'est une bonne idée 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, 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 éléments suivants : commandes:

  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 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. Cela peut à l'aide de JavaScript ou d'en-têtes de réponse.

• Utiliser JavaScript

  Pour mettre à jour les valeurs de clés existantes, utilisez sharedStorage.append() dans : à 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 des en-têtes de réponse

  Comme pour le stockage partagé, vous pouvez utiliser le paramètre 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 des données à partir d'un espace de stockage partagé

Vous ne pouvez lire des données depuis le stockage partagé qu'à partir d'un Worklet.

await sharedStorage.get('mykey');

Origine du contexte de navigation à partir duquel le module de Worklet a été chargé détermine quel espace de stockage partagé est lu.

Supprimer des éléments de stockage partagé

Vous pouvez effectuer des suppressions dans le stockage partagé à l'aide de JavaScript ou en dehors du Worklet, ou à l'aide d'en-têtes de réponse avec delete(). Pour supprimer toutes les clés en même temps, utilisez clear() à partir de l'une ou l'autre des clés.

• Utiliser JavaScript

  Pour supprimer des éléments de l'espace de stockage partagé en dehors du workflow, procédez comme suit:

  window.sharedStorage.delete('myKey');
  

  Pour supprimer des éléments de l'espace de stockage partagé à partir du Worklet:

  sharedStorage.delete('myKey');
  

  Pour supprimer toutes les clés en même temps depuis l'extérieur du Worklet:

  window.sharedStorage.clear();
  

  Pour supprimer toutes les clés en même temps 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 origin (origine) (par exemple, https://example.adtech.com) du contexte de navigation dans lequel l'appel dont elle provient.

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. Ainsi, lorsque le code tiers appelle sharedStorage.set(), les données sont écrites dans la classe Shared Cloud Storage. Lorsque vous chargez le code tiers dans un iFrame, le code reçoit un nouveau contexte de navigation, dont l'origine est l'origine de l'iFrame. Par conséquent, l'appel sharedStorage.set() effectué à partir de l'iFrame stocke les données dans Stockage partagé de l'origine de l'iFrame.

Contexte propriétaire

Si une page propriétaire intègre un 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 ad tech ou tiers créer un iFrame et appeler set() ou delete() dans le code JavaScript depuis dans l'iFrame.

API Private Aggregation

Pour mesurer les données agrégables stockées dans Shared Storage, vous pouvez utiliser la classe API d'agrégation.

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

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

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

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

Exécuter le stockage partagé et l'agrégation privée

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 Worklet en appelant addModule(). Pour exécuter la enregistrée dans le fichier Worklet sharedStorageWorklet.js, dans même code JavaScript pour l'iFrame d'annonce, appelez sharedStorage.run().

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Dans le script du Worklet, vous devez créer une classe avec un run asynchrone. . Et register cette classe pour qu'elle soit exécutée 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: bucket,
      value: 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 nécessiter d'iFrames multi-origines.

La page propriétaire peut appeler un appel createWorklet() vers l'origine croisée du point de terminaison JavaScript.

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

Le point de terminaison JavaScript multi-origines devra répondre avec les en-têtes Shared-Storage-Cross-Origin-Worklet-Allowed et autoriser le multi-origine à l'aide de Access-Control-Allow-Origin

Avertissement :Les en-têtes de réponse du script du Worklet devront activer cette option avec CORS Access-Control-Allow-Origin et Shared-Storage-Cross-Origin-Worklet-Allowed. Veillez à fournir l'accès à votre travaillet, car ce n'est pas votre document qui demande votre Worklet de travail à exécuter.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1
Access-Control-Allow-Origin : https://first-party.dev

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: bucket,
      value: value
    });
  }
}

Débogage

Pour activer le débogage, appelez la méthode JavaScript enableDebugMode() dans le même dans lequel Shared Storage et Private Aggregation sont utilisés. Ce sera appliquée aux futurs rapports dans le même contexte.

privateAggregation.enableDebugMode();

Pour associer les rapports aux contextes qui les ont déclenchés, vous pouvez définir un Clé de débogage de type entier non signé de 64 bits transmise à l'appel JavaScript. La debugKey est de type BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Déboguer le stockage partagé

Shared Storage renvoie un message d'erreur générique:

Promise is rejected without and explicit error message

Vous pouvez déboguer le stockage partagé en encapsulant les appels avec tentative de jeu blocs.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Déboguer l'agrégation privée

Les rapports sont envoyés à /.well-known/private-aggregation/report-shared-storage et /.well-known/private-aggregation/debug/report-shared-storage Rapports de débogage reçoivent une charge utile semblable au code JSON suivant. Cette charge utile définit le api est défini sur "shared-storage".

{
   "aggregation_coordinator_origin": "https://publickeyservice.msmt.gcp.privacysandboxservices.com",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhlKJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAB1vNFaJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAGlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "1569ab37-da44-4a26-80d9-5ed6524ab2a7",
      "payload": "/9nHrWn1MnJWRxFvanbubciWE9mPyIij6uYLi5k351eQCd3/TZpe2knaatUNcniq4a4e61tmKebv50OmMRZFnnCfcAwIdIgLHu1a3en97PojqWJBfO52RiVMIcP7KQTLzMxq2LhvPSdV4zjXo1Teu/JuIK3LIyis3vUMpS+tUAX0QV+I6X5SVmZFiNW9aMb8DwLOtqrBy5JJ/EkOIY0G+1Fi1/3R7UtKsqM1o71A/OzdmlNkwO7EV/VUNinGvWnd19FvDHe/kqkNdTHKbhAnMmbZzHW9bsEQS81leElCla6BTdbdbeeFU/jbTj0AOaoNOIe5r7FU5NG6nW4ULXTCbLLjTQ1mtl3id3IP41Zin1JvABCDC/HUSgLFz8EUqkmbMIOlMfNYA79aURq6FqE0GO0HtICYf0GPNdVv7p4jY3FNn6+JS4l5F3t+3lP9ceo4IpCE+31jzMtYJ+19xFh6C5ufteBR/iknZFcc1w3caQBhgRl5jt8DbaOzYcW4690H8Ul4Oh2wRO+6/njifk+pExLay/O5swLi2lUUph5OUEaaztwwzh2mnhwIBxMkPnfsGihiF+5KDEajVfMZ3NLsIDoZO+l4RTZrkqE+jVkAqaZGBiCIx42Edp/JV0DXfrryypCdQBZr8iEbSzCM9hKsMfLN7S/VkPe5rDwOZbhKCn5XXgfGz5tSx/KbZgsQf4OCEhwAyNPHAh3MHU7xmkQ3pKg4EIUC/WOtKAlVDOtDMmPPoQY1eAwJhw9SxZaYF1kHjUkTm3EnGhgXgOwCRWqeboNenSFaCyp6DbFNI3+ImONMi2oswrrZO+54Tyhca5mnLIiInI+C3SlP4Sv1jFECIUdf/mifJRM5hMj6OChzHf4sEifjqtD4A30c4OzGexWarie2xakdQej9Go4Lm0GZEDBfcAdWLT9HwmpeI2u4HDAblXDvLN8jYFDOOtzOl90oU7AwdhkumUCFLRadXAccXW9SvLfDswRkXMffMJLFqkRKVE1GPonFFtlzaRqp7IgE8L6AOtz6NDcxAjHnEuzDPPMcWMl1AFH0gq7h"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"80d93c0a-a94e-4ab7-aeb5-a4ecd4bfc598\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1717784740\",\"version\":\"0.1\"}"
}

Déboguer la charge utile en texte clair

debug_cleartext_payload est Base64 encodée en CBOR. Vous pouvez afficher le bucket à l'aide du decoder ou utilisez le code JavaScript qui se trouve dans le stockage partagé encodeur/décodeur.

Étapes suivantes

Les pages suivantes expliquent des aspects importants des protocoles de stockage partagé et API d'agrégation.

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

Une fois que vous vous serez familiarisé avec les API, vous pourrez commencer à collecter les rapports, qui sont envoyés sous forme de requêtes POST aux points de terminaison suivants sous forme de 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 en local outil ou configurez l'environnement d'exécution sécurisé pour l'agrégation d'assistance pour obtenir les rapports agrégés.

Envoyer des commentaires

Vous pouvez nous faire part de vos commentaires sur les API et la documentation sur GitHub.

• Stockage partagé
• Agrégation privée