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

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.

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.