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.

Nota: Este artículo forma parte de una serie sobre la depuración de la API de Attribution Reporting. En esta serie, se aborda la depuración del cliente para los informes a nivel del evento y los informes agregables. La guía de depuración del servidor para informes de resumen está disponible en GitHub.

Glosario

• El origen de los informes es el origen que [establece la fuente y los encabezados del activador de Attribution Reporting. Todos los informes que genera el navegador se envían a este origen. En esta guía, usamos https://adtech.example como origen de informes de ejemplo.
• Un informe de atribución (también conocido como informe) es el informe final (a nivel del evento o agregable) que contiene los datos de medición que solicitaste.
• Un informe de depuración contiene datos adicionales sobre un informe de atribución o sobre una fuente o un evento activador. Recibir un informe de depuración no significa necesariamente que algo esté funcionando de forma incorrecta. Existen dos tipos de informes de depuración
• Un informe de depuración de transición es aquel que requiere que se configure una cookie para que se pueda generar y enviar. Los informes de depuración transitorios no estarán disponibles si no se configura una cookie y una vez que las cookies de terceros dejen de estar disponibles. Todos los informes de depuración que se describen en esta guía son informes de depuración transitorios.
• Los informes de depuración de errores realizan un seguimiento de la generación correcta de un informe de atribución. Se relacionan directamente con un informe de atribución. Los informes de depuración correcta están disponibles desde Chrome 101 (abril de 2022).
• Los informes de depuración detallados pueden hacer un seguimiento de los informes faltantes y ayudarte a determinar por qué no aparecen. Indican casos en los que el navegador no registró una fuente o un evento activador (lo que significa que no generará un informe de atribución) y casos en los que, por algún motivo, no se puede generar ni enviar un informe de atribución. Los informes de depuración detallados incluyen un campo type que describe el motivo por el que no se generó un evento de fuente, un evento de activador o un informe de atribución. Los informes de depuración detallados están disponibles a partir de la versión 109 de Chrome (estable a partir de enero de 2023).
• Las claves de depuración son identificadores únicos que puedes configurar en el lado del código fuente y en el del activador. Las claves de depuración te permiten asignar conversiones basadas en cookies y conversiones basadas en atribuciones. Cuando hayas configurado tu sistema para generar informes de depuración y establecer claves de depuración, el navegador incluirá estas claves de depuración en todos los informes de atribución y de depuración.

Para conocer más conceptos y términos clave que se usan en nuestra documentación, consulta el glosario de Privacy Sandbox.

¿Tienes preguntas sobre la implementación?

Si tienes algún problema mientras configuras informes de depuración, crea un problema 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:

Comprueba que aplicaste las prácticas recomendadas para la integración de APIs

• Verifica que tu código esté restringido detrás de la detección de funciones. Para asegurarte de que la política de permisos no bloquee la API, 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 atributos 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 Política de Permisos).

Punto clave: Se disminuyeron los requisitos de la Política de Permisos para las pruebas, pero los publicadores o anunciantes aún pueden inhabilitar explícitamente la API de Attribution Reporting mediante la Política de Permisos. En este caso, no se puede registrar ninguna fuente ni activador (y, por lo tanto, no se puede generar ni enviar ningún informe).

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 se pueden detectar de forma local. Los problemas de configuración incorrecta del encabezado de fuente y activador, los problemas de análisis de JSON, el contexto no seguro (no HTTPS) y otros problemas que impiden el funcionamiento de la API se mostrarán en la pestaña Problemas de Herramientas para desarrolladores.

Nota: Estos problemas no generarán informes de depuración detallados, ya que provocan que la API no funcione. Solo la ausencia de informes de depuración correctos indica que es posible que encuentres algunos de estos problemas. Obtén más información en la Parte 3: Guía de soluciones de depuración.

Los problemas de Herramientas para desarrolladores pueden ser de diferentes tipos. Si encuentras 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.

Cómo configurar informes de depuración: pasos comunes para los informes de éxito y los informes detallados

Paso 1: Configura la cookie de depuración

Establece 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 de éxito solo se generará si la cookie está presente en ambos momentos.

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

Ten en cuenta que se pueden habilitar los informes de depuración para los navegadores en el modo B, en el que las cookies de terceros están inhabilitadas 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 necesitas configurar la cookie de depuración para habilitar los informes de depuración. Ve al paso 2 para configurar claves de depuración para informes de depuración de éxito.

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. Convierte cada clave de depuración en 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 lado del código fuente a la información adicional del tiempo de origen que consideres relevante para la depuración.
• Asigna la clave de depuración del lado del activador a información adicional del tiempo de activación que consideres relevante para la depuración.

Por ejemplo, podrías configurar las siguientes claves de depuración:

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

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

Haz que la clave de depuración del lado del código fuente sea diferente de source_event_id para poder diferenciar los informes individuales que tengan 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 origen Código de demostración: clave de depuración de activador

Nota: En el código de demostración, asignamos a ambas claves de depuración el valor de la cookie de medición heredada de terceros. En un sistema real, convertirías cada clave en un ID único y la asignarías a la información adicional de hora de origen que consideres útil para la depuración, como se sugiere en los ejemplos de claves de depuración anteriores.

Cómo configurar informes de depuración de éxito

Nota: Prueba la demostración para generar informes de depuración de éxito y obtener una vista previa en tu navegador. Revisa el código correspondiente.

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

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

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

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

Cuando se activa una atribución, el navegador enviará de inmediato un informe de depuración a este extremo a través de una solicitud POST. El código de servidor para administrar los informes de depuración correctos entrantes puede verse de la siguiente manera (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 de éxito

• Abre chrome://attribution-internals en el navegador.
• Asegúrate de que la casilla de verificación Mostrar informes de depuración esté marcada en las pestañas Informes de nivel del evento y Informes agregables.
• Abre los sitios en los que implementaste Attribution Reporting. Completa los pasos que utilizas para generar informes de atribución; con estos mismos pasos se generarán informes de depuración de éxito.
• En chrome://attribution-internals:
  • Comprobar que los Informes de atribución se generen correctamente
  • En la pestaña Informes de nivel del evento y en la pestaña Informes agregables, verifica que los informes de depuración de éxito también se generen. Reconócelos en la lista con su ruta debug azul.

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

Paso 5: Observa los informes de depuración de éxito

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 del código 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"
}

Cómo configurar informes de depuración detallados

Nota: Prueba la demostración para generar informes de depuración detallados y obtener una vista previa en tu navegador. Revisa el código correspondiente.

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

Establece debug_reporting como 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 fuente

Código de demostración: encabezado del activador

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

Configura 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:

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 este extremo a través de una solicitud POST. El código de tu servidor para manejar los informes de depuración detallados entrantes puede verse 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 correctamente, solo hay un extremo para los informes detallados. Los informes detallados que se relacionan con los informes a nivel del evento y los agregados se enviarán al mismo extremo.

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

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

Si bien hay numerosos tipos de informes de depuración detallados, basta 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, esto significa que todos los tipos de informes de depuración detallados también se generarán y recibirán de forma correcta, 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 con una conversión. Los informes detallados que se relacionan con los eventos de activación suelen ser mejores candidatos, mientras que los tipos de informes detallados que se relacionan con eventos fuente son más tediosos para generarlos de forma deliberada.

1. Abre chrome://attribution-internals en el navegador.
2. Activa una atribución (conversión) en tu sitio que se configure con Attribution Reporting. Dado que no hubo participación del anuncio (impresión o clic) antes de esta conversión, es probable que se genere un informe de depuración detallado del tipo trigger-no-matching-source.
3. En chrome://attribution-internals, abre la pestaña Verbose debug reports y verifica que se haya generado un informe de depuración detallado de tipo trigger-no-matching-source.
4. En tu servidor, verifica que tu 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 generados en el momento del activador incluyen la clave de depuración del lado del código fuente y la del activador (si hay una fuente coincidente para el activador). Los informes de depuración detallados generados en la hora del origen incluyen la clave de depuración del lado del código fuente.

Ejemplo de una solicitud que contiene informes de depuración detallados, enviada por 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"
  }
]

Punto clave: A diferencia de una solicitud de depuración correcta, una solicitud de depuración detallada contiene una lista (array) de informes detallados en su cuerpo.

Cada informe detallado contiene los siguientes campos:

Type

Qué provocó que se generara el informe. Para obtener información sobre todos los tipos de informes detallados y qué medidas debes tomar según cada uno, revisa 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: Guía de soluciones de depuración.

El cuerpo de una solicitud contendrá al menos un informe detallado y dos 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 tiene un solo motivo. Por lo tanto, 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 agregables, con la excepción de que el motivo de la falla es el mismo para los informes a nivel del evento y 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