Configurer des rapports de débogage pour Attribution Reporting

Partie 2 sur 3 sur le débogage d'Attribution Reporting. Configurez vos rapports de débogage.

Remarque:Cet article fait partie d'une série sur le débogage de l'API Attribution Reporting. Cette série traite du débogage côté client pour les rapports au niveau des événements et les rapports agrégables. Les conseils de débogage côté serveur pour les rapports récapitulatifs sont disponibles sur GitHub.

Glossaire

• L'origine du rapport est l'origine qui [définit les en-têtes de source et de déclencheur Attribution Reporting. Tous les rapports générés par le navigateur sont envoyés à cette origine. Dans ces conseils, nous utilisons https://adtech.example comme exemple d'origine du rapport.
• Un rapport d'attribution (rapport en abrégé) est le rapport final (au niveau de l'événement ou agrégable) qui contient les données de mesure que vous avez demandées.
• Un rapport de débogage contient des données supplémentaires sur un rapport sur l'attribution, ou sur un événement de source ou de déclencheur. La réception d'un rapport de débogage ne signifie pas nécessairement que quelque chose ne fonctionne pas correctement. Il existe deux types de rapports de débogage.
• Un rapport de débogage de transition est un rapport de débogage qui nécessite la définition d'un cookie pour être généré et envoyé. Les rapports de débogage de transition ne sont plus disponibles si aucun cookie n'est défini, et une fois les cookies tiers obsolètes. Tous les rapports de débogage décrits dans ce guide sont des rapports de débogage de transition.
• Les rapports de débogage de réussite permettent d'analyser la génération d'un rapport sur l'attribution. Elles sont directement liées à un rapport sur l'attribution. Les rapports de débogage de réussite sont disponibles depuis Chrome 101 (avril 2022).
• Les rapports de débogage détaillés permettent de suivre les rapports manquants et de vous aider à déterminer pourquoi. Ils indiquent les cas où le navigateur n'a enregistré aucun événement de source ou déclencheur (ce qui signifie qu'il ne génère pas de rapport sur l'attribution), et les cas où un rapport sur l'attribution ne peut pas être généré ni envoyé pour une raison quelconque. Les rapports de débogage de type "verbose" incluent un champ type qui décrit la raison pour laquelle un événement source, un événement déclencheur ou un rapport sur l'attribution n'ont pas été générés. Les rapports de débogage détaillés sont disponibles à partir de Chrome 109 (stable en janvier 2023).
• Les clés de débogage sont des identifiants uniques que vous pouvez définir côté source et côté déclencheur. Les clés de débogage vous permettent de mapper les conversions basées sur les cookies et les conversions basées sur l'attribution. Une fois que vous avez configuré votre système pour générer des rapports de débogage et définir des clés de débogage, le navigateur les inclura dans tous les rapports sur l'attribution et les rapports de débogage.

Pour découvrir d'autres concepts et termes clés utilisés dans notre documentation, consultez le glossaire de la Privacy Sandbox.

Vous avez des questions concernant l'implémentation ?

Si vous rencontrez un problème lors de la configuration des rapports de débogage, signalez un problème dans notre dépôt d'assistance pour les développeurs afin que nous vous aidions à le résoudre.

Préparer la configuration des rapports de débogage

Avant de configurer des rapports de débogage, procédez comme suit:

Vérifier que vous avez appliqué les bonnes pratiques d'intégration de l'API

• Vérifiez que votre code est protégé par la détection des fonctionnalités. Pour vous assurer que l'API n'est pas bloquée par Permissions-Policy, exécutez le code suivant:

  if (document.featurePolicy.allowsFeature('attribution-reporting')) {
  // the Attribution Reporting API is enabled
  }
  

  Si ce contrôle de détection de fonctionnalité renvoie la valeur "true", l'API est autorisée dans le contexte (page) où la vérification est exécutée.

• (Facultatif pendant la phase de test: vérifiez que vous avez défini une règle Permissions-Policy)

Important:Les exigences du règlement relatif aux autorisations ont été assouplies pour les tests, mais un éditeur ou un annonceur peut toujours décider de désactiver explicitement l'API Attribution Reporting à l'aide de l'en-tête Permissions-Policy. Dans ce cas, aucune source ni aucun déclencheur ne peuvent être enregistrés (et par conséquent, aucun rapport ne peut être généré ni envoyé).

Résoudre les problèmes d'intégration fondamentaux

Bien que les rapports de débogage soient utiles pour vous aider à détecter et à analyser la perte à grande échelle, certains problèmes d'intégration peuvent être détectés localement. Les problèmes de configuration des en-têtes de source et de déclencheur, d'analyse JSON, de contexte non sécurisé (autre que HTTPS) et d'autres problèmes qui empêchent l'API de fonctionner sont listés dans l'onglet Problèmes dans DevTools.

Remarque:Ces problèmes ne génèrent pas de rapports de débogage détaillés, car ils empêchent l'API de fonctionner. Seule l'absence de rapports de débogage réussis indique que vous pouvez rencontrer certains de ces problèmes. Pour en savoir plus, consultez la Partie 3: Déboguer le livre de recettes.

Il existe différents types de problèmes dans les outils de développement. Si vous rencontrez un problème invalid header, copiez l'en-tête dans l'outil de validation des en-têtes. Cela vous aidera à identifier et à corriger le champ à l'origine du problème.

Configurer des rapports de débogage: étapes courantes des rapports de réussite et des rapports de type "verbose"

Étape 1: Définissez le cookie de débogage

Définissez le cookie suivant sur l'origine du rapport:

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

Le navigateur vérifie la présence de ce cookie à la fois lors de l'enregistrement de la source et du déclencheur. Le rapport de débogage de réussite n'est généré que si le cookie est présent aux deux moments.

Code de démonstration: cookie de débogage

Notez que les rapports de débogage peuvent être activés pour les navigateurs en mode B, où les cookies tiers sont désactivés afin de faciliter les tests et la préparation à l'abandon des cookies tiers. Pour les navigateurs en mode B, vous n'avez pas besoin de définir le cookie de débogage pour activer les rapports de débogage. Passez à l'étape 2 pour configurer les clés de débogage en vue de générer des rapports de débogage réussis.

Étape 2: Définissez les clés de débogage

Chaque clé de débogage doit être un entier non signé de 64 bits au format chaîne en base 10. Faites de chaque clé de débogage un ID unique. Le rapport de débogage de réussite n'est généré que si les clés de débogage sont définies.

• Mappez la clé de débogage côté source avec des informations supplémentaires sur l'heure à la source que vous pensez être utiles pour le débogage.
• Mappez la clé de débogage côté déclencheur avec des informations supplémentaires sur l'heure du déclencheur que vous pensez être pertinentes pour le débogage.

Par exemple, vous pouvez définir les clés de débogage suivantes:

• ID de cookie + horodatage source en tant que clé de débogage source (et capturez le même horodatage dans votre système basé sur les cookies)
• ID de cookie + horodatage du déclencheur en tant que clé de débogage du déclencheur (et capturez le même horodatage dans votre système basé sur les cookies)

Vous pouvez ainsi utiliser les informations de conversion basées sur les cookies pour rechercher les rapports de débogage ou d'attribution correspondants. Pour en savoir plus, consultez la Partie 3 : Livre de recettes.

La clé de débogage côté source doit être différente de source_event_id, afin de pouvoir différencier les rapports individuels ayant le même ID d'événement source.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}

Code de démonstration: clé de débogage source Code de démonstration: clé de débogage du déclencheur

Remarque:Dans le code de démonstration, nous attribuons aux deux clés de débogage la valeur de l'ancien cookie tiers de mesure. Dans un système réel, vous transformeriez chaque clé en un identifiant unique et le mapperiez à des informations supplémentaires sur l'heure source que vous jugeriez utiles pour le débogage, comme suggéré dans les exemples de clés de débogage ci-dessus.

Configurer des rapports de débogage de réussite

Remarque:Essayez la démonstration pour générer et prévisualiser des rapports de débogage de réussite dans votre navigateur. Examinez le code correspondant.

L'exemple de code de cette section génère des rapports de débogage de réussite pour les rapports au niveau des événements et les rapports agrégables. Les rapports au niveau des événements et les rapports agrégables utilisent les mêmes clés de débogage.

Étape 3: Configurez un point de terminaison pour collecter des rapports de débogage de réussite

Configurez un point de terminaison pour collecter les rapports de débogage. Ce point de terminaison doit être semblable au point de terminaison d'attribution principal, avec une chaîne debug supplémentaire dans le chemin:

• Point de terminaison pour les rapports de débogage de réussite au niveau de l'événement :https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
  • Point de terminaison pour les rapports de débogage de réussite agrégables : https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

Lorsqu'une attribution est déclenchée, le navigateur envoie immédiatement un rapport de débogage via une requête POST à ce point de terminaison. Le code de votre serveur permettant de gérer les rapports de débogage de réussite entrants peut se présenter comme suit (ici, sur un point de terminaison de nœud):

// Handle incoming event-Level Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-event-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

// Handle incoming aggregatable Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-aggregate-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

Code de démonstration: point de terminaison des rapports de débogage au niveau des événements

Code de démonstration: point de terminaison des rapports de débogage agrégables

Étape 4: Vérifiez que votre configuration génère des rapports de débogage de réussite

• Ouvrez chrome://attribution-internals dans votre navigateur.
• Assurez-vous que la case Afficher les rapports de débogage est cochée dans les onglets Rapports au niveau des événements et Rapports agrégables.
• Ouvrez les sites sur lesquels vous avez implémenté Attribution Reporting. Suivez les étapes permettant de générer des rapports sur l'attribution. Ces mêmes étapes généreront des rapports de débogage de réussite.
• Dans chrome://attribution-internals :
  • Vérifiez que les rapports sur l'attribution sont correctement générés.
  • Dans les onglets Rapports au niveau de l'événement et Rapports agrégables, vérifiez que les rapports de débogage de réussite sont également générés. Reconnaissez-les dans la liste à l'aide de leur chemin d'accès debug bleu.

• Sur votre serveur, vérifiez que votre point de terminaison reçoit immédiatement ces rapports de débogage de réussite. Assurez-vous de vérifier les rapports de débogage de réussite au niveau des événements et les rapports de débogage de réussite agrégables.

Étape 5: Examinez les rapports de débogage de réussite

Un rapport de débogage de réussite est identique à un rapport sur l'attribution, et contient à la fois les clés de débogage côté source et côté déclencheur.

{
  "attribution_destination": "https://advertiser.example",
  "randomized_trigger_rate": 0.0000025,
  "report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
  "source_debug_key": "647775351539539",
  "source_event_id": "760938763735530",
  "source_type": "event",
  "trigger_data": "0",
  "trigger_debug_key": "156477391437535"
}

{
  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
      "payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
    }
  ],
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
  "source_debug_key": "647775351539539",
  "trigger_debug_key": "156477391437535"
}

Configurer des rapports de débogage de type "verbose"

Remarque:Essayez la démonstration pour générer et prévisualiser des rapports de débogage de type "verbose" dans votre navigateur. Examinez le code correspondant.

Étape 3: Activez le débogage détaillé dans les en-têtes de la source et du déclencheur

Définissez debug_reporting sur true dans Attribution-Reporting-Register-Source et Attribution-Reporting-Register-Trigger.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Demo code: source header (Code de démonstration : en-tête source)

Demo code: trigger header (Code de démonstration : en-tête du déclencheur)

Étape 4: Configurez un point de terminaison pour collecter des rapports de débogage détaillés

Configurez un point de terminaison pour collecter les rapports de débogage. Ce point de terminaison doit être semblable au point de terminaison d'attribution principal, avec une chaîne debug/verbose supplémentaire dans le chemin:

https://adtech.example/.well-known/attribution-reporting/debug/verbose

Lorsque des rapports de débogage de type "verbose" sont générés, c'est-à-dire lorsqu'une source ou un déclencheur n'est pas enregistré, le navigateur envoie immédiatement un rapport de débogage détaillé à ce point de terminaison via une requête POST. Le code de votre serveur permettant de gérer les rapports de débogage détaillés entrants peut se présenter comme suit (ici, sur un point de terminaison de nœud):

// Handle incoming verbose debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/verbose',
  async (req, res) => {
    // List of verbose debug reports is in req.body
    res.sendStatus(200);
  }
);

Contrairement aux rapports de débogage de réussite, les rapports de type "verbose" ne disposent que d'un seul point de terminaison. Les rapports détaillés qui concernent les rapports agrégés et les rapports au niveau des événements sont tous envoyés au même point de terminaison.

Code de démonstration: point de terminaison des rapports de débogage détaillés

Étape 5: Vérifiez que votre configuration génère des rapports de débogage détaillés

Bien qu'il existe de nombreux types de rapports de débogage détaillés, il suffit de vérifier votre configuration de débogage de type "verbose" avec un seul type de rapport de débogage détaillé. Si ce type de rapport de débogage de type "verbose" est correctement généré et reçu, tous les types de rapports de débogage de type "verbose" seront également générés et reçus correctement. En effet, tous les rapports de débogage de type "verbose" utilisent la même configuration et sont envoyés au même point de terminaison.

Important:Choisissez un rapport de débogage détaillé et facile à tester. trigger-no-matching-source est un bon candidat, car vous pouvez le générer par conversion. Les rapports détaillés liés aux événements déclencheurs sont généralement plus adaptés. Les types de rapports détaillés liés aux événements sources sont plus fastidieux à générer délibérément.

1. Ouvrez chrome://attribution-internals dans votre navigateur.
2. Déclenchez une attribution (conversion) sur votre site configuré avec Attribution Reporting. Étant donné qu'il n'y a pas eu d'engagement avec l'annonce (impression ou clic) avant cette conversion, attendez-vous à recevoir un rapport de débogage détaillé de type trigger-no-matching-source.
3. Dans chrome://attribution-internals, ouvrez l'onglet Rapports de débogage de type "verbose" et vérifiez qu'un rapport de débogage de type trigger-no-matching-source a été généré.
4. Sur votre serveur, vérifiez que votre point de terminaison a immédiatement reçu ce rapport de débogage détaillé.

Étape 6: Consultez les rapports de débogage détaillés

Les rapports de débogage détaillés générés au moment du déclencheur incluent à la fois la clé de débogage côté source et côté déclencheur (s'il existe une source correspondante pour le déclencheur). Les rapports de débogage détaillés générés au moment de la source incluent la clé de débogage côté source.

Exemple de requête contenant des rapports de débogage de type "verbose" envoyés par le navigateur:

[
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "randomized_trigger_rate": 0.0000025,
      "report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_type": "event",
      "trigger_data": "1",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-event-low-priority"
  },
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "limit": "65536",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_site": "http://arapi-publisher.localhost",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-aggregate-insufficient-budget"
  }
]

Important:Contrairement à une requête de débogage réussie, le corps d'une requête de débogage détaillée contient une liste (tableau) de rapports détaillés.

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

Type

Raisons pour lesquelles le rapport a été généré. Pour en savoir plus sur tous les types de rapports de type "verbose" et les actions à effectuer en fonction de chaque type, consultez la documentation de référence sur les rapports de type "verbose" dans la Partie 3: Débogage du livre de recettes.

Body

Corps du rapport. Tout dépend de son type. Consultez la documentation de référence sur les rapports détaillés dans la Partie 3: Déboguer le livre de recettes.

Le corps d'une requête contient au moins un rapport détaillé et au maximum deux:

• Un rapport détaillé si l'échec n'affecte que les rapports au niveau des événements (ou s'il n'affecte que les rapports agrégables). Un échec d'enregistrement de la source ou du déclencheur n'a qu'une seule raison : un rapport détaillé peut donc être généré par échec et par type de rapport (au niveau de l'événement ou agrégable).
• Deux rapports de type "verbose" si l'échec affecte les rapports au niveau des événements et les rapports agrégables, à une exception près : si le motif de l'échec est le même pour les rapports au niveau des événements et les rapports agrégables, un seul rapport de type "verbose" est généré (par exemple, trigger-no-matching-source).

À suivre

Partie 3: Déboguer le livre de recettes