Cette page a été traduite par l'API Cloud Translation.

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 comprendre les deux API, car le stockage partagé stocke les valeurs et Private Aggregation crée les rapports agrégables.

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

Essayer la version de démonstration

Essayez la démonstration en direct. Suivez les étapes des instructions de la démonstration pour activer les API Privacy Sandbox. L'ouverture des outils pour les développeurs Chrome vous permet de visualiser les résultats de différents cas d'utilisation. Cas d'utilisation disponibles dans la démonstration:

Agrégation privée
- Mesure de la couverture unique
- Mesure des données démographiques
- Mesure de fréquence K+
Utilisation générale
- Mesurer les événements de survol au-dessus dans des cadres cloisonnés
- Navigation de premier niveau
- Contrôle où les tiers peuvent écrire

Afficher le stockage partagé

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

Affichez les données stockées dans le stockage partagé à l'aide des outils pour les développeurs Chrome.

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) à [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage, avec le rapport en 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.

Afficher les rapports dans chrome://private-opportunity-internals.

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. Toutefois, dans certains cas, 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).

Shared Storage présente une limite de capacité par origine, chaque entrée étant 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 de données sont décrites dans la présentation du stockage partagé.

Appeler le stockage partagé

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

Utiliser JavaScript Les technologies publicitaires peuvent exécuter des fonctions spécifiques de stockage partagé, telles que la définition, l'ajout et la suppression de valeurs en dehors d'un worklet JavaScript. Toutefois, les fonctions telles que la lecture de stockage partagé et l'exécution de l'agrégation privée doivent être effectuées via un worklet JavaScript. Les méthodes utilisables en dehors d'un worklet JavaScript sont disponibles dans la section Proposition de la surface d'API - À l'extérieur du worklet.

Les méthodes utilisées dans le worklet lors d'une opération sont disponibles dans Proposed API Surface - In the worklet (Surface d'API proposée : dans le worklet).
Utiliser des en-têtes de réponse

Cette fonctionnalité est disponible depuis M119.

Comme pour JavaScript, seules des fonctions spécifiques, 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 requête.

Pour lancer une requête à partir du 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 la page Stockage partagé: en-têtes de réponse.

Écrire des données dans un stockage partagé

Pour écrire dans le stockage partagé, appelez sharedStorage.set() à l'intérieur ou à l'extérieur d'un worklet JavaScript. Si elles sont appelées en dehors du worklet, les données sont écrites dans l'origine du contexte de navigation à partir duquel l'appel a été effectué. Si elles sont appelées 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 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 mise à jour si elle existe déjà. L'expiration de la clé est renouvelée pour une durée de 30 jours à compter de l'appel set(), même si la clé n'est pas mise à jour.

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

En utilisant 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 du 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 ainsi que 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 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 du code JavaScript ou des en-têtes de réponse.

En utilisant 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 éléments à l'intérieur du worklet:

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

Utiliser des 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"
```

Lire des données depuis un stockage partagé

Vous ne pouvez lire des données depuis 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 dont le stockage partagé est lu.

Suppression du stockage partagé

Vous pouvez effectuer des suppressions de stockage partagé à l'aide de JavaScript à l'intérieur ou à l'extérieur du worklet, ou à l'aide d'en-têtes de réponse avec delete(). Pour supprimer toutes les clés à la fois, utilisez clear() à partir de l'une ou l'autre de ces méthodes.

En utilisant JavaScript

Pour supprimer du stockage partagé depuis l'extérieur du worklet:
```
window.sharedStorage.delete('myKey');
```
Pour supprimer du stockage partagé à partir du 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 même temps à partir du 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 d'où provient l'appel.

Lorsque vous chargez le code tiers à l'aide d'une balise <script>, le code est exécuté dans le contexte de navigation de l'outil d'intégration. Par conséquent, lorsque le code tiers appelle sharedStorage.set(), les données sont écrites dans le stockage partagé de l'élément intégré. Lorsque vous chargez le code tiers dans un iFrame, celui-ci reçoit un nouveau contexte de navigation dont l'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 propriétaire

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.

Données stockées sur une page propriétaire avec du code JavaScript tiers intégré.

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, puis en appelant set() ou delete() dans le code JavaScript à partir de l'iFrame.

Données stockées dans le contexte de la technologie publicitaire ou d'un tiers

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 doit être 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 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é dans une période donnée et sur tous les buckets. Si le budget actuel est dépassé, aucun rapport n'est généré.

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

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

Dans l'iFrame de l'annonce, chargez le module de 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.

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

Dans le script de worklet, vous devez créer une classe avec une méthode run asynchrone. register cette classe à 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: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

Débogage

Pour activer le débogage, appelez la méthode JavaScript enableDebugMode() dans le même contexte que celui où sont utilisés le stockage partagé et l'agrégation privée. Cette information s'appliquera aux futurs rapports du même contexte.

privateAggregation.enableDebugMode();

Pour associer les rapports aux contextes qui les ont déclenchés, vous pouvez définir une clé de débogage (entier) non signée de 64 bits qui est transmise à l'appel JavaScript. 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 des blocs try-catch.

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. Les rapports de débogage reçoivent une charge utile semblable au JSON suivant. Cette charge utile définit le champ api sur "shared-storage".

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

Déboguer la charge utile en texte clair

Le debug_cleartext_payload est encodé au format CBOR Base64. Vous pouvez afficher le bucket et la valeur à l'aide du décodeur ou du code JavaScript disponible dans le décodeur de stockage partagé.

Étapes suivantes

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

Une fois familiarisé avec les API, vous pouvez commencer à collecter les rapports, qui sont envoyés en tant que 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 nous faire part de vos commentaires sur les API et la documentation sur GitHub.