Parte 3 de 3 sobre a depuração do Relatório de atribuição. Confira instruções sobre como usar os relatórios de depuração.
Neste manual, 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.
Instruções: verifique sua integração em tempo real
- Configure o sistema para gerar relatórios de depuração concluídos. Saiba como fazer isso na Parte 2: configurar relatórios de depuração.
- Sempre que você implantar o código do Attribution Reporting, verifique em tempo real se está recebendo relatórios de depuração no endpoint. Em caso afirmativo, a configuração da API Attribution Reporting está funcionando.
- Os relatórios de depuração de sucesso são enviados somente quando ocorre uma conversão. Em vez disso, verifique se a integração está configurada corretamente, independentemente de conversões, ou seja, se as origens foram registradas. Para fazer isso, use os relatórios de depuração detalhados sucessos do registro da fonte. Veja como configurá-los na Parte 2: configurar relatórios de depuração.
Instruções: analise perdas e resolva problemas de integração
Para comparar os resultados da medição de conversões baseada em cookies com os Relatórios de atribuição, use chaves de depuração e mapeie as conversões de cookies com esses relatórios. Os relatórios de depuração são enviados imediatamente ao endpoint.
Visão geral
![Etapas para uma análise de perda](https://developers.google.cn/static/privacy-sandbox/assets/images/steps-a-loss-analysis-92c05fa7a306c.png?authuser=6&hl=pt-br)
Use as chaves de depuração (par <source_debug_key, trigger_debug_key>
) para mapear as conversões de cookies em relatórios de depuração bem-sucedidos.
Para cada conversão de cookie, você recebeu um relatório de depuração de sucesso correspondente no momento da conversão?
Em caso afirmativo: para todos esses relatórios de depuração de sucesso, você vai receber um Relatório de atribuição posteriormente, com algumas exceções. Analise o cenário do relatório de depuração de sucesso para mais detalhes.
Se não for: significa que a conversão não foi registrada na API Attribution Reporting. Use o par <source_debug_key, trigger_debug_key>
(ou a chave de depuração da origem, se a chave do acionador estiver ausente) para mapear as conversões de cookies em relatórios de depuração detalhados. Para cada uma dessas conversões, você recebeu em algum momento (tempo de origem ou acionador) um relatório de depuração detalhado?
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. Analise o cenário sem relatório de depuração para mais detalhes.
Se você recebeu um relatório de depuração detalhado, confira o campo
type
.Se o
type
forsource-success
: isso significa que a origem foi registrada, mas o acionador não. Para restringir por que o relatório de depuração de sucesso está ausente, procure um relatório de depuração detalhado de qualquer outro tipo⏤ que indique um problema no acionador.Se o
type
for qualquer outro, a origem ou o acionador não foi registrado.type
informa o motivo. O relatório de atribuição correspondente (e o relatório de depuração de sucesso) não vai aparecer. Dependendo dotype
de um relatório de depuração detalhado, talvez você queira considerar essas informações apenas como um ponto de dados de análise de perda (em outras palavras, nenhuma ação para você), registrar um bug ou solucionar problemas da sua implementação. Analise o cenário do relatório de depuração detalhado para mais detalhes.
Cenários possíveis
Relatório de depuração bem-sucedido
Se, para uma determinada conversão de cookie, você recebeu um relatório de depuração, isso significa que essa conversão foi registrada no Relatório de atribuição.
Você vai receber um relatório de atribuição sobre essa conversão mais tarde⏤ com algumas exceções:
- Comportamento do usuário: limpar os 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 somente ao nível do evento: um relatório de evento é substituído por outro relatório com 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 bem-sucedido. Dependendo se o registro do acionador também for bem-sucedido posteriormente, você poderá receber um relatório sobre a conversão ou não.
Há uma ressalva quanto a isso:
Relatório de depuração detalhado de qualquer outro tipo
Se, para uma determinada conversão de cookie, você recebeu um relatório de depuração detalhado de qualquer outro tipo, não vai receber um relatório de depuração de sucesso e, portanto, nenhum relatório de atribuição ⏤, já que um relatório detalhado significa que ocorreu uma falha reportável. Algo impediu o registro da fonte, o registro do acionador e a geração ou o envio de relatórios. Possíveis causas:
- Limites de privacidade
- Limites de armazenamento
- Regras personalizadas
- Problema de implementação no seu código
- Bug no navegador
Alguns deles são esperados. A ação a ser realizada depende do type
de cada relatório detalhado. Revise a referência de relatórios detalhados.
Nenhum relatório de depuração
Se, em uma determinada conversão de cookie, você recebeu apenas um relatório de atribuição (nenhum 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 ausente ou chaves de depuração ausentes (chave de depuração apagada devido a um cookie ausente). Em
chrome://attribution-internals
, abra a guia Registros e verifique se há algum problema. - Problemas de rede que ocorreram no momento da fonte ou do acionador, mas não quando o relatório de atribuição foi enviado.
Você recebe relatórios de atribuição?
Esse é um subcaso de não receber um relatório de depuração: se, em uma determinada conversão de cookie, você não recebeu nenhum tipo de relatório (nenhum relatório de depuração de qualquer tipo, nenhum relatório de atribuição), isso significa que ocorreu uma falha não reportável. Possíveis causas:
- Problema fundamental de integração. Confira como resolver isso 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 detalhada
Cada relatório de depuração detalhado tem um campo type
que captura o motivo do descarte do relatório de atribuição correspondente. Use a referência para descobrir, para cada type
de relatório detalhado, que ação realizar.
Registro de origem bem-sucedido
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 de usuários 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 do relatório estiver acima do limite. É possível registrar no máximo uma conversão para visualizações e três para cliques. É possível configurar quais relatórios serão recebidos definindo as 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 impedir 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 quando você usa filtragem, eliminação de duplicação, prioridades ou filtragem com base em janelas. Por precaução, verifique novamente as regras personalizadas correspondentes para confirmar se o relatório correspondente ao relatório detalhado é realmente um relatório que você quer descartar. Se 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 código.
trigger-no-matching-source
- Isso pode ser um problema de implementação. Verifique se não há erros de configuração na configuração do
<reporting origin, destination>
. Esse também pode ser o comportamento esperado da API. Por exemplo, o usuário apagou os dados em algum momento depois de interagir com um anúncio e antes de converter, ou o usuário converteu sem nunca ver um anúncio associado. Detalhes e corpo do relatório trigger-aggregate-no-contributions
- Esse provavelmente não é o comportamento que você pretende que seu código tenha. Solucione o problema do 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ê pretende 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. Eles podem ser devido a um bug do navegador. Registre um bug e especifique na descrição as etapas para reproduzi-lo.
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 da Parte 2: configurar relatórios de depuração para configurar o sistema a fim de gerar relatórios de depuração concluídos e relatórios de depuração detalhados.
Com isso, é possível usar as informações de conversão com base em cookies para procurar os Relatórios de depuração ou de atribuição correspondentes.
Etapa 2: identificar registros concluídos e relatórios ausentes
Neste exemplo, vamos supor que você tenha acompanhado 100 conversões com seu sistema com base em cookies.
Sempre que você registrar uma conversão com base em cookies, procure o relatório de depuração de sucesso (enviado imediatamente) que tem o mesmo par de <source_debug_key, trigger_debug_key>
que essa conversão baseada em cookies.
Vamos supor que você tenha recebido um relatório de depuração de sucesso para 70 dessas conversões de cookies.
- Os relatórios de sucesso indicam que a atribuição foi registrada. Assim, é possível presumir com segurança que você receberá um relatório de atribuição correspondente a cada relatório de sucesso, com algumas exceções.
- É possível monitorar essas exceções. Para fazer isso, como os Relatórios de atribuição são enviados ao seu endpoint nos próximos dias/semanas (dependendo da validade), procure aqueles que tenham o mesmo par de chaves de depuração que cada relatório de depuração bem-sucedido. Aguarde um pouco: os relatórios podem não ser enviados imediatamente no final de cada janela. Vamos supor que você encontre somente 60 Relatórios de atribuição. Os 10 Relatórios de atribuição ausentes podem ser causados pelo comportamento do usuário.
Etapa 3: avaliação breve de perdas
De 100 a 70 = 30 relatórios de depuração de sucesso estão faltando. Isso significa que essas 30 conversões (que foram acompanhadas na implementação baseada em cookies) não foram registradas com a API Attribution Reporting. Você não receberá relatórios de atribuição por elas.
Como você tem 100 conversões com base em cookies e apenas 70 conversões 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 ausentes, 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 origem. Use as chaves das conversões com base em cookies para mapeá-las em relatórios de depuração detalhados.
- Vamos supor que existam 10 chaves para as quais não há relatório de depuração detalhado. Verifique se há algum problema de integração. Caso contrário, talvez seja devido ao comportamento do usuário.
- Você tem 20 relatórios de depuração detalhados. Agora é possível refinar sua análise de perdas. Analise o campo
type
de cada relatório detalhado. Por exemplo:- 10 (= 10% no nosso exemplo) relatórios estão faltando devido a
pending destination limit
- 5 (= 5%) relatórios estão ausentes devido a
trigger-aggregate-no-contributions
. - 5 (= 5%) relatórios estão ausentes devido a
unknown-error
.
- 10 (= 10% no nosso exemplo) relatórios estão faltando devido a
Etapa 5: tomar medidas e resolver problemas
Agora que você ganhou visibilidade sobre por que os relatórios estão ausentes, pode agir com base nesses insights.
A ação a ser realizada depende do type
de cada relatório detalhado. Revise a referência de relatórios detalhados para mais detalhes. Exemplo:
- O
pending-destination-limit
é uma proteção de privacidade. Nenhuma ação é necessária. Use esse número como um ponto de dados para sua própria visibilidade e monitoramento. trigger-aggregate-no-contributions
pode ser o sinal de um problema de implementação. Analise isso mais a fundo. Use as informações no corpo do relatório detalhado para resolver o problema e corrigir, se necessário.unknown-error
pode ser o sinal de um bug do navegador ou de um erro de rede. Se isso acontecer com frequência, registre um bug para os desenvolvedores do navegador.