Esta página foi traduzida pela API Cloud Translation.

Attribution Reporting: visão geral completa do sistema

Visão geral dos serviços conectados para a API Attribution Reporting, destinada a tomadores de decisões técnicas.

A API Attribution Reporting permite que as adtechs e os anunciantes meçam quando um clique ou uma visualização no anúncio leva a uma conversão, como uma compra. Essa API depende de uma combinação de integrações do lado do cliente e do servidor, dependendo das necessidades da sua empresa.

Antes de continuar, leia a Visão geral dos Relatórios de atribuição. Isso ajudará você a entender a finalidade da API e o fluxo dos diferentes relatórios de saída (relatórios de eventos e de resumo). Se você se deparar com termos desconhecidos, consulte o glossário do Sandbox de privacidade.

Qual é o público deste artigo?

Leia este artigo se:

Você é o tomador de decisões técnicas de uma adtech ou de um anunciante. Você pode trabalhar em operações, DevOps, ciência de dados, TI, marketing ou outra função em que toma decisões de implementação técnica. Você está se perguntando como as APIs funcionam para fazer medições que preservam a privacidade.
Você é um profissional técnico (como desenvolvedor, operador de sistemas, arquiteto de sistemas ou cientista de dados) que vai configurar experimentos com esse ambiente de API e serviço de agregação.

Neste artigo, você vai ler uma explicação de alto nível sobre como os serviços funcionam para a API Attribution Reporting. Se você é um profissional técnico, teste essa API localmente.

Visão geral

A API Attribution Reporting consiste em muitos serviços que exigem configurações específicas do lado do cliente e implantações de servidor. Para determinar o que você precisa, primeiro:

Tomar decisões de design. Defina as informações que você quer coletar, identifique as conversões que espera de determinada campanha e determine qual tipo de relatório coletar. O resultado final é um ou ambos os tipos de relatório: relatórios de eventos e relatórios de resumo.

Sempre há dois (e às vezes três) componentes que trabalham juntos para dar suporte aos relatórios:

Comunicação entre sites e navegadores. Em sistemas baseados em cookies, as informações de conversões e engajamentos com o anúncio são anexadas a um identificador que permite que você ou um serviço de análise participe desses eventos posteriormente. Com essa API, o navegador associa as conversões a cliques/visualizações de anúncios com base nas suas instruções antes de enviá-lo para análise. Portanto, o código de renderização do anúncio e o acompanhamento de conversões precisam:
- Informe ao navegador quais conversões devem ser atribuídas a quais cliques ou impressões de anúncio.
- Sinalize outros dados a serem incluídos nos relatórios finais.
Coleta de dados. Você vai precisar de um endpoint do coletor para receber os relatórios gerados nos navegadores dos usuários. A saída dos navegadores pode ser um destes dois relatórios possíveis: relatórios de eventos e agregáveis, que são criptografados e usados para gerar relatórios de resumo.

Se você coletou relatórios agregáveis, vai precisar de um terceiro componente:

Geração de relatórios de resumo. Relatórios agregáveis em lote e usar o serviço de agregação para processar os relatórios e gerar um relatório de resumo.

Decisões de design

Um princípio fundamental da API Attribution Reporting são decisões iniciais de design. Você decide quais dados coletar em quais categorias e com que frequência processar esses dados. Os relatórios resultantes fornecem insights sobre suas campanhas ou negócios.

O relatório de saída pode ser:

Os relatórios de evento associam um clique ou uma visualização específica do anúncio (no lado do anúncio) com os dados do lado da conversão. Para preservar a privacidade do usuário limitando a combinação de identidades de usuários em todos os sites, os dados de conversão são muito limitados e confusos. Isso significa que, em uma pequena porcentagem de casos, dados aleatórios são enviados em vez de relatórios reais.
Os relatórios de resumo não estão vinculados a um evento específico no anúncio. Esses relatórios oferecem dados de conversão mais detalhados e flexibilidade para unir dados de cliques e visualizações a dados de conversão.

A seleção do relatório determina quais dados você precisará coletar.

Também é possível pensar no resultado final como uma entrada para as ferramentas que você usa para tomar decisões. Por exemplo, se você gerar relatórios de resumo para determinar quantas conversões levaram a um valor de gasto total, isso pode ajudar sua equipe a decidir qual deve ser a meta da próxima campanha publicitária para gerar um gasto total maior.

Depois de decidir o que medir, configure o lado do cliente para a API Attribution Reporting.

Comunicação entre sites e navegadores

As fontes de atribuição no site de um editor se conectam aos acionadores no site de um anunciante. — As fontes de atribuição no site de um editor se conectam a acionadores no site de um anunciante.

Fluxo de eventos de atribuição

Imagine o site de um editor que exibe anúncios. Cada anunciante ou provedor de adtech quer saber mais sobre as interações com os anúncios e atribuir conversões ao anúncio correto. Os relatórios (de evento e agregáveis) seriam gerados desta forma:

No site do editor, um elemento de anúncio (tag <a> ou <img>) é configurado com um atributo especial attributionsrc. O valor dela é um URL, por exemplo, https://adtech.example/register-source/ad_id=....

Veja um exemplo de link que registra uma fonte quando é clicado:
```
<a href="https://shoes.example/landing" 
  attributionsrc="http://adtech.example/register-source?..."
  target="_blank">
Click me</a>
```
Confira um exemplo de imagem que causa o registro de uma origem quando visualizada:
```
<img href="https://advertiser.example/landing" 
  attributionsrc="https://adtech.example/register-source?..."/>
```
Como alternativa, em vez de elementos HTML, as chamadas JavaScript podem ser usadas.

Confira um exemplo de JavaScript usando window.open(). O URL é codificado para evitar problemas com caracteres especiais.
```
const encodedUrl = encodeURIComponent(
  'https://adtech.example/attribution_source?ad_id=...');
window.open(
  "https://shoes.example/landing",
  "_blank",
  attributionsrc=${encodedUrl});
```

Quando o usuário clica ou visualiza o anúncio, o navegador envia uma solicitação GET para attributionsrc, que normalmente é um endpoint de anunciante ou provedor de adtech.
Ao receber essa solicitação, o anunciante ou provedor de adtech decide instruir o navegador a registrar eventos de origem para interações com o anúncio. Assim, as conversões podem ser atribuídas a ele mais tarde. Para isso, o anunciante ou provedor de adtech inclui um cabeçalho HTTP especial na resposta. Ele anexa esses dados personalizados do cabeçalho que fornecem informações sobre o evento de origem (o clique ou a visualização do anúncio). Se ocorrer uma conversão nesse anúncio, esses dados personalizados serão exibidos no Relatório de atribuição.
Mais tarde, o usuário visita o site do anunciante.
Em cada página relevante do site do anunciante (por exemplo, uma página de confirmação de compra ou uma página de produto), um pixel de conversão (elemento <img>) ou uma chamada JavaScript faz uma solicitação para https://adtech.example/conversion?param1=...&param2=....
O serviço nesse URL, normalmente o anunciante ou o provedor de adtech, recebe a solicitação. Ele decide classificá-la como conversão e precisa instruir o navegador a registrar uma conversão, ou seja, acionar uma atribuição. Para isso, o anunciante ou provedor de adtech inclui na resposta à solicitação de pixel um cabeçalho HTTP especial que inclui dados personalizados sobre a conversão.
O navegador no dispositivo local do usuário recebe essa resposta e faz a correspondência dos dados de conversão com o evento de origem (clique ou visualização do anúncio). Saiba mais em Corresponder origens a acionadores
O navegador programa o envio de um relatório para attributionsrc. Esse relatório inclui:
1. São os dados de configuração da atribuição personalizada que o provedor de adtech ou o anunciante anexou ao evento de origem na etapa 3.
2. O conjunto de dados de conversão personalizado na etapa 6
Mais tarde, o navegador envia os relatórios para o endpoint definido em attributionsrc, com algum atraso e ruído. Os relatórios agregáveis são criptografados, mas os relatórios de eventos não.

Acionadores de atribuição (site do anunciante)

O acionador de atribuição é o evento que instrui o navegador a capturar conversões.

Recomendamos capturar as conversões mais importantes para o anunciante, como compras. Vários tipos de conversão e metadados podem ser capturados em relatórios de resumo.

Isso garante que os resultados agregados sejam detalhados e precisos para esses eventos.

Corresponder origens a acionadores

Quando um navegador recebe uma resposta do acionador de atribuição, ele acessa o armazenamento local para encontrar uma fonte que corresponda à origem do acionador e ao eTLD+1 do URL da página.

Por exemplo, quando o navegador recebe um acionador de atribuição de adtech.example em shoes.example/shoes123, ele procura uma fonte no armazenamento local que corresponda a adtech.example e shoes.example.

Filtros (ou regras personalizadas) podem ser definidos para determinar quando um acionador corresponde a uma fonte específica. Por exemplo, defina um filtro para contar apenas conversões de uma categoria específica de produto e ignorar todas as outras categorias. Filtros e modelos de priorização permitem relatórios de atribuição mais avançados.

Quando várias fontes de atribuição são encontradas no armazenamento local, o navegador escolhe aquela que foi armazenada mais recentemente. Em alguns casos em que as fontes de atribuição recebem prioridade, o navegador vai selecionar a fonte com a maior prioridade.

Coleta de dados

Juntos, um acionador de atribuição que corresponde a uma fonte correspondente, é enviado como um relatório pelo navegador para um endpoint de relatórios em um servidor de adtech (às vezes chamado de endpoint de coleta ou serviço de coleta). Esses relatórios podem ser de eventos ou agregáveis.

Os relatórios agregáveis são usados para gerar relatórios de resumo. Um relatório agregável é uma combinação de dados coletados do anúncio (no site de um editor) e de conversão (do site do anunciante), gerados e criptografados pelo navegador no dispositivo do usuário antes de serem coletados pela adtech.

Os relatórios de eventos têm um atraso de 2 a 30 dias. Os relatórios agregáveis são enviados com um atraso aleatório em até uma hora, e os eventos precisam estar dentro do orçamento de contribuição. Essas escolhas protegem a privacidade e impedem a exploração das ações de qualquer usuário.

Se você só tem interesse em relatórios de eventos, essa é a última parte da infraestrutura de que você precisa. No entanto, se você quiser gerar relatórios de resumo, será necessário processar os relatórios agregáveis com um serviço adicional.

Geração de relatórios de resumo

Para gerar relatórios de resumo, use o Serviço de agregação (operado pela adtech) para processar os relatórios agregáveis. O serviço de agregação adiciona ruído para proteger a privacidade do usuário e retorna o relatório de resumo final.

Os relatórios agregáveis são coletados, agrupados e enviados ao ambiente de adtechs. — Esse diagrama representa o fluxo assíncrono de dados do endpoint de coleta, relatórios em lote, até o processamento no serviço de agregação da adtech.

Depois de enviar em lote os relatórios agregáveis coletados, o lote é processado pelo serviço de agregação. Um coordenador fornece as chaves de descriptografia apenas para versões atestados do serviço de agregação. Em seguida, o serviço de agregação descriptografa os dados, os agrega e adiciona ruído antes de retornar os resultados como um relatório de resumo.

Relatórios agregáveis em lote

Antes do processamento dos relatórios agregáveis, eles precisam ser organizados em lote. Um lote consiste em relatórios agregáveis agrupados estrategicamente. É provável que sua estratégia reflita um período específico, como uma vez por dia ou por semana. Esse processo pode ocorrer no mesmo servidor que atua como endpoint de relatórios.

Os lotes devem conter muitos relatórios para garantir que a proporção sinal-ruído seja alta.

Períodos maiores levam a resultados com menos ruído. — Comparar a espera de um dia e uma semana. Em 1 hora, você terá um valor de resumo menor com resultados provavelmente com mais ruído. Em um dia, você terá um valor de resumo maior, então é provável que haja menos ruído.

Os períodos de lote podem mudar a qualquer momento para garantir que você capture eventos específicos em que espera um volume maior, como uma promoção anual. O período de lote pode ser alterado sem a necessidade de mudar as fontes de atribuição ou os acionadores.

Serviço de agregação

O Serviço de agregação é responsável por processar relatórios agregáveis para gerar um relatório de resumo. Os relatórios agregáveis são criptografados e só podem ser lidos pelo serviço de agregação, que é executado em um ambiente de execução confiável (TEE).

O serviço de agregação solicita chaves de descriptografia ao coordenador para descriptografar e agregar os dados. Depois de descriptografados e agregados, os resultados são gerados para preservar a privacidade e retornados como um relatório de resumo.

Os profissionais podem gerar relatórios agregáveis de texto não criptografado para testar o serviço de agregação localmente. Ou é possível testar com relatórios criptografados na AWS usando Nitro Enclaves.

A seguir

Queremos conversar com você para garantir a criação de uma API que funcione para todos.

Conversar sobre a API

Assim como outras APIs do Sandbox de privacidade, essa API é documentada e discutida publicamente.

Teste a API

Você pode fazer testes e participar de conversas sobre a API Attribution Reporting.