Se usó la API de Cloud Translation para traducir esta página.

Cómo configurar informes de depuración para Attribution Reporting

Parte 2 de 3 sobre la depuración de Attribution Reporting. Configura tus informes de depuración.

Glosario

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

如需了解我们的文档中使用的更多概念和关键术语，请参阅 Privacy Sandbox 术语表。

¿Tienes preguntas sobre la implementación?

Si tienes algún problema durante la configuración de los informes de depuración, crea uno en nuestro repositorio de asistencia para desarrolladores y te ayudaremos a solucionarlo.

Prepárate para configurar informes de depuración

Antes de configurar informes de depuración, sigue estos pasos:

Verifica que hayas aplicado las prácticas recomendadas para la integración de la API

Verifica que tu código esté protegido por la detección de funciones. Para asegurarte de que la API no esté bloqueada por la Política de permisos, ejecuta el siguiente código:
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
Si esta verificación de detección de funciones muestra un valor verdadero, la API se permite en el contexto (página) en el que se ejecuta la verificación.
(No es obligatorio durante la fase de prueba: verifica que hayas configurado una Permissions-Policy).

Cómo solucionar problemas fundamentales de integración

Si bien los informes de depuración son útiles para ayudarte a detectar y analizar las pérdidas a gran escala, algunos problemas de integración pueden detectarse a nivel local. Los problemas de configuración incorrecta del encabezado de origen y del activador, los problemas de análisis de JSON, el contexto no seguro (no HTTPS) y otros problemas que impiden que la API funcione aparecerán en la pestaña Problemas de DevTools.

Los problemas de DevTools pueden ser de diferentes tipos. Si tienes un problema con invalid header, copia el encabezado en la herramienta de validación de encabezados. Esto te ayudará a identificar y corregir el campo que causa el problema.

Valida los encabezados de Attribution Reporting

Puedes usar el validador de encabezados para validar los encabezados relacionados con la API de Attribution Reporting. Puedes supervisar los errores de validación que se originan en el navegador para facilitar la depuración de la API.

Para habilitar la recepción de informes de depuración, responde con report-header-errors como parte del encabezado de respuesta Attribution-Reporting-Info.

Attribution-Reporting-Info: report-header-errors

Ten en cuenta que Attribution-Reporting-Info es un encabezado estructurado de diccionarioAttribution-Reporting-Info, por lo que proporcionar la clave booleana report-header-errors implica un valor verdadero.

Los informes de depuración se envían de inmediato al extremo de informes:

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

Los datos del informe se incluyen en el cuerpo de la solicitud como una lista JSON de objetos con el siguiente formato:

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

Captura de pantalla: Herramienta de validación de encabezados

Configura informes de depuración: pasos comunes para los informes de éxito y los detallados

Configure la siguiente cookie en el origen de los informes:

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

El navegador verificará la presencia de esta cookie en el registro de la fuente y del activador. El informe de depuración exitoso solo se generará si la cookie está presente en ambos momentos.

Código de demostración: cookie de depuración

Ten en cuenta que los informes de depuración se pueden habilitar para los navegadores en el modo B, en los que se inhabilitan las cookies de terceros para facilitar las pruebas y la preparación para la baja de las cookies de terceros. En el caso de los navegadores en modo B, no es necesario configurar la cookie de depuración para habilitar los informes de depuración. Avanza al paso 2 para configurar las claves de depuración para el éxito de los informes de depuración.

Paso 2: Configura claves de depuración

Cada clave de depuración debe ser un número entero de 64 bits sin firma con formato de cadena de base 10. Haz que cada clave de depuración tenga un ID único. El informe de depuración de éxito solo se generará si se configuran las claves de depuración.

Asigna la clave de depuración del código fuente a información adicional del tiempo de origen que consideres relevante para depurar.
Asigna la clave de depuración del activador a la información adicional del tiempo de activación que consideres relevante para depurar.

Por ejemplo, puedes establecer las siguientes claves de depuración:

ID de cookie + marca de tiempo de origen como clave de depuración de origen (y captura esa misma marca de tiempo en tu sistema basado en cookies)
ID de cookie + marca de tiempo del activador como clave de depuración del activador (y captura esa misma marca de tiempo en tu sistema basado en cookies)

Con esto, puedes usar la información de conversiones basada en cookies para buscar los informes de depuración o de atribución correspondientes. Obtén más información en la Parte 3: guía de recetas.

Haz que la clave de depuración del lado de la fuente sea diferente de source_event_id para que puedas diferenciar los informes individuales que tienen el mismo ID de evento de origen.

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"
}

Código de demostración: clave de depuración de la fuente Código de demostración: clave de depuración del activador

Configura informes de depuración de atribución correcta

El código de ejemplo en esta sección genera informes de depuración de éxito para informes a nivel del evento y agregables. Los informes agregables y a nivel del evento usan las mismas claves de depuración.

Paso 3: Configura un extremo para recopilar informes de depuración correctos

Configura un extremo para recopilar los informes de depuración. Este extremo debe ser similar al extremo de atribución principal, con una string debug adicional en la ruta de acceso:

Extremo para los informes de depuración correcta a nivel del evento: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Extremo para informes de depuración de éxito aggregables: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

Cuando se active una atribución, el navegador enviará de inmediato un informe de depuración a través de una solicitud POST a este extremo. El código de tu servidor para manejar los informes de depuración de éxito entrantes puede ser similar a lo siguiente (aquí en un extremo de nodo):

// 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);
  }
);

Código de demostración: extremo de informes de depuración a nivel del evento

Código de demostración: extremo de informes de depuración agregables

Paso 4: Confirma que tu configuración generará informes de depuración correctos

Abre chrome://attribution-internals en el navegador.
Asegúrate de que la casilla de verificación Show Debug Reports esté marcada en las pestañas Event-Level Reports y Aggregatable Reports.
Abre los sitios en los que implementaste los Informes de atribución. Completa los pasos que usas para generar informes de atribución. Estos mismos pasos generarán informes de depuración correctos.
En chrome://attribution-internals, haz lo siguiente:
- Verifica que los informes de atribución se generen correctamente.
- En las pestañas Informes a nivel del evento y Informes agregables, verifica que también se generen los informes de depuración correctos. Reconócelas en la lista con la ruta de acceso debug azul.

Captura de pantalla: Elementos internos de Attribution

En tu servidor, verifica que tu extremo reciba inmediatamente estos informes de depuración correctos. Asegúrate de verificar los informes de depuración de éxito a nivel del evento y los informes agregables.

Captura de pantalla: Informe de registros del servidor de origen

Paso 5: Observa los informes de depuración correctos

Un informe de depuración de éxito es idéntico a un informe de atribución y contiene las claves de depuración del lado de la fuente y del activador.

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

Configura informes de depuración detallados

Paso 3: Habilita la depuración detallada en la fuente y los encabezados del activador

Establece debug_reporting en true en Attribution-Reporting-Register-Source y 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
}

Código de demostración: encabezado de fuente

Código de demostración: encabezado del activador

Paso 4: Configura un extremo para recopilar informes de depuración detallados

Configurar un extremo para recopilar los informes de depuración Este extremo debe ser similar al extremo de atribución principal, con una cadena debug/verbose adicional en la ruta de acceso:

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

Cuando se generan informes de depuración detallados, es decir, cuando no se registra una fuente o un activador, el navegador enviará de inmediato un informe de depuración detallado a través de una solicitud POST a este extremo. Es posible que el código del servidor para controlar los informes de depuración detallados entrantes se vea de la siguiente manera (aquí en un extremo de nodo):

// 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);
  }
);

A diferencia de los informes de depuración correctos, solo hay un extremo para los informes detallados. Los informes detallados que se relacionan con los informes agregados y a nivel del evento se enviarán al mismo extremo.

Código de demostración: extremo de informes detallados de depuración

Paso 5: Confirma que la configuración generará informes de depuración detallados

Si bien existen numerosos tipos de informes de depuración detallados, es suficiente con verificar la configuración de depuración detallada con solo un tipo de informe de depuración detallado. Si este tipo de informe de depuración detallado se genera y recibe correctamente, todos los tipos de informes de depuración detallados también se generarán y recibirán correctamente, ya que todos los informes de depuración detallados usan la misma configuración y se envían al mismo extremo.

Punto clave: Elige un informe de depuración detallado que sea fácil de probar. trigger-no-matching-source es un buen candidato, ya que puedes generarlo mediante una conversión. Los informes detallados que se relacionan con eventos de activación suelen ser mejores candidatos; los tipos de informes detallados que se relacionan con eventos de origen son más tediosos de generar a propósito.

Abre chrome://attribution-internals en tu navegador.
Activa una atribución (conversión) en tu sitio que esté configurada con Attribution Reporting. Dado que no hubo participación en el anuncio (impresión o clic) antes de esta conversión, se generará un informe de depuración detallado del tipo trigger-no-matching-source.
En chrome://attribution-internals, abre la pestaña Informes de depuración detallados y verifica que se haya generado un informe de depuración detallado de tipo trigger-no-matching-source.
En tu servidor, verifica que el extremo haya recibido de inmediato este informe de depuración detallado.

Paso 6: Observa los informes de depuración detallados

Los informes de depuración detallados que se generan en el momento del activador incluyen la clave de depuración del activador y la de la fuente (si hay una fuente coincidente para el activador). Los informes de depuración detallados que se generan en el momento de la fuente incluyen la clave de depuración del lado de la fuente.

Ejemplo de una solicitud que contiene informes de depuración detallados que envía el navegador:

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

Cada informe detallado contiene los siguientes campos:

Type: Es la razón por la que se generó el informe. Para obtener información sobre todos los tipos de informes detallados y qué medidas tomar según cada uno, consulta la referencia de informes detallados en la Parte 3: Guía de soluciones de depuración.
Body: El cuerpo del informe. Dependerá de su tipo. Revisa la referencia de informes detallados en la Parte 3: Recetario de depuración.

El cuerpo de una solicitud contendrá al menos uno y dos informes detallados como máximo:

Un informe detallado si la falla solo afecta a los informes a nivel del evento (o si solo afecta a los informes agregables) Una falla de registro de fuente o activador solo tiene un motivo, por lo que se puede generar un informe detallado por falla y por tipo de informe (a nivel del evento o agregable).
Dos informes detallados si la falla afecta a los informes a nivel del evento y a los informes agregables, con una excepción: si el motivo de la falla es el mismo para los informes a nivel del evento y los informes agregables, solo se genera un informe detallado (por ejemplo, trigger-no-matching-source)

A continuación

Parte 3: Guía de soluciones de depuración