Esta página foi traduzida pela API Cloud Translation.

Manual de depuração da API Attribution Reporting

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 da geração de relatórios é a origem que [define os cabeçalhos da origem e do acionador do Attribution Reporting. Todos os relatórios gerados pelo navegador são enviados para esta origem. Nesta orientação, usamos https://adtech.example como o exemplo de origem do relatório.
O relatório de atribuição (ou relatório, na sigla em inglês) é o relatório final (no nível do evento ou agregável) que contém os dados de medição solicitados.
Um relatório de depuração contém dados adicionais 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 incorretamente. 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. Eles 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 relatórios de depuração transicionais.
Os relatórios de depuração de sucesso acompanham a geração de um Relatório de atribuição. 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 relatórios ausentes e ajudar você a determinar o motivo deles. 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 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 de origem, um evento acionador ou um relatório de atribuição não foi gerado. Relatórios de depuração detalhados estão disponíveis a partir do Chrome 109 (Estável em janeiro de 2023).
As chaves de depuração são identificadores exclusivos que podem ser definidos no lado da origem e do acionador. As chaves de depuração permitem mapear conversões com base em cookies e em atribuição. Quando você configurar o sistema para gerar relatórios de depuração e definir chaves, o navegador vai incluir essas chaves em todos os Relatórios de atribuição e de depuração.

Para mais conceitos e termos-chave usados ao longo da 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

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 for source-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 do type 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.

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 o type de um relatório detalhado começar com trigger-aggregate, ele só poderá ser gerado para eventos de fonte ou acionador associados a relatórios agregáveis. Em todos os outros casos, é para um relatório agregável ou de evento.

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.

Observação:é possível que você tenha Relatórios de atribuição no nível do evento que não mapeiam para uma conversão com base em cookies. Provavelmente, esses são relatórios com ruído que foram 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 fonte que o relatório de evento.

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.

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.