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

L'API Attribution Reporting permet d'attribuer des sources à plusieurs applications et sur le Web et les déclencheurs qui se produisent sur le même appareil. Les navigateurs, comme Chrome, peuvent déléguer les enregistrements de sources et de 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 à la fois sur les sites et dans les applications.

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

Lorsque vous configurez l'attribution Web et entre applications, il est vivement recommandé familiarisez-vous avec les solutions de débogage disponibles pour vous assurer fonctionne correctement.

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

L'attribution multi-applications et Web ne sera disponible que si L'API Reporting est activée à la fois dans le navigateur et dans l'OS Android 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, en fonction de ce qui est disponible sur cet appareil. Si les deux disponibles, les technologies publicitaires auront alors le choix d'enregistrer des sources Web et des avec le navigateur ou le système d'exploitation.

La technologie publicitaire doit décider d'enregistrer la source Web ou le déclencheur Web. avec le navigateur ou le système d'exploitation.

  • 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, pour lesquelles la source ou le déclencheur peuvent se produire 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 classes WebView.
  • Les technologies publicitaires doivent éviter d'enregistrer les sources et les déclencheurs avec Chrome et les API Android simultanément afin d'éviter de créer des attributions en double rapports.
  • L'attribution s'effectue séparément pour les navigateurs et le système d'exploitation. Si une source est enregistré dans le navigateur, mais le déclencheur est enregistré auprès du système d'exploitation, ces deux ne peuvent pas être mises en correspondance et inversement.
  • Pour les sources susceptibles de déclencher un déclencheur Web ou d'application, il est fortement recommandé pour que la technologie publicitaire délègue la source Web et déclenche les enregistrements à l'API Android Attribution Reporting.
  • Pour les déclencheurs qui ont pu être pilotés par des sources basées sur l'application, la technologie publicitaire peut choisir de déléguer l'enregistrement du déclencheur Web à Android Attribution Reporting API.
  • Pour les campagnes dont la source et le déclencheur se produisent dans une application, les deux doivent être enregistrés auprès de l'API OS Attribution Reporting.

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

Pour certaines campagnes, la source peut se produire dans une application alors que le déclencheur se produit. sur un site Web dans le navigateur mobile sur le 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 mots clés vols vers Paris et se réjouir de cliquer pour réserver. La technologie publicitaire diffusant 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, sur laquelle il peut convertir. La technologie publicitaire sur le site de l'annonceur vérifie si l'API au niveau du système d'exploitation est disponible, et c’est le cas. La technologie publicitaire enregistre le déclencheur de conversion demander à Chrome de déléguer l'enregistrement au système d'exploitation au lieu de l'enregistrer. directement avec l'API Attribution Reporting de Chrome. Attribution au niveau du système d'exploitation L'API Reporting peut alors faire correspondre la source de l'application et le déclencheur Web, et envoyer les rapports pertinents.

<ph type="x-smartling-placeholder">
</ph> Flux d&#39;attribution Application/Web
Flux d'attribution Application/Web
.

Enregistrement de la source d'application:

  1. Le SDK de technologie publicitaire de l'application Android Actualités quotidiennes enregistre le clic en utilisant registerSource()

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

  3. Le serveur de technologie publicitaire répond avec le code source Attribution-Reporting-Register-Source en-tête pour terminer 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 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 Web ARA d'appeler l'API OS ARA Fonction registerWebTrigger()

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

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

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

  7. OS ARA effectuera l'attribution selon la même logique appliquée à app<>d'attribution d'application et d'envoyer les mêmes rapports

Workflow

Les étapes suivantes incluent des détails supplémentaires sur la façon d'effectuer cette tâche:

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

    • Pour enregistrer une source d'application censée générer une conversion sur un site Web, l'élément L'en-tête de réponse Attribution-Reporting-Register-Source doit inclure une URL (eTLD+1) au lieu d'une destination d'application.
    Attribution-Reporting-Register-Source: {
        "web_destination": "https://advertiser.example",
        ...
    }
    
      .
    • Certains annonceurs peuvent faire appel à plusieurs fournisseurs de solutions de mesure (par exemple, (un outil de mesure ou d'analyse tiers) par le biais 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 et à dans le même temps que le chemin de redirection 302 s'exécute au premier plan pour les requêtes de navigation. Ces requêtes seront dirigées vers la même URL et pourraient se produire dans les enregistrements en double des enregistrements du fournisseur de mesure tiers. À éviter la double comptabilisation des enregistrements, les technologies publicitaires peuvent modifier le comportement de redirection pour envoyer l'enregistrement de l'API Attribution Reporting vers une autre solution une URL déterministe.
    • Pour activer ce comportement, les technologies publicitaires doivent inclure un nouvel en-tête HTTP lorsque en réponse à une demande d'inscription:

      • 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 le même que pour enregistrement de la source d'une application à une autre.

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

    • Une fois qu'un utilisateur effectue une conversion sur un site Web, la technologie publicitaire effectue une demande d'enregistrement du déclencheur avec 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 dans le 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 au système d'exploitation à l'aide du Attribution-Reporting-Register-OS-Trigger:

      1. Demande à Chrome de déléguer l'enregistrement au système d'exploitation

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

        • L'appel à registerWebTrigger() s'effectue 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 la technologie publicitaire transmis à depuis 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 préférence plate-forme pour gérer l'enregistrement du déclencheur en incluant En-tête Attribution-Reporting-Info. La clé est "Preferred-platform", les valeurs autorisées sont os et web. Le navigateur utilisera la plate-forme préférée le cas échéant et reviendra à la plateforme web lorsque le système d’exploitation sera indisponible.

    Attribution-Reporting-Info: preferred-platform=os
    
    • Pour terminer l'enregistrement du déclencheur, le point de terminaison de la technologie publicitaire doit répondre à la requête 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, la source peut apparaître sur un site dans un navigateur mobile alors que le se déclenche dans une application sur le même appareil.

Exemple

Un utilisateur consulte un site dans le navigateur Chrome de 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 le bouton annonce et sont redirigés vers l'application qu'il a déjà téléchargée. La technologie publicitaire le site Web sur lequel l'annonce a été diffusée enregistre la source du clic en demandant à Chrome pour déléguer l'enregistrement à l'API Android Attribution Reporting à l'aide de l'API Attribution Reporting sur Chrome. L'utilisateur achète le pull l'application d'achat. La technologie publicitaire dans l'application de l'annonceur enregistre ensuite le déclencheur de conversion avec l'API Android Attribution Reporting. Au niveau de l'OS L'API Attribution Reporting peut faire correspondre la source Web et le déclencheur d'application. envoyer les rapports pertinents.

<ph type="x-smartling-placeholder">
</ph> Flux d&#39;attribution Web-to-App
Flux d'attribution Web-application
.

Enregistrement de la source Web:

  1. La technologie publicitaire enregistre une source et vérifie la disponibilité de l'OS dans 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 Web ARA d'appeler l'API OS ARA Fonction registerWebSource()

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

  5. L'ARA du système d'exploitation prend le relais et envoie une demande à l'URL du serveur de technologie publicitaire fournie par l'en-tête Attribution-Reporting-Register-OS-Source

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

Enregistrement du déclencheur d'application:

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

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

  3. Le serveur de technologie publicitaire renvoie le code Attribution-Reporting-Register-Trigger pour terminer l'enregistrement du déclencheur

  4. OS ARA effectuera l'attribution selon la même logique appliquée à app<>d'attribution d'application et d'envoyer les mêmes rapports

Workflow

Les étapes suivantes incluent des détails supplémentaires sur la façon d'effectuer cette tâche:

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

    • Pour un cas d'utilisation web-to-app, lors de l'enregistrement d'une source, l'attribution le paramètre source doit être spécifié directement, soit à l'aide de la méthode la balise attributionsrc ou à 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 les technologies publicitaires. 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"
    
  3. La technologie publicitaire doit indiquer à Chrome de déléguer à l'API au niveau du système d'exploitation à l'aide de la méthode Attribution-Reporting-Register-OS-Source:

    1. Demande à Chrome de déléguer l'enregistrement au système d'exploitation
    2. Chrome délègue l'enregistrement à l'OS en appelant la fonction de l'API OS registerWebSource()
    3. L'appel à registerWebSource() se produit en arrière-plan, la technologie publicitaire pas besoin d'appeler registerWebSource() directement
    4. L'API OS lance un appel d'API secondaire à l'URI de la technologie publicitaire transmis depuis 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 à gérer. l'enregistrement de la source en incluant l'en-tête Attribution-Reporting-Info. La clé correspond à la plate-forme préférée, et les valeurs autorisées sont os et web. La le navigateur utilise la plate-forme préférée disponible et utilise la plateforme Web lorsque le système d’exploitation n’est pas disponible.
    Attribution-Reporting-Info: preferred-platform=os
    
    • Pour terminer l'enregistrement de la source, le point de terminaison de la technologie publicitaire doit répondre à la requête API Android Attribution Reporting avec l'en-tête de réponse Attribution-Reporting-Register-Source La réponse doit également spécifier vers la destination de l'application dans le champ de destination.
    Attribution-Reporting-Register-Source {
        "source_event_id":"123001",
        "destination":"android-app://com.example.advertiser",
        ...
    }
    
  4. La technologie publicitaire dans l'application de l'annonceur enregistre un déclencheur avec Android API Attribution Reporting:

    • Pour les déclencheurs qui se produisent dans les applications, celles-ci enregistrent les déclencheurs à l'aide du paramètre API Android Attribution Reporting, comme d'habitude.

Campagnes associées à des destinations potentielles (application et Web)

  1. Configurer deux destinations

    • Certaines campagnes peuvent être configurées pour générer des conversions dans l'application de l'annonceur sur la page Web de l'annonceur, en fonction de différents facteurs, par exemple si l'utilisateur où l'application est installée.
    • Dans ce cas, nous vous recommandons de déléguer l'enregistrement de la source (si disponible) afin que la source puisse être attribuée correctement de l'emplacement du déclencheur. Lors de l'enregistrement de la source auprès du système d'exploitation, une l'application et la destination Web peuvent être spécifiées dans leurs paramètres respectifs.
    • La destination de l'application doit se trouver dans le champ destination
    • La destination Web doit se trouver dans le champ web_destination
    • Les développeurs Chrome doivent noter que le champ destination pour le système d'exploitation L'API Attribution Reporting 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 sommaires vous expliquera comment utiliser deux destinations. peut avoir un impact sur le bruit de vos rapports.
  2. Utilisez des rapports sommaires pour réduire le bruit dans les rapports au niveau des événements pour les sources de la destination:

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

Pour les applications utilisant les onglets personnalisés Chrome

Certaines applications peuvent utiliser les onglets personnalisés pour afficher le contenu Web. Comportement des onglets personnalisés de la même manière qu'une page Web standard pour les mesures dans les applications et les sites Web mobiles.

  1. Enregistrez une source d'application et un déclencheur d'onglet personnalisé: <ph type="x-smartling-placeholder">
  2. Enregistrez une source d'onglet personnalisé et un déclencheur d'application: <ph type="x-smartling-placeholder">
  3. Enregistrer une source et un déclencheur CCT <ph type="x-smartling-placeholder">

Pour les applications utilisant WebView

Certaines applications peuvent utiliser WebView pour afficher du contenu. Il existe différents cas d'utilisation pour WebView, comme l'affichage d'annonces, l'hébergement de contenu Web ou d'applications personnalisées plus adaptées à un format Web.

  1. Seule l'attribution au niveau de l'OS est disponible dans WebView. La L'en-tête Attribution-Reporting-Support renvoie uniquement os, et seulement si L'API Android Attribution Reporting est disponible.

  2. Lors de la délégation à l'OS, WebView peut utiliser registerSource ou registerWebSource et registerTrigger ou registerWebTrigger. Quelles sont les méthodes utilisé par WebView est défini par l'application qui l'affiche et est déterminé par par WebView.

    • La différence entre registerSource et registerWebSource est la suivante : la source est consignée en tant qu'éditeur. Avec registerSource, l'application est journalisée en tant qu'éditeur ; un exemple d'utilisation de registerSource serait une application d'éditeur qui diffuse une annonce affichée à l'aide de WebView. Avec registerWebSource, le site Web hébergé dans WebView est enregistré en tant que éditeur un exemple d'utilisation de registerWebSource serait une application qui héberge un composant WebView, qui affiche le site Web la diffusion d'annonces. registerTrigger et registerWebTrigger se comportent de la même manière. La Le graphique de l'élément 3 détaille les différents scénarios dans lesquels le développeur d'une application ou d'un SDK configurer l'API pour qu'elle utilise registerSource ou registerWebSource, et registerTrigger ou registerWebTrigger.
  3. Par défaut, WebView utilise registerSource et registerWebTrigger lorsque en appelant l'API Android Attribution Reporting. Cela associe des sources à l'application et les déclencheurs avec 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 androidx.webkit.WebViewSettingsCompat . Cette méthode indiquera si WebView doit appeler registerWebSource() ou registerWebTrigger() au lieu de registerSource() ou registerTrigger().
      • Vous devez définir ce comportement pour chaque WebView lancé.
      • Si le SDK de technologie publicitaire lance WebView, il devra définir ce comportement par défaut.
      • Pour les applications qui souhaitent utiliser registerWebSource() pour associer la source auprès du site Web dans WebView et non de l'application, ils doivent rejoindre la liste d'autorisation d'applications Web. Remplissez ce formulaire pour la rejoindre. La l'objectif de la liste d'autorisation est de limiter les considérations liées à la confidentialité établir la confiance pour le contexte Web.
    • Options pour setAttributionRegistrationBehavior
    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 de la source et du déclencheur à partir de WebView.
  4. Enregistrements de sources et de déclencheurs à partir de WebView

    • Les technologies publicitaires doivent répondre aux enregistrements de sources à l'aide de la méthode En-tête Attribution-Reporting-Register-OS-Source. En fonction du comportement défini pour WebView, cela appelle registerSource() ou registerWebSource(). avec le système d'exploitation et lancer un appel d'API secondaire à partir du module Reporting à l'URI de la technologie publicitaire.

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

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

    • Pour terminer l'enregistrement du déclencheur, le point de terminaison de la technologie publicitaire doit répondre à la requête API Android Attribution Reporting avec la réponse en-tête.
    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 l'implémentation d'une application pour le Web, il est recommandé de configurer le débogage pour vérifier si les sources et les déclencheurs sont enregistrés correctement, et s'ils ne sont pas enregistrés, pour recevoir des informations sur la raison.

Pour connaître les étapes générales de débogage d'Attribution Reporting, consultez le livre de recettes de débogage.