Parte 2 de 3 sobre depuração da API Attribution Reporting. Configurar os relatórios de depuração.
Glossário
- A origem de relatórios é a origem
que define os cabeçalhos de origem e acionador da API Attribution Reporting.
Todos os relatórios gerados pelo navegador são enviados para esta origem. Nesta orientação,
usamos
https://adtech.example
como exemplo de origem do relatório. - Um relatório de atribuição (abreviado como relatório) é o relatório final (de evento ou agregável) que contém os dados de medição solicitados.
- Um relatório de depuração contém mais dados sobre um relatório de atribuição ou sobre um evento de fonte ou acionador. Receber um relatório de depuração não significa necessariamente que algo está funcionando de forma incorreta. Há dois tipos de relatórios de depuração.
- Um relatório de depuração transicional é aquele que exige a definição de um cookie para ser gerado e enviado. Os relatórios de depuração transicionais ficarão indisponíveis se um cookie não for definido e se os cookies de terceiros forem descontinuados. Todos os relatórios de depuração descritos neste guia são transicionais.
- Os relatórios de depuração com êxito acompanham a geração de um Relatório de atribuição bem-sucedida. Elas estão diretamente relacionadas a um relatório de atribuição. Os relatórios de depuração de sucesso estão disponíveis desde o Chrome 101 (abril de 2022).
- Os relatórios de depuração detalhados podem rastrear os relatórios ausentes e ajudar você a determinar por que
eles estão ausentes. Elas indicam casos em que o navegador não registrou um evento
de fonte ou acionador (o que significa que ele não vai gerar um relatório de atribuição) e
casos em que um relatório de atribuição não pode ser gerado ou enviado por algum motivo.
Os relatórios de depuração detalhados incluem um campo
type
que descreve o motivo pelo qual um evento da fonte, um evento acionador ou um relatório de atribuição não foi gerado. Os relatórios de depuração detalhados estão disponíveis a partir do Chrome 109 (Stable em janeiro de 2023). - As chaves de depuração são identificadores exclusivos que podem ser definidos no lado da fonte e do acionador. As chaves de depuração permitem mapear conversões baseadas em cookies e conversões baseadas em atribuição. Depois que você configurar o sistema para gerar relatórios de depuração e definir chaves de depuração, o navegador vai incluir essas chaves em todos os Relatórios de atribuição e depuração.
Para conferir mais conceitos e termos-chave usados em toda a nossa documentação, consulte o glossário do Sandbox de privacidade.
Dúvidas de implementação?
Se você encontrar problemas ao configurar os relatórios de depuração, crie um problema no nosso suporte ao desenvolvedor repositório e nós ajudaremos você a solucionar o problema.
Preparar-se para configurar relatórios de depuração
Antes de configurar relatórios de depuração, siga estas etapas:
Verifique se você aplicou as práticas recomendadas para a integração da API
Verifique se o código está protegido pela detecção de recursos. Para ter certeza de que a API não está bloqueado pela Permissions-Policy, execute o seguinte código:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
Se essa verificação de detecção de recursos retornar "true", a API será permitida no contexto (página) em que a verificação é executada.
(Não é necessário durante a fase de teste: verifique se você definiu um Permissions-Policy).
Corrigir problemas fundamentais de integração
Embora os relatórios de depuração sejam úteis para detectar e analisar perdas em grande escala, alguns problemas de integração podem ser detectados localmente. Cabeçalho de origem e acionador de configuração incorreta, problemas de análise de JSON, contexto não seguro (não HTTPS) outros problemas que impedem o funcionamento da API serão Guia Problemas do DevTools.
Os problemas do DevTools podem ser de diferentes tipos. Se você encontrar uma invalid header
problema, copie o cabeçalho no validador de cabeçalhos
ferramenta. Isso
vai ajudar você a identificar e corrigir o campo que está causando o problema.
![Captura de tela: ferramenta de validação de cabeçalho](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-header-valida-6fe8347784caf.png?authuser=19&hl=pt-br)
Configurar relatórios de depuração: etapas comuns para relatórios de sucesso e detalhados
Defina o seguinte cookie na origem do relatório:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
O navegador verificará a presença desse cookie na origem e do acionador. O relatório de depuração com êxito só será gerado se o o cookie está presente nos dois momentos.
Código de demonstração: depurar cookie
Os relatórios de depuração podem ser ativados para navegadores no modo B, em que os cookies de terceiros são desativados para facilitar os testes e a preparação para descontinuação dos cookies de terceiros. Para navegadores no modo B, não é preciso definir o cookie de depuração para ativar os relatórios de depuração. Pule para a etapa 2 para configurar chaves de depuração para relatórios de depuração.
Etapa 2: definir chaves de depuração
Cada chave de depuração precisa ser um número inteiro não assinado de 64 bits formatado como uma string de base 10. Transformar cada chave de depuração em um ID exclusivo. O relatório de depuração será gerado apenas se as chaves de depuração estiverem definidas.
- Mapeie a chave de depuração do lado da origem para outras informações de horário da origem que você considerar relevantes para a depuração.
- Mapeie a chave de depuração do lado do gatilho para outras informações de tempo de gatilho que você considerar relevantes para a depuração.
Você pode, por exemplo, definir as seguintes chaves de depuração:
- ID do cookie + carimbo de data/hora da origem como uma chave de depuração da origem (e capturar essa mesma carimbo de data/hora no seu sistema com base em cookies)
- ID do cookie + carimbo de data/hora do acionador como chave de depuração do acionador (e capturar essa mesma carimbo de data/hora no seu sistema com base em cookies)
Com isso, você pode usar informações de conversão com base em cookies para procurar relatórios de depuração ou de atribuição correspondentes. Saiba mais na Parte 3: Manual (em inglês).
Diferencie a chave de depuração do lado da origem de source_event_id
para que você possa:
diferenciar relatórios individuais que têm o mesmo ID de evento de origem.
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 demonstração: depuração de origem chave Código de demonstração: depuração do gatilho chave
Configurar relatórios de depuração de sucesso
O código de exemplo nesta seção gera relatórios de depuração para os dois relatórios agregáveis e de evento. Os relatórios agregáveis e de evento usam as mesmas chaves de depuração.
Etapa 3: configurar um endpoint para coletar relatórios de depuração de sucesso
Configurar um endpoint para coletar os relatórios de depuração. Esse endpoint precisa ser semelhante
ao endpoint de atribuição principal, com uma string debug
extra no caminho:
- Endpoint para relatórios de depuração no nível do evento:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Endpoint para relatórios de depuração agregáveis:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Endpoint para relatórios de depuração agregáveis:
Quando uma atribuição é acionada, o navegador envia imediatamente uma mensagem de depuração
um relatório por uma solicitação POST
para esse endpoint. O código do servidor que será processado
os relatórios de depuração recebidos podem ter a seguinte aparência (aqui em um endpoint do nó):
// 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 demonstração: relatórios de depuração no nível do evento endpoint
Código de demonstração: relatórios de depuração agregáveis endpoint
Etapa 4: confirmar se a configuração vai gerar relatórios de depuração
- Abra
chrome://attribution-internals
no seu navegador. - Verifique se a caixa de seleção Mostrar relatórios de depuração está marcada, nos dois Relatórios no nível do evento e Relatórios agregáveis.
- Abra os sites em que você implementou a API Attribution Reporting. Completa as etapas usadas para gerar os Relatórios de atribuição; essas mesmas etapas gerar relatórios de depuração.
- Em
chrome://attribution-internals
:- Verifique se os relatórios de atribuição foram gerados corretamente.
- Na guia Relatórios no nível do evento e na guia Relatórios agregáveis,
verificar se os relatórios de depuração foram gerados. Reconhecê-los
na lista pelo caminho
debug
azul.
![Captura de tela: componentes internos da atribuição](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-attribution-i-e7d3e5d9e396.png?authuser=19&hl=pt-br)
- No seu servidor, verifique se o endpoint recebe esses erros imediatamente e relatórios de depuração. Verifique os atributos no nível do evento e os valores agregáveis relatórios de depuração de sucesso.
![Captura de tela: relatórios de registros do servidor de origem](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-reporting-ori-89d44854473d7.png?authuser=19&hl=pt-br)
Etapa 5: observar os relatórios de depuração
Um Relatório de depuração bem-sucedido é idêntico a um Relatório de atribuição e contém as chaves de depuração do lado da fonte e do acionador.
{
"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"
}
Configurar relatórios de depuração detalhados
Etapa 3: ativar a depuração detalhada nos cabeçalhos de origem e acionador
Definir debug_reporting
como true
nos Attribution-Reporting-Register-Source
e 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 demonstração: origem cabeçalho
Código de demonstração: gatilho cabeçalho
Etapa 4: configurar um endpoint para coletar relatórios de depuração detalhados
Configurar um endpoint para coletar os relatórios de depuração. Esse endpoint precisa ser semelhante
ao endpoint de atribuição principal, com uma string debug/verbose
extra em
o caminho:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Relatórios de depuração detalhados são gerados quando uma fonte ou um gatilho não são gerados
estiver registrada, o navegador enviará imediatamente um relatório de depuração detalhado por uma
POST
para esse endpoint. O código de servidor para processar mensagens detalhadas de entrada
os relatórios de depuração podem ter a seguinte aparência (aqui em um endpoint do nó):
// 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);
}
);
Ao contrário dos relatórios de depuração de sucesso, há apenas um endpoint para relatórios detalhados. Os relatórios detalhados relacionados a eventos e relatórios agregados serão enviados para o mesmo endpoint.
Código de demonstração: relatórios de depuração detalhados endpoint
Etapa 5: confirmar se a configuração vai gerar relatórios de depuração detalhados
Embora existam vários tipos de relatórios de depuração detalhados, eles são suficientes para Verificar sua configuração de depuração detalhada com apenas um tipo de depuração detalhada. no relatório. Se esse tipo de relatório de depuração detalhado for gerado corretamente e isso significa que todos os tipos de relatórios de depuração detalhados serão exibidos corretamente gerados e recebidos, pois todos os relatórios de depuração detalhados usam a mesma e são enviados para o mesmo endpoint.
- Abra
chrome://attribution-internals
no seu navegador. - Acionar uma atribuição (converter) no seu site configurado com a Atribuição
Geração de relatórios. Como não houve engajamento com o anúncio (impressão ou clique)
antes dessa conversão, será exibido um relatório de depuração detalhado do tipo
trigger-no-matching-source
será gerado. - Em
chrome://attribution-internals
, abra a guia Relatórios de depuração detalhados. e verifique se um relatório de depuração detalhado do tipotrigger-no-matching-source
for gerado. - No seu servidor, verifique se o endpoint recebeu imediatamente esse relatório de depuração detalhado.
Etapa 6: observar os relatórios de depuração detalhados
Os relatórios de depuração detalhados gerados no momento do acionamento incluem os dados da fonte e a chave de depuração do acionador (se houver uma origem correspondente para o acionador). Os relatórios de depuração detalhados gerados no momento da origem incluem a depuração da fonte. de dados.
Exemplo de uma solicitação que contém relatórios de depuração detalhados, enviados pelo 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 relatório detalhado contém os campos abaixo:
Type
- O que gerou o relatório. Para saber mais sobre todos os detalhes tipos de relatório e que ação realizar dependendo de cada tipo, reveja o Referência de relatórios detalhados na Parte 3: depuração manual.
Body
- O corpo do relatório. Depende do tipo. Analise as informações detalhadas Referência de relatórios na Parte 3: depuração manual.
O corpo de uma solicitação vai conter pelo menos um e no máximo dois relatórios detalhados:
- Um relatório detalhado se a falha afetar apenas relatórios de eventos (ou se ela afeta somente os relatórios agregáveis). Falha no registro da fonte ou do acionador tem apenas um motivo: Assim, é possível gerar um relatório detalhado por falha. e por tipo de relatório (nível de evento ou agregável).
- Dois relatórios detalhados se a falha afetar os níveis de evento e agregáveis
relatórios, com uma exceção: se o motivo da falha for o mesmo para eventos
e agregáveis, apenas um relatório detalhado será gerado (exemplo:
trigger-no-matching-source
)