Guide d'implémentation de l'API Attribution Reporting pour plusieurs sites Web et applications

L'API Attribution Reporting permet l'attribution multi-applications et Web pour les sources et les déclencheurs qui se produisent sur le même appareil. Les navigateurs, tels que Chrome, peuvent déléguer l'enregistrement des sources et des déclencheurs à l'API Attribution Reporting pour Android au lieu de gérer ces enregistrements dans le navigateur. Cela permet à Android de faire correspondre les sources et les déclencheurs sur les sites et dans les applications.

Ce guide vous explique comment configurer l'attribution entre applications et sur le Web.

Lorsque vous configurez l'attribution cross-app et Web, nous vous recommandons vivement de vous familiariser également avec les solutions de débogage disponibles pour vérifier que votre configuration fonctionne comme prévu.

Enregistrer des sources et des déclencheurs avec l'OS Android

L'attribution entre applications et sur le Web ne sera disponible que si l'API Attribution Reporting est activée à la fois dans le navigateur et dans l'OS Android sur le même appareil. La disponibilité de l'API Android Attribution Reporting est envoyée via l'en-tête Attribution-Reporting-Support. Cet en-tête renverra "os", "web" ou les deux, selon ce qui est disponible sur l'appareil. Si les deux sont disponibles, les technologies publicitaires pourront choisir d'enregistrer les sources Web et les déclencheurs Web avec le navigateur ou l'OS.

La technologie publicitaire doit décider d'enregistrer la source Web ou le déclencheur Web auprès du navigateur ou de l'OS.

  • Pour les campagnes Web uniquement, les technologies publicitaires peuvent toujours enregistrer les sources et les déclencheurs avec l'API Attribution Reporting de Chrome, ou choisir de déléguer les deux à l'OS. Pour les campagnes Web uniquement où la source ou le déclencheur peuvent se produire dans une WebView, les technologies publicitaires doivent déléguer l'enregistrement de la source et du déclencheur à l'OS. Pour en savoir plus, consultez la section sur les WebViews.

  • Les technologies publicitaires doivent éviter d'enregistrer simultanément des sources et des déclencheurs avec les API Chrome et Android afin d'éviter de créer des rapports d'attribution en double.

  • L'attribution est effectuée séparément pour les navigateurs et l'OS. Si une source est enregistrée auprès du navigateur, mais que le déclencheur est enregistré auprès de l'OS, ces deux éléments ne peuvent pas être mis en correspondance, et inversement.

  • Pour les sources pouvant entraîner un déclencheur d'application ou Web, il est fortement recommandé que l'ad tech délègue les enregistrements de source et de déclencheur Web à l'API Android Attribution Reporting.

  • Pour les déclencheurs qui peuvent avoir été générés par des sources basées sur des applications, la technologie publicitaire peut choisir de déléguer l'enregistrement des déclencheurs Web à l'API Android Attribution Reporting.

  • Pour les campagnes dans lesquelles la source et le déclencheur se produisent dans une application, les deux devront être enregistrés avec l'API Attribution Reporting de l'OS.

Enregistrer une source d'application et un déclencheur Web

Pour certaines campagnes, la source peut se trouver dans une application, tandis que le déclencheur se trouve sur un site Web dans le navigateur mobile du même appareil.

Exemple

Un utilisateur lit des articles dans son application d'actualités préférée. Il voit une annonce pour des vols pas chers à destination de Paris et clique dessus avec enthousiasme pour réserver. La technologie publicitaire qui diffuse l'annonce dans l'application d'actualités enregistre la source du clic avec l'API Android Attribution Reporting. L'utilisateur est redirigé vers la page Web de l'annonceur dans Chrome, où il peut effectuer une conversion. La technologie publicitaire sur le site de l'annonceur vérifie si l'API au niveau de l'OS est disponible (ce qui est le cas). Elle enregistre le déclencheur de conversion en demandant à Chrome de déléguer l'enregistrement à l'OS au lieu de l'enregistrer directement avec l'API Attribution Reporting de Chrome. L'API Attribution Reporting au niveau de l'OS peut ensuite faire correspondre la source de l'application et le déclencheur Web, et envoyer les rapports concernés.

Flux d'attribution d'application à Web
Flux d'attribution de l'application au Web

Enregistrement de la source de l'application :

  1. Le SDK de technologie publicitaire de l'application Android Daily News enregistre le clic à l'aide de registerSource().

  2. L'API Attribution Reporting sur Android envoie une requête à l'URL du serveur de technologie publicitaire fournie à registerSource().

  3. Le serveur de technologie publicitaire répond avec l'en-tête Attribution-Reporting-Register-Source pour finaliser l'enregistrement de la source.

Enregistrement du déclencheur Web :

  1. La technologie publicitaire enregistre un déclencheur et vérifie la disponibilité de l'OS dans l'API Attribution Reporting.

  2. L'ARA Web renvoie des informations sur la plate-forme compatible.

  3. L'en-tête OS-Trigger indique à l'API ARA Web d'appeler la fonction registerWebTrigger() de l'API ARA OS.

  4. L'appel à registerWebTrigger() se produit en arrière-plan et le développeur n'a pas besoin d'appeler registerWebTrigger() directement avec l'OS.

  5. L'ARA de l'OS prend le relais et envoie une requête à l'URL du serveur ad tech fournie par l'en-tête Attribution-Reporting-Register-OS-Trigger.

  6. La technologie publicitaire finalise l'enregistrement du déclencheur avec l'API de l'OS.

  7. L'ARA de l'OS effectue l'attribution selon la même logique que celle appliquée à l'attribution d'application à application et envoie les mêmes rapports.

Workflow

Les étapes suivantes fournissent plus de détails sur la façon d'effectuer la tâche :

  1. La technologie publicitaire de l'application enregistre une source auprès de l'API Attribution Reporting d'Android avec les ajustements suivants :

    • Pour enregistrer une source d'application censée générer une conversion sur un site Web, l'en-tête de réponse Attribution-Reporting-Register-Source doit inclure une destination Web (eTLD+1) au lieu d'une destination d'application.
    Attribution-Reporting-Register-Source: {
    "web_destination": "https://advertiser.example",
    ...
}
    • Certains annonceurs peuvent utiliser plusieurs fournisseurs de mesure (par exemple, un outil de mesure tiers ou un outil d'analyse) à l'aide de chaînes de redirection 302. Dans certains cas, l'API Attribution Reporting suivra le chemin de redirection spécifié dans l'en-tête Attribution-Reporting-Redirect en arrière-plan, tandis que le chemin de redirection 302 s'exécutera au premier plan pour les demandes de navigation existantes. Ces demandes seront envoyées à la même URL et pourraient entraîner une double comptabilisation des inscriptions par le fournisseur de mesures tiers. Pour éviter le double comptage des enregistrements, les technologies publicitaires peuvent modifier le comportement de redirection afin d'envoyer l'enregistrement de l'API Attribution Reporting vers une autre URL déterministe.

    • Pour activer ce comportement, les technologies publicitaires doivent inclure un nouvel en-tête HTTP lorsqu'elles répondent à une demande d'enregistrement :

      • L'en-tête est Attribution-Reporting-Redirect-Config
      • La valeur de l'en-tête doit être "redirect-302-to-well-known".
      Attribution-Reporting-Redirect-Config: redirect-302-to-well-known

    • Le reste du processus d'enregistrement de la source est identique à celui d'un enregistrement de source standard d'application à application.

  2. La technologie publicitaire sur le site Web de l'annonceur enregistre le déclencheur en demandant à Chrome de déléguer l'enregistrement à l'API Android Attribution Reporting :

    • Lorsqu'un utilisateur effectue une conversion sur un site Web, la technologie publicitaire envoie une demande pour enregistrer le déclencheur auprès de Chrome.

      1. Une requête de pixel ou fetch() peut être utilisée pour enregistrer un déclencheur.

      2. L'en-tête de requête Attribution-Reporting-Support est renvoyé par Chrome à l'ad tech. Si l'API est activée à la fois sur le navigateur Chrome et sur l'appareil Android, l'en-tête renvoie os, web.

      Attribution-Reporting-Support: os, web

    • La technologie publicitaire doit ensuite indiquer à Chrome de déléguer au système d'exploitation à l'aide de l'en-tête Attribution-Reporting-Register-OS-Trigger, qui :

      1. Indique à Chrome de déléguer l'enregistrement à l'OS

      2. Chrome délègue l'enregistrement à l'OS en appelant la fonction de l'API de l'OS. registerWebTrigger()

        • L'appel à registerWebTrigger() se produit en arrière-plan. La technologie publicitaire n'a pas besoin d'appeler registerWebTrigger() directement.

      3. L'API OS lance un appel d'API secondaire à l'URI de technologie publicitaire transmis par le navigateur.

      Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger",
"https://other-adtech.example/register-trigger"

    • Dans certains cas, l'en-tête Attribution-Reporting-Support n'est pas disponible et ne peut pas être envoyé. Dans ce cas, la technologie publicitaire peut toujours définir une plate-forme préférée pour gérer l'enregistrement du déclencheur en incluant l'en-tête Attribution-Reporting-Info. La clé est "preferred-platform" et les valeurs autorisées sont os et web. Le navigateur utilise la plate-forme préférée lorsqu'elle est disponible et revient à la plate-forme Web lorsque l'OS n'est pas disponible.

    Attribution-Reporting-Info: preferred-platform=os
    • Pour finaliser l'enregistrement du déclencheur, le point de terminaison de la technologie publicitaire doit répondre à la requête de l'API Attribution Reporting Android à l'aide de l'en-tête de réponse.
    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

Enregistrer une source Web et un déclencheur d'application

Pour certaines campagnes, une source peut se produire sur un site dans un navigateur mobile, tandis que le déclencheur se produit dans une application sur le même appareil.

Exemple

Un utilisateur navigue sur un site dans son navigateur Chrome sur son téléphone Android. Il voit une annonce pour un pull de l'un de ses magasins préférés. Il clique sur l'annonce et est redirigé vers l'application qu'il a déjà téléchargée. La technologie publicitaire sur le site Web où l'annonce a été diffusée enregistre la source du clic en demandant à Chrome de déléguer l'enregistrement à l'API Android Attribution Reporting au lieu d'utiliser l'API Attribution Reporting sur Chrome. L'utilisateur achète le pull dans l'application d'achat. La technologie publicitaire de l'application de l'annonceur enregistre ensuite le déclencheur de conversion avec l'API Android Attribution Reporting. L'API Attribution Reporting au niveau de l'OS est capable d'associer la source Web et le déclencheur d'application, et d'envoyer les rapports correspondants.

Flux d'attribution Web to App
Flux d'attribution Web to App

Enregistrement de la source Web :

  1. La technologie publicitaire enregistre une source et vérifie la disponibilité de l'OS dans l'API Attribution Reporting.

  2. L'ARA Web renvoie des informations sur la plate-forme compatible.

  3. L'en-tête OS-Source indique à l'API ARA Web d'appeler la fonction registerWebSource() de l'API ARA OS.

  4. L'appel à registerWebSource() se produit en arrière-plan et le développeur n'a pas besoin d'appeler registerWebSource() directement avec l'OS.

  5. L'ARA de l'OS prend le relais et envoie une requête à l'URL du serveur ad tech fournie par l'en-tête Attribution-Reporting-Register-OS-Source.

  6. La technologie publicitaire enregistre la source avec l'API de l'OS.

Enregistrement du déclencheur d'application :

  1. Le SDK de technologie publicitaire dans l'application Android du magasin de vêtements enregistre le déclencheur auprès de l'ARA de l'OS.

  2. L'API Attribution Reporting sur Android envoie une requête à l'URL du serveur de technologie publicitaire fournie à registerTrigger().

  3. Le serveur de technologie publicitaire répond avec l'en-tête Attribution-Reporting-Register-Trigger pour finaliser l'enregistrement du déclencheur.

  4. L'ARA de l'OS effectue l'attribution selon la même logique que celle appliquée à l'attribution d'application à application et envoie les mêmes rapports.

Workflow

Les étapes suivantes fournissent plus de détails sur la façon d'effectuer la tâche :

  1. La technologie publicitaire sur le site Web de l'éditeur enregistre la source en demandant à Chrome de déléguer l'enregistrement à l'API Android Attribution Reporting :

    • Dans le cas d'utilisation Web vers application, lorsque vous enregistrez une source, le paramètre de source d'attribution doit être spécifié directement, soit à l'aide de la balise attributionsrc, soit à l'aide de l'enregistrement JavaScript.
    • L'exemple suivant utilise le tag attributionsrc pour spécifier le paramètre source :
    <img src="https://adtech.example/conversionpixel"
attributionsrc="https://adtech.example/register-source?purchase=12">

  2. L'en-tête de requête Attribution-Reporting-Support est renvoyé par Chrome à l'ad tech. Si l'API est activée à la fois dans le navigateur Chrome et sur l'appareil Android, l'en-tête renvoie os, web.

    Attribution-Reporting-Support: os, web

  3. La technologie publicitaire doit indiquer à Chrome de déléguer à l'API au niveau de l'OS à l'aide de l'en-tête Attribution-Reporting-Register-OS-Source, qui :

    1. Indique à Chrome de déléguer l'enregistrement à l'OS
    2. Chrome délègue l'enregistrement à l'OS en appelant la fonction de l'API de l'OS. registerWebSource()
    3. L'appel à registerWebSource() se produit en arrière-plan. La technologie publicitaire n'a pas besoin d'appeler registerWebSource() directement.
    4. L'API OS lance un appel d'API secondaire à l'URI de technologie publicitaire transmis par le navigateur.
    Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
    • Dans certains cas, l'en-tête Attribution-Reporting-Support n'est pas disponible. Dans ce cas, la technologie publicitaire peut toujours définir une plate-forme préférée pour gérer l'enregistrement de la source en incluant l'en-tête Attribution-Reporting-Info. La clé est "preferred-platform" et les valeurs autorisées sont os et web. Le navigateur utilisera la plate-forme préférée lorsqu'elle sera disponible et reviendra à la plate-forme Web lorsque l'OS ne sera pas disponible.
    Attribution-Reporting-Info: preferred-platform=os
    • Pour finaliser l'enregistrement de la source, le point de terminaison de la technologie publicitaire doit répondre à la requête de l'API Android Attribution Reporting avec l'en-tête de réponse Attribution-Reporting-Register-Source. La réponse doit également spécifier une destination d'application dans le champ de destination.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    ...
}
    • Pour prendre en charge les redirections pour les enregistrements de sources, Chrome suivra les redirections et appellera les API de contexte Web pour chaque saut de redirection.
    • Le reste de l'enregistrement de la source reste identique.

  4. La technologie publicitaire dans l'application de l'annonceur enregistre un déclencheur avec l'API Android Attribution Reporting :

    • Pour les déclencheurs qui se produisent dans les applications, celles-ci enregistrent les déclencheurs avec l'API Android Attribution Reporting comme d'habitude.

Campagnes avec des destinations potentielles pour les applications et le Web

  1. Configurer des destinations doubles

    • Certaines campagnes peuvent être configurées pour générer des conversions dans l'application de l'annonceur ou sur sa page Web, en fonction de divers facteurs (par exemple, si l'utilisateur a installé l'application).
    • Dans ce cas, il est recommandé de déléguer l'enregistrement de la source à l'OS, si disponible, afin que la source puisse être correctement attribuée, quel que soit l'emplacement du déclencheur. Lorsque vous enregistrez la source auprès de l'OS, vous pouvez spécifier une destination d'application et une destination Web dans les paramètres respectifs.
    • La destination de l'application doit figurer dans le champ destination.
    • La destination Web doit figurer dans le champ web_destination.
    • Les développeurs Chrome doivent noter que le champ destination de l'API Attribution Reporting pour OS doit être un package d'application et non une URL.
    Attribution-Reporting-Register-Source: {
    "source_event_id":"123001",
    "destination":"android-app://com.example.advertiser",
    "web_destination": "https://example.advertiser"
    ...
}
    • La section suivante sur les rapports approximatifs explique comment l'utilisation de deux destinations peut avoir un impact sur le bruit dans vos rapports.

  2. Utilisez les rapports approximatifs pour réduire le bruit dans les rapports au niveau des événements pour les sources à double destination :

    • Si une destination d'OS (application) et une destination Web ont été spécifiées lors de l'enregistrement de la source, les rapports au niveau des événements indiqueront par défaut si le déclencheur s'est produit dans une destination Web ou une destination d'application. Toutefois, pour respecter les limites de confidentialité, du bruit supplémentaire sera ajouté à ces rapports.
    • Les technologies publicitaires peuvent utiliser le champ coarse_event_report_destinations sous l'en-tête Attribution-Reporting-Register-Source pour activer les rapports approximatifs et réduire le bruit. Si une source avec le champ coarse_event_report_destinations spécifié remporte l'attribution, le rapport obtenu inclut à la fois les destinations d'application et Web, sans distinction de l'emplacement du déclencheur réel, mais avec moins de bruit que les rapports où la destination d'application ou Web est spécifiée.
    • Les rapports agrégés restent inchangés.

Pour les applications utilisant des onglets personnalisés Chrome

Certaines applications peuvent utiliser des onglets personnalisés pour afficher du contenu Web. Les onglets personnalisés se comportent de la même manière qu'une page Web standard lorsqu'ils sont mesurés dans les applications et sur les sites Web mobiles.

  1. Enregistrez une source d'application et un déclencheur d'onglet personnalisé :

  2. Enregistrez une source d'onglet personnalisé et un déclencheur d'application :

  3. Enregistrer une source et un déclencheur CCT

Pour les applications utilisant WebView

Certaines applications peuvent utiliser WebView pour afficher du contenu. WebView peut être utilisé dans de nombreux cas, par exemple pour afficher des annonces, héberger du contenu Web ou des fonctionnalités d'application personnalisées mieux adaptées à un format Web.

  1. Pour permettre aux WebViews d'utiliser l'API Attribution Reporting, l'application d'intégration doit être configurée avec les autorisations appropriées.

  2. Seule l'attribution au niveau de l'OS est disponible dans WebView. L'en-tête "Attribution-Reporting-Support" ne renvoie que l'OS, et uniquement si l'API Attribution Reporting d'Android est disponible.

  3. Lors de la délégation à l'OS, WebView peut utiliser registerSource ou registerWebSource et registerTrigger ou registerWebTrigger. Les méthodes utilisées par WebView sont définies par l'application qui affiche WebView et sont déterminées pour chaque WebView.

    • La différence entre registerSource et registerWebSource réside dans la source qui est enregistrée en tant qu'éditeur. Avec registerSource, l'application est enregistrée en tant qu'éditeur. Un exemple d'utilisation de registerSource serait une application d'éditeur qui affiche une annonce rendue à l'aide de WebView. Avec registerWebSource, le site Web hébergé dans WebView est enregistré en tant qu'éditeur. Un exemple d'utilisation de registerWebSource serait une application qui héberge un WebView et dont le site Web affiché par WebView diffuse des annonces. registerTrigger et registerWebTrigger se comportent de manière similaire. Le graphique de l'élément 3 détaille différents scénarios dans lesquels un développeur d'application ou de SDK souhaiterait configurer l'API pour utiliser registerSource ou registerWebSource, et registerTrigger ou registerWebTrigger.
    • Par défaut, WebView utilisera registerSource et registerWebTrigger lors de l'appel de l'API Android Attribution Reporting. Cette opération associe les sources à l'application et les déclencheurs à l'origine de premier niveau de l'URL dans la WebView lorsque le déclencheur se produit.

      • Si une application nécessite un comportement différent, elle devra utiliser une nouvelle méthode setAttributionRegistrationBehavior sur la classe androidx.webkit.WebViewSettingsCompat. Cette méthode spécifie si WebView doit appeler registerWebSource() ou registerWebTrigger() plutôt que registerSource() ou registerTrigger().

      • Ce comportement devra être défini pour chaque WebView initiée.

      • Si le SDK AdTech lance la WebView, il devra définir ce comportement par défaut.

      • Les applications qui souhaitent utiliser registerWebSource() pour associer les enregistrements de source au site Web dans WebView plutôt qu'à l'application doivent rejoindre la liste d'autorisation WebApp. Remplissez ce formulaire pour rejoindre la liste d'autorisation. Cette liste d'autorisation vise à réduire les considérations de confidentialité permettant d'établir la confiance pour le contexte Web.

      Valeur Description Exemple d'utilisation
      APP_SOURCE_AND_WEB_TRIGGER (par défaut) Permet aux applications d'enregistrer des sources d'application (sources associées au nom du package de l'application) et des déclencheurs Web (déclencheurs associés à l'eTLD+1) à partir de WebView. Applications qui utilisent WebView pour diffuser des annonces au lieu de permettre la navigation Web.
      WEB_SOURCE_AND_WEB_TRIGGER Permet aux applications d'enregistrer des sources Web et des déclencheurs Web à partir de WebView. Applications de navigateur basées sur WebView pour lesquelles des impressions et des conversions d'annonces peuvent se produire sur des sites Web dans WebView.
      APP_SOURCE_AND_APP_TRIGGER Permet aux applications d'enregistrer des sources d'application et des déclencheurs d'application à partir de WebView. Applications basées sur WebView pour lesquelles les impressions et les conversions d'annonces doivent toujours être associées à l'application plutôt qu'à l'eTLD+1 du composant WebView.
      DÉSACTIVÉ Désactive l'enregistrement des sources et des déclencheurs à partir de WebView.
    1. Enregistrement de sources et de déclencheurs depuis WebView

    2. Les technologies publicitaires doivent répondre aux enregistrements de source à l'aide de l'en-tête Attribution-Reporting-Register-OS-Source. En fonction du comportement défini pour WebView, cela appellera registerSource() ou registerWebSource() avec l'OS et lancera un appel d'API secondaire à partir de l'API Android Attribution Reporting vers l'URI de technologie publicitaire.

      • Pour finaliser l'enregistrement de la source, le point de terminaison de la technologie publicitaire doit répondre à la requête de l'API Attribution Reporting Android avec l'en-tête de réponse.
       Attribution-Reporting-Register-OS-Source: {
  "source_event_id":"123001",
  "destination":"android-app://com.example.advertiser",
  ...
}

    3. Le reste de l'enregistrement de la source reste identique.

    4. Les technologies publicitaires doivent répondre aux enregistrements de déclencheurs à l'aide de l'en-tête Attribution-Reporting-Register-OS-Trigger. En fonction du comportement défini pour WebView, cela appellera registerTrigger() ou registerWebTrigger() avec l'OS et lancera un appel d'API secondaire de Rb à l'URI de la technologie publicitaire.

    5. Pour finaliser l'enregistrement du déclencheur, le point de terminaison de la technologie publicitaire doit répondre à la requête de l'API Android Attribution Reporting avec l'en-tête de réponse.

    Attribution-Reporting-Register-OS-Trigger: {
    "event_trigger_data": [{"trigger_data":"1"}],
    "aggregatable_trigger_data": [
        {"key_piece":"0x400","source_keys":["campaignCounts"]},
        {"key_piece":"0xA80","source_keys":["geoValue"]}
    ],
    ...
}

Déboguer

Lorsque vous configurez une implémentation d'application vers le Web, nous vous recommandons de configurer des rapports de débogage pour vérifier si les sources et les déclencheurs sont correctement enregistrés et, si ce n'est pas le cas, pour obtenir des informations sur la raison.

Pour obtenir des étapes de dépannage générales concernant Attribution Reporting, consultez le manuel de dépannage.