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

L'API Attribution Reporting permet d'attribuer des actions entre les applications et le 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 les enregistrements de source et de déclencheur à l'API Attribution Reporting pour Android au lieu de gérer ces enregistrements dans le navigateur. Android peut ainsi faire correspondre les sources et les déclencheurs sur les sites et les applications.

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

Lorsque vous configurez l'attribution entre les applications et le Web, nous vous recommandons vivement de vous familiariser également avec les solutions de débogage disponibles pour vous assurer que votre configuration fonctionne comme prévu.

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

L'attribution entre les applications et 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 Attribution Reporting d'Android est envoyée via l'en-tête Attribution-Reporting-Support. Cet en-tête renvoie "os", "web" ou les deux, selon ce qui est disponible sur cet appareil. Si les deux sont disponibles, les technologies publicitaires ont alors le choix d'enregistrer des sources Web et des 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 à la fois 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 les enregistrements 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 auprès des API Chrome et Android afin d'éviter de créer des rapports d'attribution en double.

  • L'attribution se fait 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 Web ou une application, il est fortement recommandé à la technologie publicitaire de déléguer les enregistrements de source Web et de déclencheur à l'API Android Attribution Reporting.

  • Pour les déclencheurs qui peuvent avoir été générés par des sources basées sur une application, 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 doivent être enregistrés auprès de l'API Attribution Reporting de l'OS.

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

Pour certaines campagnes, la source peut se produire dans une application, tandis que le déclencheur se produit 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 vers Paris et clique avec enthousiasme pour réserver. La technologie publicitaire diffusant l'annonce dans l'application d'actualités enregistre la source de clic auprès de 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. Elle l'est. La technologie publicitaire 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, puis envoyer les rapports pertinents.

Flux d'attribution d'application à site Web
Flux d'attribution d'application à un site 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 de l'OS.

  4. L'appel à registerWebTrigger() se produit en interne, 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 appliquée à l'attribution d'application à application et envoie les mêmes rapports.

Workflow

Les étapes suivantes vous expliquent comment procéder:

  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 qui devrait 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 suit le chemin de redirection spécifié dans l'en-tête Attribution-Reporting-Redirect en arrière-plan, et le chemin de redirection 302 s'exécute en premier plan pour les requêtes de navigation existantes. Ces requêtes seront envoyées à la même URL et pourraient entraîner une double comptabilisation des enregistrements par le fournisseur de mesures tiers. Pour éviter de doubler le nombre d'enregistrements, les technologies publicitaires peuvent modifier le comportement de redirection afin d'envoyer l'enregistrement de l'API Attribution Reporting vers une URL alternative, mais déterministe.
    • Pour activer ce comportement, les technologies publicitaires doivent inclure un nouvel en-tête HTTP lorsqu'elles répondent à une requête 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 à un enregistrement de source standard d'une application à une autre.

  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:

    • Une fois qu'un utilisateur a effectué une conversion sur un site Web, la technologie publicitaire envoie une demande pour enregistrer le déclencheur dans Chrome.

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

      2. L'en-tête de requête Attribution-Reporting-Support est renvoyé par Chrome à la technologie publicitaire. 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
      
    • La technologie publicitaire doit ensuite demander à Chrome de déléguer à l'OS à 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 interne. La technologie publicitaire n'a pas besoin d'appeler registerWebTrigger() directement.
      3. L'API de l'OS lance un appel d'API secondaire à l'URI de la 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 Android Attribution Reporting à 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 d'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 de clic en demandant à Chrome de déléguer l'enregistrement à l'API Attribution Reporting d'Android au lieu d'utiliser l'API Attribution Reporting sur Chrome. L'utilisateur achète le pull dans l'application de shopping. 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 peut faire correspondre la source Web et le déclencheur de l'application, puis envoyer les rapports pertinents.

Flux d'attribution Web vers application
Flux d'attribution Web vers application

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 de l'OS.

  4. L'appel à registerWebSource() se produit en interne, 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 de technologie publicitaire fournie par l'en-tête Attribution-Reporting-Register-OS-Source.

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

Enregistrement du déclencheur d'application :

  1. Le SDK de technologie publicitaire de l'application Android de la boutique 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 appliquée à l'attribution d'application à application et envoie les mêmes rapports.

Workflow

Les étapes suivantes vous expliquent comment procéder:

  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:

    • Pour un 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 la balise attributionsrc pour spécifier le paramètre de 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 à la technologie publicitaire. 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 interne. La technologie publicitaire n'a pas besoin d'appeler registerWebSource() directement.
    4. L'API de l'OS lance un appel d'API secondaire à l'URI de la 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 utilise la plate-forme préférée lorsqu'elle est disponible et se rabat sur la plate-forme Web lorsque l'OS n'est 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 inchangé.
  4. La technologie publicitaire de l'application de l'annonceur enregistre un déclencheur auprès de l'API Android Attribution Reporting:

    • Pour les déclencheurs qui se produisent dans les applications, les applications 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 ou sur la page Web de l'annonceur, en fonction de divers facteurs, comme si l'utilisateur a installé l'application.
    • Dans ce cas, il est recommandé de déléguer l'enregistrement de la source à l'OS, le cas échéant, 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 à la fois 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 de l'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 bruts explique comment l'utilisation de destinations doubles peut avoir un impact sur le bruit dans vos rapports.
  2. Utilisez des rapports bruts pour réduire le bruit dans les rapports au niveau des événements pour les sources à double destination:

    • Si un OS (application) et une destination Web ont été spécifiés dans l'enregistrement de la source, les rapports au niveau des événements spécifient si le déclencheur s'est produit dans une destination Web ou une destination d'application par défaut. Toutefois, pour respecter les limites de confidentialité, un 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 bruts 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 Web et d'appli, sans distinction de l'emplacement du déclencheur réel, mais avec moins de bruit que les rapports dans lesquels la destination Web ou d'application est spécifiée.
    • Les rapports agrégés restent inchangés.

Pour les applications qui utilisent les onglets personnalisés Chrome

Certaines applications peuvent utiliser des onglets personnalisés pour afficher du contenu Web. Les onglets personnalisés se comportent comme une page Web standard lors des mesures dans les applications et 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 qui utilisent WebView

Certaines applications peuvent utiliser WebView pour afficher du contenu. WebView présente différents cas d'utilisation, tels que l'affichage d'annonces, l'hébergement de contenu Web ou les fonctionnalités d'application personnalisées plus 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, ainsi que registerTrigger ou registerWebTrigger. Les méthodes utilisées par WebView sont définies par l'application qui effectue le rendu de la WebView et sont déterminées par WebView.

    • La différence entre registerSource et registerWebSource réside dans la source enregistrée en tant qu'éditeur. Avec registerSource, l'application est enregistrée en tant qu'éditeur. Un exemple d'utilisation de registerSource est une application d'éditeur qui affiche une annonce affichée à l'aide de WebView. Avec registerWebSource, le site Web hébergé dans la WebView est enregistré en tant qu'éditeur. Par exemple, une application qui héberge une WebView et le site Web affiché par la WebView diffusent des annonces.registerWebSource registerTrigger et registerWebTrigger se comportent de manière similaire. Le graphique de l'élément 3 détaille les différents scénarios dans lesquels un développeur d'application ou de SDK souhaite 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 doit utiliser la 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 doit être défini pour chaque WebView lancée.

      • Si le SDK de technologie publicitaire lance la WebView, il doit définir ce comportement par défaut.

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

      Valeur Description Exemple de cas 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. Enregistrements 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 la WebView, registerSource() ou registerWebSource() sera appelé avec l'OS et un appel d'API secondaire sera lancé à partir de l'API Android Attribution Reporting vers l'URI de la 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 Android Attribution Reporting 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 inchangé.

    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 la WebView, registerTrigger() ou registerWebTrigger() sera appelé avec l'OS et un appel d'API secondaire sera lancé à partir de Rb vers 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 application pour l'implémentation Web, nous vous recommandons de configurer des rapports de débogage afin de vérifier si les sources et les déclencheurs sont correctement enregistrés. Si ce n'est pas le cas, vous recevrez des informations sur la raison.

Pour connaître les étapes générales de débogage des rapports sur l'attribution, consultez le guide de débogage.