Certaines technologies de la Privacy Sandbox sont en cours d'abandon.

Consultez notre information sur l'avenir des technologies de la Privacy Sandbox. La page État des fonctionnalités de la Privacy Sandbox fournit plus d'informations sur l'état des différentes API et fonctionnalités de la plate-forme.

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

Configurer des rapports de débogage pour Attribution Reporting

Deuxième partie sur trois du débogage d'Attribution Reporting. Configurez vos rapports de débogage.

Glossaire

L'origine des rapports est l'origine qui définit les en-têtes de source et de déclencheur d'Attribution Reporting. Tous les rapports générés par le navigateur sont envoyés à cette origine. Dans ce guide, nous utilisons https://adtech.example comme exemple d'origine de création de rapports.
Un rapport sur l'attribution (rapport en abrégé) est le rapport final (au niveau des événements 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 une source ou un événement déclencheur. L'envoi 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 seront pas 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'assurer le suivi des rapports sur l'attribution générés correctement. 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 peuvent suivre les rapports manquants et vous aider à déterminer pourquoi ils sont manquants. Elles 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é ou envoyé pour une raison quelconque. Les rapports de débogage détaillés incluent un champ type qui décrit la raison pour laquelle un événement source, un événement déclencheur ou un rapport d'attribution n'a pas été généré. Les rapports de débogage détaillés sont disponibles à partir de Chrome 109 (version 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 inclut ces clés de débogage dans tous les rapports sur l'attribution et dans tous 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.

Des questions sur l'implémentation ?

Si vous rencontrez des problèmes lors de la configuration des rapports de débogage, créez un problème dans notre dépôt d'assistance aux développeurs. Nous vous aiderons à le résoudre.

Préparer la configuration des rapports de débogage

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

Vérifiez que vous avez appliqué les bonnes pratiques pour l'intégration de l'API.

Vérifiez que votre code est protégé par 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 la 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.
(Non requis lors de la phase de test : vérifiez que vous avez défini une Permissions-Policy.)

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 les pertes à grande échelle, certains problèmes d'intégration peuvent être détectés localement. Les problèmes de configuration incorrecte des en-têtes de source et de déclencheur, les problèmes d'analyse JSON, les contextes non sécurisés (non HTTPS) et les autres problèmes qui empêchent l'API de fonctionner s'affichent dans l'onglet Problèmes des outils de développement.

Les problèmes liés aux outils de développement 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 Attribution Reporting

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

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

Attribution-Reporting-Info: report-header-errors

Notez qu'Attribution-Reporting-Info est un en-tête structuré sous forme de dictionnaireAttribution-Reporting-Info. Par conséquent, fournir la clé booléenne report-header-errors implique une valeur "true".

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

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

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

[{
  "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
  }
}]

Configurer les rapports de débogage : étapes communes aux rapports de réussite et aux rapports détaillés

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

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

Le navigateur vérifiera la présence de ce cookie lors de 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 aux deux moments.

Code de démonstration : cookie debug

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 pour 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 pour les rapports de débogage "success".

É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 jugez pertinentes pour le débogage.
Mappez la clé de débogage côté déclencheur à des informations supplémentaires sur le moment du déclencheur qui vous semblent pertinentes pour le débogage.

Par exemple, vous pouvez 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 ce même code temporel dans votre système basé sur les cookies)

Vous pouvez ainsi utiliser les informations sur les conversions 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.

Définissez une clé de débogage côté source différente de source_event_id afin de pouvoir différencier les rapports individuels qui ont 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

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 de l'événement 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 d'attribution principal, avec une chaîne debug supplémentaire dans le chemin d'accès :

Point de terminaison pour les rapports de débogage sur le succès 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 agrégables sur les réussites : 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 à ce point de terminaison à l'aide d'une requête POST. 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è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 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 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 grâce à leur chemin d'accès bleu debug.

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 réussite au niveau des événements et agrégables.

Signaler les journaux du serveur d'origine

Étape 5 : Examiner les rapports de débogage "success"

Un rapport de débogage "success" est identique à un rapport d'attribution et contient 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 détaillés

Étape 3 : Activez le débogage détaillé 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 source

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

Étape 4 : Configurez un point de terminaison pour collecter des 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é à ce point de terminaison à l'aide d'une requête POST. Le code de votre serveur pour gérer les rapports de débogage détaillés entrants peut ressembler à ce qui 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, il n'existe qu'un seul point de terminaison pour les rapports détaillés. Les rapports détaillés liés aux rapports au niveau des événements et aux rapports agrégés 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 : Confirmez 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 détaillés, il suffit de vérifier la configuration du débogage détaillé avec un seul type de rapport de débogage détaillé. Si ce type de rapport de débogage détaillé est correctement généré et reçu, cela signifie que tous les types de rapports de débogage détaillés seront également correctement 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 détaillé qui est facile à tester. trigger-no-matching-source est un bon candidat, car vous pouvez le générer en effectuant une conversion. Les rapports détaillés liés aux événements déclencheurs sont généralement de meilleurs candidats. Les types de rapports détaillés liés aux événements sources 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 devriez obtenir un rapport de débogage détaillé de type trigger-no-matching-source.
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 : Observer 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 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 détaillés, envoyée 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: Origine du rapport. Pour en savoir plus sur tous les types de rapports détaillés et sur les actions à effectuer en fonction de chaque type, consultez la référence sur les rapports détaillés dans le manuel de débogage, partie 3.
Body: Corps du rapport. Cela dépendra de son type. Consultez la documentation de référence sur les rapports détaillés dans la partie 3 du guide de dépannage.

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

Un rapport détaillé si l'échec n'affecte que les rapports au niveau des événements (ou uniquement les rapports agrégables). Un échec d'enregistrement de source ou de déclencheur n'a qu'une seule raison. Par conséquent, un rapport détaillé peut être généré par échec et par type de rapport (au niveau de l'événement ou agrégable).
Deux rapports détaillés si l'échec affecte à la fois les rapports au niveau des événements et les rapports agrégables (sauf si la raison de l'échec est la même pour les deux types de rapports, auquel cas un seul rapport détaillé est généré, par exemple : trigger-no-matching-source)

À suivre

Partie 3 : Guide de débogage