Attribution Reporting

Envoyer un commentaire

Dernières mises à jour

  • Mise à jour de la liste des modifications à venir et des problèmes connus.
  • Introduction d'une configuration flexible allégée au niveau des événements comme passerelle vers la configuration flexible complète au niveau des événements.
  • À partir de septembre 2023, registerWebSource, registerWebTrigger, registerAppSource et registerAppTrigger devront utiliser des chaînes pour les champs qui attendent une valeur numérique (comme priority, source_event_id, debug_key, trigger_data, deduplication_key, etc.).
  • Au 4e trimestre 2023, l'API Android Attribution Reporting sera ajouté à Google Cloud afin de générer des rapports récapitulatifs à l'aide du service d'agrégation de Google Cloud. Un calendrier plus spécifique est fourni ici. Pour en savoir plus sur la configuration du service d'agrégation avec Google Cloud, consultez le guide de déploiement.
  • Nouvelles limites de débit protégeant la confidentialité pour un certain nombre de destinations uniques.
  • Une nouvelle fonctionnalité pour les filtres déclencheurs de période d'analyse sera disponible au premier trimestre 2024.

Présentation

Aujourd'hui, les solutions d'attribution et de mesure sur mobile utilisent souvent des identifiants multipartites, tels que l'identifiant publicitaire. L'API Attribution Reporting est conçue pour améliorer la confidentialité des utilisateurs en supprimant la dépendance aux identifiants utilisateur multipartites, et pour prendre en charge des cas d'utilisation clés liés à l'attribution et à la mesure des conversions dans les applications et sur le Web.

Cette API dispose des mécanismes structurels suivants, qui offrent un framework permettant d'améliorer la confidentialité, que nous détaillerons plus loin sur cette page :

Les mécanismes ci-dessus limitent la possibilité d'associer l'identité des utilisateurs entre deux applications ou domaines différents.

L'API Attribution Reporting prend en charge les cas d'utilisation suivants :

  • Rapports sur les conversions : aidez les annonceurs à mesurer les performances de leurs campagnes en leur montrant le nombre de conversions (déclencheur) et les valeurs de conversion (déclencheur) en fonction de dimensions telles que la campagne, le groupe d'annonces et la création publicitaire.
  • Optimisation : fournissez des rapports sur les événements qui permettent d'optimiser les dépenses publicitaires, en fournissant des données d'attribution par impression pouvant servir à entraîner des modèles de ML.
  • Détection d'activité incorrecte : fournissez des rapports utilisables pour la détection et l'analyse du trafic incorrect et de la fraude publicitaire.

De manière générale, l'API Attribution Reporting fonctionne comme indiqué ci-dessous, et nous détaillerons ce fonctionnement plus loin dans cet article :

  1. La technologie publicitaire termine le processus d'enregistrement afin d'utiliser l'API Attribution Reporting.
  2. La technologie publicitaire enregistre les sources d'attribution (clics ou vues d'annonces) avec l'API Attribution Reporting.
  3. La technologie publicitaire enregistre les déclencheurs (conversions utilisateur dans l'application ou sur le site Web de l'annonceur) à l'aide de l'API Attribution Reporting.
  4. L'API Attribution Reporting établit une correspondance entre les déclencheurs et les sources d'attribution (une attribution de conversion), et un ou plusieurs déclencheurs sont envoyés depuis l'appareil via des rapports au niveau des événements et des rapports agrégables aux technologies publicitaires.

Obtenir l'accès aux API Attribution Reporting

Les plates-formes de technologie publicitaire doivent demander l'accès aux API Attribution Reporting. Pour en savoir plus, consultez la section Créer un compte Privacy Sandbox.

Enregistrer une source d'attribution (clic ou vue)

Dans l'API Attribution Reporting, les clics sur une annonce et les vues sont appelés sources d'attribution. Pour enregistrer un clic ou une vue d'annonce, appelez registerSource(). Cette API attend les paramètres suivants :

  • URI de la source d'attribution : la plate-forme envoie une requête à cet URI afin de récupérer les métadonnées associées à la source d'attribution.
  • Événement d'entrée : objet InputEvent (pour un événement de clic) ou null (pour un événement de vue).

Lorsque l'API envoie une requête à l'URI de la source d'attribution, la technologie publicitaire doit répondre avec les métadonnées de la source d'attribution dans un nouvel en-tête HTTP Attribution-Reporting-Register-Source, avec les champs suivants :

  • Source event ID (ID de l'événement source) : cette valeur représente les données au niveau des événements associées à cette source d'attribution (clic sur une annonce ou visionnage d'annonce). Il doit s'agir d'un entier non signé de 64 bits au format chaîne.
  • Destination : eTLD+1 ou nom du package de l'application d'une origine où l'événement déclencheur se produit.
  • Expiry (Expiration, facultatif) : expiration, en secondes, pour la suppression de la source de l'appareil. La valeur par défaut est de 30 jours, avec une valeur minimale de 1 jour et une valeur maximale de 30 jours. Cette valeur est arrondie au jour le plus proche. Peut prendre la forme d'une chaîne ou d'un entier non signé de 64 bits.
  • Event report window (Fenêtre de création des rapports sur les événements, facultatif) : durée pendant laquelle les rapports sur les événements peuvent être créés pour cette source, en secondes après l'enregistrement de la source. Si la fenêtre de création des rapports sur les événements est passée, mais que l'expiration ne l'est pas encore, un déclencheur peut toujours être mis en correspondance avec une source, mais aucun rapport d'événement n'est envoyé pour ce déclencheur. Ne peut pas dépasser la valeur "Expiry" (Expiration). Peut prendre la forme d'une chaîne ou d'un entier non signé de 64 bits.
  • Aggregatable report window (Fenêtre de création des rapports agrégables, facultatif) : durée pendant laquelle les rapports agrégables peuvent être créés pour cette source, en secondes après l'enregistrement de la source. Ne peut pas dépasser la valeur "Expiry" (Expiration). Peut prendre la forme d'une chaîne ou d'un entier non signé de 64 bits.
  • Source priority (Priorité de la source, facultatif) : utilisé pour sélectionner la source d'attribution à laquelle un déclencheur doit être associé, au cas où plusieurs sources d'attribution pourraient lui être associées. Il doit s'agir d'un entier signé de 64 bits au format chaîne.

    Lorsqu'un déclencheur est reçu, l'API trouve la source d'attribution correspondante avec la valeur de priorité source la plus élevée et génère un rapport. Chaque plate-forme de technologie publicitaire peut définir sa propre stratégie de priorisation. Pour en savoir plus sur l'impact de la priorité sur l'attribution, consultez la section Exemple de priorisation.

    Plus la valeur est élevée, plus les priorités sont élevées.
  • Install and post-install attribution windows (Fenêtres d'attribution pendant et après l'installation, facultatif) : permet de déterminer l'attribution pour les événements post-installation, décrits plus loin sur cette page.
  • Filter data (Filtrer les donnée, facultatif) : permet de filtrer de manière sélective certains déclencheurs, en les ignorant. Pour en savoir plus, consultez la section Filtres de déclencheurs de cette page.
  • Clés d'agrégation (facultatif) : spécifiez la segmentation à utiliser pour les rapports agrégables.

La réponse aux métadonnées de la source d'attribution peut éventuellement inclure des données supplémentaires dans l'en-tête Redirections des rapports d'attribution. Les données contiennent des URL de redirection, qui permettent à plusieurs technologies publicitaires d'enregistrer une demande.

Le guide du développeur comprend des exemples qui montrent comment accepter l'enregistrement de la source.

Les étapes suivantes sont un exemple de workflow :

  1. Le SDK de technologie publicitaire appelle l'API pour lancer l'enregistrement de la source d'attribution, en spécifiant un URI que l'API doit appeler :

    registerSource(
        Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
        myClickEvent);
    
  2. L'API envoie une requête à https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA, en utilisant l'un des en-têtes suivants :

    <!-- For click events -->
    Attribution-Reporting-Source-Info: navigation
    
    <!-- For view events -->
    Attribution-Reporting-Source-Info: event
    
  3. Le serveur HTTPS de cette de technologie publicitaire répond avec des en-têtes contenant les éléments suivants :

    Attribution-Reporting-Register-Source: {
        "destination": "android-app://com.advertiser.example",
        "source_event_id": "234",
        "expiry": "60000",
        "priority": "5"
    }
    Attribution-Reporting-Redirect:
    https://adtechpartner1.example?their_ad_click_id=567
    Attribution-Reporting-Redirect:
    https://adtechpartner2.example?their_ad_click_id=890
    
  4. L'API envoie une requête à chaque URL spécifiée dans Attribution-Reporting-Redirect. Dans cet exemple, deux URL de partenaires de technologie publicitaire sont spécifiées. L'API envoie donc une requête à https://adtechpartner1.example?their_ad_click_id=567 et une autre à https://adtechpartner2.example?their_ad_click_id=890.

  5. Le serveur HTTPS de cette de technologie publicitaire répond avec des en-têtes contenant les éléments suivants :

    Attribution-Reporting-Register-Source: {
        "destination": "android-app://com.advertiser.example",
        "source_event_id": "789",
        "expiry": "120000",
        "priority": "2"
    }
    

Trois sources d'attribution de navigation (clic) sont enregistrées en fonction des requêtes présentées aux étapes précédentes.

Enregistrer une source d'attribution depuis WebView

WebView est compatible avec les cas où une application affiche une annonce dans un composant WebView. Cette situation est gérée par WebView, qui appelle directement registerSource() en tant que requête d'arrière-plan. Cet appel associe la source d'attribution à l'appli au lieu de l'origine de niveau supérieur. L'enregistrement de sources à partir d'un contenu Web intégré dans un contexte de navigateur est également pris en charge. Les appelants d'API et les applis doivent ajuster les paramètres pour y parvenir. Consultez Enregistrer la source d'attribution et le déclencheur depuis WebView pour obtenir des instructions pour les appelants d'API, et Enregistrer la source d'attribution et le déclencheur depuis WebView pour obtenir des instructions pour les applications.

Étant donné que les technologies publicitaires utilisent du code commun sur le Web et WebView, WebView suit les redirections HTTP 302 et transmet les enregistrements valides à la plate-forme. Nous ne prévoyons pas de prendre en charge l'en-tête Attribution-Reporting-Redirect pour ce scénario, mais contactez-nous si votre cas d'utilisation est concerné.

Enregistrer un déclencheur (conversion)

Les plates-formes de technologie publicitaire peuvent enregistrer des déclencheurs (des conversions telles que des événements d'installation ou post-installation) à l'aide de la méthode registerTrigger().

La méthode registerTrigger() attend le paramètre URI de déclenchement. L'API envoie une requête à cet URI pour récupérer les métadonnées associées au déclencheur.

L'API suit les redirections. La réponse du serveur de technologie publicitaire doit inclure un en-tête HTTP appelé Attribution-Reporting-Register-Trigger, qui représente des informations sur un ou plusieurs déclencheurs enregistrés. Le contenu de l'en-tête doit être encodé en JSON et inclure les champs suivants :

  • Trigger data (Données du déclencheur) : données permettant d'identifier l'événement déclencheur (3 bits pour les clics, 1 bit pour les vues). Il doit s'agir d'un entier signé de 64 bits au format chaîne.
  • Trigger priority (Priorité du déclencheur, facultatif) : représente la priorité de ce déclencheur par rapport aux autres déclencheurs de la même source d'attribution. Il doit s'agir d'un entier signé de 64 bits au format chaîne. Pour en savoir plus sur l'impact de la priorité sur les rapports, consultez la section Exemple de priorisation.
  • Deduplication key (Clé de déduplication, facultatif) : permet d'identifier les cas où le même déclencheur est enregistré plusieurs fois par la même plate-forme de technologie publicitaire, pour la même source d'attribution. Il doit s'agir d'un entier signé de 64 bits au format chaîne.
  • Aggregation keys (Clés d'agrégation, facultatif) : liste de dictionnaires spécifiant les clés d'agrégation et valeurs pouvant être agrégées dans les rapports agrégables.
  • Valeurs d'agrégation (facultatif) : liste des montants de valeur qui contribuent à chaque clé.
  • Filtres (facultatif) : permet de filtrer de manière sélective des déclencheurs ou des données. Pour en savoir plus, consultez la section Filtres de déclencheurs de cette page.

La réponse du serveur de technologie publicitaire peut éventuellement inclure des données supplémentaires dans l'en-tête Redirections des rapports d'attribution. Les données contiennent des URL de redirection, qui permettent à plusieurs technologies publicitaires d'enregistrer une demande.

Plusieurs technologies publicitaires peuvent enregistrer le même événement déclencheur à l'aide de redirections dans le champ Attribution-Reporting-Redirect ou de plusieurs appels à la méthode registerTrigger(). Nous vous recommandons d'utiliser le champ clé de déduplication afin d'éviter d'inclure des déclencheurs en double dans les rapports au cas où une même technologie publicitaire fournit plusieurs réponses pour le même événement déclencheur. Découvrez quand et comment utiliser une clé de déduplication.

Le guide du développeur comprend des exemples qui montrent comment accepter l'enregistrement des déclencheurs.

Les étapes suivantes sont un exemple de workflow :

  1. Le SDK de technologie publicitaire appelle l'API pour lancer l'enregistrement du déclencheur à l'aide d'un URI préenregistré. Pour en savoir plus, consultez la section Créer un compte Privacy Sandbox.

    registerTrigger(
        Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
    
  2. L'API envoie une requête à https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA.

  3. Le serveur HTTPS de cette de technologie publicitaire répond avec des en-têtes contenant les éléments suivants :

    Attribution-Reporting-Register-Trigger: {
        "event_trigger_data": [{
        "trigger_data": "1122",
        // This returns 010 for click-through conversions (CTCs) and 0 for
        // view-through conversions (VTCs) in reports
        "priority": "3",
        "deduplication_key": "3344"
        }],
    }
    Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567
    
  4. L'API envoie une requête à chaque URL spécifiée dans Attribution-Reporting-Redirect. Dans cet exemple, une seule URL est spécifiée. L'API envoie donc une requête à https://adtechpartner.example?app_install=567.

  5. Le serveur HTTPS de cette de technologie publicitaire répond avec des en-têtes contenant les éléments suivants :

    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data":[{
      "trigger_data": "5566",
      "priority": "3",
      "deduplication_key": "3344"
    }]
    }
    

    Deux déclencheurs sont enregistrés en fonction des requêtes des étapes précédentes.

Fonctionnalités d'Attribution

Les sections suivantes expliquent comment l'API Attribution Reporting met en correspondance les déclencheurs de conversion et les sources d'attribution.

Algorithme d'attribution selon la source appliqué

L'API Attribution Reporting utilise un algorithme d'attribution basé sur la source pour associer un déclencheur (conversion) à une source d'attribution.

Les paramètres de priorité permettent de personnaliser l'attribution des déclencheurs aux sources :

  • Vous pouvez attribuer des déclencheurs à certains événements d'annonce plutôt qu'à d'autres. Par exemple, vous pouvez choisir de privilégier les clics plutôt que sur les vues, ou de vous concentrer sur les événements de certaines campagnes.
  • Vous pouvez configurer la source d'attribution et le déclencher de sorte que, si vous atteignez les limites de débit, vous soyez plus susceptible de recevoir les rapports les plus importants pour vous. Par exemple, vous souhaiterez peut-être vous assurer que les conversions enchérissables ou les conversions à forte valeur sont plus susceptibles d'apparaître dans ces rapports.

Lorsque plusieurs technologies publicitaires enregistrent une source d'attribution, comme décrit plus loin sur cette page, cette attribution est effectuée indépendamment pour chaque technologie publicitaire. Pour chacune d'elles, la source d'attribution ayant la priorité la plus élevée est attribuée à l'événement déclencheur. Si plusieurs sources d'attribution ont la même priorité, l'API sélectionne la dernière source d'attribution enregistrée. Toutes les autres sources d'attribution non sélectionnées sont supprimées et ne sont plus éligibles pour l'attribution de déclencheurs.

Filtres des déclencheurs

L'enregistrement de la source et du déclencheur inclut des fonctionnalités facultatives supplémentaires permettant de :

  • filtrer de manière sélective certains déclencheurs, en les ignorant de manière efficace ;
  • choisir les données de déclenchement pour les rapports au niveau des événements en fonction des données sources ;
  • choisir d'exclure un déclencheur des rapports au niveau des événements.

Pour filtrer de façon sélective les déclencheurs, la technologie publicitaire peut spécifier des données de filtre, composées de clés et de valeurs, lors de l'enregistrement de la source et des déclencheurs. Si la même clé est spécifiée à la fois pour la source et le déclencheur, le déclencheur est ignoré si l'intersection est vide. Par exemple, une source peut spécifier "product": ["1234"], où product est la clé de filtre et 1234 la valeur. Si le filtre de déclencheur est défini sur "product": ["1111"], le déclencheur est ignoré. Si aucune clé de filtre de déclencheur ne correspond à product, les filtres sont ignorés.

Les plates-formes de technologie publicitaire sont également susceptibles de vouloir filtrer de manière sélective les déclencheurs lorsqu'une période d'expiration plus courte est soumise. Lors de l'enregistrement du déclencheur, une technologie publicitaire peut définir une période d'analyse (en secondes) à partir du moment où la conversion s'est produite. Par exemple, une période d'analyse de 7 jours est définie comme suit : "_lookback_window": 604800 // 7d

Pour déterminer si un filtre correspond, l'API vérifie d'abord la période d'analyse. Le cas échéant, la durée qui s'est écoulée depuis l'enregistrement de la source doit être inférieure ou égale à la durée de la période d'analyse.

Les plates-formes de technologies publicitaires peuvent également choisir des données de déclenchement en fonction des données d'événements sources. Par exemple, source_type est automatiquement généré par l'API sous la forme navigation ou event. Lors de l'enregistrement du déclencheur, trigger_data peut être défini comme une valeur pour "source_type": ["navigation"] et comme une valeur différente pour "source_type": ["event"].

Les déclencheurs sont exclus des rapports au niveau des événements si l'une des conditions suivantes est remplie :

  • Aucune trigger_data n'est spécifiée.
  • La source et le déclencheur spécifient la même clé de filtre, mais les valeurs ne correspondent pas. Notez que, dans ce cas, le déclencheur est ignoré pour les rapports au niveau des événements et pour les rapports agrégables.

Attribution après installation

Dans certains cas, il est nécessaire que les déclencheurs post-installation soient attribués à la même source d'attribution qui a généré l'installation, même si d'autres sources d'attribution éligibles sont plus récentes.

L'API peut répondre à ce cas d'utilisation en permettant aux technologies publicitaires de définir une période d'attribution post-installation :

  • Lorsque vous enregistrez une source d'attribution, spécifiez une période d'attribution pour les installations au cours de laquelle les installations sont attendues (généralement entre 2 et 7 jours, plage acceptée de 1 à 30 jours). Spécifiez cette fenêtre temporelle en nombre de secondes.
  • Lorsque vous enregistrez une source d'attribution, spécifiez une période d'exclusivité post-installation où tous les événements déclencheurs doivent être associés à la source qui a généré l'installation (en général, entre 7 et 30 jours, plage acceptée de 0 à 30 jours). Spécifiez cette fenêtre temporelle en nombre de secondes.
  • L'API Attribution Reporting valide l'installation d'une application et l'attribue en interne à la source d'attribution ayant la priorité en fonction de sa source. Cependant, l'installation n'est pas envoyée aux technologies publicitaires et ne compte pas dans les limites de débit respectives des plates-formes.
  • La validation des installations d'applis est disponible pour toutes les applications téléchargées.
  • Tous les déclencheurs ultérieurs qui se produisent au cours de la période d'attribution post-installation sont attribués à la même source d'attribution que l'installation validée, à condition que cette source d'attribution soit éligible.

À l'avenir, nous pourrions envisager d'étendre la conception à des modèles d'attribution plus avancés.

Le tableau suivant montre comment les technologies publicitaires peuvent utiliser l'attribution post-installation. Supposons que toutes les sources et tous les déclencheurs d'attribution soient enregistrés par le même réseau publicitaire, et que toutes les priorités soient identiques.

Événement Jour de l'événement Notes
Clic 1 1 install_attribution_window est définie sur 172800 (2 jours) post_install_exclusivity_window est définie sur864000 (10 jours)
Installation validée 2 L'API attribue des installations validées en interne, mais elles ne sont pas considérées comme des déclencheurs. Par conséquent, aucun rapport n'est envoyé à ce stade.
Déclencheur 1 (première ouverture) 2 Premier déclencheur enregistré par la technologie publicitaire. Dans cet exemple, il s'agit d'une première ouverture, mais il peut s'agir de n'importe quel type de déclencheur.
Attribué au clic 1 (correspond à l'attribution de l'installation validée).
Clic 2 4 Utilise les mêmes valeurs pour install_attribution_window et post_install_exclusivity_window que Clic 1.
Déclencheur 2 (après installation) 5 Deuxième déclencheur enregistré par la technologie publicitaire. Dans cet exemple, il représente une conversion post-installation tel qu'un achat.
Attribué au clic 1 (correspond à l'attribution de l'installation validée).
Le clic 2 est supprimé et ne sera plus éligible pour une attribution ultérieure.

La liste suivante fournit des remarques supplémentaires sur l'attribution post-installation :

  • Si l'installation validée ne se produit pas dans le délai spécifié par install_attribution_window, l'attribution post-installation n'est pas appliquée.
  • Les installations validées ne sont pas enregistrées par les technologies publicitaires et ne sont pas envoyées dans les rapports. Elles ne sont pas comptabilisées dans les limites de débit d'une technologie publicitaire. Les installations validées ne sont utilisées que pour identifier la source d'attribution à laquelle attribuer l'installation.
  • Dans l'exemple du tableau précédent, le déclencheur 1 et le déclencheur 2 représentent respectivement une première ouverture et une conversion post-installation. Cependant, les plates-formes de technologie publicitaire peuvent enregistrer tout type de déclencheur. En d'autres termes, le premier déclencheur ne doit pas nécessairement être un déclencheur de première ouverture.
  • Si plus de déclencheurs sont enregistrés après l'expiration de post_install_exclusivity_window, le clic 1 peut toujours être attribué, à condition qu'il n'ait pas expiré et qu'il n'ait pas atteint ses limites de débit.
    • Si une source d'attribution de priorité supérieure est enregistrée, le clic 1 risque d'être perdu ou d'être supprimé.
  • Si l'application de l'annonceur est désinstallée puis réinstallée, la réinstallation est comptabilisée comme une nouvelle installation validée.
  • Si le clic 1 était un événement de vue, les déclencheurs "première ouverture" et "post-installation" lui sont toujours attribués. L'API limite l'attribution à un déclencheur par vue, sauf dans le cas de l'attribution post-installation, où un maximum de deux déclencheurs par vue est autorisé. Dans le cas de l'attribution post-installation, la technologie publicitaire peut recevoir deux périodes de référence différentes (à deux jours ou à l'expiration de la source).

Toutes les combinaisons de chemins de déclenchement basés sur l'application et sur le Web sont prises en charge

L'API Attribution Reporting permet d'attribuer les chemins de déclenchement suivants sur un seul appareil Android :

  • Application/application : l'utilisateur voit une annonce dans une application, puis effectue la conversion dans cette application ou dans une autre application installée.
  • Application/Web : l'utilisateur voit une annonce dans une application, puis effectue une conversion dans un navigateur mobile ou d'application.
  • Web vers l'application : l'utilisateur voit une annonce dans un navigateur mobile ou d'application, puis effectue une conversion dans une application.
  • Web vers le Web : l'utilisateur voit une annonce dans un navigateur mobile ou d'application, puis effectue une conversion dans le même navigateur ou dans un autre navigateur sur le même appareil.

Nous autorisons les navigateurs Web à accepter de nouvelles fonctionnalités exposées sur le Web, telles que la fonctionnalité semblable à la Privacy Sandbox pour l'API Attribution Reporting sur le Web, qui peut appeler les API Android pour activer l'attribution dans l'application et sur le Web.

Découvrez les modifications que les technologies publicitaires et les applications doivent apporter afin de prendre en charge les chemins de déclenchement pour les mesures multiapplications et Web.

Donner la priorité à plusieurs déclencheurs pour une seule source d'attribution

Une même source d'attribution peut générer plusieurs déclencheurs. Par exemple, un parcours d'achat peut impliquer un déclencheur "installation d'une application", un ou plusieurs déclencheurs "ajouter au panier", et un déclencheur "acheter". Chaque déclencheur est attribué à une ou plusieurs sources d'attribution, conformément à l'algorithme d'attribution selon le niveau de priorité des sources, décrit plus loin sur cette page.

Il existe des limites quant au nombre de déclencheurs pouvant être attribué à une seule source d'attribution. Pour en savoir plus, consultez la section sur l'affichage des données de mesure dans les rapports sur l'attribution plus loin sur cette page. Dans les cas où plusieurs déclencheurs dépassent ces limites, il est utile d'introduire une logique de priorisation pour récupérer les déclencheurs les plus intéressants. Par exemple, les développeurs d'une technologie publicitaire peuvent souhaiter privilégier les déclencheurs "acheter" par rapport à ceux "ajouter au panier".

Pour appliquer cette logique, vous pouvez définir un champ de priorité distinct sur le déclencheur, et les déclencheurs de priorité les plus élevés sont sélectionnés avant l'application des limites, dans une fenêtre de rapport donnée.

Autoriser plusieurs technologies publicitaires à enregistrer des sources d'attribution ou des déclencheurs

Il est courant que plusieurs technologies publicitaires reçoivent des rapports sur l'attribution, généralement pour effectuer une déduplication multiréseau. Par conséquent, l'API permet à plusieurs technologies publicitaires d'enregistrer la même source d'attribution ou le même déclencheur. Une technologie publicitaire doit enregistrer à la fois des sources d'attribution et des déclencheurs pour recevoir des postbacks de l'API. L'attribution s'effectue entre les sources d'attribution et les déclencheurs que la technologie publicitaire a enregistrés auprès de l'API.

Les annonceurs qui souhaitent faire appel à un tiers pour effectuer une déduplication multiréseau peuvent continuer à le faire en utilisant une technique semblable à celle-ci :

  • Configurer un serveur interne pour enregistrer et recevoir les rapports de l'API.
  • Continuer à utiliser un partenaire de mesure existant pour mobile.

Sources d'attribution

Les redirections de source d'attribution sont prises en charge par la méthode registerSource() :

  1. La technologie publicitaire qui appelle la méthode registerSource() peut fournir un champ Attribution-Reporting-Redirect supplémentaire dans sa réponse, qui représente l'ensemble des URL de redirection de la technologie publicitaire partenaire.
  2. L'API appelle ensuite les URL de redirection pour que la source d'attribution puisse être enregistrée par les technologies publicitaires partenaires.

Plusieurs URL de technologies publicitaires partenaires peuvent être indiquées dans le champ Attribution-Reporting-Redirect, mais les technologies publicitaires partenaires ne peuvent pas spécifier leur propre champ Attribution-Reporting-Redirect.

L'API autorise également différentes technologies publicitaires pour chaque appel registerSource().

Déclencheurs

Pour l'enregistrement d'un déclencheur, les tiers sont compatibles de la même manière : les technologies publicitaires peuvent soit utiliser le champ supplémentaire Attribution-Reporting-Redirect, soit appeler la méthode registerTrigger().

Lorsqu'un annonceur utilise plusieurs technologies publicitaires pour enregistrer le même événement déclencheur, une clé de déduplication doit être utilisée. La clé de déduplication permet de distinguer les rapports répétés du même événement enregistré par la même plate-forme de technologie publicitaire. Par exemple, une technologie publicitaire peut avoir son SDK qui appelle directement l'API pour enregistrer un déclencheur et obtenir son URL dans le champ de redirection de l'appel d'une autre technologie publicitaire. Si aucune clé de déduplication n'est fournie, les déclencheurs en double peuvent être signalés à chaque technologie publicitaire comme uniques.

Gérer les déclencheurs en double

Une technologie publicitaire peut enregistrer plusieurs fois le même déclencheur avec l'API. Voici des scénarios possibles :

  • L'utilisateur effectue la même action (déclencher) plusieurs fois. Par exemple, l'utilisateur parcourt le même produit plusieurs fois dans la même période de référence.
  • L'application de l'annonceur utilise plusieurs SDK pour mesurer les conversions. Ils redirigent tous vers la même technologie publicitaire. Par exemple, l'application de l'annonceur fait appel à deux partenaires de mesure : MMP n° 1 et MMP n° 2. Ces deux MMP redirigent vers la technologie publicitaire n° 3. Lorsqu'un déclencheur intervient, les deux MMP l'enregistrent avec l'API Attribution Reporting. La technologie publicitaire n° 3 reçoit ensuite deux redirections distinctes, une de MMP n° 1 et une autre de MMP n° 2, pour le même déclencheur.

Dans ce cas, il existe plusieurs façons de supprimer les rapports au niveau des événements pour les déclencheurs en double afin d'éviter de dépasser les limites de débit appliquées aux rapports au niveau des événements. La méthode recommandée consiste à utiliser une clé de déduplication.

Méthode recommandée : la clé de déduplication

La méthode recommandée est que l'application de l'annonceur transmette une clé de déduplication unique à toutes les technologies publicitaires ou aux SDK qu'elle utilise pour mesurer les conversions. Lorsqu'une conversion se produit, l'application transmet une clé de déduplication aux technologies publicitaires ou aux SDK. Ces technologies publicitaires ou SDK continuent ensuite à transmettre la clé de déduplication aux redirections à l'aide d'un paramètre des URL spécifiées dans Attribution-Reporting-Redirect.

Les technologies publicitaires peuvent choisir d'enregistrer uniquement le premier déclencheur avec une clé de déduplication donnée, ou d'enregistrer plusieurs déclencheurs ou tous les déclencheurs. Les technologies publicitaires peuvent spécifier la deduplication_key lors de l'enregistrement des déclencheurs en double.

Si une technologie publicitaire enregistre plusieurs déclencheurs avec la même clé de déduplication et la même source attribuée, seul le premier déclencheur enregistré est envoyé dans les rapports au niveau des événements. Les déclencheurs en double sont toujours envoyés dans des rapports agrégables chiffrés.

Méthode alternative : les technologies publicitaires conviennent des types de déclencheurs par annonceur

Dans les cas où les technologies publicitaires ne souhaitent pas utiliser la clé de déduplication, ou lorsque l'application de l'annonceur ne peut pas transmettre une clé de déduplication, une autre option existe. Toutes les technologies publicitaires qui mesurent les conversions pour un annonceur donné doivent collaborer pour définir différents types de déclencheurs pour chaque annonceur.

Les technologies publicitaires qui initient l'appel d'enregistrement du déclencheur, par exemple les SDK, incluent un paramètre dans les URL spécifiées dans Attribution-Reporting-Redirect, tel que duplicate_trigger_id. Ce paramètre duplicate_trigger_id peut inclure des informations telles que le nom du SDK et le type de déclencheur pour cet annonceur. Les technologies publicitaires peuvent ensuite envoyer un sous-ensemble de ces déclencheurs en double aux rapports au niveau des événements. Elles peuvent également inclure ce duplicate_trigger_id dans leurs clés d'agrégation.

Exemple d'attribution multiréseau

Dans l'exemple décrit dans cette section, l'annonceur utilise deux plates-formes de technologie publicitaire (technologie publicitaire A et technologie publicitaire B) et un partenaire de mesure (MMP).

Pour commencer, la technologie publicitaire A, la technologie publicitaire B et le MMP doivent terminer chaque enregistrement pour utiliser l'API Attribution Reporting. Pour en savoir plus, consultez la section Créer un compte Privacy Sandbox.

La liste suivante fournit une série hypothétique d'actions utilisateur qui s'exécutent à un jour d'intervalle, et explique comment l'API Attribution Reporting gère ces actions pour la technologie publicitaire A, la technologie publicitaire B et le MMP :

Jour 1 : l'internaute clique sur une annonce diffusée par la technologie publicitaire A

La technologie publicitaire A appelle registerSource() avec son URI. L'API envoie une requête à l'URI, et le clic est enregistré avec les métadonnées de la réponse du serveur de la technologie publicitaire A.

La technologie publicitaire A inclut également l'URI du MMP dans l'en-tête Attribution-Reporting-Redirect. L'API envoie une requête à l'URI de MMP, et le clic est enregistré avec les métadonnées de la réponse du serveur du MMP.

Jour 2 : l'internaute clique sur une annonce diffusée par la technologie publicitaire B

La technologie publicitaire B appelle registerSource() avec son URI. L'API envoie une requête à l'URI, et le clic est enregistré avec les métadonnées de la réponse du serveur de la technologie publicitaire B.

Tout comme la technologie publicitaire A, la technologie publicitaire B a également inclus l'URI du MMP dans l'en-tête Attribution-Reporting-Redirect. L'API envoie une requête à l'URI du MMP, et le clic est enregistré avec les métadonnées de la réponse du serveur du MMP.

Jour 3 : l'utilisateur voit une annonce diffusée par la technologie publicitaire A

L'API répond de la même manière que le jour 1, à la différence qu'une vue est enregistrée pour la technologie publicitaire A et pour le MMP.

Jour 4 : l'utilisateur installe l'application, qui utilise le MMP pour mesurer les conversions.

Le MMP appelle registerTrigger() avec son URI. L'API envoie une requête à l'URL, et la conversion est enregistrée avec les métadonnées de la réponse du serveur du MMP.

Le MMP inclut également les URI de la technologie publicitaire A et de la technologie publicitaire B dans l'en-tête Attribution-Reporting-Redirect. L'API envoie des requêtes aux serveurs de la technologie publicitaire A et de la technologie publicitaire B, et la conversion est enregistrée en conséquence avec les métadonnées des réponses du serveur.

La figure 1 illustre le processus décrit dans la liste précédente :

Figure 1. Exemple de la manière dont l'API Attribution Reporting répond à une série d'actions utilisateur.

L'attribution fonctionne comme suit :

  • La technologie publicitaire A définit la priorité des clics comme étant plus élevée que celle des vues, et obtient donc l'installation attribuée au clic le jour 1.
  • L'installation est attribuée à la technologie publicitaire B le jour 2.
  • Le MMP définit la priorité des clics comme étant plus élevée que celle des vues, et obtient donc l'installation attribuée au clic le jour 2. Le clic du 2e jour est l'événement publicitaire le plus récent, dont la priorité est la plus élevée.

Attribution multiréseau sans redirections

Bien que nous vous recommandions d'utiliser des redirections pour permettre à plusieurs technologies publicitaires d'enregistrer des sources et des déclencheurs d'attribution, nous sommes conscient que cela n'est pas toujours possible. Cette section explique en détail comment permettre l'attribution multiréseau sans redirection.

Étapes clés

  1. Lors de l'enregistrement des sources, le réseau ad tech de diffusion partage les clés d'agrégation correspondantes.
  2. Lors de l'enregistrement du déclencheur, l'annonceur ou le partenaire de mesure choisit les éléments de clé côté source à utiliser et spécifie sa configuration d'attribution.
  3. L'attribution est basée sur la configuration d'attribution, les clés partagées et toutes les sources qui ont été enregistrées par cet annonceur ou ce partenaire de mesure (par exemple, un autre réseau ad tech de diffusion ayant activé les redirections).
  4. Si le déclencheur est attribué à une source provenant d'une technologie publicitaire sans redirection, l'annonceur ou le partenaire de mesure peut recevoir un rapport agrégable qui combine la source et les éléments clés du déclencheur définis à l'étape 2.

Enregistrement de la source

Lors de l'enregistrement de la source, le réseau ad tech de diffusion peut choisir de partager les clés d'agrégation correspondantes ou un sous-ensemble de clés d'agrégation de la source plutôt que de les rediriger. La technologie ad tech de diffusion n'est pas obligée d'utiliser ces clés dans ses propres rapports agrégés et peut les déclarer uniquement pour le compte de l'annonceur ou du partenaire de mesure si nécessaire.

Les clés d'agrégation partagées sont accessibles à toute technologie publicitaire qui enregistre un déclencheur pour le même annonceur. Toutefois, il revient à la technologie publicitaire de diffusion et à la technologie publicitaire de mesure des déclencheurs de collaborer sur les types de clés d'agrégation nécessaires, leur nom et la façon de décoder ces clés en dimensions lisibles.

Enregistrement du déclencheur

Lors de l'enregistrement du déclencheur, la technologie publicitaire de mesure choisit les éléments de clé côté source à appliquer à chaque élément de clé du déclencheur, y compris les éléments partagés par les technologies publicitaires de diffusion.

En outre, elle doit également spécifier leur logique d'attribution en cascade via un nouvel appel d'API de configuration d'attribution. Dans cette configuration, la technologie publicitaire peut spécifier la priorité, l'expiration et les filtres des sources pour lesquelles elle n'avait pas de visibilité (par exemple, les sources qui n'utilisaient pas de redirection).

Attribution

L'API Attribution Reporting effectue l'attribution basée sur la priorité de la source et le dernier contact pour la technologie publicitaire de mesure en fonction de la configuration de l'attribution, de ses clés partagées et de toutes les sources enregistrées. Par exemple :

  • L'utilisateur a cliqué sur des annonces diffusées par les technologies publicitaires A, B, C et D. Il a ensuite installé l'application de l'annonceur, qui utilise un partenaire de technologie publicitaire de mesure (MMP).
  • La technologie publicitaire A redirige ses sources vers ce MMP.
  • Les technologies publicitaires B et C ne redirigent pas leurs sources, mais partagent leurs clés d'agrégation.
  • La technologie publicitaire D ne redirige pas ses sources et ne partage pas les clés d'agrégation.

Le MMP enregistre une source à partir de la technologie publicitaire A et définit une configuration d'attribution qui inclut les technologies publicitaires B et D.

L'attribution pour le MMP comprend désormais les éléments suivants :

  • La technologie publicitaire A, car le MMP a enregistré une source à partir de la redirection de cette technologie publicitaire
  • La technologie publicitaire B, étant donné qu'elle a partagé des clés et que le MMP l'a incluse dans sa configuration d'attribution

L'attribution pour le MMP n'inclut pas les éléments suivants :

  • La technologie publicitaire C, car le MMP ne l'a pas incluse dans sa configuration d'attribution
  • La technologie publicitaire D, car elle n'a pas redirigé les sources ni partagé de clés d'agrégation

Débogage

Afin de prendre en charge le débogage de l'attribution multiréseau sans redirections, les technologies publicitaires peuvent définir un champ supplémentaire (shared_debug_key) lors de l'enregistrement de la source. Si celles-ci sont définies sur l'enregistrement de la source d'origine, elles seront également définies sur debug_key, sur la source dérivée correspondante lors de l'enregistrement du déclencheur pour l'attribution multiréseau sans redirections. Cette clé de débogage est associée en tant que source_debug_key dans les rapports d'événement et agrégables.

Cette fonctionnalité de débogage ne sera compatible avec l'attribution multiréseau sans redirection que dans les cas suivants :

  • Mesure d'une appli à l'autre, pour lesquelles l'identifiant publicitaire est autorisé
  • Mesure appli/Web où l'identifiant publicitaire est autorisé et mis en correspondance à la fois au niveau de la source de l'appli et du déclencheur Web
  • Mesure Web/Web (sur la même appli de navigateur) lorsque ar_debug est présent à la fois sur la source et sur le déclencheur

Découverte de clés pour l'attribution multiréseau sans redirections

La découverte de clés vise à simplifier la façon dont les technologies publicitaires (généralement des MMP) mettent en œuvre leur configuration d'attribution à des fins d'attribution multiréseau lorsqu'une ou plusieurs technologies publicitaires de diffusion utilisent des clés d'agrégation partagées (comme décrit dans la section [Attribution multiréseau sans redirections][45] ci-dessus).

Lorsqu'un MMP interroge le service d'agrégation pour générer des rapports récapitulatifs sur des campagnes qui incluent des sources dérivées, il doit spécifier la liste des clés possibles en entrée de la tâche d'agrégation. Dans certains cas, la liste des clés d'agrégation sources potentielles peut être très longue ou indéterminée. Les longues listes de clés possibles sont difficiles à suivre et sont généralement complexes et coûteuses à traiter. Exemples :

  • La liste de toutes les clés possibles est longue :
    • Un réseau publicitaire de diffusion exécute une initiative d'acquisition d'utilisateurs complexe qui comprend 20 campagnes, chacune avec 10 groupes d'annonces, et chaque groupe d'annonces avec cinq créations actualisées chaque semaine en fonction des performances.
  • La liste de toutes les clés possibles est indéterminée :
    • Un réseau publicitaire de diffusion diffuse des annonces sur de nombreuses applications mobiles, où la liste complète des ID d'applications d'éditeurs n'est pas connue au lancement de la campagne.
    • Un annonceur travaille sur plusieurs réseaux publicitaires de diffusion qui ne redirigent pas vers le MMP lors de l'enregistrement de la source. Chaque réseau publicitaire de diffusion présente une structure et des valeurs de clé différentes, qui ne peuvent pas être partagées à l'avance avec le MMP.

Avec l'introduction de la découverte de clés :

  • Le service d'agrégation ne nécessite plus une énumération complète des clés d'agrégation possibles.
  • Au lieu de spécifier la liste complète des clés possibles, un MMP peut créer un ensemble de clés vide (ou partiellement vide) et définir un seuil, de sorte que seules les clés (non prédéclarées) dont les valeurs dépassent le seuil soient incluses dans la sortie.
  • Le MMP reçoit un rapport récapitulatif qui inclut les valeurs comportant du bruit pour les clés dont les valeurs dépassent le seuil défini. Le rapport peut également inclure des clés qui ne sont pas associées à des contributions réelles d'utilisateurs et qui comportent uniquement du bruit.
  • Le MMP utilise le champ x_network_bit_mapping lors de l'enregistrement du déclencheur pour déterminer quelle technologie publicitaire correspond à quelle clé.
  • Le MMP peut ensuite contacter la technologie publicitaire de diffusion appropriée pour comprendre les valeurs de la clé source.

En résumé, la découverte de clés permet aux MMP d'obtenir des clés d'agrégation sans les connaître à l'avance et d'éviter de traiter un grand volume de clés sources qui s'accompagne de bruit supplémentaire.

Afficher les données de mesure dans les rapports sur l'attribution

L'API Attribution Reporting permet d'effectuer les types de rapports suivants, détaillés plus loin sur cette page :

  • Les rapports au niveau des événements associent une source d'attribution particulière (clic ou vue) à un nombre limité de données de déclencheur haute fidélité.
  • Les rapports agrégables ne sont pas nécessairement liés à une source d'attribution spécifique. Ces rapports fournissent des données sur les déclencheurs plus riches et plus fiables que les rapports au niveau des événements, mais ces données ne sont disponibles que sous forme agrégée.

Ces deux types de rapports sont complémentaires et peuvent être utilisés simultanément.

Rapports au niveau des événements

Une fois qu'un déclencheur est attribué à une source d'attribution, un rapport au niveau des événements est généré et stocké sur l'appareil jusqu'à ce qu'il soit renvoyé à l'URL de postback de chaque technologie publicitaire pendant l'une des périodes d'envoi de rapports détaillées plus loin sur cette page.

Les rapports au niveau des événements sont utiles lorsque très peu d'informations sont nécessaires concernant le déclencheur. Les données de déclencheur au niveau des événements sont limitées à 3 bits de données de déclencheur pour les clics (ce qui signifie qu'un déclencheur peut se voir attribué l'une des huit catégories) et à 1 bit pour les vues. De plus, les rapports au niveau des événements ne prennent pas en charge l'encodage de données de haute qualité côté déclencheur, tels que les prix ou les heures de déclenchement spécifiques. Étant donné que l'attribution s'effectue sur l'appareil, les rapports multiappareils ne sont pas compatibles avec les rapports multiappareils.

Le rapport au niveau des événements contient les données suivantes :

  • Destination : nom du package de l'application de l'annonceur ou eTLD+1 lorsque le déclencheur s'est produit
  • ID de la source d'attribution : le même ID de la source d'attribution que celui utilisé pour enregistrer une source d'attribution
  • Type de déclencheur : 1 ou 3 bits de données de déclencheur faible fidélité, en fonction du type de source d'attribution

Mécanismes préservant la confidentialité appliqués à tous les rapports

Les limites suivantes s'appliquent une fois que les priorités concernant les sources d'attribution et les déclencheurs sont prises en compte.

Limites applicables au nombre de technologies publicitaires

Le nombre de technologies publicitaires pouvant enregistrer ou recevoir des rapports depuis l'API est limité. Voici la proposition actuelle :

  • 100 technologies publicitaires avec sources d'attribution par {application source, application de destination, 30 jours}.
  • 10 technologies publicitaires avec des déclencheurs attribués par {application source, application de destination, 30 jours, appareil}.
  • 20 technologies publicitaires peuvent enregistrer une seule source d'attribution ou un seul déclencheur (via Attribution-Reporting-Redirect).
Limites applicables au nombre de destinations uniques

Ces limites empêchent un ensemble de technologies publicitaires de s'accorder en interrogeant un grand nombre d'applis pour comprendre le comportement d'un utilisateur donné dans l'utilisation de ses applis.

  • Pour toutes les sources enregistrées et toutes les technologies publicitaires, l'API ne prend pas en charge plus de 200 destinations uniques par application source et par minute.
  • Pour toutes les sources enregistrées et pour une seule technologie publicitaire, l'API ne prend pas en charge plus de 50 destinations uniques par application source et par minute. Cette limite empêche une technologie publicitaire d'utiliser la totalité du budget par rapport à la limite de débit mentionnée précédemment.

Les sources expirées ne sont pas comptabilisées dans les limites de débit.

Une seule origine de création de rapports par application source et par jour

Une plate-forme de technologie publicitaire ne peut utiliser qu'une seule origine de création de rapports afin d'enregistrer des sources dans une application d'éditeur, pour un appareil donné, le même jour. Cette limitation du débit empêche les technologies publicitaires d'utiliser plusieurs origines de création de rapports afin d'avoir accès à un budget supplémentaire dédié à la confidentialité.

Prenons le scénario suivant : une technologie publicitaire souhaite utiliser plusieurs origines de création de rapports pour enregistrer des sources dans une application d'éditeur pour un seul appareil.

  1. L'origine de création de rapports 1 de la technologie publicitaire A enregistre une source dans l'application B.
  2. Douze heures plus tard, l'origine de création de rapports 2 de la technologie publicitaire A tente d'enregistrer une source dans l'application B.

La deuxième source, pour l'origine de création de rapports 2 de la technologie publicitaire A, serait refusée par l'API. L'origine de création de rapports 2 de la technologie publicitaire A ne pourrait pas enregistrer correctement une source sur le même appareil dans l'application B avant le jour suivant.

Récupération et limitation

Pour réduire le risque de fuite d'identité d'un utilisateur entre une paire {source, destination}, l'API limite la quantité totale d'informations envoyées au cours d'une période donnée pour un utilisateur.

La proposition actuelle consiste à limiter chaque technologie publicitaire à 100 déclencheurs attribués par {application source, application de destination, 30 jours, appareil}.

Nombre de destinations uniques

L'API limite le nombre de destinations qu'une technologie publicitaire peut tenter de mesurer. Plus la limite est faible, plus il est difficile pour une technologie publicitaire d'utiliser l'API pour essayer de mesurer l'activité de navigation des utilisateurs qui n'est pas associée aux annonces diffusées.

La proposition actuelle consiste à limiter chaque technologie publicitaire à 100 destinations distinctes avec des sources n'ayant pas expiré par application source.

Mécanismes de protection de la confidentialité appliqués aux rapports au niveau des événements

Fidélité limitée des données du déclencheur

L'API fournit 1 bit pour les déclencheurs de conversion après affichage et 3 pour les déclencheurs de clic. Les sources d'attribution prennent toujours en charge la totalité des 64 bits des métadonnées.

Vous devez évaluer si et comment réduire les informations exprimées dans les déclencheurs afin qu'ils fonctionnent avec le nombre limité de bits disponibles dans les rapports au niveau des événements.

Framework pour le bruit de la confidentialité différentielle

L'objectif de cette API est de permettre aux mesures au niveau des événements de répondre aux exigences de confidentialité différentielle locales en utilisant des réponses aléatoires k afin de générer une sortie bruyante pour chaque événement source.

Le bruit est appliqué pour déterminer si un événement de source d'attribution est honnêtement signalé. Une source d'attribution est enregistrée sur l'appareil avec une probabilité $ 1-p $ que la source d'attribution est enregistrée normalement, et avec une probabilité $ p $ sélectionnée par l'appareil de manière aléatoire parmi tous les états de sortie possibles de l'API (ne rien signaler du tout ou signaler de faux rapports, par exemple).

La réponse k-aléatoire est un algorithme qui est epsilon différentiellement confidentiel si l'équation suivante est satisfaite :

\[p = \frac{k}{k + e^ε - 1}\]

Pour des valeurs basses de ε, la sortie réelle est protégée par le mécanisme de réponse k-aléatoire. Les paramètres de bruit exacts sont en cours d'élaboration et peuvent changer en fonction des commentaires. Voici la proposition actuelle :

  • p=0,24 % pour les sources de navigation
  • p=0,00025 % pour les sources d'événements

Limites applicables aux déclencheurs disponibles (comportement par défaut)

Par défaut, le nombre de déclencheurs (conversions) par source d'attribution est limité :

  • Un à deux déclencheurs pour les sources d'attribution des visionnages d'annonce (uniquement deux déclencheurs disponibles dans le cas d'une attribution post-installation)
  • Trois déclencheurs pour les sources d'attribution des annonces avec clic

Périodes spécifiques d'envoi de rapports (comportement par défaut)

Pour les sources d'attribution des visionnages d'annonce, les rapports au niveau des événements sont envoyés après l'expiration de la source. Cette date d'expiration peut être configurée, mais elle doit être comprise entre 1 et 30 jours. Si deux déclencheurs sont attribués à une source d'attribution de visionnage d'annonce (via l'attribution post-installation), des rapports au niveau des événements peuvent être envoyés dans les intervalles correspondant aux périodes de référence spécifiées ci-dessous.

Les rapports au niveau des événements pour les sources d'attribution des clics sur les annonces sont envoyés avant ou à l'expiration de la source, à des moments précis par rapport à la date d'enregistrement de la source. Le temps écoulé entre la source d'attribution et l'expiration est réparti entre plusieurs périodes de référence. Une période spécifique s'applique à chaque période de référence (à partir de l'heure source de l'attribution). À la fin de chaque période de référence, l'appareil collecte tous les déclencheurs survenus depuis la période de référence précédente et envoie un rapport planifié. L'API prend en charge les périodes de référence par défaut suivantes :

  • 2 jours : L'appareil collecte tous les déclencheurs qui sont survenus au plus tard 2 jours après l'enregistrement de la source d'attribution, puis envoie le rapport.
  • 7 jours : L'appareil collecte tous les déclencheurs qui sont survenus plus de 2 jours, mais moins de 7 jours après l'enregistrement de la source d'attribution, puis envoie le rapport.
  • Durée personnalisée, définie par l'attribut "expiration" d'une source d'attribution. Le rapport est envoyé après le délai d'expiration spécifié, qui ne peut être inférieur à 1 jour, ni supérieur à 30 jours.
.

Configuration flexible au niveau des événements

La configuration par défaut pour les rapports au niveau des événements est celle qu'il est recommandé aux technologies publicitaires d'utiliser pour commencer les tests d'utilité, mais elle n'est pas idéale pour tous les cas d'utilisation. L'API Attribution Reporting prend en charge des configurations facultatives et plus flexibles afin que les technologies publicitaires aient davantage de contrôle sur la structure de leurs rapports au niveau des événements et puissent maximiser l'utilité des données.

Cette flexibilité supplémentaire sera introduite dans l'API Attribution Reporting en deux phases :

  • Phase 1 : Configuration flexible allégée au niveau des événements
    • Cette version fournit un sous-ensemble des fonctionnalités complètes et peut être utilisée indépendamment de la phase 2.
  • Phase 2 : Configuration flexible complète au niveau des événements

La phase 1 (configuration flexible allégée au niveau des événements) peut être utilisée pour :

  • Varier la fréquence des rapports en spécifiant le nombre de fenêtres de création de rapports
  • Varier le nombre d'attributions par enregistrement de source
  • Réduire la quantité totale de bruit en diminuant les paramètres ci-dessus
  • Configurer les périodes de création de rapports au lieu d'utiliser les valeurs par défaut

La phase 2 (configuration flexible complète au niveau des événements) peut être utilisée pour toutes les fonctionnalités de la phase 1 et :

  • Varier la cardinalité des données du déclencheur dans un rapport
  • Réduire la quantité totale de bruit en diminuant la cardinalité des données du déclencheur

La réduction d'une seule dimension de la configuration par défaut permet à la technologie publicitaire d'augmenter une autre dimension. Il est également possible de limiter la quantité totale de bruit dans un rapport au niveau des événements en réduisant la valeur des paramètres mentionnés ci-dessus.

En plus de définir dynamiquement les niveaux de bruit en fonction de la configuration choisie par une technologie publicitaire, nous allons limiter certains paramètres pour éviter les coûts de calcul importants et les configurations comportant trop d'états de sortie (ce qui augmenterait considérablement le bruit). Voici un exemple d'ensemble de restrictions. Nous vous invitons à nous faire part de vos commentaires sur la [proposition de conception][52] :

  • Un total de 20 rapports au maximum, à l'échelle mondiale et conformément aux données du déclencheur
  • 5 périodes de création de rapports possibles au maximum, conformément aux données du déclencheur
  • 32 cardinalités des données du déclencheur au maximum (non applicable à la configuration flexible allégée au niveau des événements en phase 1)

Alors que des technologies publicitaires commencent à utiliser cette fonctionnalité, sachez que l'utilisation de valeurs extrêmes peut entraîner un bruit important ou l'échec de l'enregistrement si les niveaux de confidentialité ne sont pas respectés.

Rapports agrégables

Avant d'utiliser les rapports agrégables, vous devez [configurer][53] votre compte cloud et commencer à recevoir des rapports de ce type.

Les rapports agrégables fournissent plus rapidement des données de déclencheur haute fidélité depuis l'appareil, en comparaison avec les rapports au niveau des événements. Ces données haute fidélité ne peuvent être analysées que de manière agrégée et ne sont pas associées à un déclencheur ou à un utilisateur particulier. Les clés d'agrégation vont jusqu'à 128 bits. Cela permet aux rapports agrégables de prendre en charge les cas d'utilisation de création de rapports suivants :

  • Rapports sur les valeurs de déclenchement, telles que le revenu
  • Gestion de plus de types de déclencheurs

En outre, les rapports agrégés utilisent la même logique d'attribution prioritaire basée sur la source que les rapports au niveau des événements, mais ils acceptent davantage de conversions attribuées à un clic ou une vue.

La figure 2 illustre la conception globale de la préparation et de l'envoi des rapports agrégables par l'API Attribution Reporting et correspond aux étapes suivantes :

  1. L'appareil envoie des rapports agrégables chiffrés à la technologie publicitaire. Dans un environnement de production, les technologies publicitaires ne peuvent pas utiliser ces rapports directement.
  2. La technologie publicitaire envoie un lot de rapports agrégables au service d'agrégation.
  3. Le service d'agrégation lit un lot de rapports agrégables, les déchiffre et les agrège.
  4. Les agrégats finaux sont renvoyés à la technologie publicitaire dans un [rapport récapitulatif][53]{: .external}.
Figure 2. Processus utilisé par l'API Attribution Reporting pour préparer et envoyer des rapports agrégables.

Les rapports agrégés contiennent les données suivantes concernant les sources d'attribution :

  • Destination : nom du package ou URL Web eTLD+1 de l'application où le déclencheur a eu lieu.
  • Date : date à laquelle l'événement représenté par la source d'attribution s'est produit.
  • Charge utile : valeurs des déclencheurs, collectées sous forme de paires clé/valeur chiffrées. La charge utile est utilisée dans le service d'agrégation sécurisé pour calculer les agrégations.

Services d'agrégation

Les services suivants fournissent des fonctionnalités d'agrégation et protègent contre les accès inappropriés aux données d'agrégation.

Ces services sont gérés par différentes parties, qui sont décrites plus en détail dans la suite de cette page :

  • Le service d'agrégation est le seul que les technologies publicitaires sont censées déployer.
  • Les services de gestion de clés et de comptabilisation des rapports agrégables sont assurés par des tiers de confiance appelés coordinateurs. Ces coordinateurs certifient que le code qui exécute le service d'agrégation est le code public fourni par Google, et que les mêmes services de gestion des clés et de comptabilisation des rapports agrégables sont appliqués à tous les utilisateurs du service d'agrégation.
Service d'agrégation

Les plates-formes de technologie publicitaire doivent déployer à l'avance un service d'agrégation basé sur des binaires fournis par Google.

Ce service d'agrégation fonctionne dans un environnement d'exécution sécurisé (TEE) hébergé dans le cloud. Un TEE offre les avantages de sécurité suivants :

  • Il garantit que le code opérant dans le TEE est le binaire fourni par Google. À moins que cette condition ne soit satisfaite, le service d'agrégation ne peut pas accéder aux clés de déchiffrement nécessaires à son fonctionnement.
  • Elle offre une sécurité autour du processus en cours d'exécution, en l'isolant de toute surveillance ou de la falsification externes.

Ces avantages de sécurité permettent à un service d'agrégation d'effectuer des opérations sensibles, telles que l'accès à des données chiffrées de façon plus sécurisée.

Pour en savoir plus sur les considérations de conception, de workflow et de sécurité du service d'agrégation, consultez le [document relatif au service d'agrégation][59]{: external} sur GitHub.

Service de gestion des clés

Ce service vérifie qu'un service d'agrégation exécute une version approuvée du binaire, puis fournit au service d'agrégation, dans la technologie publicitaire, les clés de déchiffrement appropriées pour ses données de déclencheur.

Comptabilisation des rapports agrégables

Ce service suit la fréquence à laquelle le service d'agrégation d'une technologie publicitaire accède à un déclencheur spécifique, qui peut contenir plusieurs clés d'agrégation, et limite l'accès au nombre de déchiffrements approprié. Pour en savoir plus, reportez-vous à la proposition de conception du service d'agrégation pour l'API Attribution Reporting.

API Aggregatable Reports

L'API permettant de créer des contributions aux rapports agrégables utilise la même API de base que pour enregistrer une source d'attribution pour les rapports au niveau des événements. Les sections suivantes décrivent les extensions de l'API.

Enregistrer les données sources agrégables

Lorsque l'API envoie une requête à l'URI source de l'attribution, la technologie publicitaire peut enregistrer une liste de clés d'agrégation, nommée histogram_contributions, en réponse à un nouveau champ nommé aggregation_keys dans l'en-tête HTTP Attribution-Reporting-Register-Source, avec la clé comme key_name et la valeur comme key_piece :

  • (Key) Key name ((Clé) Nom de la clé) : chaîne du nom de la clé. Utilisée comme clé de jointure pour combiner des clés côté déclencheur afin de former la clé finale.
  • (Value) Key piece ((Valeur) Clé) :chaîne de caractères pour la clé.

La clé finale du bucket d'histogrammes est entièrement définie au moment du déclenchement en effectuant une opération binaire OU une opération sur ces éléments et sur les éléments côté déclencheur.

Les clés finales sont limitées à un maximum de 128 bits. Les clés plus longues sont tronquées. Cela signifie que les chaînes hexadécimales dans le fichier JSON ne doivent pas comporter plus de 32 chiffres.

En savoir plus sur la structure des clés d'agrégation et sur la configuration des clés d'agrégation

Dans l'exemple suivant, une technologie publicitaire utilise l'API pour collecter les éléments suivants :

  • Nombre total de conversions au niveau de la campagne
  • Regrouper les valeurs d'achat au niveau géographique
// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

Enregistrer le déclencheur agrégable

L'enregistrement du déclencheur inclut deux champs supplémentaires.

Le premier champ permet d'enregistrer une liste de clés agrégables du côté du déclencheur. La technologie publicitaire doit répondre avec le champ aggregatable_trigger_data dans l'en-tête HTTP Attribution-Reporting-Register-Trigger, avec les champs suivants pour chaque clé agrégable de la liste :

  • Key piece (Clé) : valeur de chaîne de bits pour la clé.
  • Source keys (Clés sources) : liste de chaînes avec les noms des clés sources d'attribution auxquelles la clé du déclencheur doit être combinée pour former les clés finales.

Le deuxième champ permet d'enregistrer une liste de valeurs qui doivent contribuer à chaque clé. La technologie publicitaire doit renvoyer le champ aggregatable_values dans l'en-tête HTTP Attribution-Reporting-Register-Trigger. Le deuxième champ permet d'enregistrer une liste de valeurs qui doivent contribuer à chaque clé. Il peut s'agir d'un entier compris dans la plage $ [1, 2^{16}] $.

Chaque déclencheur peut apporter plusieurs contributions aux rapports agrégables. Le montant total des contributions à un événement source donné est lié par un paramètre $ L1 $, qui correspond à la somme maximale des contributions (valeurs) de toutes les clés agrégées pour une source donnée. $ L1 $ correspond à la sensibilité ou à la norme L1 des contributions de l'histogramme par événement source. Le dépassement de ces limites entraîne la baisse silencieuse des contributions futures. La proposition initiale consiste à définir $ L1 $ sur $ 2^{16} $ (65536).

Le bruit du service d'agrégation est ajusté proportionnellement à ce paramètre. Il est donc recommandé d'ajuster correctement les valeurs rapportées pour une clé agrégée donnée, en fonction de la part du budget $ L1 $ qui lui est allouée. Cette approche permet de garantir que les rapports agrégés conservent la plus grande fidélité possible lorsque le bruit est appliqué. Ce mécanisme est extrêmement flexible et peut accepter de nombreuses stratégies d'agrégation.

Dans l'exemple suivant, le budget dédié à la confidentialité est réparti équitablement, en répartissant la contribution de $ L1 $, entre campaignCounts et geoValue :

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

L'exemple précédent génère les contributions d'histogramme suivantes :

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

Les facteurs de scaling peuvent être inversés pour obtenir les valeurs correctes, modulo le bruit appliqué :

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

Confidentialité différentielle

L'un des objectifs de cette API est de disposer d'un framework pouvant prendre en charge les mesures agrégées à confidentialité différentielle. Pour ce faire, vous pouvez ajouter un bruit proportionnel au budget $ L1 $, par exemple en affectant le bruit avec la répartition suivante :

\[ Laplace(\frac{L1}{ε}) \]

Intégration de l'API Protected Audience et de l'API Attribution Reporting

L'intégration multi-API dans les API Protected Audience et Attribution Reporting permet aux technologies publicitaires d'évaluer leurs performances d'attribution selon différentes stratégies de remarketing afin d'identifier les types d'audiences qui génèrent le ROI le plus élevé.

Grâce à cette intégration multi-API, les technologies publicitaires peuvent :

  • Créer un mappage clé-valeur des URI à utiliser pour 1) les rapports sur les interactions et 2) l'enregistrement de la source.
  • Inclure CustomAudience dans leur mappage de clé côté source pour les rapports récapitulatifs globaux (à l'aide de l'API Attribution Reporting).

Lorsqu'un utilisateur voit une annonce ou clique dessus :

  • L'URL utilisée pour enregistrer ces interactions à l'aide de Protected Audience servira également à enregistrer une vue ou un clic en tant que source éligible avec l'API Attribution Reporting.
  • La technologie publicitaire peut choisir de transmettre des CustomAudience (ou d'autres informations contextuelles pertinentes sur l'annonce, telles que l'emplacement de l'annonce ou la durée de visionnage) à l'aide de cette URL afin que ces métadonnées puissent se propager dans les rapports récapitulatifs lorsque la technologie publicitaire examine les performances agrégées de la campagne.

Pour en savoir plus sur l'activation de cette fonctionnalité dans Protected Audience, consultez la section correspondante de la [présentation de l'API Protected Audience][64].

Priorité d'enregistrement, attribution et exemples de rapports

Cet exemple présente un ensemble d'interactions utilisateurs et la manière dont les priorités d'attribution et de déclencheur définies par les technologies publicitaires peuvent affecter les rapports attribués. Cet exemple suppose que les points suivants ont été pris en compte :

  • Tous les déclencheurs et sources d'attribution sont enregistrés par la même technologie publicitaire, pour le même annonceur.
  • Tous les déclencheurs et sources d'attribution ont lieu au cours de la première fenêtre de création de rapports sur les événements (dans les deux jours suivant l'affichage initial des annonces dans l'application d'un éditeur).

Prenons l'exemple d'un utilisateur qui effectue les opérations suivantes :

  1. L'utilisateur voit une annonce. La technologie publicitaire enregistre une source d'attribution auprès de l'API, avec une priorité de 0 (vue n° 1).
  2. L'utilisateur voit une annonce enregistrée avec une priorité de 0 (vue n° 2).
  3. L'utilisateur clique sur une annonce enregistrée avec une priorité de 1 (clic n° 1).
  4. L'utilisateur effectue une conversion (atteint la page de destination) dans l'application d'un annonceur. La technologie publicitaire enregistre un déclencheur avec l'API, avec une priorité de 0 (conversion n° 1).
    • À mesure que les déclencheurs sont enregistrés, l'API comment par effectuer l'attribution avant de générer des rapports.
    • Trois sources d'attribution sont disponibles : vue n° 1, vue n° 2 et clic n° 1. L'API attribue ce déclencheur au clic n° 1, car il s'agit de la priorité la plus élevée et la plus récente.
    • Les vues n° 1 et 2 sont supprimées et ne peuvent plus être attribuées.
  5. L'utilisateur ajoute un article à son panier dans l'application de l'annonceur, enregistré avec une priorité de 1 (conversion n° 2).
    • Le clic n° 1 est la seule source d'attribution éligible. L'API attribue ce déclencheur au clic 1.
  6. L'utilisateur ajoute un article à son panier dans l'application de l'annonceur, enregistré avec une priorité de 1 (conversion n° 3).
    • Le clic n° 1 est la seule source d'attribution éligible. L'API attribue ce déclencheur au clic 1.
  7. L'utilisateur ajoute un article à son panier dans l'application de l'annonceur, enregistré avec une priorité de 1 (conversion n° 4).
    • Le clic n° 1 est la seule source d'attribution éligible. L'API attribue ce déclencheur au clic 1.
  8. L'utilisateur effectue un achat dans l'application de l'annonceur, enregistrée avec une priorité de 2 (conversion n° 5).
    • Le clic n° 1 est la seule source d'attribution éligible. L'API attribue ce déclencheur au clic 1.

Les rapports au niveau des événements présentent les caractéristiques suivantes :

  • Par défaut, les trois premiers déclencheurs attribués à un clic et le premier attribué à une vue sont envoyés après les périodes de référence applicables.
  • Dans la fenêtre de création de rapports, si des déclencheurs sont enregistrés avec un niveau de priorité plus élevé, ceux-ci remplacent les déclencheurs les plus récents.
  • Dans l'exemple précédent, la technologie publicitaire reçoit trois rapports sur les événements après la période de référence de deux jours (pour les conversions n° 2, n° 3 et n° 5).
    • Les cinq déclencheurs sont attribués au clic 1. Par défaut, l'API envoie des rapports pour les trois premiers déclencheurs : conversion n° 1, conversion n° 2 et conversion n° 3.
    • Toutefois, la priorité de la conversion n° 4 (1) est supérieure à celle de la conversion n° 1 (0). Le rapport sur les événements de la conversion n° 4 remplace celui de la conversion n°1 à envoyer.
    • De plus, la priorité de la conversion n° 5 (2) est plus élevée que pour tout autre déclencheur. Le rapport sur les événements de la conversion n° 5 remplace celui de la conversion n° 4 à envoyer.

Les rapports agrégables présentent les caractéristiques suivantes :

  • Les rapports agrégables chiffrés sont envoyés à la technologie publicitaire dès qu'ils sont traités, soit quelques heures après l'enregistrement des déclencheurs.

    En tant que technologie publicitaire, vous créez leurs lots en fonction des informations qui ne sont pas chiffrées dans vos rapports agrégables. Ces informations sont contenues dans le champ shared_info de votre rapport agrégable, et incluent l'horodatage et l'origine du rapport. Vous ne pouvez pas effectuer de traitement par lot sur la base d'informations chiffrées dans vos paires clé/valeur d'agrégation. Vous pouvez cependant regrouper vos rapports en lots quotidiennement ou hebdomadairement. Idéalement, les lots doivent contenir au moins 100 rapports chacun.

  • C'est à la technologie publicitaire de déterminer quand et comment regrouper les rapports agrégables et comment les envoyer au service d'agrégation.

  • Les rapports agrégables chiffrés peuvent attribuer plus de déclencheurs à une source que les rapports au niveau des événements.

  • Dans l'exemple précédent, cinq rapports agrégés sont envoyés, un pour chaque déclencheur enregistré.

Rapports de débogage de transition

L'API Attribution Reporting est une nouvelle méthode assez complexe contribuant à mesurer l'attribution sans identifiants interapplications. Nous sommes donc disposés à introduire un mécanisme de transition permettant d'en savoir plus sur les rapports sur l'attribution lorsque l'identifiant publicitaire est disponible (si l'utilisateur n'a pas désactivé la personnalisation à l'aide de l'identifiant publicitaire, et si l'application de l'éditeur et de l'annonceur a déclaré les autorisations requises pour l'identifiant publicitaire). Cela permettra de s'assurer que l'API est entièrement comprise lors du déploiement, d'éliminer les bugs éventuels et de comparer plus facilement les performances avec les alternatives basées sur l'identifiant publicitaire. Il existe deux types de rapports de débogage : attribution-success et verbose.

Consultez le guide sur les rapports de débogage de transition pour en savoir plus sur les rapports de débogage avec la mesure "Application/Web" et "Web/application".

Rapports de débogage "attribution-success"

Les enregistrements de source et du déclencheur acceptent un nouveau champ debug_key 64 bits (formaté en tant que chaîne) qui est renseigné par la technologie publicitaire. source_debug_key et trigger_debug_key sont transmis tels quels dans les rapports agrégés et les rapports sur les événements.

Si un rapport est créé avec des clés de débogage pour les sources et le déclencheur, un rapport de débogage en double est envoyé avec un délai limité à un point de terminaison .well-known/attribution-reporting/debug/report-event-attribution.

Pour les versions DP 10 et ultérieures, les requêtes de rapport de débogage "attribution-success" contiendront un titre de version similaire à celui-ci : Version: 202310

Les rapports de débogage sont identiques aux rapports normaux, y compris les deux champs de clé de débogage. Ces deux clés permettent d'associer les rapports standards au flux distinct de rapports de débogage.

  • Pour les rapports au niveau des événements :
    • Les rapports de débogage en double sont envoyés avec un délai limité et ne sont donc pas supprimés par les limites des déclencheurs disponibles, ce qui permet à la technologie publicitaire de comprendre l'impact de ces limites pour les rapports au niveau des événements.
    • Les rapports associés à de faux événements déclencheurs n'ont pas de trigger_debug_key. Cela permet à la technologie publicitaire de mieux comprendre comment le bruit est appliqué dans l'API.
  • Pour les rapports agrégables :
    • Nous acceptons un nouveau champ debug_cleartext_payload contenant la charge utile déchiffrée, uniquement si source_debug_key et trigger_debug_key sont tous deux définis.

Rapports de débogage de type "verbose"

Les rapports de débogage de type "verbose" permettent aux développeurs de surveiller certains échecs d'enregistrement de la source d'attribution ou du déclencheur. Ces rapports de débogage sont envoyés avec un délai limité après l'enregistrement de la source ou du déclencheur d'attribution dans unpoint de terminaison well-known/attribution-reporting/debug/verbose.

Pour les versions DP 10 et ultérieures, les requêtes de rapport de débogage "attribution-success" contiendront un titre de version similaire à celui-ci : Version: 202310

Chaque rapport de type "verbose" contient les champs suivants :

  • Type : origine du rapport. Consultez la [liste complète des types de rapports de type "verbose"][67]{:.external}.
    • En général, il existe des rapports de type "verbose" pour les sources et pour les déclencheurs.
    • Les rapports de type "verbose" pour la source nécessitent que l'identifiant publicitaire soit accessible pour l'application de l'éditeur, tandis que les rapports de type "verbose" pour le déclencheur nécessitent que l'identifiant publicitaire soit accessible à l'application de l'annonceur.
    • Les rapports de type "verbose" du déclencheur (à l'exception de trigger-no-matching-source) peuvent inclure l'élément source_debug_key. Il ne peut être inclus que si l'identifiant publicitaire est également disponible pour l'application de l'éditeur.
  • Body (Corps) : corps du rapport, qui dépend de son type.

Les technologies publicitaires doivent activer la réception de rapports de débogage de type "verbose" via un nouveau champ de dictionnaire debug_reporting dans les en-têtes Attribution-Reporting-Register_Source et Attribution-Reporting-Register-Trigger.

  • Les rapports de type "verbose" pour la source ne doivent être activés que dans l'en-tête d'enregistrement de la source.
  • Les rapports de débogage du déclencheur nécessitent une activation uniquement dans l'en-tête d'enregistrement du déclencheur.

Fonctionnement des rapports de débogage

Si une conversion a eu lieu (selon votre système de mesure existant) et qu'un rapport de débogage a été reçu pour cette conversion, cela signifie que le déclencheur a bien été enregistré.

Pour chaque rapport d'attribution de débogage, vérifiez si vous recevez un rapport d'attribution standard correspondant aux deux clés de débogage.

S'il n'existe aucune correspondance, plusieurs raisons sont possibles.

Fonctionne normal :

  • Comportements de l'API protégeant la confidentialité :
    • Un utilisateur atteint la limite de débit des rapports (les rapports ultérieurs cessent donc d'être envoyés durant cette période), ou une source est supprimée en raison de la limite de destination en attente.
    • Pour les rapports au niveau des événements : le rapport au niveau des événements est soumis à une réponse aléatoire (bruit) et supprimé, ou vous pouvez recevoir un rapport aléatoire.
    • Pour les rapports au niveau des événements : vous avez atteint la limite de trois rapports (pour les clics) ou d'un seul rapport (pour les vues), et aucune priorité explicite n'est définie pour les rapports suivants, ou la priorité est inférieure à celle des rapports existants.
    • Les limites de contribution des rapports agrégables ont été dépassées.
  • Logique métier définie par la technologie publicitaire :
    • Un déclencheur est filtré via des filtres ou des règles de priorité.
  • Délais ou interactions avec la disponibilité du réseau (par exemple, l'utilisateur éteint son appareil pendant une période prolongée).

Causes inattendues :

  • Problèmes d'implémentation :
    • L'en-tête source est mal configuré.
    • L'en-tête du déclencheur est mal configuré.
    • D'autres problèmes de configuration sont survenus.
  • Problèmes liés à l'appareil ou au réseau :
    • Échecs dus à l'état du réseau.
    • La réponse d'enregistrement de la source ou du déclencheur ne parvient pas au client.
    • Bug de l'API.

Questions à venir et questions ouvertes

L'API Attribution Reporting est en cours de développement. Nous explorons également de futures fonctionnalités potentielles, telles que des modèles d'attribution non basés sur le dernier clic et des cas d'utilisation de mesures multiappareils.

Nous aimerions également connaître l'avis de la communauté sur quelques problèmes :

  1. Existe-t-il des cas d'utilisation pour lesquels vous souhaiteriez que l'API envoie des rapports pour l'installation validée ? Ces rapports seraient alors comptabilisés dans les limites de débit respectives des plates-formes de technologie publicitaire.
  2. Envisagez-vous des difficultés pour transmettre l'identifiant InputEvent de l'application à la technologie publicitaire pour l'enregistrement de la source ?
  3. Avez-vous des cas d'utilisation particuliers d'attribution pour les applications préchargées ou réinstallées ?