Algumas tecnologias do Sandbox de privacidade estão sendo desativadas.

Confira nossa Atualização sobre os planos para as tecnologias do Sandbox de privacidade. O

status dos recursos do Sandbox de privacidade fornece mais informações sobre o status de APIs e recursos da plataforma individuais.

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 a depuração dos Relatórios de atribuição. Configure seus 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.

Dúvidas sobre a implementação?

Se você tiver problemas ao configurar relatórios de depuração, crie um problema no repositório de suporte a desenvolvedores e vamos ajudar você a resolver.

Preparar para configurar relatórios de depuração

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

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

Verifique se o código está protegido por detecção de recursos. Para garantir que a API não esteja 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 fundamentais de integração

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 incorreta do cabeçalho de origem e de acionamento, problemas de análise JSON, contexto não seguro (não HTTPS) e outros problemas que impedem o funcionamento da API vão aparecer na guia Problemas do DevTools.

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

Validar cabeçalhos de 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 originados do navegador para facilitar a depuração da API.

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

Attribution-Reporting-Info: report-header-errors

A Attribution-Reporting-Info é um cabeçalho estruturado em 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 para o 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
  }
}]

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 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 são desativados para facilitar os testes e a preparação para a descontinuação do uso de 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 de sucesso.

Etapa 2: definir chaves de depuração

Cada chave de depuração precisa ser um número inteiro sem sinal de 64 bits formatado como uma string de base 10. Faça de cada chave de depuração 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 origem para outras informações de tempo de origem que você considera relevantes para depurar.
Mapeie a chave de depuração do lado do gatilho para outras informações de tempo de acionamento que você acha relevantes para depurar.

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

ID do cookie + carimbo de data/hora de origem como uma chave de depuração de origem (e capture o mesmo carimbo de data/hora no seu sistema baseado em cookie)
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).

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. Saiba mais na Parte 3: 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 que têm 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 de acionador

Configurar relatórios de depuração de sucesso

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

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

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 adicional 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 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 usando uma solicitação POST para esse endpoint. O código do servidor para processar relatórios de depuração de sucesso recebidos pode ter esta 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 event-level debug reports

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

Etapa 4: confirmar se 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 no nível do evento e Relatórios agregáveis.
Abra os sites em que você implementou a API Attribution Reporting. Siga as etapas que você usa para gerar relatórios de atribuição. Elas também vão gerar relatórios de depuração de sucesso.
Em chrome://attribution-internals:
- Verifique se os relatórios de atribuição estão sendo 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 foram gerados. Reconheça-os na lista com o caminho azul debug.

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

Como informar registros do servidor de origem — Relatório de registros do servidor de origem

Etapa 5: analisar 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

Etapa 3: ativar a depuração detalhada nos cabeçalhos de origem e de acionamento

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: origem cabeçalho

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

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 adicional 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 ser semelhante a este (aqui em um endpoint de 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 de eventos e agregados 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, basta verificar a 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 de relatórios de depuração detalhados também serão gerados e recebidos corretamente, porque todos usam a mesma configuração e são enviados para o mesmo endpoint.

Importante:escolha um relatório de depuração detalhado que seja óbvio para testar. trigger-no-matching-source é uma boa opção porque pode ser gerado por conversão. Relatórios detalhados relacionados a eventos de acionamento tendem a ser melhores candidatos. Já os tipos de relatórios detalhados relacionados a eventos de origem são mais difíceis de gerar propositalmente.

Abra chrome://attribution-internals no navegador.
Acione uma atribuição (conversão) no seu site configurado com os relatórios de atribuição. 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 origem 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 contendo relatórios de depuração detalhada, enviada 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 qual ação tomar dependendo de cada tipo, consulte a referência de relatórios detalhados em Parte 3: Receitas de depuração.
Body: O corpo do relatório. Isso depende do tipo de arquivo. Consulte a referência de relatórios detalhados em Parte 3: Receitas 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 no nível do evento ou agregáveis. Uma falha no registro de origem ou acionador tem apenas um motivo. Portanto, um relatório detalhado pode ser gerado por falha e por tipo de relatório (no nível do evento ou agregável).
Dois relatórios detalhados se a falha afetar os relatórios no nível do evento e agregáveis, com uma exceção: se o motivo da falha for o mesmo para os dois tipos de relatórios, apenas um relatório detalhado será gerado (exemplo: trigger-no-matching-source).

Parte 3: manual de depuração