API Attribution Reporting : guide d'intégration

Lorsque vous lisez la documentation concernant la Privacy Sandbox sur Android, cliquez sur le bouton Preview développeur ou Bêta pour sélectionner la version du programme que vous utilisez, car les instructions peuvent varier.

L'API Attribution Reporting est conçue pour prendre en charge des cas d'utilisation clés de l'attribution et de la mesure des conversions dans les applications et sur le Web, sans dépendre d'identifiants utilisateur multipartites. Par rapport aux conceptions courantes d'aujourd'hui, les responsables de l'implémentation de l'API Attribution Reporting doivent prendre en compte quelques points importants :

  • Les rapports au niveau des événements incluent des données de conversion basse fidélité. Un faible nombre de valeurs de conversion fonctionnent bien.
  • Les rapports cumulables incluent des données de conversion dont la fidélité est plus élevée. Vos solutions doivent concevoir des clés d'agrégation en fonction des exigences de votre entreprise et de la limite de 128 bits.
  • Les modèles de données et le traitement de votre solution doivent tenir compte des limites de débit pour les déclencheurs disponibles, des délais d'envoi des événements de déclencheur et du bruit appliqué par l'API.

Pour vous aider dans la planification de l'intégration, ce guide offre un aperçu complet, qui peut inclure des fonctionnalités qui ne sont pas encore implémentées au stade actuel de la Privacy Sandbox dans la version Preview développeur Android. Dans ce cas, une estimation de leur disponibilité est donnée.

Sur cette page, nous utilisons le terme source pour représenter un clic ou une vue, et le terme déclencheur pour représenter une conversion.

Le graphique ci-dessous affiche les différentes options de workflow pour l'intégration de l'attribution. Les sections répertoriées dans la même colonne (entourées en vert) peuvent être traitées en parallèle. Par exemple, l'engagement partenaire peut être effectué en même temps que l'attribution au niveau de l'événement d'une application à une autre.

Schéma du workflow d'intégration de l'attribution

Figure 1. Workflow d'intégration de l'attribution.

Conditions préalables et configuration

Suivez les étapes de cette section pour mieux comprendre l'API Attribution Reporting. Cette procédure vous permettra d'obtenir des résultats pertinents lorsque vous utiliserez l'API dans l'écosystème publicitaire.

Se familiariser avec l'API

  1. Lisez la proposition de conception pour vous familiariser avec l'API Attribution Reporting et ses fonctionnalités.
  2. Consultez le guide du développeur pour découvrir comment intégrer le code et les appels d'API dont vous avez besoin pour vos cas d'utilisation.
  3. Envoyez vos commentaires concernant la documentation. Surtout, n'hésitez pas à nous faire part des questions qui sont restées sans réponse.
  4. Inscrivez-vous pour recevoir des informations régulières importantes sur l'API Attribution Reporting. Vous serez ainsi notifié en cas d'ajout de fonctionnalités dans les futures versions.

Configurer et tester l'application exemple

  1. Une fois que vous êtes prêt à commencer l'intégration, configurez la dernière version Preview développeur dans Android Studio.
  2. Configurez des points de terminaison de serveur fictifs pour les enregistrements d'événements et la distribution des rapports. Nous mettons à votre disposition des simulations que vous pouvez utiliser conjointement avec des outils disponibles en ligne.
  3. Téléchargez et exécutez le code dans notre application exemple pour vous familiariser avec l'enregistrement des sources et des déclencheurs.
    1. Définissez le délai d'envoi des rapports. L'API accepte des délais de deux ou sept jours, ou une période personnalisée comprise entre deux et 30 jours.
    2. Une fois que vous avez exécuté et utilisé l'application exemple pour enregistrer des sources et des déclencheurs, et que le délai défini est écoulé, vérifiez que vous avez reçu un rapport au niveau de l'événement et un rapport cumulable chiffré. Si vous avez besoin de déboguer des rapports, vous pouvez les générer plus rapidement en forçant l'exécution des tâches de création de rapports.
    3. Examinez les résultats de l'attribution d'une application à une autre. Vérifiez que les données de ces résultats sont celles attendues pour les modèles d'attribution au dernier contact et après installation.

  4. Une fois que vous avez compris comment l'API cliente et le serveur interagissent l'un avec l'autre, utilisez l'application exemple pour orienter votre propre intégration. Configurez votre propre serveur de production et ajoutez des appels d'enregistrement d'événements à vos applications.

Préintégration

Inscrivez votre organisation auprès de la Privacy Sandbox sur Android. Cette inscription vise à éviter la duplication inutile de plates-formes de technologie publicitaire, ce qui permettrait d'accéder à plus d'informations que nécessaire sur les activités de l'utilisateur.

Engagement des partenaires

Les partenaires ad tech (MMP/SSP/DSP) créent souvent des solutions d'attribution intégrées. Les étapes de cette section contribuent à optimiser la collaboration avec vos partenaires ad tech.

  1. Planifiez une discussion avec vos principaux partenaires de mesure afin de discuter des tests et de l'adoption de l'API Attribution Reporting. Les partenaires de mesure peuvent inclure les réseaux de technologie publicitaire, les SSP, les DSP, les annonceurs ou tout autre partenaire avec lequel vous travaillez actuellement ou souhaitez travailler.
  2. Collaborez avec les partenaires de mesure pour définir les délais d'intégration, allant des tests initiaux à l'adoption.
  3. Déterminez avec l'aide des partenaires de mesure les domaines que chacun de vous couvrira lors de la conception de l'attribution.
  4. Mettez en place des canaux de communication entre les partenaires de mesure afin que tout le monde soit sur la même longueur d'onde en termes de délais et de tests de bout en bout.
  5. Concevez des flux de données de haut niveau pour l'ensemble des partenaires de mesure. Voici les principaux points à prendre en considération :
    • Comment les partenaires de mesure enregistreront-ils les sources d'attribution avec l'API Attribution Reporting ?
    • Comment les réseaux de technologie publicitaire enregistreront-ils les déclencheurs avec l'API Attribution Reporting ?
    • Comment chaque technologie publicitaire validera-t-elle les requêtes API et renverra-t-elle des réponses pour effectuer les enregistrements des sources et des déclencheurs ?
    • Existe-t-il des rapports à partager entre les partenaires en dehors de l'API Attribution Reporting ?
    • D'autres points d'intégration ou ajustements sont-ils nécessaires entre les partenaires ? Par exemple, vos partenaires et vous-même devez-vous travailler à la déduplication des conversions ou vous aligner sur les clés d'agrégation ?
  6. En cas de modèle d'attribution entre une application et un site Web, planifiez une discussion avec les partenaires de mesure sur le Web sur les thèmes de la conception, des tests et de l'adoption de l'API Attribution Reporting. Reportez-vous aux questions de l'étape précédente pour orienter la conversation avec les partenaires Web.

Prototyper l'attribution au niveau de l'événement d'une application à une autre

Cette section vous permet de configurer une attribution de base d'une application à une autre à l'aide de rapports au niveau des événements dans votre application ou dans votre SDK. Vous devez terminer cette section avant de pouvoir commencer à prototyper l'attribution au serveur d'agrégation.

  1. Configurez un serveur de collecte pour les enregistrements d'événements. Pour ce faire, vous pouvez utiliser les spécifications fournies afin de générer un serveur fictif, ou configurer votre propre serveur avec cet exemple de code.
  2. Ajoutez des appels d'événements d'enregistrement de sources dans votre SDK ou votre application lorsque des annonces sont diffusées.
    • Voici quelques points essentiels à prendre en compte :
      • Assurez-vous que les ID d'événement des sources sont disponibles et correctement transmis aux appels de l'API d'enregistrement des sources.
      • Veillez à transmettre également un "InputEvent" pour enregistrer les sources de clics.
      • Déterminez comment vous allez configurer la priorité des sources pour différents types d'événements. Par exemple, attribuez une priorité élevée aux événements considérés comme étant à forte valeur ajoutée, tels que les clics plutôt que les vues.
      • La valeur d'expiration par défaut est acceptable pour les tests. Toutefois, vous pouvez également configurer des périodes d'expiration différentes.
      • Vous pouvez conserver les filtres et les périodes d'attribution par défaut des tests.
    • Voici également quelques suggestions :
      • Concevez des clés d'agrégation si vous êtes prêt à les utiliser.
      • Tenez compte de votre stratégie de redirection lorsque vous déterminez comment vous souhaitez collaborer avec d'autres partenaires de mesure.
  3. Ajoutez des événements d'enregistrement de déclencheurs dans votre SDK ou votre application pour enregistrer les événements de conversion.
    • Voici quelques points essentiels à prendre en compte :
    • Voici également quelques suggestions :
      • Ignorez la création de clés de déduplication tant que vous n'effectuez pas de tests de précision.
      • Ignorez la création des clés et des valeurs d'agrégation tant que les tests de simulation ne sont pas prêts.
      • Ignorez les redirections tant que vous n'avez pas déterminé comment vous souhaitez collaborer avec d'autres partenaires de mesure.
      • La priorité du déclencheur n'est pas essentielle pour les tests.
      • Il est probable que les filtres soient ignorés pour les tests initiaux.
  4. Vérifiez que les événements d'enregistrement de sources sont générés pour les annonces et que les déclencheurs mènent à la création de rapports sur les événements.

Tests de simulation

Cette section explique comment tester l'impact que le transfert de vos conversions actuelles dans des rapports d'événements et des rapports cumulables peut avoir sur les systèmes de création de rapports et d'optimisation. Vous pourrez ainsi lancer des tests d'impact avant de terminer votre intégration.

Pour effectuer les tests, vous devez simuler la génération d'événements et de rapports cumulables en fonction de l'historique des enregistrements de conversion dont vous disposez, puis obtenir les résultats agrégés à partir d'un serveur d'agrégation simulé. Ces résultats pourront être comparés à l'historique du nombre de conversions afin de déterminer l'évolution du niveau de précision des rapports.

Les modèles d'optimisation, tels que les calculs du taux de conversion prévu, peuvent être entraînés au niveau de ces rapports afin de comparer leur précision par rapport à ceux créés à partir des données actuelles. Il s'agit également d'une bonne occasion pour tester différentes structures de clés d'agrégation et leur impact sur les résultats.

  1. Configurez la bibliothèque de simulation de mesure sur un ordinateur local.
  2. Lisez les spec concernant la mise en forme de vos données de conversion pour qu'elles soient compatibles avec le générateur de rapports simulé.
  3. Concevez vos clés d'agrégation en fonction des exigences métier.
    • Voici quelques points essentiels à prendre en compte :
      • Tenez compte des dimensions essentielles dont vos clients ou partenaires ont besoin pour agréger et cibler votre évaluation par rapport à celles-ci.
      • Déterminez le nombre minimal de dimensions et de cardinalités agrégées nécessaires.
      • Assurez-vous que les éléments de clé côté source et déclencheur ne dépassent pas 128 bits.
      • Si vos solutions impliquent la contribution à plusieurs valeurs par événement déclencheur, veillez à ajuster ces valeurs par rapport au budget de contribution maximal, à savoir L1. Cette approche permet de minimiser l'impact du bruit.
      • Voici un exemple de configuration d'une clé pour collecter le nombre total de conversions au niveau d'une campagne, et de configuration d'une clé pour collecter les valeurs d'achat agrégées à un niveau géographique.
  4. Exécutez le générateur de rapports pour créer des rapports sur les événements et des rapports cumulables.
  5. Exécutez les rapports cumulables via les serveurs d'agrégation simulés afin d'obtenir des rapports récapitulatifs.
  6. Effectuez des tests utilitaires :
    • Pour déterminer la précision des rapports sur les conversions, comparez les totaux des conversions issus des rapports au niveau des événements et des rapports récapitulatifs à l'historique des données de conversion. Pour optimiser les résultats, effectuez des tests et des comparaisons des rapports dans une partie large et représentative de la base d'annonceurs.
    • Réentraînez vos modèles en fonction des données de rapport au niveau des événements et, éventuellement, des données des rapports récapitulatifs. Comparez la précision avec les modèles basés sur des données d'entraînement historiques.
    • Testez différentes stratégies de traitement par lot et étudiez leur impact sur vos résultats.
      • Voici quelques points essentiels à prendre en compte :
      • Exécution en temps opportun des rapports récapitulatifs pour l'ajustement des enchères
      • Fréquences moyennes des événements attribuables sur l'appareil (par exemple, les utilisateurs ponctuels reviennent en fonction de l'historique des données d'événements d'achat)
      • Niveau de bruit (plus le nombre de lots est élevé, plus l'agrégation est faible, et plus l'agrégation est faible, plus le bruit est important)

Prototyper l'attribution au serveur d'agrégation : configuration

Ces étapes vous permettront de recevoir des rapports agrégables sur les événements de vos sources et de vos déclencheurs.

  1. Configurez votre serveur d'agrégation :
  2. Concevez vos clés d'agrégation en fonction des exigences métier. Si vous avez déjà effectué cette tâche dans la section d'attribution au niveau de l'événement d'une application à une autre, vous pouvez ignorer cette étape.
  3. Configurez un serveur de collecte pour les rapports cumulables. Si vous en avez déjà créé un dans la section d'attribution au niveau de l'événement d'une application à une autre, vous pouvez le réutiliser.

Prototyper l'attribution au serveur d'agrégation : intégration

Pour continuer, vous devez avoir suivi toutes les étapes de la section Prototyper l'attribution au serveur d'agrégation : configuration ou Prototyper l'attribution au niveau de l'événement d'une application à une autre**.

  1. Ajoutez des données de clé d'agrégation aux événements de vos sources et de vos déclencheurs. Vous devrez probablement transmettre plus de données sur l'événement d'annonce, comme l'ID de campagne, à votre SDK ou votre application pour inclure la clé d'agrégation.
  2. Collectez des rapports cumulables d'attribution d'une application à une autre à partir des événements des sources et des déclencheurs que vous avez enregistrés avec les données de la clé d'agrégation.
  3. Testez différentes stratégies de traitement par lot lorsque vous exécutez ces rapports cumulables via le serveur d'agrégation et observez leur impact sur vos résultats.

Itérer la conception avec des fonctionnalités facultatives

Vous trouverez ci-dessous des fonctionnalités supplémentaires que vous pouvez inclure dans votre solution de mesure.

  1. La définition d'une clé de débogage vous permet de recevoir un rapport non modifié l'événement d'une source ou d'un déclencheur, ainsi que les rapports générés par l'API Attribution Reporting. Vous pouvez utiliser des clés de débogage pour comparer les rapports et détecter des bugs pendant l'intégration.

Personnaliser les comportements d'attribution

  1. Attribution pour les déclencheurs après installation
    • Cette fonctionnalité peut être utilisée dans le cas où les déclencheurs après installation doivent être attribués à la source d'attribution qui a généré l'installation, même si d'autres sources d'attribution éligibles sont plus récentes.
    • Par exemple, il peut arriver qu'un utilisateur clique sur une annonce qui génère une installation. Une fois l'installation effectuée, il clique sur une autre annonce et effectue un achat. Dans ce cas, la société de technologie publicitaire peut préférer attribuer l'achat au premier clic plutôt qu'au clic de réengagement.
  2. Affinez les données dans les rapports d'attribution au niveau des événements à l'aide de filtres.
    • Vous pouvez définir des filtres de conversion pour ignorer les déclencheurs sélectionnés et les exclure des rapports sur les événements. Étant donné que le nombre de déclencheurs est limité par source d'attribution, les filtres vous permettent d'inclure uniquement les déclencheurs qui fournissent les informations les plus utiles dans les rapports sur les événements.
    • Vous pouvez également utiliser certains filtres pour exclure certains déclencheurs et, par conséquent, les ignorer. Par exemple, si votre campagne cible les installations d'applications, il peut être utile d'empêcher les déclencheurs après installation d'être attribués aux sources de cette campagne.
    • Les filtres permettent également de personnaliser les données des déclencheurs en fonction des données des sources. Par exemple, une source peut spécifier "product" : ["1234"], où product correspond à la clé de filtre, et 1234 à la valeur. Tout déclencheur dont la clé de filtre est "product" et dont la valeur est différente de "1234" sera ignoré.
  3. Personnalisation de la priorité des sources et des déclencheurs
    • Dans le cas où plusieurs sources d'attribution peuvent être associées à un déclencheur ou que plusieurs déclencheurs peuvent être attribués à une source, vous pouvez utiliser un entier signé de 64 bits pour donner la priorité à certaines attributions de source/déclencheur par rapport à d'autres.

Collaborer avec des MMP et autres partenaires

  1. Redirections vers d'autres tiers pour les événements de sources et de déclencheurs
    • Vous pouvez définir des URL de redirection pour permettre à plusieurs plates-formes de technologie publicitaire d'enregistrer une requête. Cela permet d'activer la déduplication multiréseau dans l'attribution.
  2. Clés de déduplication
    • Lorsqu'un annonceur utilise plusieurs plates-formes de technologie publicitaire pour enregistrer le même événement de déclencheur, une clé de déduplication peut être utilisée pour faire la distinction entre ces rapports répétés. Si aucune clé de déduplication n'est fournie, les déclencheurs en double peuvent être renvoyés à chaque plate-forme de technologie publicitaire comme étant uniques.

Utiliser les mesures multiplates-formes

  1. Attribution d'une application à une autre et d'une application à un site Web (disponible à la fin du 4e trimestre)
    • Permet les cas d'utilisation où un utilisateur voit une annonce dans une application, puis effectue une conversion dans le navigateur d'un appareil mobile ou d'une application, ou inversement.