Esta página foi traduzida pela API Cloud Translation.

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

Parte 2 de 3 sobre depuração da API Attribution Reporting. Configurar os relatórios de depuração.

Glossário

报告来源是用于设置归因报告来源和触发器标头的来源。浏览器生成的所有报告都会发送到此源。在本指南中，我们使用 https://adtech.example 作为示例报告来源。
归因报告（简称“报告”）是包含您请求的衡量数据的最终报告（事件级报告或可汇总报告）。
调试报告包含有关归因报告或者来源或触发器事件的其他数据。收到调试报告并不一定表示存在问题！调试报告有两种
过渡调试报告是一种调试报告，需要设置 Cookie 才能生成和发送。如果 Cookie 未设置且第三方 Cookie 被弃用，过渡调试报告将不可用。本指南中描述的所有调试报告都是过渡性调试报告。
成功调试报告用于跟踪成功生成归因报告。它们与归因报告直接相关。从 Chrome 101（2022 年 4 月）开始，已提供成功调试报告。
详细调试报告可以跟踪缺失的报告，并帮助您确定缺失报告的原因。它们分别用于表明浏览器未记录来源或触发器事件（这意味着浏览器不会生成归因报告）以及由于某种原因无法生成或发送归因报告的情况。详细调试报告包含一个 type 字段，用于说明未生成来源事件、触发器事件或归因报告的原因。从 Chrome 109（2023 年 1 月稳定版）开始提供详细调试报告。
调试键是您可以在来源端和触发器端设置的唯一标识符。通过调试键，您可以映射基于 Cookie 的转化和基于归因的转化。将系统设置为生成调试报告并设置调试密钥后，浏览器会将这些调试密钥添加到所有归因报告和调试报告中。

如需了解我们的文档中使用的更多概念和关键术语，请参阅 Privacy Sandbox 术语表。

Dúvidas de implementação?

Se você encontrar problemas ao configurar os relatórios de depuração, crie um problema no nosso repositório de suporte ao desenvolvedor e vamos ajudar a solucionar o problema.

Preparar para configurar relatórios de depuração

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

Confira se você aplicou as práticas recomendadas para integração de API

Verifique se o código está protegido pela detecção de recursos. Para garantir que a API não seja bloqueada pela 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 "true", 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.

Corrigir problemas de integração fundamentais

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

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

Validar cabeçalhos dos Relatórios de atribuição

Use o validador de cabeçalho para validar cabeçalhos relacionados à API Attribution Reporting. É possível monitorar erros de validação originários do navegador para facilitar a depuração da API.

Para ativar o recebimento de relatórios de depuração, responda com report-header-errors como parte do cabeçalho de resposta "Attribution-Reporting-Info".

Attribution-Reporting-Info: report-header-errors

Attribution-Reporting-Info é um cabeçalho estruturado de dicionárioAttribution-Reporting-Info. Portanto, fornecer a chave booleana report-header-errors implica um valor verdadeiro.

Os relatórios de depuração são enviados imediatamente ao endpoint de relatórios:

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

Os dados do relatório são incluídos no corpo da solicitação como uma lista JSON de objetos com este formato:

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]

Captura de tela: ferramenta de validação de cabeçalho

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

Defina o seguinte cookie na origem de relatórios:

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

O navegador vai verificar a presença desse cookie no registro da origem 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 são desativados para facilitar os testes 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 para configurar chaves de depuração para relatórios de depuração com sucesso.

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 de base 10. Crie um ID exclusivo para cada chave de depuração. 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 do código-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 outras informações de tempo de acionamento que você acha relevante para depuração.

Você pode, por exemplo, definir as seguintes chaves de depuração:

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

Dessa forma, você pode usar 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: livro de receitas.

Faça com que a chave de depuração do lado da origem seja diferente de source_event_id para que você possa diferenciar relatórios individuais com o mesmo ID de 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

Configurar relatórios de depuração de sucesso

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

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

Configurar 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 no nível do evento: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Endpoint para relatórios de depuração de sucesso 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 com uma solicitação POST para esse endpoint. O código do servidor para processar relatórios de depuração de sucesso recebidos pode ter a seguinte aparência (aqui em um endpoint de 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 dos relatórios de depuração no nível do evento

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

Etapa 4: confirmar que a configuração vai gerar relatórios de depuração de sucesso

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 os Relatórios de atribuição. Siga as etapas que você usa para gerar Relatórios de atribuição. Essas mesmas etapas vão gerar relatórios de depuração.
Em chrome://attribution-internals:
- Verifique se os relatórios de atribuição são gerados corretamente.
- Nas guias Relatórios no nível do 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.

Captura de tela: detalhes internos da atribuição

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

Captura de tela: relatórios de registros do servidor de origem

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 origem 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

Etapa 3: ativar a depuração detalhada nos cabeçalhos de origem 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 de 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 endpoint de atribuição principal, 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 é registrado, o navegador envia imediatamente um relatório de depuração detalhado usando uma solicitação POST para esse endpoint. O código do servidor para processar 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 a relatórios agregados e de eventos são enviados para o mesmo endpoint.

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

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

Embora existam vários tipos de relatórios de depuração detalhados, basta verificar a configuração de depuração detalhada com apenas um tipo de relatório detalhado. Se esse tipo de relatório de depuração detalhado for gerado e recebido corretamente, todos os tipos de relatórios de depuração detalhados 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 ele pode ser gerado por uma conversão. Relatórios detalhados relacionados a eventos acionadores tendem a ser melhores candidatos. Os tipos de relatórios detalhados relacionados a eventos de origem são mais tediosos de serem gerados propositalmente.

Abra chrome://attribution-internals no navegador.
Acionar uma atribuição (converter) no seu site 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.
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.
No 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 acionador incluem a chave de depuração do lado da fonte e 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"
  }
]

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 um, consulte a referência dos relatórios detalhados na Parte 3: manual de depuração.
Body: O corpo do relatório. Isso vai depender do tipo. Consulte a referência de relatórios detalhados na Parte 3: Guia de depuração.

O corpo de uma solicitação vai 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 só relatórios agregáveis). Uma falha no registro de fonte ou acionador tem apenas um motivo. Portanto, um relatório detalhado pode ser gerado por falha e por tipo de relatório (de evento ou agregável).
Dois relatórios detalhados se a falha afetar os relatórios de evento e agregáveis, com uma exceção: se o motivo da falha for o mesmo para os relatórios de evento e agregáveis, apenas um relatório detalhado será gerado (exemplo: trigger-no-matching-source).

Parte 3: manual de depuração