Algunas tecnologías de Privacy Sandbox se están descontinuando.

Consulta nuestra Actualización sobre los planes para las tecnologías de Privacy Sandbox.

Estado de las funciones de Privacy Sandbox proporciona más información sobre el estado de las APIs y las funciones de la plataforma individuales.

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

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

Glosario

The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

¿Tienes preguntas sobre la implementación?

Si tienes algún problema para configurar los 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 los 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 Permissions-Policy, 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 devuelve 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 establecido 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 la pérdida a gran escala, algunos problemas de integración se pueden detectar de forma local. Los problemas de configuración incorrecta de la fuente y el encabezado del activador, los problemas de análisis de JSON, el contexto no seguro (no HTTPS) y otros problemas que impiden que la API funcione se mostrarán en la pestaña Problemas de Herramientas para desarrolladores.

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

Valida los encabezados de los informes de atribución

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 opción para recibir 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 como 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 este 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
  }
}]

Herramienta de validación de encabezados

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

Establece la siguiente cookie en el origen de 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 los informes de depuración se pueden habilitar 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 el modo B, no es necesario que establezcas la cookie de depuración para habilitar los informes de depuración. Ve al paso 2 para configurar las claves de depuración de los informes de depuración de éxito.

Paso 2: Establece claves de depuración

Cada clave de depuración debe ser un número entero de 64 bits sin signo con formato de cadena en base 10. Haz que cada clave de depuración sea 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 de la fuente a información adicional del momento de la fuente que creas que es pertinente para depurar.
Asigna la clave de depuración del activador a información adicional del momento del activador que creas que es relevante para depurar.

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

ID de cookie + marca de tiempo de la fuente como clave de depuración de la fuente (y captura esa misma marca de tiempo en tu sistema basado en cookies)
ID de cookie y 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: Recetario.

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

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 de esta sección genera informes de depuración de éxito para los informes a nivel del evento y los informes agregables. Los informes a nivel del evento y los informes 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:

Es el extremo para los informes de depuración de éxito a nivel del evento: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Es el extremo para los informes de depuración de éxito agregables: 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 con una solicitud POST a este extremo. El código del servidor para controlar los informes de depuración de éxito 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: Endopoint de informes de depuración a nivel del evento

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

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

Abre chrome://attribution-internals en tu navegador.
Asegúrate de que la casilla de verificación Mostrar informes de depuración esté marcada en las pestañas Informes a nivel del evento y Informes agregables.
Abre los sitios en los que implementaste el Informe de atribución. Completa los pasos que usas para generar informes de atribución. Estos mismos pasos generarán informes de depuración de éxito.
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ócelos en la lista con su ruta de acceso azul debug.

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

Registros del servidor de origen de informes — Registra los registros del servidor de origen

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 de la fuente y del lado 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

Paso 3: Habilita la depuración detallada en los encabezados de origen y de activación

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 de activación

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

Configura un extremo para recopilar los informes de depuración. Este extremo debería 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 con una solicitud POST a este extremo. El código del servidor para controlar 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 de éxito, solo hay un extremo para los informes detallados. Todos los informes detallados relacionados con los informes a nivel del evento y agregados se enviarán al mismo extremo.

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

Paso 5: Confirma que tu 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, significa que 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 obvio para probar. trigger-no-matching-source es un buen candidato, ya que puedes generarlo a través de la conversión. Los informes detallados relacionados con los eventos de activador suelen ser mejores candidatos; los tipos de informes detallados relacionados con los eventos de fuente 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é configurado 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 de 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 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 que se generan en el momento del activador incluyen la clave de depuración del lado de la fuente y la del lado del activador (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 detallados de depuración, 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"
  }
]

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é acción tomar según cada tipo, consulta la referencia de informes detallados en Part 3: Debugging cookbook.
Body: Es el cuerpo del informe. Dependerá de su tipo. Consulta la referencia de los informes detallados en la Parte 3: Recetario de depuración.

El cuerpo de una solicitud contendrá, al menos, un informe detallado y, como máximo, dos:

Un informe detallado si la falla solo afecta a los informes a nivel del evento (o si solo afecta a los informes agregables) Un error de registro de fuente o activador tiene solo un motivo. Por lo tanto, se puede generar un informe detallado por error y por tipo de informe (a nivel del evento o agregable).
Dos informes detallados si la falla afecta tanto a los informes a nivel del evento como 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 (ejemplo: trigger-no-matching-source).

A continuación

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