Cette page a été traduite par l'API Cloud Translation.

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.

Glossaire

报告来源是用于设置归因报告来源和触发器标头的来源。浏览器生成的所有报告都会发送到此源。在本指南中，我们使用 https://adtech.example 作为示例报告来源。
归因报告（简称“报告”）是包含您请求的衡量数据的最终报告（事件级报告或可汇总报告）。
调试报告包含有关归因报告或者来源或触发器事件的其他数据。收到调试报告并不一定表示存在问题！调试报告有两种
过渡调试报告是一种调试报告，需要设置 Cookie 才能生成和发送。如果 Cookie 未设置且第三方 Cookie 被弃用，过渡调试报告将不可用。本指南中描述的所有调试报告都是过渡性调试报告。
成功调试报告用于跟踪成功生成归因报告。它们与归因报告直接相关。从 Chrome 101（2022 年 4 月）开始，已提供成功调试报告。
详细调试报告可以跟踪缺失的报告，并帮助您确定缺失报告的原因。它们分别用于表明浏览器未记录来源或触发器事件（这意味着浏览器不会生成归因报告）以及由于某种原因无法生成或发送归因报告的情况。详细调试报告包含一个 type 字段，用于说明未生成来源事件、触发器事件或归因报告的原因。从 Chrome 109（2023 年 1 月稳定版）开始提供详细调试报告。
调试键是您可以在来源端和触发器端设置的唯一标识符。通过调试键，您可以映射基于 Cookie 的转化和基于归因的转化。将系统设置为生成调试报告并设置调试密钥后，浏览器会将这些调试密钥添加到所有归因报告和调试报告中。

如需了解我们的文档中使用的更多概念和关键术语，请参阅 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, créez un problème dans notre dépôt d'assistance pour les développeurs. Nous vous aiderons à résoudre le problème.

Préparer la configuration des rapports de débogage

Avant de configurer les 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 soumis à la détection de 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 cette vérification de détection de caractéristiques renvoie la valeur "true", l'API est autorisée dans le contexte (page) dans lequel la vérification est exécutée.
(Facultatif pendant la phase de test: vérifiez que vous avez défini un élément Permissions-Policy)

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

Bien que les rapports de débogage vous aident à 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 de l'en-tête de source et de déclencheur, les problèmes d'analyse JSON, le contexte non sécurisé (non-HTTPS) et d'autres problèmes qui empêchent le fonctionnement de l'API s'affichent dans l'onglet Problèmes de DevTools.

Les problèmes DevTools peuvent être de différents types. 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.

Valider les en-têtes des rapports sur l'attribution

Vous pouvez utiliser le validateur d'en-tête pour valider les en-têtes liés à l'API Attribution Reporting. Vous pouvez surveiller les erreurs de validation provenant du navigateur afin de faciliter le débogage de l'API.

Pour activer la réception de rapports de débogage, répondez avec report-header-errors dans l'en-tête de réponse Attribution-Reporting-Info.

Attribution-Reporting-Info: report-header-errors

Notez que Attribution-Reporting-Info est un en-tête structuré de dictionnaireAttribution-Reporting-Info. Par conséquent, fournir la clé booléenne report-header-errors implique une valeur réelle.

Les rapports de débogage sont envoyés immédiatement au point de terminaison des rapports:

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

Les données de rapport sont incluses dans le corps de la requête sous la forme d'une liste JSON d'objets ayant le format suivant:

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]

Capture d'écran: outil de validation d'en-tête

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

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 pour l'enregistrement de la source et du déclencheur. Le rapport de débogage de réussite ne sera généré que si le cookie est présent à ces deux moments.

Code de démonstration: debug cookie

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, il n'est pas nécessaire de définir le cookie de débogage pour activer les rapports de débogage. Passez à l'étape 2 pour configurer des clés de débogage afin de générer des rapports de débogage de réussite.

É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. Attribuez un ID unique à chaque clé de débogage. Le rapport de débogage de réussite ne sera généré que si les clés de débogage sont définies.

Mappez la clé de débogage côté source à des informations supplémentaires au moment de la source que vous pensez utiles pour le débogage.
Mappez la clé de débogage côté déclencheur sur des informations supplémentaires sur le moment du déclencheur que vous pensez utiles pour le débogage.

Vous pouvez par exemple définir les clés de débogage suivantes:

ID de cookie + code temporel source en tant que clé de débogage source (et capturez ce même code temporel dans votre système basé sur les cookies)
ID de cookie + code temporel 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.

Faites en sorte que la clé de débogage côté source soit 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 de la source Code de démonstration : clé de débogage du déclencheur

Configurer les rapports de débogage "success"

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 les 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 principal de l'attribution, avec une chaîne debug supplémentaire dans le chemin:

Point de terminaison pour les rapports de débogage de réussite au niveau des événements : https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Point de terminaison pour les rapports de débogage de succès 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 pour 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érera 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é les rapports sur l'attribution. Suivez les étapes que vous utilisez pour générer des rapports sur l'attribution. Ces mêmes étapes généreront des rapports de débogage de réussite.
Dans la fonction chrome://attribution-internals :
- Vérifiez que les rapports sur l'attribution sont correctement générés.
- Dans les onglets Rapports au niveau des événements et Rapports agrégables, vérifiez que les rapports de débogage de réussite sont également générés. Vous les reconnaîtrez dans la liste grâce à 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. Veillez à vérifier les rapports de débogage de succès au niveau des événements et agrégables.

Capture d'écran : journaux du serveur d'origine de création de rapports

Étape 5: Observez 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 les rapports de débogage de type "verbose"

Étape 3 : Activez le débogage de type "verbose" dans les en-têtes de source et de 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
}

Code de démonstration : en-tête de source

Code de démonstration : en-tête de déclencheur

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

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

Lorsque des rapports de débogage détaillés 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é via une requête POST à ce point de terminaison. Le code du serveur permettant de gérer les rapports de débogage "verbose" entrants peut se présenter comme suit (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 succès, il n'existe qu'un seul point de terminaison pour les rapports de type "verbose". Les rapports détaillés liés aux rapports au niveau des événements et agrégables seront 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érera des rapports de débogage détaillés

Bien qu'il existe de nombreux types de rapports de débogage de type "verbose", il suffit de vérifier votre configuration de débogage de type "verbose" avec un seul type. 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" sont également générés et reçus, car ils utilisent tous la même configuration et sont envoyés au même point de terminaison.

Important:Choisissez un rapport de débogage de type "verbose" et simple à 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 de déclencheur sont généralement plus adaptés. Les types de rapports détaillés liés aux événements de source sont plus difficiles à générer intentionnellement.

Ouvrez chrome://attribution-internals dans votre navigateur.
Déclenchez une attribution (conversion) sur votre site configuré avec Attribution Reporting. Étant donné qu'il n'y a eu aucune interaction avec l'annonce (impression ou clic) avant cette conversion, vous devez vous attendre à ce qu'un rapport de débogage détaillé de type trigger-no-matching-source soit généré.
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é.
Sur votre serveur, vérifiez que votre point de terminaison a immédiatement reçu ce rapport de débogage détaillé.

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

Les rapports de débogage de type "verbose" 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é 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"
  }
]

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

Type: Raison pour laquelle le rapport a été généré. Pour en savoir plus sur tous les types de rapports de type "verbose" et les mesures à prendre en fonction de chacun d'eux, consultez la documentation de référence sur les rapports de type "verbose" dans la Partie 3: livre de recettes sur le débogage.
Body: Corps du rapport. Cela dépend de son type. Consultez la référence des rapports de type "verbose" dans la partie 3 : Guide de débogage.

Le corps d'une requête contient au moins un et deux rapports de type "verbose" :

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 de type "verbose" 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 à la fois 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é (exemple : trigger-no-matching-source).

À suivre

Partie 3: Livre de recettes sur le débogage