Esta página foi traduzida pela API Cloud Translation.

Manual de depuração da API Attribution Reporting

Parte 3 de 3 sobre depuração dos Relatórios de atribuição. Encontre instruções sobre como usar os relatórios de depuração.

Neste guia, você vai encontrar instruções sobre como usar relatórios de depuração para vários casos de uso descritos na Parte 1: Introdução aos relatórios de depuração.

Glossário

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.

Tutorial: verificar a integração em tempo real

Configure o sistema para gerar relatórios de depuração de sucesso. Saiba como na Parte 2: configurar relatórios de depuração.
Sempre que você implantar o código de relatórios de atribuição, verifique em tempo real se está recebendo alguns relatórios de depuração de sucesso no seu endpoint. Se sim, a configuração do Attribution Reporting está funcionando.
Os relatórios de depuração de sucesso só são enviados quando uma conversão ocorre. Em vez disso, verifique se a integração está configurada corretamente, independentemente das conversões, ou seja, se as fontes foram registradas. Para isso, use relatórios de depuração detalhados de sucesso no registro de origem. Saiba como configurá-los na Parte 2: configurar relatórios de depuração.

Como fazer: analisar perdas e resolver problemas de integração

Para comparar os resultados da medição de conversões com base em cookies com os relatórios de relatórios de atribuição, use chaves de depuração e mapeie as conversões de cookies com relatórios de depuração. Os relatórios de depuração são enviados imediatamente para o endpoint.

Visão geral

Use as chaves de depuração (par <source_debug_key, trigger_debug_key>) para mapear as conversões de cookies para relatórios de depuração de sucesso. Você recebeu um relatório de depuração de sucesso correspondente para cada conversão de cookie no momento da conversão?

Se sim: para todos esses relatórios de depuração de sucesso, você vai receber um relatório de atribuição mais tarde, com algumas exceções. Confira os detalhes no cenário do relatório de depuração de sucesso.

Se não: significa que a conversão não foi registrada nos Relatórios de atribuição. Use o par <source_debug_key, trigger_debug_key> (ou a chave de depuração de origem se a chave de depuração do acionador estiver ausente) para mapear as conversões de cookies para relatórios de depuração detalhados. Para cada uma dessas conversões, você recebeu em algum momento (no momento da origem ou do acionador) um relatório de depuração detalhado correspondente?

Se você não recebeu um relatório de depuração detalhado: isso pode ser devido ao comportamento do usuário ou a um problema de integração. Confira os detalhes no cenário sem relatório de depuração.
Se você recebeu um relatório de depuração detalhado, analise o campo type.
- Se o type for source-success, isso significa que a origem foi registrada, mas o acionador não. Para descobrir por que o relatório de depuração de sucesso está ausente, procure um relatório de depuração detalhado correspondente de qualquer outro tipo. Esse relatório vai indicar um problema no acionador.
- Se o type for qualquer outro valor: a origem ou o acionador não foram registrados. type explica o motivo. O relatório de atribuição correspondente (e o relatório de depuração de sucesso) não vai estar disponível. Dependendo do type de um relatório de depuração detalhado, você pode usar essas informações como um ponto de dados de análise de perda (ou seja, não precisa fazer nada) ou registrar um bug ou solucionar problemas na implementação. Confira os detalhes no cenário de relatório de depuração detalhado.

Possíveis cenários

Relatório de depuração de sucesso

Se você recebeu um relatório de depuração de sucesso para uma conversão de cookie específica, isso significa que ela foi registrada com os Relatórios de atribuição.

Você vai receber um relatório de atribuição para essa conversão mais tarde⏤, com algumas exceções:

Comportamento do usuário: limpeza de dados após a conversão e antes do envio do relatório de atribuição, fechamento do navegador etc. Se um usuário fechar o navegador após a conversão e não abrir o navegador por uma semana, o relatório não será enviado por uma semana ou mais. Você pode considerar esse atraso como uma perda.
Aplicável apenas ao nível do evento: um relatório no nível do evento é substituído por outro relatório de prioridade mais alta.
Possíveis problemas de rede.

Relatório de depuração detalhado do tipo `source-success`

Se você recebeu um relatório de depuração detalhado do tipo source-success para a origem de uma determinada conversão de cookie, isso significa que o registro da origem foi concluído. Dependendo se o registro do acionador também for bem-sucedido mais tarde, você poderá ou não receber um relatório para essa conversão.

Há uma ressalva:

Relatório de depuração detalhado de qualquer outro tipo

Se você receber um relatório de depuração detalhado de qualquer outro tipo para uma determinada conversão de cookie, não vai receber um relatório de depuração de sucesso e, portanto, nenhum relatório de atribuição mais tarde, porque um relatório detalhado significa que ocorreu uma falha que pode ser relatada. Algo impediu o registro da fonte, do acionador, a geração ou o envio do relatório. Possíveis causas:

Limites de privacidade
Limites de armazenamento
Regras personalizadas
Problema de implementação no código
Bug do navegador

Alguns deles são esperados. A ação a ser tomada depende do type de cada relatório detalhado. Consulte a referência de relatórios detalhados.

Nenhum relatório de depuração

Se você recebeu apenas um relatório de atribuição para uma determinada conversão de cookie (sem relatório de depuração de sucesso nem detalhado), isso significa que algo impediu a geração dos relatórios de depuração. Possíveis causas:

Preferências do usuário (o usuário desativou os cookies de terceiros)
Cookie ou chaves de depuração ausentes (a chave de depuração foi limpa devido à ausência de um cookie). Em chrome://attribution-internals, abra a guia Registros e verifique se há algum problema.
Problemas de rede que ocorreram no momento da origem ou do acionador, mas não quando o relatório de atribuição foi enviado.

Você está recebendo relatórios de atribuição?

Este é um subcaso de não receber um relatório de depuração: se, para uma determinada conversão de cookie, você não recebeu relatórios de nenhum tipo (nenhum relatório de depuração, nenhum relatório de atribuição), isso significa que ocorreu uma falha não acionável. Possíveis causas:

Problema de integração fundamental. Saiba como resolver esses problemas em Corrigir problemas de integração fundamentais.
Possíveis problemas de rede.
Preferências do usuário nas configurações do navegador, como o Sandbox de privacidade desativado.

Referência de relatórios de depuração detalhados

Cada relatório de depuração detalhado tem um campo type que registra o motivo pelo qual o relatório de atribuição correspondente foi descartado. Use a referência para descobrir, para cada type do relatório detalhado, qual ação tomar.

Observação:se o type de um relatório detalhado começar com trigger-event, ele só poderá ser gerado para eventos de origem ou acionador associados a relatórios de eventos. Se a type de um relatório detalhado começar com trigger-aggregate, ele só poderá ser gerado para eventos de origem ou acionador associados a relatórios agregáveis. Em todos os outros casos, é para um relatório agregado ou de evento.

Registro da fonte concluído

Uma origem foi registrada.

source-success: Detalhes e corpo do relatório

Relatórios de limitações de privacidade

Esses relatórios são esperados. Elas indicam limitações de privacidade para reduzir o vazamento de identidade do usuário entre sites.

source-destination-limit: Detalhes e corpo do relatório
source-noised: Detalhes e corpo do relatório
trigger-attributions-per-source-destination-limit: Detalhes e corpo do relatório
trigger-reporting-origin-limit: Detalhes e corpo do relatório
trigger-event-noise: Detalhes e corpo do relatório
trigger-event-excessive-reports: Esse valor é gerado se a contagem de relatórios ultrapassar o limite. Você pode registrar no máximo uma conversão para visualizações e três para cliques. É possível configurar quais relatórios receber definindo prioridades. Detalhes e corpo do relatório

Relatórios de limitações de armazenamento

Esses relatórios são esperados. Elas indicam limitações de armazenamento para evitar o uso excessivo de recursos.

source-storage-limit: Detalhes e corpo do relatório
trigger-event-storage-limit: Detalhes e corpo do relatório
trigger-aggregate-storage-limit: Detalhes e corpo do relatório

Relatórios de regras personalizadas

Esses relatórios são esperados se você estiver usando filtragem, eliminação de duplicação, prioridades ou filtragem baseada em janelas. Verifique novamente as regras personalizadas correspondentes para confirmar se o relatório correspondente a esse relatório detalhado é realmente o que você quer excluir. Se isso estiver correto, nenhuma ação é necessária.

trigger-no-matching-filter-data: Detalhes e corpo do relatório
trigger-event-no-matching-configuration: Detalhes e corpo do relatório
trigger-event-deduplicated: Detalhes e corpo do relatório
trigger-aggregate-deduplicated: Detalhes e corpo do relatório
trigger-event-low-priority: Detalhes e corpo do relatório
trigger-event-report-window-passed: Detalhes e corpo do relatório
trigger-aggregate-report-window-passed: Detalhes e corpo do relatório

Outros relatórios detalhados

Esses relatórios podem indicar possíveis problemas de implementação no código.

trigger-no-matching-source: Pode ser um problema de implementação. Verifique se não há uma configuração incorreta de <reporting origin, destination>. Esse também pode ser o comportamento esperado da API. Por exemplo, o usuário excluiu dados em algum momento depois de interagir com um anúncio e antes de converter ou converteu sem ver um anúncio associado. Detalhes e corpo do relatório
trigger-aggregate-no-contributions: Esse provavelmente não é o comportamento que você quer que seu código tenha. Resolva problemas com o código de registro do acionador. Verifique se a configuração da contribuição está correta. Detalhes e corpo do relatório
trigger-aggregate-insufficient-budget: Esse provavelmente não é o comportamento que você quer que seu código tenha. Verifique o código de registro do acionador para garantir que a soma de todas as contribuições não exceda o orçamento de contribuição. Detalhes e corpo do relatório

Erros inesperados (possíveis bugs do navegador)

Esses relatórios são inesperados. Elas podem ser causadas por um bug do navegador. Registre um bug e especifique na descrição as etapas para reproduzir o problema.

source-unknown-error: Detalhes e corpo do relatório
trigger-unknown-error: Detalhes e corpo do relatório

Exemplo de análise de perda

Etapa 1: configurar e mapear com cookies

Siga as instruções na Parte 2: Configurar relatórios de depuração para configurar o sistema para gerar relatórios de depuração de sucesso e detalhados.

Assim, você pode usar as informações de conversão baseadas em cookies para procurar os relatórios de depuração ou de atribuição correspondentes.

Etapa 2: identificar registros bem-sucedidos e relatórios ausentes

Neste exemplo, vamos supor que você tenha rastreado 100 conversões com seu sistema baseado em cookies.

Sempre que você registrar uma conversão baseada em cookies, procure o relatório de depuração de sucesso (enviado imediatamente) que tenha o mesmo par <source_debug_key, trigger_debug_key> dessa conversão.

Vamos supor que você tenha recebido um relatório de depuração de sucesso para 70 dessas conversões de cookie.

Os relatórios de sucesso significam que a atribuição foi registrada. Portanto, você pode presumir que vai receber um relatório de atribuição correspondente a cada relatório de sucesso, com algumas exceções.
Você pode monitorar essas exceções. Para isso, procure os relatórios de atribuição que têm o mesmo par de chaves de depuração de cada relatório de depuração com sucesso, já que eles são enviados para seu endpoint nos próximos dias/semanas (dependendo da expiração). Aguarde um pouco: os relatórios podem não ser enviados imediatamente no final de cada janela. Vamos supor que você encontre apenas 60 relatórios de atribuição. Os 10 relatórios de atribuição ausentes podem ser devido ao comportamento do usuário.

Observação:talvez você tenha relatórios de atribuição no nível do evento que não são mapeados para uma conversão baseada em cookies. Esses são provavelmente relatórios com ruídos gerados aleatoriamente pela API. Para confirmar isso, procure relatórios detalhados de depuração do tipo source-noised que tenham a mesma chave de depuração de origem do seu relatório no nível do evento.

Etapa 3: avaliação breve da perda

100-70 = 30 relatórios de depuração de sucesso estão faltando. Isso significa que essas 30 conversões (que foram acompanhadas na sua implementação baseada em cookies) não foram registradas nos Relatórios de atribuição. Você não vai receber relatórios de atribuição para eles.

Como você tem 100 conversões com base em cookies e apenas 70 com base em atribuição, sua perda é de 30%. Agora você tem uma breve avaliação de perda.

Etapa 4: analisar as causas

Para investigar por que esses relatórios estão faltando, procure os relatórios de depuração detalhados correspondentes que você recebeu no momento da conversão (registro do acionador) ou antes, no momento do registro da fonte. Use as chaves das conversões baseadas em cookies para mapeá-las em relatórios de depuração detalhados.

Vamos supor que haja 10 chaves para as quais não há um relatório de depuração detalhado. Verifique se há algum problema de integração. Caso contrário, isso pode ser devido ao comportamento do usuário.
Você tem 20 relatórios de depuração detalhados. Agora você pode refinar sua análise de perdas. Analise o campo type de cada relatório detalhado. Por exemplo, você pode descobrir que:
- Dez relatórios (10% no nosso exemplo) estão ausentes devido a pending destination limit
- Cinco relatórios (5%) estão faltando devido a trigger-aggregate-no-contributions.
- Cinco relatórios (5%) estão faltando devido a unknown-error.

Etapa 5: tomar medidas e resolver problemas

Agora que você sabe por que os relatórios estão faltando, pode agir com base nesses insights.

A ação a ser tomada depende do type de cada relatório detalhado. Consulte a referência de relatórios detalhados para mais detalhes. Exemplo:

pending-destination-limit é uma proteção de privacidade. Não é necessário fazer nada. Use esse número como um ponto de dados para sua própria visibilidade e monitoramento.
trigger-aggregate-no-contributions pode ser um sinal de um problema de implementação do seu lado. Analise melhor. Use os detalhes no corpo do relatório detalhado para resolver o problema, se necessário.
unknown-error pode ser um sinal de um bug do navegador ou erro de rede. Se isso acontecer várias vezes, informe um bug para os desenvolvedores do navegador.