Noções básicas sobre as chaves de agregação para a API Attribution Reporting

bookmark_border Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O que são as chaves de agregação, como elas são usadas na API Attribution Reporting e como converter metas em chaves.

Como uma empresa de adtech que veicula campanhas em vários locais para várias categorias de produtos, você quer ajudar os anunciantes a responder às seguintes perguntas:

1. Quantas compras de cada categoria de produto foram geradas por cada uma das minhas campanhas em cada região geográfica?
2. Quanta receita para cada categoria de produto foi gerada por cada uma das minhas campanhas em cada região geográfica?

Embora muitas empresas de adtech incentivem os anunciantes a configurar vários tipos de conversão, concentrar-se nas conversões mais importantes, como compras, é uma boa maneira de garantir que os resultados do resumo sejam detalhados e precisos para esses eventos importantes.

Para isso, você precisa pensar nas perguntas que quer responder antes da coleta de dados.

Dimensões, chaves e valores

Para responder a essas perguntas, vamos analisar as dimensões, chaves e valores.

Dimensões

Para entender como suas campanhas estão gerando receita, conforme descrito aqui, rastreie as seguintes dimensões:

• ID da campanha publicitária: o identificador da campanha específica.
• ID da região geográfica: a região geográfica em que o anúncio foi veiculado.
• Categoria do produto: o tipo de produto que você definiu.

As dimensões do ID da campanha e do ID da região são conhecidas quando o anúncio é veiculado (momento da veiculação do anúncio), mas a categoria do produto é conhecida por um evento acionado quando o usuário conclui uma conversão (momento da conversão).

As dimensões que você quer acompanhar neste exemplo são mostradas na imagem a seguir:

O que são chaves de agregação (buckets)?

Os termos "chave de agregação" e "bucket" se referem à mesma coisa. A chave de agregação é usada nas APIs do navegador para configurar relatórios. O termo bucket é usado nos relatórios de agregação e de resumo e nas APIs de serviço de agregação.

Uma chave de agregação é um conjunto de dados que representa os valores das dimensões que estão sendo acompanhadas. Os dados são agregados posteriormente em cada chave de agregação.

Por exemplo, vamos supor que você esteja rastreando as dimensões "Categoria do produto", "ID da região" e "ID da campanha".

Quando um usuário localizado no ID de localização geográfica 7 visualiza um anúncio do ID da campanha 12 e depois converte ao comprar um produto na categoria 25, é possível definir uma chave de agregação semelhante à mostrada na imagem a seguir:

Você vai perceber mais tarde que uma chave de agregação não é exatamente assim na prática, mas, por enquanto, vamos nos concentrar nas informações contidas na chave.

O que são valores agregáveis?

Para responder às suas perguntas sobre as dimensões que descrevemos, você precisa saber:

• O número de compras (a contagem de compras). Depois de agregada e disponibilizada em um relatório de resumo, essa será a contagem total de compras (valor de resumo).
• A receita de cada compra (o valor da compra). Depois de agregada e disponibilizada em um relatório de resumo, ela será a receita total (valor de resumo).

Cada um deles, a contagem de compras de uma conversão e o valor de compra de uma conversão, é um valor agregável. Pense nos valores agregáveis como os valores das suas metas de medição.

Quando um usuário localizado no ID de área geográfica 7 visualiza um anúncio da campanha 12 e depois converte comprando um produto da categoria 25 por US $120 (considerando que sua moeda é o dólar americano), você pode definir uma chave de agregação e valores agregáveis semelhantes a estes:

Os valores agregáveis são somados por chave em vários usuários para gerar insights agregados, na forma de valores de resumo nos relatórios de resumo.

Os valores agregáveis são somados para gerar insights agregados para suas metas de medição.

Este diagrama omite a descriptografia e representa um exemplo simplificado sem ruído aplicado. Na próxima seção, vamos esboçar esse exemplo com ruído.

De chaves e valores para relatórios

Agora vamos discutir como as chaves e os valores agregáveis se relacionam com os relatórios.

Relatórios agregáveis

Quando um usuário clica ou visualiza um anúncio e depois faz uma conversão, você instrui o navegador a armazenar um par {chave de agregação, valor agregável}.

No nosso exemplo, quando um usuário clica ou visualiza um anúncio e depois faz uma conversão, você instrui o navegador a gerar duas contribuições (uma por meta de medição).

Mais adiante, você vai notar que um relatório agregável {aggregation key, aggregatable value} não é exatamente assim, mas, por enquanto, vamos nos concentrar nas informações contidas no relatório.

Quando você instrui o navegador a gerar duas contribuições, ele gera um relatório agregável (se puder corresponder à conversão com uma visualização ou clique anterior).

Um relatório agregável contém:

• As contribuições que você configurou.
• Metadados sobre o evento de clique ou visualização e o evento de conversão: o site em que a conversão ocorreu e muito mais. Conferir todos os campos em um relatório agregável.

Os relatórios agregáveis têm formato JSON e incluem, entre outras coisas, um campo de payload que será usado como uma entrada de dados para o relatório de resumo final.

O payload contém uma lista de contribuições, cada uma sendo um par {chave de agregação, valor agregável}:

• bucket: a chave de agregação, codificada como uma string de bytes.
• value: o valor agregável para essa meta de medição, codificado como uma string de bytes.

Veja um exemplo:

{
  "data": [
    {
      "bucket": "111001001",
      "value": "11111010000",
    }
  ],
  "operation": "histogram"
}

Na prática, os relatórios agregáveis são codificados de uma maneira que faz com que os buckets e os valores pareçam diferentes do exemplo anterior. Ou seja, um bucket pode ter a aparência de \u0000\u0000\x80\u0000. Bucket e valor são strings de bytes.

Relatórios de resumo

Os relatórios agregáveis são agrupados em vários navegadores e dispositivos (usuários) da seguinte maneira:

• Uma adtech solicita relatórios de resumo para um determinado conjunto de chaves e um determinado conjunto de relatórios agregáveis que vêm de vários navegadores (usuários) diferentes.
• Os relatórios agregáveis são descriptografados pelo serviço de agregação.
• Para cada chave, os valores agregáveis dos relatórios agregáveis são somados.
• O ruído é adicionado ao valor do resumo.

O resultado é um relatório de resumo que contém um conjunto de pares {chave de agregação, valor de resumo}.

Um relatório de resumo contém um conjunto de pares de chave-valor no estilo de dicionário JSON. Cada par contém:

• bucket: a chave de agregação, codificada como uma string de bytes.
• value: o valor de resumo em decimal para uma determinada meta de medição, somado de todos os relatórios agregáveis disponíveis, com um nível adicional de ruído.

Exemplo:

[
  {"bucket": "111001001", "value": "2558500"},
  {"bucket": "111101001", "value": "3256211"},
  {...}
]

Na prática, os relatórios de resumo são codificados de uma maneira que faz com que os buckets e os valores pareçam diferentes do indicado no exemplo (ou seja, um bucket pode ter a aparência de \u0000\u0000\x80\u0000). Bucket e valor são ambos bytestrings.

Chaves de agregação na prática

As chaves de agregação (buckets) são definidas por uma empresa de adtech, geralmente em duas etapas: quando um anúncio é clicado ou visualizado e quando um usuário converte.

Estrutura da chave

Usaremos o termo estrutura de chave para designar o conjunto de dimensões codificadas em uma chave.

Por exemplo, ID da campanha × ID geográfico × Categoria do produto é uma estrutura de chave.

Tipos de chave

Os valores agregáveis são somados para uma determinada chave em vários usuários/navegadores. No entanto, os valores agregáveis podem acompanhar diferentes metas de medição, como o valor ou a contagem de compras. Você quer garantir que o serviço de agregação some valores agregáveis do mesmo tipo.

Para isso, em cada chave, codifique um conjunto de dados que informe o que o valor do resumo representa, ou seja, a meta de medição a que a chave se refere. Uma maneira de fazer isso é criar uma dimensão extra para a chave que representa o tipo de meta de medição.

Usando nosso exemplo anterior, esse tipo de meta de medição teria dois valores possíveis:

• A contagem de compras é o primeiro tipo de meta de medição.
• O valor da compra é o segundo tipo de meta de medição.

Se você tivesse n metas de medição, o tipo de meta de medição teria n tipos diferentes de valores.

Pense nas dimensões de uma chave como uma métrica. Por exemplo, "o número de compras de um determinado produto por campanha e região".

Tamanho da chave, tamanho da dimensão

O tamanho máximo da chave é definido em bits, ou seja, o número de zeros e uns em binário para criar a chave completa. A API permite um comprimento de chave de 128 bits.

Esse tamanho permite chaves muito granulares, mas é mais provável que elas gerem valores mais ruidosos. Leia mais sobre ruído em Entenda o ruído.

Como mencionado anteriormente, as dimensões são codificadas na chave de agregação. Cada dimensão tem uma determinada cardinalidade, ou seja, o número de valores distintos que ela pode assumir. Dependendo da cardinalidade, cada dimensão precisa ser representada por um determinado número de bits. Com n bits, é possível expressar 2ⁿ opções distintas.

Por exemplo, uma dimensão "País" pode ter uma cardinalidade de 200, já que existem cerca de 200 países no mundo. Quantos bits são necessários para codificar essa dimensão?

Sete bits armazenariam apenas 2⁷ = 128 opções distintas, o que é menor do que as 200 necessárias.

8 bits armazenariam 2⁸ = 256 opções distintas, o que é mais do que as 200 necessárias. Portanto, você pode usar n=8 bits para codificar essa dimensão.

Codificação de chaves

Quando você define chaves no navegador, elas precisam ser codificadas em hexadecimal. Nos relatórios de resumo, as chaves aparecem em binário (e são nomeadas como buckets).

Definir duas partes de uma chave

Vamos supor que você use uma chave para acompanhar as seguintes dimensões:

• ID da campanha
• ID de geografia
• Categoria do produto

As dimensões do ID da campanha e da região são conhecidas quando o anúncio é veiculado (momento da veiculação do anúncio), mas a categoria do produto é conhecida por um evento acionado, quando o usuário conclui uma conversão (momento da conversão).

Na prática, isso significa que você vai definir uma chave em duas etapas:

1. Você vai definir uma parte da chave (ID da campanha × ID da região geográfica) no momento do clique ou da visualização.
2. Você vai definir a segunda parte da chave, "Categoria do produto", no momento da conversão.

Essas partes diferentes das chaves são chamadas de peças-chave.

Uma chave é calculada usando a operação OU (v) das partes principais.

Exemplo:

• Parte da chave do lado da origem = 0x159
• Parte da chave do acionador = 0x400
• Tecla = 0x159 v 0x400 = 0x559

Como alinhar as peças-chave

Com duas peças de chave de 64 bits estendidas para 128 bits usando preenchimentos/deslocamentos de 64 bits cuidadosamente posicionados (os dezesseis zeros), a OR das peças de chave é equivalente à concatenação delas, o que é mais fácil de entender e verificar:

• Parte da chave do lado da origem = 0xa7e297e7c8c8d0540000000000000000
• Parte da chave do acionador = 0x0000000000000000674fbe308a597271
• Tecla = 0xa7e297e7c8c8d0540000000000000000 v 0x0000000000000000674fbe308a597271 = 0xa7e297e7c8c8d054674fbe308a597271

Várias chaves por clique ou visualização de anúncio

Na prática, é possível definir várias chaves por evento de fonte de atribuição (clique ou visualização do anúncio). Por exemplo, você pode definir:

• Uma chave que rastreia o ID da campanha × ID da geografia.
• Outra chave que rastreia o ID da campanha × tipo de criativo.

Confira a estratégia B para ver outro exemplo.

Codificação de dimensões em chaves

Ao solicitar relatórios de resumo, você precisa informar ao serviço de agregação quais métricas quer acessar, solicitando relatórios de resumo para um determinado conjunto de chaves de agregação.

Os relatórios de resumo contêm pares brutos {chave, valor do resumo} e nenhuma informação adicional sobre a chave. Isso significa que:

• Ao definir chaves quando o usuário visualiza ou clica em um anúncio e depois faz uma conversão, é necessário definir chaves confiáveis com base nos valores das dimensões que elas representam.
• Ao definir as chaves para as quais você quer solicitar relatórios de resumo, é necessário gerar ou acessar de forma confiável as mesmas chaves definidas quando o usuário visualizou ou clicou em um anúncio e converteu, com base nos valores das dimensões para as quais você quer ver dados agregados.

Como codificar dimensões usando mapas de estrutura de chaves

Para codificar dimensões em chaves, crie e mantenha um mapa de estrutura de chaves com antecedência, ao definir as chaves (antes do horário de veiculação do anúncio).

Um mapa de estrutura de chaves representa cada uma das suas dimensões e a posição delas na chave.

Na prática, criar e manter mapas de estrutura de chaves significa implementar e manter a lógica do decodificador. Se você estiver procurando um método que não exija isso, use uma abordagem baseada em hash.

Veja um exemplo:

Vamos supor que você queira acompanhar as compras e os valores de compra de campanhas, regiões geográficas e produtos específicos.

A categoria do produto, o ID da região geográfica e o ID da campanha precisam ser dimensões nas suas chaves. Além disso, como você quer acompanhar duas metas de medição diferentes (contagem e valor de compra), é necessário adicionar uma dimensão na chave que acompanhe o tipo de chave. Isso permite que você defina o que o valor agregável representa ao receber pares {chave, valor agregável} nos relatórios de resumo.

Com essas metas de medição, a chave tem as seguintes dimensões:

• Categoria do produto
• Tipo de meta de medição
• ID de geografia
• ID da campanha

Agora, analisando cada dimensão, vamos supor que, para seu caso de uso, você precisa acompanhar o seguinte:

• 29 categorias de produtos diferentes.
• 8 regiões geográficas diferentes: América do Norte, América Central, América do Sul, Europa, África, Ásia, Caribe e Oceania.
• 16 campanhas diferentes.

Confira o número de bits necessários para codificar cada dimensão na chave:

• Categoria do produto: 5 bits (2⁵ = 32 > 29).
• Tipo de meta de medição: 1 bit. A meta de medição é a contagem ou o valor da compra, o que significa duas possibilidades distintas. Portanto, um bit é suficiente para armazenar isso.

• ID da região geográfica: 3 bits (2³ = 8). Você também precisa definir um mapa de dimensão para o ID geográfico para saber qual região geográfica cada valor binário representa. O mapa de dimensão da dimensão "ID geográfico" pode ser parecido com este:

  Valor binário na chave	Geografia
  000	América do Norte
  001	América Central
  010	América do Sul
  011	Europa
  100	África
  101	Ásia
  110	Caribe
  111	Oceania

• ID da campanha: 4 bits (2⁴ = 16)

As chaves que seguem essa estrutura têm 13 bits (5 + 1 + 3 + 4).

Para este exemplo, o mapa de estrutura de chaves dessas chaves seria assim:

A ordem das dimensões na chave é sua escolha.

Para ilustrar como as dimensões compõem uma estrutura de chave, vamos usar uma representação binária. Por isso, o ID da campanha (primeiros bits) é o da direita, e a categoria do produto (últimos bits) é o da esquerda.

Em cada dimensão, o bit mais significativo, ou seja, aquele que tem o maior valor numérico, é o da esquerda. O bit menos significativo, aquele que tem o menor valor numérico, é o da direita.

Vamos ver como usar um mapa de estrutura de chave para decodificar uma chave.

Vamos usar 0b1100100111100 como um exemplo de chave arbitrária e supor que você tenha uma maneira de saber que essa chave segue o mapa de estrutura de chaves na ilustração anterior.

De acordo com o mapa da estrutura da chave, essa chave seria decodificada como:

`11001 0 011 1100`

Portanto, a chave 0b11001001111100 representa o número de compras da categoria de produto 25 para o ID da campanha 12 lançado na Europa.

Codificar dimensões usando uma função hash

Em vez de usar um mapa de estrutura de chaves, você pode usar uma função de hash para gerar chaves dinamicamente de maneira consistente e confiável.

Isso funciona da seguinte maneira:

1. Selecione um algoritmo de hash.
2. No momento da veiculação do anúncio, gere uma string que inclua todas as dimensões que você quer acompanhar e os valores delas. Para gerar a parte da chave do lado do autor, faça um hash dessa string e considere adicionar um sufixo de 64 bits de zeros para alinhar com a parte da chave do lado do acionador e facilitar a compreensão da OR.
   • Parte da chave do lado da origem
     = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
   • COUNT codifica a mesma coisa que measurementGoalType=0 na abordagem do mapa de estrutura de chaves. COUNT é um pouco mais simples e explícito.
3. No momento da conversão, gere uma string que inclua todas as dimensões que você quer acompanhar e os valores delas. Para gerar uma parte da chave do acionador, faça hash desta string e adicione um prefixo de 64 bits de zeros:
   • Parte da chave do acionador = <64-bit 00000000…><64-bit hex hash("productCategory=25")>
4. O navegador ORs essas chaves para gerar uma chave.
   • Chave de agregação de 128 bits
     = <64-bit hex source-side key piece hash><64-bit hex source-side key piece hash>
5. Depois, quando quiser solicitar um relatório de resumo para essa chave, gere-o em tempo real:
   • Com base nas dimensões de seu interesse, gere uma chave do lado da origem e do acionador, como fez anteriormente.
     • Parte da chave do lado da origem
       = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
     • Parte da chave do acionador
       = <64-bit 00000000…><64-bit hex hash("productCategory=25")>
     • Parte da chave do acionador = toHex(hash("productCategory=25"))
   • Assim como o navegador, OU essas peças-chave para gerar a mesma chave que o navegador gerou anteriormente.
     • Chave de agregação de 128 bits
       = <64-bit source-side key piece hash><64-bit source-side key piece hash>

Confira algumas dicas práticas se você estiver usando essa abordagem baseada em hash:

• Sempre use a mesma ordem das dimensões. Isso garante que os hashes possam ser regenerados de forma confiável. "COUNT, CampaignID=12, GeoID=7" não vai gerar o mesmo hash que "COUNT, GeoID=7, CampaignID=12". Uma maneira simples de fazer isso é classificar as dimensões de forma alfanumérica. É isso que vamos fazer no exemplo, exceto pelo fato de que sempre vamos fazer com que COUNT ou VALUE seja o primeiro item na dimensão. Essa é uma escolha para facilitar a leitura, já que COUNT ou VALUE codifica informações que são um pouco diferentes conceitualmente de todas as outras dimensões.
• Acompanhe o conjunto de dimensões que você está usando nas chaves. Você quer evitar gerar chaves com base em um conjunto de dimensões que nunca usou.
• As colisões de hashes são raras se uma função de hash adequada for usada, mas a verificação de hashes usados anteriormente (que precisam ser armazenados para interpretar os resultados do serviço de agregação) pode evitar a introdução de novas chaves que colidem com chaves mais antigas.

Saiba como usar chaves baseadas em hash na prática no exemplo de uma conversão por clique ou visualização.

Valores agregáveis na prática

A empresa de adtech define valores agregáveis quando um usuário converte.

Para proteger a privacidade do usuário, as contribuições de cada usuário têm um limite máximo. Em todos os valores agregáveis associados a uma única origem (clique ou visualização do anúncio), nenhum valor pode ser maior que um determinado limite de contribuição.

Vamos chamar esse limite de CONTRIBUTION_BUDGET. Na explicação, esse limite é chamado de orçamento L1, mas é o mesmo que o CONTRIBUTION_BUDGET.

Para uma discussão detalhada sobre o orçamento de contribuição, consulte Orçamento de contribuição para relatórios de resumo.

Exemplo: uma conversão por clique ou visualização

Neste exemplo, vamos supor que você quer responder às seguintes perguntas:

• Quais categorias de produtos são mais valiosas em cada região?
• Quais estratégias de campanha são mais eficazes em cada região?

Vamos supor também que, para seu caso de uso, você precisa de insights semanais.

Você também precisa acompanhar o seguinte:

• 16 campanhas diferentes.
• 8 regiões geográficas diferentes: América do Norte, América Central, América do Sul, Europa, África, Ásia, Caribe e Oceania.
• 29 categorias de produtos diferentes.

O que medir

Embora muitas empresas de adtech incentivem os anunciantes a configurar vários tipos de conversão, focar nas conversões mais importantes, como compras, é uma boa maneira de garantir que os resultados agregados sejam detalhados e precisos para esses eventos importantes. Na verdade, quanto mais métricas você medir, menor será o orçamento de contribuição por métrica e, portanto, maior será o ruído de cada valor. Portanto, é preciso selecionar com cuidado o que medir.

Neste exemplo, vamos nos concentrar nas configurações de campanha que medem apenas uma conversão por clique ou visualização: uma compra.

Você ainda vai medir a contagem e o valor das compras e acessar várias estatísticas agregadas importantes, como o valor total das compras e a divisão geográfica. Isso mantém o ruído em um nível razoável e garante uma abordagem de escalonamento simples para o orçamento de contribuição.

E as moedas?

A veiculação de campanhas em diferentes regiões implica que as moedas precisam ser levadas em consideração. Você pode:

• Torne a moeda uma dimensão dedicada nas chaves de agregação.
• Ou inferir a moeda de um ID de campanha e converter todas as moedas em moedas de referência.

Neste exemplo, vamos supor que você pode inferir a moeda de um ID da campanha. Isso permite que você converta qualquer valor de compra da moeda local do usuário para uma moeda de referência de sua escolha. Você também pode realizar essa conversão imediatamente, quando o usuário compra um item.

Com essa técnica, todos os valores que podem ser agregados estão na mesma moeda de referência e, portanto, podem ser somados para gerar um valor total de compra agregado, ou seja, um valor de compra resumido.

Transformar metas em chaves

Com as metas e métricas de medição, você tem várias opções para sua estratégia principal. Vamos nos concentrar em duas dessas estratégias:

• Estratégia A: uma estrutura de chave granular.
• Estratégia B: duas estruturas de chaves grosseiras.

Estratégia A: uma árvore profunda (uma estrutura de chave granular)

Na estratégia A, você usa uma estrutura de chave granular, que inclui todas as dimensões necessárias:

Todas as suas chaves usam essa estrutura.

Você divide essa estrutura de chaves em dois tipos de chaves para atender a dois objetivos de medição.

• Tipo de chave 0: tipo de meta de medição = 0, que você define como uma contagem de compras.
• Tipo de chave 1: tipo de meta de medição = 1, que você define como um valor de compra.

Os relatórios de resumo têm esta aparência:

Pense na estratégia A como uma estratégia de "árvore única":

• Cada valor de resumo nos relatórios de resumo é associado a todas as dimensões que você está acompanhando.
• Você pode agrupar esses valores de resumo com cada uma dessas dimensões, de modo que esses agrupamentos possam ser tão profundos quanto o número de dimensões que você tem.

Com a estratégia A, você responderia às suas perguntas da seguinte maneira:

Com a estratégia A, você também pode responder diretamente a esta terceira pergunta:

"Quanta receita para cada produto cada uma das minhas campanhas em cada região geográfica gerou?"

Mesmo que os valores de resumo sejam imprecisos, você pode determinar quando as diferenças no valor medido entre cada campanha não são causadas apenas por ruído. Saiba como fazer isso em Entenda o ruído.

Estratégia B: duas árvores rasas (duas estruturas de chaves grosseiras)

Na estratégia B, você usa duas estruturas de chaves grosseiras, cada uma incluindo um subconjunto das dimensões necessárias:

Você divide cada uma dessas estruturas em dois tipos principais para apoiar duas metas de medição.

• O tipo de meta de medição é 0, que você define como uma contagem de compras.
• O tipo de meta de medição é 1, que você define como um valor de compra.

Você vai ter quatro tipos de chave:

• Tipo de chave I-0: estrutura de chave I, contagem de compras.
• Tipo de chave I-1: estrutura de chave I, valor de compra.
• Tipo de chave II-0: estrutura da chave II, contagem de compras.
• Tipo de chave II-1: estrutura de chave II, valor de compra.

Os relatórios de resumo têm esta aparência:

Você pode pensar na estratégia B como uma estratégia de "duas árvores rasas":

• Os valores de resumo nos relatórios de resumo são mapeados para um dos dois pequenos conjuntos de dimensões.
• É possível agrupar esses valores de resumo com cada uma das dimensões nesses conjuntos. Isso significa que esses agrupamentos não são tão profundos quanto na opção A, porque há menos dimensões para agrupar.

Com a estratégia B, você responderia às perguntas da seguinte maneira:

Decisão: estratégia A

A estratégia A é mais simples. Todos os dados seguem a mesma estrutura de chaves, o que também significa que você só precisa manter uma estrutura de chaves.

No entanto, com a estratégia A, você precisa somar os valores de resumo que recebe nos relatórios de resumo para responder a algumas perguntas. Cada um desses valores de resumo é barulhento. Ao somar esses dados, você também somará o ruído.

Isso não acontece com a estratégia B, em que os valores de resumo expostos nos relatórios de resumo já fornecem as informações necessárias. Isso significa que a estratégia B provavelmente vai gerar um impacto menor do que a estratégia A.

Como determinar qual estratégia usar? Para anunciantes ou campanhas atuais, você pode usar dados históricos para determinar se o volume de conversões é mais adequado para a estratégia A ou B. No entanto, para novos anunciantes ou campanhas, você pode:

• Colete dados de um mês com as chaves granulares (estratégia A). Como você está estendendo a duração da coleta de dados, os valores de resumo vão ser maiores e o ruído será relativamente menor.
• Avalie com precisão razoável a contagem de conversões e o valor da compra semanais.

Neste exemplo, vamos supor que a contagem e o valor de compra semanais sejam altos o suficiente para que a estratégia A leve a uma porcentagem de ruído que você considere aceitável para seu caso de uso.

Como a estratégia A é mais simples e leva a um impacto de ruído que não afeta sua capacidade de tomar decisões, você decide usar a estratégia A.

Selecionar um algoritmo de hash

Você decide adotar uma abordagem baseada em hash para gerar as chaves. Para isso, você precisa selecionar um algoritmo de hash para oferecer suporte a essa abordagem.

Vamos supor que você selecionou SHA-256. Você também pode usar um algoritmo mais simples e menos seguro, como o MD5.

No navegador: definir chaves e valores

Agora que você decidiu uma estrutura de chaves e um algoritmo de hash, está tudo pronto para registrar chaves e valores quando os usuários clicam ou visualizam anúncios e, em seguida, fazem a conversão.

A seguir, confira uma visão geral dos cabeçalhos que você vai definir para registrar chaves e valores no navegador:

Definir elementos-chave do lado da origem

Quando um usuário clica ou visualiza um anúncio, defina as chaves de agregação no cabeçalho Attribution-Reporting-Register-Aggregatable-Source. Nesse estágio, para cada chave, só é possível definir a parte da chave, ou parte da chave, que é conhecida no momento da veiculação do anúncio.

Vamos gerar as peças-chave:

Vamos definir as peças-chave:

// Upon receiving the request from the publisher site
res.set(
  "Attribution-Reporting-Register-Aggregatable-Source",
  JSON.stringify([
    {
      "id": "key_purchaseCount",
      "key_piece": "0x3cf867903fbb73ec0000000000000000"
    },
    {
      "id": "key_purchaseValue",
      "key_piece": "0x245265f432f16e730000000000000000"
    }
  ])
);

Os IDs de chave não vão aparecer nos relatórios finais. Elas são usadas apenas ao definir chaves no navegador, para que as partes da chave do lado da origem e do acionador possam ser mapeadas entre si e combinadas em uma chave completa.

Opcional: relatórios de eventos

Se você precisar usar relatórios de evento com relatórios agregáveis, verifique se, para uma determinada origem, os dados de evento (ID do evento de origem e dados do acionador) e a chave de agregação podem ser combinados.

Você pode usar os dois relatórios se, por exemplo, planeja usar relatórios no nível do evento para executar modelos sobre quais tipos de anúncios tendem a gerar o maior número de compras.

Um usuário converte

Quando um usuário faz uma conversão, uma solicitação de pixel geralmente é enviada ao servidor de adtech. Ao receber essa solicitação:

• Defina as partes da chave do lado da conversão (do acionador) para concluir a chave. Você vai definir essas peças-chave pelo cabeçalho Attribution-Reporting-Register-Aggregatable-Trigger-Data.
• Defina o valor agregável para essa conversão usando o cabeçalho Attribution-Reporting-Register-Aggregatable-Values.

Definir peças da chave do lado do acionador para concluir a chave

Vamos gerar as peças-chave:

Vamos definir as peças-chave:

// Upon receiving the pixel request from the advertiser site
res.set(
  "Attribution-Reporting-Register-Aggregatable-Trigger-Data",
  JSON.stringify([
    // Each dictionary independently adds pieces to multiple source keys
    {
      "key_piece": "0x0000000000000000f9e491fe37e55a0c",
      "source_keys": ["key_purchaseCount", "key_purchaseValue"]
    },
  ])
);

Observe como você está adicionando a mesma parte da chave a várias chaves, listando vários IDs de chave em source_keys. A parte da chave será adicionada às duas chaves.

Definir valores agregáveis

Antes de definir os valores agregáveis, é necessário aumentá-los para reduzir o ruído.

Vamos supor que uma compra foi feita para o tipo de produto 25 por US $52.

Não defina esses valores diretamente como valores agregáveis:

• key_purchaseCount: 1 conversão
• key_purchaseValue: US$ 52

Em vez disso, antes de registrar esses valores agregáveis, é necessário dimensioná-los para minimizar o ruído.

Você tem duas metas para gastar seu orçamento de contribuição. Por isso, pode decidir dividir o orçamento de contribuição em dois.

Nesse caso, cada meta recebe um máximo de CONTRIBUTION_BUDGET/2 (=65.536/2=32.768).

Vamos supor que o valor máximo de compra de um único usuário, com base no histórico de compras de todos os usuários do site, é de US $1.500. Pode haver valores fora da curva, por exemplo, muito poucos usuários que gastaram mais do que essa quantia, mas você pode decidir ignorar esses valores.

O fator de escalonamento para o valor da compra precisa ser:

((CONTRIBUTION_BUDGET/2) / 1.500) = 32.768/1.500 = 21,8 ≈ 22

O fator de escalonamento para a contagem de compras é 32.768/1 = 32.768, já que você decidiu acompanhar no máximo uma compra por clique ou visualização de anúncio (evento de origem).

Agora é possível definir estes valores:

• key_purchaseCount: 1 × 32.768 = 32.768
• key_purchaseValue: 52 × 22 = 1.144

Na prática, você as definiria da seguinte maneira, usando o cabeçalho Attribution-Reporting-Register-Aggregatable-Values dedicado:

// Instruct the browser to schedule-send a report
res.set(
  "Attribution-Reporting-Register-Aggregatable-Values",
  JSON.stringify({
    "key_purchaseCount": 32768,
    "key_purchaseValue": 1144,
  })
);

O relatório agregável é gerado

O navegador faz a correspondência da conversão com uma visualização ou um clique anterior e gera um relatório agregável, que inclui o payload criptografado ao lado dos metadados do relatório.

Confira a seguir um exemplo dos dados que podem ser encontrados no payload do relatório agregável, se ele for legível em texto não criptografado:

[
  {
    key: 0x3cf867903fbb73ecf9e491fe37e55a0c, // = source-side key piece OR conversion-side key piece for the key key_purchaseCount
    value: 32768 // the scaled value for 1 conversion, in the context of [CONTRIBUTION_BUDGET/2]
  },
  {
    key: 0x245265f432f16e73f9e491fe37e55a0c, // source-side key piece OR conversion-side key piece for the key key_purchaseValue
    value: 1144 // the scaled value for $52, in the context of [CONTRIBUTION_BUDGET/2]
  },
]

Aqui, você pode conferir duas contribuições separadas em um único relatório agregado.

Solicitar um relatório resumido

• Relatórios agregáveis em lote. Siga as orientações em Batching.
• Gere as chaves para as quais você quer ver dados. Por exemplo, para ver dados resumidos de COUNT (número total de compras) e VALUE (valor total da compra) para o ID da campanha 12 × ID da região 7 × Categoria de produto 25:
  • Gere a parte da chave do lado da origem, como fez ao configurá-la no navegador.
  • Gere a parte da chave do gatilho, como fez ao configurá-la no navegador.

• Solicitar dados de resumo ao serviço de agregação para essas chaves.

Processar o relatório resumido

Você vai receber um relatório resumido parecido com este:

[
  {"bucket": "00111100111110000110011110010000001111111011101101110011111011001111100111100100100100011111111000110111111001010101101000001100",
    "value": "2558500"},
  {"bucket": "00100100010100100110010111110100001100101111000101101110011100111111100111100100100100011111111000110111111001010101101000001100",
    "value": "687060"},
  …
]

O primeiro bucket é a chave COUNT em binário. O segundo bucket é a chave VALUE em binário. Embora as chaves sejam heterogêneas (COUNT em vez de VALUE), elas estão contidas no mesmo relatório.

Reduzir os valores

• 2.558.500 se refere ao número de compras para essa chave, dimensionado pelo fator de dimensionamento calculado anteriormente. O fator de escalonamento para a contagem de compras foi 32.768. Divida 2.558.500 pelo orçamento de contribuição da meta: 2.558.500/32.768 = 156,15 compras.
• 687.060 → 687.060/22 = US $31.230 valor total da compra.

Como resultado, os relatórios de resumo oferecem os seguintes insights:

- Within the reporting time period, campaign #12
  run in Europe drove about 156 purchases (± noise)
  for the product category #25
  ```

  ```text
- Within the reporting time period, campaign #12
  run in Europe drove $31,230 of purchases (± noise)
  for the product category #25.