Configurar relatórios de depuração para a API Attribution Reporting

Parte 2 de 3 sobre a depuração dos Relatórios de atribuição. Configure seus relatórios de depuração.

Observação:este artigo faz parte de uma série sobre depuração da API Attribution Reporting. Esta série aborda a depuração do lado do cliente em relatórios agregáveis e de eventos. As orientações de depuração do lado do servidor para relatórios de resumo estão disponíveis no GitHub (link em inglês).

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.

Dúvidas sobre implementação?

Se você encontrar algum problema ao configurar os relatórios de depuração, crie um problema no nosso repositório de suporte ao desenvolvedor e ajudaremos você a solucioná-lo.

Preparar-se para configurar os relatórios de depuração

Antes de configurar relatórios de depuração, siga estas etapas:

Verificar se você aplicou as práticas recomendadas para a integração de APIs

• Confira se o seu código está protegido pela detecção de recursos. Para garantir que a API não seja bloqueada por Permissions-Policy, execute o seguinte código:

  if (document.featurePolicy.allowsFeature('attribution-reporting')) {
  // the Attribution Reporting API is enabled
  }
  

  Se essa verificação de detecção de recursos retornar verdadeiro, a API será permitida no contexto (página) em que a verificação é executada.

• Não é necessário durante a fase de teste: verifique se você definiu uma Permissions-Policy.

Importante:os requisitos da política de permissões foram flexíveis para testes, mas um editor ou anunciante ainda pode decidir desativar explicitamente a API Attribution Reporting usando a política Permissions-Policy. Nesse caso, nenhuma fonte ou acionador pode ser registrado e, portanto, nenhum relatório pode ser gerado ou enviado.

Corrigir problemas fundamentais de integração

Embora os relatórios de depuração sejam úteis para detectar e analisar a perdas em grande escala, alguns problemas de integração podem ser detectados localmente. Problemas de configuração incorreta do cabeçalho da origem e do acionador, problemas de análise do JSON, contexto não seguro (não HTTPS) e outros problemas que impedem o funcionamento da API são exibidos na guia Problemas do DevTools.

Observação:esses problemas não geram relatórios de depuração detalhados, porque fazem com que a API não funcione. Somente a ausência de relatórios de depuração bem-sucedidos indica que você pode estar encontrando alguns desses problemas. Saiba mais na Parte 3: manual de depuração.

Os problemas do DevTools podem ser de diferentes tipos. Se você encontrar um problema com o invalid header, copie o cabeçalho na ferramenta de validação de cabeçalhos. Isso ajudará você a identificar e corrigir o campo que está causando um problema.

Configurar relatórios de depuração: etapas comuns para relatórios de sucesso e relatórios detalhados

Etapa 1: definir o cookie de depuração

Defina o seguinte cookie na origem do relatório:

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

O navegador vai verificar a presença desse cookie no registro da fonte e do acionador. O relatório de depuração de sucesso só será gerado se o cookie estiver presente nos dois momentos.

Código de demonstração: cookie de depuração

Os relatórios de depuração podem ser ativados para navegadores no modo B, em que os cookies de terceiros estão desativados para facilitar o teste e a preparação para a descontinuação dos cookies de terceiros. Para navegadores no modo B, não é necessário definir o cookie de depuração para ativar os relatórios de depuração. Pule para a etapa 2 e configure chaves de depuração para relatórios de depuração bem-sucedidos.

Etapa 2: definir chaves de depuração

Cada chave de depuração precisa ser um número inteiro não assinado de 64 bits formatado como uma string base-10. Transforme cada chave de depuração em um ID exclusivo. O relatório de depuração de sucesso só será gerado se as chaves de depuração estiverem definidas.

• Mapeie a chave de depuração do lado da fonte para outras informações do tempo de origem que você acha relevantes para depuração.
• Mapeie a chave de depuração do lado do acionador para ver outras informações do tempo de acionamento que você achar que são relevantes para depuração.

Por exemplo, você pode definir as seguintes chaves de depuração:

• ID do cookie + carimbo de data/hora da origem como uma chave de depuração de origem (e capturar o mesmo carimbo de data/hora no sistema baseado em cookies)
• ID do cookie + carimbo de data/hora do acionador como uma chave de depuração do acionador (e capturar o mesmo carimbo de data/hora no sistema baseado em cookies)

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. Saiba mais na Parte 3: manual.

Torne a chave de depuração no lado da origem diferente de source_event_id para diferenciar relatórios individuais que têm o mesmo ID do evento de origem.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}

Código de demonstração: chave de depuração de origem Código de demonstração: chave de depuração do acionador

Observação:no código de demonstração, fornecemos às duas chaves de depuração o valor do cookie de terceiros de medição legado. Em um sistema real, você tornaria cada chave um ID exclusivo e o mapearia para outras informações de tempo de origem que você considera úteis para depuração, conforme sugerido no exemplo de chaves de depuração acima.

Configurar relatórios de depuração bem-sucedidos

Observação:teste a demonstração para gerar e visualizar relatórios de depuração bem-sucedidos no navegador. Analise o código correspondente.

O código de exemplo nesta seção gera relatórios de depuração de sucesso para relatórios agregáveis e de evento. Os relatórios agregáveis e de evento usam as mesmas chaves de depuração.

Etapa 3: configurar um endpoint para coletar relatórios de depuração bem-sucedidos

Configure um endpoint para coletar os relatórios de depuração. Esse endpoint precisa ser semelhante ao endpoint de atribuição principal, com uma string debug extra no caminho:

• Endpoint para relatórios de depuração de sucesso no nível do evento: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
  • Endpoint para relatórios de depuração agregáveis: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

Quando uma atribuição é acionada, o navegador envia imediatamente um relatório de depuração por uma solicitação POST para esse endpoint. O código do servidor para processar os relatórios de depuração de sucesso recebidos pode ter a seguinte aparência (em um endpoint do nó):

// Handle incoming event-Level Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-event-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

// Handle incoming aggregatable Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-aggregate-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

Código de demonstração: endpoint de relatórios de depuração no nível do evento

Código de demonstração: endpoint de relatórios de depuração agregáveis

Etapa 4: confirmar se sua configuração vai gerar relatórios de depuração bem-sucedidos

• Abra chrome://attribution-internals no navegador.
• Verifique se a caixa de seleção Mostrar relatórios de depuração está marcada nas guias Relatórios de evento e Relatórios agregáveis.
• Abra os sites em que você implementou a API Attribution Reporting. Conclua as etapas que você usa para gerar relatórios de atribuição. Essas mesmas etapas vão gerar relatórios de depuração bem-sucedidos.
• Em chrome://attribution-internals:
  • Verifique se os Relatórios de atribuição foram gerados corretamente.
  • Nas guias Relatórios de evento e Relatórios agregáveis, verifique se os relatórios de depuração de sucesso também são gerados. Reconheça-os na lista com o caminho debug azul.

• No seu servidor, verifique se o endpoint recebe imediatamente esses relatórios de depuração bem-sucedidos. Confira se há relatórios de depuração agregáveis e no nível do evento.

Etapa 5: observar os relatórios de depuração de sucesso

Um relatório de depuração de sucesso é idêntico a um relatório de atribuição e contém as chaves de depuração do lado da fonte e do acionador.

{
  "attribution_destination": "https://advertiser.example",
  "randomized_trigger_rate": 0.0000025,
  "report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
  "source_debug_key": "647775351539539",
  "source_event_id": "760938763735530",
  "source_type": "event",
  "trigger_data": "0",
  "trigger_debug_key": "156477391437535"
}

{
  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
      "payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
    }
  ],
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
  "source_debug_key": "647775351539539",
  "trigger_debug_key": "156477391437535"
}

Configurar relatórios de depuração detalhados

Observação:teste a demonstração para gerar e visualizar relatórios de depuração detalhados no navegador. Analise o código correspondente.

Etapa 3: ativar a depuração detalhada nos cabeçalhos de fonte e acionador

Defina debug_reporting como true em Attribution-Reporting-Register-Source e Attribution-Reporting-Register-Trigger.

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Código de demonstração: cabeçalho de origem

Código de demonstração: cabeçalho do gatilho

Etapa 4: configurar um endpoint para coletar relatórios de depuração detalhados

Configure um endpoint para coletar os relatórios de depuração. Esse endpoint precisa ser semelhante ao principal de atribuição, com uma string debug/verbose extra no caminho:

https://adtech.example/.well-known/attribution-reporting/debug/verbose

Quando relatórios de depuração detalhados são gerados, ou seja, quando uma fonte ou um acionador não está registrado, o navegador envia imediatamente um relatório de depuração detalhado por uma solicitação POST para esse endpoint. O código do servidor para processar os relatórios de depuração detalhados recebidos pode ter a seguinte aparência (aqui em um endpoint do nó):

// Handle incoming verbose debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/verbose',
  async (req, res) => {
    // List of verbose debug reports is in req.body
    res.sendStatus(200);
  }
);

Ao contrário dos relatórios de depuração de sucesso, há apenas um endpoint para relatórios detalhados. Os relatórios detalhados relacionados aos relatórios agregados e de evento serão enviados para o mesmo endpoint.

Código de demonstração: endpoint de relatórios de depuração detalhados

Etapa 5: confirmar se a configuração vai gerar relatórios de depuração detalhados

Embora existam vários tipos de relatórios de depuração detalhados, é suficiente verificar sua configuração de depuração detalhada com apenas um tipo de relatório de depuração detalhado. Se esse tipo de relatório de depuração detalhado for gerado e recebido corretamente, isso significa que todos os tipos também serão gerados e recebidos corretamente, porque todos os relatórios de depuração detalhados usam a mesma configuração e são enviados para o mesmo endpoint.

Importante:escolha um relatório de depuração detalhado que seja simples de testar. trigger-no-matching-source é um bom candidato, porque você pode gerá-lo convertendo. Relatórios detalhados relacionados a eventos acionadores tendem a ser melhores candidatos. Os tipos de relatório detalhado relacionados a eventos de origem são mais tediosos de serem gerados propositalmente.

1. Abra chrome://attribution-internals no navegador.
2. Acionar uma atribuição (conversão) no seu site que está configurado com a API Attribution Reporting. Como não houve engajamento com o anúncio (impressão ou clique) antes dessa conversão, um relatório de depuração detalhado do tipo trigger-no-matching-source será gerado.
3. Em chrome://attribution-internals, abra a guia Relatórios de depuração detalhados e verifique se um relatório de depuração detalhado do tipo trigger-no-matching-source foi gerado.
4. No seu servidor, verifique se o endpoint recebeu imediatamente esse relatório de depuração detalhado.

Etapa 6: observar relatórios de depuração detalhados

Os relatórios de depuração detalhados gerados no momento do acionamento incluem a chave da fonte e a chave de depuração do acionador (se houver uma origem correspondente para o acionador). Os relatórios de depuração detalhados gerados no momento da origem incluem a chave de depuração do lado da origem.

Exemplo de uma solicitação que contém relatórios de depuração detalhados, enviados pelo navegador:

[
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "randomized_trigger_rate": 0.0000025,
      "report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_type": "event",
      "trigger_data": "1",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-event-low-priority"
  },
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "limit": "65536",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_site": "http://arapi-publisher.localhost",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-aggregate-insufficient-budget"
  }
]

Importante:ao contrário de uma solicitação de depuração bem-sucedida, uma solicitação de depuração detalhada contém uma lista (matriz) de relatórios detalhados no corpo.

Cada relatório detalhado contém os campos abaixo:

Type

O que causou a geração do relatório. Para saber mais sobre todos os tipos de relatórios detalhados e quais ações tomar dependendo de cada tipo, consulte a referência de relatórios detalhados na Parte 3: manual de depuração.

Body

O corpo do relatório. Dependerá do tipo. Consulte a referência de relatórios detalhados na Parte 3: manual de depuração.

O corpo de uma solicitação conterá pelo menos um e no máximo dois relatórios detalhados:

• Um relatório detalhado se a falha afetar apenas relatórios de eventos (ou se afetar apenas relatórios agregáveis). Uma falha no registro da fonte ou do acionador tem apenas um motivo. Portanto, um relatório detalhado pode ser gerado por falha e por tipo de relatório (nível do evento ou agregável).
• Dois relatórios detalhados se a falha afetar relatórios de evento e agregáveis com uma exceção: se o motivo da falha for o mesmo para relatórios de evento e agregáveis, apenas um relatório detalhado será gerado (exemplo: trigger-no-matching-source).

A seguir

Parte 3: manual de depuração