Générez des rapports de données globales à l'aide des données de l'API Protected Audience et des données intersites issues de Shared Storage.
Pour fournir les fonctionnalités essentielles sur lesquelles s'appuie le Web, Private Aggregation L'API a été conçue pour agréger des données intersites et générer des rapports les concernant tout en préservant la confidentialité.
État d'implémentation
Proposition | État |
---|---|
Évitez les rapports de l'API Private Aggregation non valides grâce à la validation des rapports pour le stockage partagé Explication |
Disponible dans Chrome |
Disponibilité du mode débogage de l'agrégation privée en fonction de l'éligibilité des cookies tiers Problème GitHub |
Disponible dans Chrome M119 |
Réduction du délai de signalement Contenu explicatif |
Disponible dans Chrome M119 |
Compatibilité avec l'API Private Aggregation et le service d'agrégation pour Google Cloud Contenu explicatif |
Disponible dans Chrome M121 |
Marge intérieure pour les charges utiles de rapports agrégables Contenu explicatif |
Disponible dans Chrome M119 |
Mode de débogage de l'agrégation Private Aggregation disponible pour les rapports purchaseReportBuyers Contenu explicatif |
Prévues dans Chrome M123 |
Filtrage de la compatibilité des ID Contenu explicatif |
Prévues dans Chrome M128 |
Qu'est-ce que l'API Private Aggregation ?
L'API Private Aggregation permet aux développeurs de générer des rapports sur les données agrégées à l'aide des données de l'API Protected Audience et des données intersites depuis Stockage partagé.
La fonction principale de cette API est appelée contributeToHistogram()
. L'opération d'histogramme vous permet d'agréger des données
pour plusieurs utilisateurs dans chaque bucket (appelé clé d'agrégation dans l'API) que vous définissez.
Votre appel d'histogramme accumule des valeurs et renvoie un résultat agrégé avec bruit dans
sous la forme d'un
rapport récapitulatif. Par exemple, il peut indiquer le nombre
les sites sur lesquels chaque utilisateur a vu votre contenu ou qui a rencontré un bug dans votre script tiers. Cette opération est effectuée dans le Worklet d'une autre API.
Par exemple, si vous avez déjà enregistré des données démographiques et géographiques dans Shared Storage, vous pouvez utiliser l'API Private Aggregation pour créer un histogramme indiquant le nombre approximatif d'utilisateurs de New York qui ont vu votre contenu sur plusieurs sites. Pour agréger cette mesure, vous pouvez encoder la dimension géographique dans la clé d'agrégation et compter les utilisateurs dans la valeur agrégable.
Concepts clés
Lorsque vous appelez l'API Private Aggregation avec une clé d'agrégation et une valeur agrégable, le navigateur génère un rapport agrégable.
Les rapports agrégables sont envoyés à votre serveur pour être collectés et regroupés. Les rapports par lot sont traités ultérieurement par le service d'agrégation, puis un rapport récapitulatif est généré.
Consultez le document Principes de base de l'API Private Aggregation pour en savoir plus sur les concepts clés associés à l'API Private Aggregation.
Différences par rapport à Attribution Reporting
L'API Private Aggregation présente de nombreuses similitudes avec l'API Attribution Reporting. Attribution Reporting est une API autonome conçue pour mesurer les conversions, tandis que Private Aggregation est conçu pour les mesures intersites conjointement avec des API telles que l'API Protected Audience et Shared Storage. Les deux API produisent des rapports agrégables qui sont utilisés par le backend du service d'agrégation pour générer des rapports récapitulatifs.
Attribution Reporting associe les données collectées à partir d'un événement d'impression et d'un événement de conversion, qui se produisent à des moments différents. Private Aggregation mesure un seul événement intersites.
Tester cette API
Pour tester l'API Private Aggregation en local, activez toutes les API Ad Privacy sous chrome://settings/adPrivacy
.
En savoir plus sur les tests et participation
Utiliser la version de démonstration
La démonstration de l'API Private Aggregation pour le stockage partagé est disponible à l'adresse goo.gle/shared-storage-demo, et le code est disponible sur GitHub. La démonstration implémente les opérations côté client et génère un rapport agrégable envoyé à votre serveur.
Une démonstration de l'API Private Aggregation pour l'API Protected Audience sera publiée à l'avenir.
Cas d'utilisation
Private Aggregation est une API à usage général pour les mesures intersites, disponible dans les Worklets Shared Storage et Protected Audience. La première étape consiste à décider précisément quelles informations vous souhaitez collecter. Ces points de données constituent la base de vos clés d'agrégation.
Avec stockage partagé
Le stockage partagé vous permet de lire et d'écrire des données intersites dans un environnement sécurisé pour éviter les fuites. De plus, l'API Private Aggregation vous permet de mesurer les données intersites stockées dans le stockage partagé.
Mesure de la Unique Reach
Vous voudrez peut-être mesurer le nombre d'utilisateurs uniques ayant consulté son contenu. L'API Private Aggregation peut fournir une réponse telle que "Environ 317 utilisateurs uniques ont vu le Content ID 861".
Vous pouvez définir un indicateur dans Shared Storage pour indiquer si l'utilisateur a déjà vu le contenu ou non. Lors de la première visite où l'indicateur n'existe pas, un appel à Private Aggregation est effectué, puis l'indicateur est défini. Lors des visites ultérieures de l'utilisateur, y compris des visites intersites, vous pouvez vérifier le stockage partagé et ignorer l'envoi d'un rapport à Private Aggregation si cet indicateur est défini. Pour en savoir plus sur les méthodes d'implémentation de ces mesures, consultez notre livre blanc sur la couverture.
Mesure des données démographiques
Vous pouvez mesurer les données démographiques des utilisateurs qui ont consulté votre contenu sur différents sites.
Private Aggregation peut fournir une réponse, par exemple "Environ 317 utilisateurs uniques de 18 à 45 ans proviennent d'Allemagne". Utilisez le stockage partagé pour accéder à des données démographiques provenant d'un contexte tiers. Vous pourrez ensuite générer un rapport avec l'agrégation privée en codant les dimensions de tranche d'âge et de pays dans la clé d'agrégation.
Mesure de la fréquence K+
Vous pouvez mesurer le nombre d'utilisateurs ayant vu un contenu ou une annonce au moins K fois dans un navigateur donné, pour une valeur présélectionnée de K.
L'agrégation privée peut fournir une réponse du type "Environ 89 utilisateurs ont vu l'ID de contenu 581 au moins trois fois". Un compteur peut être incrémenté dans Shared Storage à partir de différents sites et lu au sein d'un Worklet. Lorsque le nombre a atteint K, un rapport peut être envoyé via Private Aggregation.
Avec l'API Protected Audience
L'API Protected Audience permet de recibler des audiences personnalisées et de personnaliser les cas d'utilisation, tandis que Private Aggregation vous permet de créer des rapports sur les événements des Worklets d'acheteurs et de vendeurs. L'API peut servir, par exemple, à mesurer la distribution des enchères.
À partir d'un Worklet de l'API Protected Audience, vous pouvez agréger vos données directement à l'aide de contributeToHistogram()
et générer des rapports sur vos données en fonction d'un déclencheur à l'aide de contributeToHistogramOnEvent()
, qui est une extension spéciale pour l'API Protected Audience.
Fonctions disponibles
Les fonctions suivantes sont disponibles dans l'objet privateAggregation
disponible dans les Worklets de Shared Storage et de l'API Protected Audience.
contributeToHistogram()
Vous pouvez appeler privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
, où la clé d'agrégation est bucket
et la valeur agrégable en value
. Pour le paramètre bucket
, un BigInt
est requis. Pour le paramètre value
, vous devez saisir un nombre entier.
Voici un exemple d'appel dans Shared Storage pour la mesure de la couverture:
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await this.sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
L'exemple de code ci-dessus appelle Private Aggregation chaque fois que le contenu iFrame intersite est chargé. Le code iFrame charge le Worklet, qui appelle l'API Private Aggregation avec l'identifiant de contenu converti en clé d'agrégation (bucket).
contributeToHistogramOnEvent()
Dans les Worklets de l'API Protected Audience uniquement, nous fournissons un mécanisme basé sur des déclencheurs pour envoyer un rapport uniquement si un certain événement se produit. Cette fonction permet également au bucket et à la valeur de dépendre de signaux qui ne sont pas encore disponibles à ce stade de l'enchère.
La méthode privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
utilise un élément eventType
qui spécifie l'événement déclencheur et l'élément contribution
à envoyer lorsque l'événement est déclenché. L'événement déclencheur peut provenir de l'enchère elle-même après la fin de celle-ci (par exemple, une victoire ou une défaite) ou d'un frame cloisonné ayant diffusé l'annonce.
Pour envoyer un rapport sur les événements d'enchères, vous pouvez utiliser deux mots clés réservés : reserved.win
, reserved.loss
et reserved.always
. Pour envoyer un rapport déclenché par un événement dans un cadre cloisonné, définissez un type d'événement personnalisé. Pour déclencher l'événement à partir d'un frame cloisonné, utilisez la méthode fence.reportEvent()
disponible dans l'API Fenced Frames Ads Reporting.
L'exemple suivant envoie un rapport sur les impressions lorsque l'événement d'enchères remportées est déclenché, ainsi qu'un rapport sur les clics si un événement click
est déclenché à partir du frame cloisonné qui a diffusé l'annonce. Ces deux valeurs peuvent être utilisées pour calculer le taux de clics.
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
Pour en savoir plus, consultez la présentation de l'API Extended Private Aggregation Reporting.
enableDebugMode()
Bien que les cookies tiers soient toujours disponibles, nous fournirons un mécanisme temporaire qui facilitera le débogage et les tests en activant le mode débogage. Un rapport de débogage est utile pour comparer vos mesures basées sur les cookies à vos mesures Private Aggregation. Il vous permet également de valider rapidement votre intégration d'API.
L'appel de privateAggregation.enableDebugMode()
dans le Worklet active le mode débogage, ce qui entraîne l'inclusion de la charge utile non chiffrée (texte clair) dans les rapports agrégables. Vous pouvez ensuite traiter ces charges utiles avec l'outil de test local du service d'agrégation.
Le mode débogage n'est disponible que pour les appelants autorisés à accéder
aux cookies tiers. Si l'appelant n'a pas accès aux cookies tiers,
enableDebugMode()
échouera silencieusement. Cela signifie que lorsqu'un tiers
les cookies sont obsolètes
et le mode débogage ne sera plus disponible.
Vous pouvez également définir la clé de débogage en appelant privateAggregation.enableDebugMode({ <debugKey: debugKey> })
, où une BigInt
peut être utilisée comme clé de débogage. La clé de débogage peut être utilisée pour associer les données d'une mesure basée sur les cookies et celles provenant de la mesure Private Aggregation.
Ceux-ci ne peuvent être appelés qu'une seule fois par contexte. Tous les appels ultérieurs génèrent une exception.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Signaler la validation
Pour le stockage partagé, vous pouvez vérifier que les rapports agrégables que vous avez reçus sont légitimes en ajoutant un ID de contexte à l'appel d'opération de stockage partagé. L'ID est joint au rapport envoyé. Vous pourrez l'utiliser ultérieurement pour vérifier que le rapport a bien été envoyé depuis votre espace de stockage partagé.
Pour en savoir plus, consultez la présentation de la validation des rapports.
Interagir et partager des commentaires
L'API Private Aggregation est en cours de discussion et est susceptible d'être modifiée à l'avenir. Si vous essayez cette API et que vous avez des commentaires, n'hésitez pas à nous en faire part.
- GitHub: lisez l'explication, posez des questions et participez à la discussion.
- Assistance aux développeurs: posez des questions et participez à des discussions dans le dépôt de l'assistance aux développeurs Privacy Sandbox.
- Rejoignez le groupe de l'API Shared Storage et le groupe de l'API Protected Audience pour recevoir les dernières annonces sur Private Aggregation.