Visão geral dos serviços conectados para a API Attribution Reporting, voltada a tomadores de decisões técnicas.
Com a API Attribution Reporting, as adtechs e os anunciantes medem quando uma o clique ou a visualização do anúncio levam a uma conversão, como uma compra. Essa API depende uma combinação de integrações do lado do cliente e do servidor, dependendo do seu de negócios.
Antes de continuar, leia Visão geral da API Attribution Reporting. Isso vai ajudar você a entender a finalidade da API e o fluxo dos diferentes relatórios de saída (relatório de eventos e relatórios de resumo). Se você se deparar com termos desconhecidos, consulte 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 um anunciante ou adtech. Talvez você trabalhe em operações, DevOps, ciência de dados, TI, marketing ou outra função em que você toma decisões técnicas de implementação. Você quer saber como as APIs funcionam para medições que preservam a privacidade.
- Você for um profissional técnico (como desenvolvedor, operador de sistema, arquiteto de sistemas ou cientista de dados) que vai configurar experimentos essa API e o ambiente do serviço de agregação.
Neste artigo, você lerá uma explicação de alto nível de ponta a ponta de como o funcionam para a API Attribution Reporting. Se você é um técnico profissional, é possível experimentar com essa API localmente.
Visão geral
A API Attribution Reporting consiste em muitos serviços que exigem requisitos configurações do lado do cliente e implantações de servidores. Para determinar o que de que você precisa, primeiro:
- Tome decisões de design. Defina quais informações você quer coletar, identifique quais conversões você espera de uma determinada campanha e determine qual tipo de relatório coletar. O resultado final é um ou ambos os dois tipos de relatório: relatórios de evento e relatórios de resumo.
Sempre há dois (e às vezes três) componentes que trabalham juntos para oferecer suporte à geração de relatórios:
- Comunicação entre sites e navegadores. Em
sistemas com base em cookies, informações para conversões e engajamentos com anúncios
anexados a um identificador que permite a você ou um serviço de análise participar
esses eventos mais tarde. Com essa API, o navegador associa conversões a
cliques/visualizações de anúncios, com base nas suas instruções, antes da veiculação
análise. Sendo assim, seu código de renderização de anúncios e o acompanhamento de conversões precisam:
- Informar ao navegador quais conversões devem ser atribuídas a qual anúncio cliques ou impressões.
- 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 no navegadores da Web. Saída dos navegadores há dois tipos possíveis: relatórios a nível de evento e agregáveis (que são criptografados, usados para gerar relatórios de resumo).
Se você coletou relatórios agregáveis, vai precisar de um terceiro componente:
- Geração do relatório de resumo. Lote relatórios agregáveis e usar o serviço de agregação para processar os relatórios. para gerar um relatório de resumo.
Decisões de design
Um princípio fundamental da API Attribution Reporting são as decisões iniciais de design. Você decide quais dados coletar em quais categorias e com que frequência processar esses dados. Os relatórios de resultados fornecem insights sobre suas campanhas ou negócios.
O relatório de saída pode ser:
- Os relatórios de eventos associam um determinado clique ou visualização (no lado do anúncio) a dados no lado da conversão. Para preservar a privacidade do usuário limitando a combinação da identidade do usuário em todos os sites, os dados da conversão são muito limitados e têm ruído, o que 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 lado do anúncio. Esses relatórios oferecem dados de conversão mais detalhados e flexibilidade para combinar dados de cliques e visualizações com dados de conversão.
Sua seleção de relatório determina quais dados você precisa coletar.
Você também pode pensar no resultado final como uma entrada para as ferramentas usadas para a tomar decisões. Por exemplo, se você gerar relatórios de resumo para determinar Muitas conversões levaram a um valor de gasto total, o que pode ajudar sua equipe a decidir qual deve ser a meta da próxima campanha para gerar um gasto total maior.
Depois de decidir o que você quer medir, configure a análise do lado do cliente da API Attribution Reporting.
Comunicação entre sites
![As fontes de atribuição no site de um editor se conectam a acionadores no site de um anunciante.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/attribution-sources-a-pu-b04d5ed143672.png?authuser=9&hl=pt)
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 (no nível do evento e agregáveis) seriam gerados da seguinte maneira:
No site do editor, um elemento de anúncio (tag
<a>
ou<img>
) é configurado com um atributo especialattributionsrc
. O valor dela é um URL, por exemplo,https://adtech.example/register-source/ad_id=...
.Veja um exemplo de link que registra uma origem depois do clique:
<a href="https://shoes.example/landing" attributionsrc="http://adtech.example/register-source?..." target="_blank"> Click me</a>
Aqui está um exemplo de imagem que causará o registro de uma fonte quando visualizada:
<img href="https://advertiser.example/landing" attributionsrc="https://adtech.example/register-source?..."/>
Como alternativa, em vez de elementos HTML, é possível usar chamadas JavaScript.
Veja 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
paraattributionsrc
, que normalmente é um endpoint de anunciante ou provedor de adtech. Ao receber essa solicitação, o anunciante ou o 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 posteriormente. Para isso, o anunciante ou o provedor de adtech inclui na resposta um cabeçalho HTTP especial. Ele é anexado a esse cabeçalho com dados personalizados que fornecem informações sobre o evento de origem (o clique ou a visualização do anúncio). Se uma conversão ocorrer nesse anúncio, esses dados personalizados vão aparecer 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 chamada JavaScript faz uma solicitação parahttps://adtech.example/conversion?param1=...¶m2=...
.O serviço nesse URL, normalmente o anunciante ou o provedor de adtech, recebe a solicitação. Ele decide categorizar isso como uma conversão. Portanto, ele precisa instruir o navegador a registrar uma conversão, ou seja, acionar uma atribuição. Para isso, o anunciante ou provedor de adtech inclui em sua 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 original (clique ou visualização do anúncio). Saiba mais em Corresponder origens aos acionadores.
O navegador programa o envio de um relatório para
attributionsrc
. Esse relatório inclui:- 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.
- O conjunto de dados de conversão personalizado na Etapa 6.
Depois, o navegador envia os relatórios ao endpoint definido no
attributionsrc
, com algum atraso e ruído. Os relatórios agregáveis são criptografados, mas os relatórios de eventos não são.
Acionadores de atribuição (site do anunciante)
O acionador de atribuição é o evento que instrui o navegador a capturar as conversões.
Recomendamos capturar as conversões mais importantes para o anunciante, como compras. É possível usar vários tipos de conversão e metadados nos relatórios resumidos.
Isso garante que os resultados agregados sejam detalhados e precisos para esses eventos.
Corresponder origens aos acionadores
Quando um navegador recebe uma resposta de acionador de atribuição, ele acessa o armazenamento local para encontrar uma fonte que corresponda ao atributo e o URL da página eTLD+1.
Por exemplo, quando o navegador recebe um acionador de atribuição do
adtech.example
em shoes.example/shoes123
, o navegador procura uma origem em
um armazenamento local que corresponda a adtech.example
e shoes.example
.
É possível definir filtros (ou regras personalizadas) para determinar quando há correspondência com um acionador. a uma fonte específica. Por exemplo, defina um filtro para contar somente as conversões de um uma categoria específica e ignorar todas as outras. Filtros e os modelos de priorização possibilitam relatórios de atribuição mais avançados.
Se várias fontes de atribuição forem encontradas no armazenamento local, o navegador escolherá aquele que foi armazenado mais recentemente. Quando as fontes de atribuição receber uma prioridade, o navegador selecionará a origem com a maior prioridade.
Coleta de dados
Juntos, um acionador de atribuição que corresponde a uma fonte correspondente são enviados como um relatório pelo navegador para um endpoint de relatórios em um servidor da adtech (às vezes chamado de endpoint de coleta ou serviço de coleta). Esses podem ser relatórios de eventos ou relatórios agregáveis.
Relatórios agregáveis são usadas para gerar relatórios resumidos. Um relatório agregável é uma combinação de dados coletados a partir do anúncio (no site de um editor) e dados de conversão (de site do anunciante) que é gerada e criptografada pelo navegador em uma 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 dentro de uma hora, e os eventos devem caber no orçamento de contribuição. Essas escolhas protegem a privacidade e impedem a exploração das ações de quaisquer usuários individuais.
Se você tem interesse apenas em relatórios de eventos, esta é a última parte a infraestrutura de que você precisa. No entanto, se quiser gerar relatórios resumidos, você precisará processar os relatórios agregáveis com um serviço adicional.
Geração de relatórios de resumo
Para gerar relatórios resumidos, você usará o Serviço de agregação (operados pela adtech) para processar os relatórios agregáveis. A agregação O serviç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 em lote para o ambiente de adtech.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/aggregatable-reports-are-a0830fd543e6f.png?authuser=9&hl=pt)
Após agrupar os relatórios agregáveis coletados, o lote é processado pelo serviço de agregação. Um coordenador concede as chaves de descriptografia apenas a versões atestadas da agregação Serviço. O serviço de agregação, em seguida, descriptografa os dados, agrega adicionar 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 agrupados. Um lote consiste em relatórios agregáveis agrupados estrategicamente. Sua estratégia vai provavelmente refletem um período específico (diário ou semanal). Isso pode ocorrer no mesmo servidor que atua como endpoint de relatórios.
Os lotes devem conter muitos relatórios para garantir que a relação sinal-ruído seja alta.
![Períodos maiores geram resultados menos ruidosos.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/larger-periods-lead-les-4d4edffb3d2d6.png?authuser=9&hl=pt)
Os períodos do lote podem mudar a qualquer momento para garantir a captura de eventos específicos em que você espera um volume maior, como em uma promoção anual. O período de lotes podem ser alteradas sem a necessidade de alterar acionadores ou fontes de atribuição.
Serviço de agregação
O serviço de agregação é responsável pelo processamento de relatórios agregáveis para gerar um relatório de resumo. Os relatórios agregáveis são criptografados e só podem ser lidas 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 recebem ruídos para preservar a privacidade e são retornados como um relatório de resumo.
Os profissionais podem gerar relatórios de texto não criptografado agregáveis para testar o serviço de agregação localmente; Você também pode fazer testes com relatórios criptografados na AWS com Nitro Enclaves.
A seguir
Queremos conversar com você para criar uma API que que funcione para todos.
Conversar sobre a API
Assim como outras APIs do Sandbox de privacidade, essa API é documentada e discutidos publicamente.
Teste a API
Você pode testar e participar conversamos sobre a API Attribution Reporting.