Parte 3 de 3 sobre a depuração dos Relatórios de atribuição. Encontre instruções sobre como usar relatórios de depuração.
Neste livro de receitas, 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.examplecomo 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
typeque 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.
Como verificar sua integração em tempo real
- Configure seu sistema para gerar relatórios de depuração de sucesso. Saiba como em Parte 2: configurar relatórios de depuração.
- Sempre que você implantar o código dos 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 da API 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, verifique se as fontes foram registradas com sucesso. Para isso, use os relatórios de depuração detalhados de sucesso no registro da origem. Saiba como configurar em Parte 2: configurar relatórios de depuração.
Como analisar a perda e resolver problemas de integração
Para comparar os resultados da medição de conversão com base em cookies com os relatórios de atribuição, use chaves de depuração e mapeie as conversões de cookies com relatórios de depuração. Lembre-se de que os relatórios de depuração são enviados imediatamente ao seu endpoint.
Visão geral
Use as chaves de depuração (par <source_debug_key, trigger_debug_key>) para mapear conversões de cookie com relatórios de depuração de sucesso.
Para cada conversão de cookie, no momento da conversão, você recebeu um relatório de depuração de sucesso correspondente?
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. Consulte o cenário do relatório de depuração de sucesso para mais detalhes.
Caso contrário: significa que a conversão não foi registrada com a Attribution Reporting. Use o par <source_debug_key, trigger_debug_key> (ou a chave de depuração de origem se a chave de depuração de acionador estiver ausente) para mapear conversões de cookies em relatórios de depuração detalhados. Para cada uma dessas conversões, você recebeu em algum momento (origem ou horário 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 detalhes no cenário de relatório sem depuração.
Se você recebeu um relatório de depuração detalhado, consulte o campo
type.Se o
typeforsource-success: isso significa que a origem foi registrada, mas o gatilho não. Para restringir o motivo da ausência do relatório de depuração de sucesso, procure um relatório de depuração detalhado correspondente de qualquer outro tipo. Ele vai indicar um problema no lado do acionador.Se o
typefor qualquer outra coisa, a origem ou o acionador não foi registrado.typeexplica o motivo. O relatório de atribuição correspondente (e o relatório de depuração de sucesso) não vai aparecer. Dependendo dotypede um relatório de depuração detalhado, talvez você queira apenas considerar essas informações como um ponto de dados de análise de perda (ou seja, nenhuma ação para você) ou registrar um bug ou resolver problemas na sua implementação. Consulte o cenário de relatório de depuração detalhado para mais detalhes.
Possíveis cenários
Relatório de depuração de sucesso
Se você recebeu um relatório de depuração de sucesso para uma determinada conversão de cookie, isso significa que ela foi registrada com sucesso com os relatórios de atribuição.
Você vai receber um relatório de atribuição para essa conversão, com algumas exceções:
- Comportamento do usuário: limpar dados após a conversão e antes do envio do relatório de atribuição, fechar o 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 a eventos: um relatório de evento é substituído por outro de maior prioridade.
- 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 dessa conversão.
Há uma ressalva:
Relatório de depuração detalhado de qualquer outro tipo
Se você recebeu 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 depois, porque um relatório detalhado significa que ocorreu uma falha que pode ser informada. Algo impediu o registro da origem, 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 seu 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, para uma determinada conversão de cookie, você tiver recebido apenas um relatório de atribuição (sem um relatório de depuração de sucesso ou 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 cookies de terceiros)
- Cookie ou chaves de depuração ausentes (a chave de depuração foi limpa devido a um cookie ausente). Em
chrome://attribution-internals, abra a guia Registros e verifique se há algum problema. - Problemas de rede que ocorreram na origem ou no momento do acionamento, 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 recebimento de 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 de nenhum tipo, nenhum relatório de atribuição), isso significa que ocorreu uma falha não informada. Possíveis causas:
- Problema fundamental de integração. Saiba como resolver esses problemas em Corrigir problemas fundamentais de integração.
- 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 captura o motivo pelo qual o relatório de atribuição correspondente foi descartado. Use a referência para descobrir, em cada type do relatório detalhado, qual ação tomar.
Registro da fonte concluído
Uma fonte é registrada com sucesso.
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- Isso é gerado se a contagem de relatórios exceder o limite. É possível registrar no máximo uma conversão para visualizações e três para cliques. É possível configurar quais relatórios você quer receber definindo prioridades. Detalhes e corpo do relatório
Relatórios de limitações de armazenamento
Esses relatórios são esperados. Eles 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, remoção de duplicação, prioridades ou filtragem baseada em janela. Por precaução, verifique as regras personalizadas correspondentes para confirmar se o relatório detalhado é mesmo um relatório que você quer descartar. Se isso estiver correto, você não precisa fazer nada.
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 seu código.
trigger-no-matching-source- Isso pode ser um problema de implementação. Verifique se não há erros na configuração do
<reporting origin, destination>. Esse também pode ser o comportamento esperado da API. Por exemplo, o usuário limpou os dados em algum momento depois de interagir com um anúncio e antes de fazer uma conversão, ou fez uma conversão sem nunca ter visto um anúncio associado. Detalhes e corpo do relatório trigger-aggregate-no-contributions- Provavelmente não é esse o comportamento que você quer para seu código. Resolva problemas no código de registro do gatilho e verifique se a configuração de contribuição está correta. Detalhes e corpo do relatório
trigger-aggregate-insufficient-budget- Provavelmente não é esse o comportamento que você quer para seu código. Verifique novamente o código de registro do gatilho 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. Isso pode ser causado por um bug no 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: configuração e mapeamento com cookies
Siga as instruções em Parte 2: configurar relatórios de depuração para configurar seu sistema e gerar relatórios de depuração de sucesso e relatórios de depuração detalhados.
Assim, você pode usar informações de conversão com base em cookies para pesquisar 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 cookie, 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ê recebeu 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 decidir monitorar essas exceções. Para isso, à medida que os relatórios de atribuição forem enviados ao seu endpoint nos próximos dias ou semanas (dependendo da expiração), 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 de sucesso. 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.
Etapa 3: avaliação breve de perda
100 - 70 = 30 relatórios de depuração de sucesso estão faltando. Isso significa que essas 30 conversões (que foram rastreadas na sua implementação baseada em cookies) não foram registradas com os Relatórios de atribuição. Você não vai receber relatórios de atribuição para eles.
Como você tem 100 conversões baseadas em cookies e apenas 70 baseadas 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 há 10 chaves sem 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 perda. Analise o campo
typede cada relatório detalhado. Por exemplo, você pode descobrir que:- 10 (= 10% no nosso exemplo) relatórios estão faltando devido a
pending destination limit - 5 (= 5%) relatórios estão faltando devido a
trigger-aggregate-no-contributions. - 5 (= 5%) relatórios estão faltando devido a
unknown-error.
- 10 (= 10% no nosso exemplo) relatórios estão faltando devido a
Etapa 5: tome medidas e resolva problemas
Agora que você sabe por que os relatórios estão faltando, pode usar esses 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 informações. 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-contributionspode ser um sinal de problema de implementação da sua parte. Analise isso melhor. Use os detalhes no corpo do relatório detalhado para resolver o problema, se necessário.unknown-errorpode ser um sinal de bug no navegador ou erro de rede. Se isso acontecer com frequência, informe um bug para os desenvolvedores de navegadores.