Parte 2 de 3 sobre la depuración de Attribution Reporting. Configura los informes de depuración.
Glosario
- El origen de los informes es el origen que establece los encabezados de fuente y 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 (informe para abreviar) 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 un evento de fuente o activador. Recibir un informe de depuración no necesariamente significa que algo esté funcionando mal. Hay dos tipos de informes de depuración
- Un informe de depuración de transición es un informe de depuración que requiere que se configure una cookie para generarse y enviarse. Los informes de depuración de transición 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 descritos en esta guía son informes de depuración de transición.
- Los informes de depuración de éxito hacen 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 de éxito 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é faltan. Indican casos en los que el navegador no registró un evento de fuente o activador (lo que significa que no generará un informe de atribución) y casos en los que un informe de atribución no se puede generar ni enviar por algún motivo.
Los informes de depuración detallados incluyen un campo
type
que describe el motivo por el que no se generó un evento de fuente, evento activador o informe de atribución. Los informes detallados de depuración están disponibles a partir de Chrome 109 (estable en enero de 2023). - Las claves de depuración son identificadores únicos que puedes configurar en el lado de la fuente y 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 definir 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 toda nuestra documentación, consulta el glosario de Privacy Sandbox.
¿Tienes preguntas sobre la implementación?
Si tienes algún problema durante la configuración de los informes de depuración, crea un problema en nuestro servicio de asistencia para desarrolladores repositorio y te ayudaremos a solucionar problemas.
Prepárate para configurar informes de depuración
Antes de configurar informes de depuración, sigue estos pasos:
Comprueba que hayas aplicado las prácticas recomendadas para la integración de la API
Verifica que tu código esté restringido a la detección de funciones. Para asegurarse de que la API no esté bloqueado 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 comprobación de detección de funciones devuelve el valor "true", la API se permite en la el contexto (página) en el que se ejecuta la verificación.
(No obligatorio durante la fase de prueba: Comprueba que hayas establecido una Permissions-Policy)
Soluciona problemas de integración fundamentales
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. Encabezado de fuente y activador problemas de configuración incorrecta, problemas de análisis de JSON, contexto inseguro (que no sea HTTPS) y otros problemas que impidan el funcionamiento de la API aparecerán en el Pestaña Problemas de las Herramientas para desarrolladores
Los problemas de Herramientas para desarrolladores pueden ser de diferentes tipos. Si encuentras un error invalid header
copia el encabezado en el validador de encabezados
de la aplicación. Esta
te ayudará a identificar y corregir el campo que está causando el problema.
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 comprobará la presencia de esta cookie en la fuente y el registro de activadores. El informe de depuración de éxito solo se generará si el cookie está presente en ambos momentos.
Código de demostración: depuración cookie
Ten en cuenta que los informes de depuración pueden habilitarse para los navegadores en modo B, donde las cookies de terceros están inhabilitadas para facilitar la prueba y la preparación para baja de las cookies de terceros. Para los navegadores del modo B, no es necesario establecer 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 sea un ID único. El informe de depuración de éxito solo se generará si las claves de depuración están configuradas.
- Asigna la clave de depuración del lado del código fuente a información adicional de hora de origen que que es relevante para que depures.
- Asigna la clave de depuración del lado del activador a información adicional sobre el tiempo del activador que que es relevante para que depures.
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 captar 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 captar esa misma marca de tiempo en tu sistema basado en cookies)
Con esto, puede usar la información de las conversiones 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: Libro de recetas.
Haz que la clave de depuración del lado del código fuente 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: depuración de fuente clave Código de demostración: activar depuración clave
Cómo configurar informes de depuración de errores
El código de ejemplo en esta sección genera informes de depuración de éxito para ambos a nivel del evento y a nivel agregable. Los informes agregables y a nivel del evento las mismas claves de depuración.
Paso 3: Configura un extremo para recopilar informes de depuración correcta
Configurar un extremo para recopilar los informes de depuración Este extremo debería ser similar
al extremo de atribución principal, con una string debug
adicional en la ruta:
- Extremo para los 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 aggregables:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Extremo para informes de depuración de éxito aggregables:
Cuando se activa una atribución, el navegador envía inmediatamente una solicitud de depuración
a través de una solicitud POST
a este extremo. El código de servidor para controlar
Los informes de depuración de éxito entrantes pueden 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: informes de depuración a nivel del evento extremo
Código de demostración: informes de depuración agregables extremo
Paso 4: Confirma que tu configuración generará informes de depuración de éxito
- Abre
chrome://attribution-internals
en tu navegador. - Asegúrate de que la casilla de verificación Mostrar informes de depuración esté marcada, tanto en Informes a nivel del evento y las pestañas Informes agregables.
- Abre los sitios en los que implementaste Attribution Reporting. Completada los pasos que utilizas para generar informes de atribución; estos mismos pasos generar informes de depuración de éxito.
- En
chrome://attribution-internals
, haz lo siguiente:- Comprueba que los informes de atribución se generen correctamente.
- En la pestaña Informes a nivel del evento y en la pestaña Informes agregables,
Comprobar que también se generen informes de depuración correcta Reconocerlos
en la lista con su ruta de acceso
debug
azul.
- Verifica en tu servidor que el extremo reciba estos mensajes de forma correcta de inmediato los informes de depuración. Asegúrate de verificar las políticas agregables y a nivel del evento informes de depuración de éxito.
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 ambos 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 los encabezados de fuente y activador
Establecer debug_reporting
como true
en ambos 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: fuente encabezado
Código de demostración: activador encabezado
Paso 4: Configura un extremo para recopilar informes de depuración detallados
Configurar 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:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Cuando se generan informes de depuración detallados, es decir, cuando no se detecta una fuente ni un activador
el navegador enviará de inmediato un informe de depuración detallado a través de un
POST
a este extremo. El código de tu servidor para controlar la información entrante y detallada
Los informes de depuración pueden tener el siguiente aspecto (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 correcta, solo hay un extremo para los informes detallados. Los informes detallados que se relacionan con los informes a nivel del evento y los agregados enviados al mismo extremo.
Código de demostración: informes de depuración detallados extremo
Paso 5: Confirma que la configuración generará informes de depuración detallados
Si bien existen numerosos tipos de informes detallados de depuración, es suficiente con Verifica tu configuración de depuración detallada con solo un tipo de depuración detallada . Si este tipo de informe detallado de depuración se genera correctamente y recibidos, esto significa que todos los tipos de informes detallados de depuración serán correctos ya que todos los informes de depuración detallados usan la misma configuración y se envían al mismo extremo.
- Abre
chrome://attribution-internals
en tu navegador. - Activa una atribución (conversión) en tu sitio configurada con Atribución
Informes. Dado que no hubo participación en el anuncio (impresión o clic)
antes de esta conversión, deberías recibir un informe de depuración detallado del tipo
Se generará
trigger-no-matching-source
. - En
chrome://attribution-internals
, abre la pestaña Informes de depuración detallados. y verifica que un informe de depuración detallado de tipotrigger-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 generados en el momento de la activación incluyen los informes de origen y la clave de depuración del lado del activador (si existe una fuente coincidente para el activador) Los informes de depuración detallados generados en el momento de la fuente incluyen la depuración del código fuente. .
Ejemplo de una solicitud que contiene informes de depuración detallados enviados 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
- Qué provocó que se generara el informe. Para aprender sobre todas las funciones los tipos de informes y qué medidas tomar según cada uno, revisa el Referencia de informes detallados en la Parte 3: Depuración guía de soluciones.
Body
- El cuerpo del informe. Dependerá de su tipo. Revisa la información detallada Referencia de informes en la Parte 3: Depuración guía de soluciones.
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 tiene un solo motivo: por lo que se puede generar un informe detallado por cada falla y por tipo de informe (a nivel del evento o agregable).
- Dos informes detallados si el error afecta tanto al nivel del evento como al agregable
informes, con una excepción: si el motivo de la falla es el mismo para
y los informes agregables, solo se genera un informe detallado (por ejemplo,
trigger-no-matching-source
)