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

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 diversos locais para diversas 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. Qual foi a receita gerada por cada categoria de produto de cada uma das minhas campanhas em cada região geográfica?

Muitas empresas de adtech incentivam os anunciantes a configurar vários tipos de conversão. No entanto, focar 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 definido por você.

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 realiza 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 agregáveis e de resumo e nas APIs do serviço de agregação.

Uma chave de agregação (abreviada como chave) é um dado que representa os valores das dimensões que estão sendo rastreadas. Os dados são agregados posteriormente com 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:

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

O que são valores agregáveis?

Para responder às suas perguntas referentes às dimensões descritas, 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, esta será a receita total (valor do resumo).

Cada um desses itens (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 da área geográfica 7 vê um anúncio para o ID da campanha 12 e depois faz a conversão comprando um produto da categoria 25 por US $120 (supondo que sua moeda seja USD), é possível definir uma chave de agregação e valores agregáveis como estes:

Os valores que podem ser agregados 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 descrever esse exemplo com ruído.

De chaves e valores a relatórios

Agora vamos discutir como as chaves e os valores agregáveis estão relacionados aos relatórios.

Relatórios agregáveis

Quando um usuário clica ou visualiza um anúncio e depois faz a 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 agregativo {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 corresponder a conversão a uma visualização ou um 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, entre outros. 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 {aggregation key, aggregatable value}:

• 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 ambos bytestrings.

Relatórios de resumo

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

• Uma adtech solicita relatórios resumidos para um determinado conjunto de chaves e um determinado conjunto de relatórios agregáveis provenientes de vários navegadores (usuários).
• 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 forma que os buckets e os valores pareçam diferentes do indicado no exemplo (ou seja, um bucket pode ser semelhante a \u0000\u0000\x80\u0000). Bucket e value são strings de bytes.

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 recebe um clique ou é visualizado e quando um usuário faz uma conversão.

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, já sabemos que os valores agregáveis acompanham diferentes metas de medição, como o valor ou a contagem das compras. Você quer garantir que o serviço de agregação some os 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ídos em Entender ruídos.

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 ter. 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?

7 bits armazenariam apenas 2⁷ = 128 opções distintas, o que é menos do que os 200 necessários.

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 teclas

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 chave para uma chave completa

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

• ID da campanha
• ID da região geográfica
• Categoria do produto

Embora as dimensões "ID da campanha" e "ID de geografia" sejam conhecidas quando o anúncio é veiculado (momento da veiculação do anúncio), a categoria do produto é conhecida por um evento acionador, quando o usuário conclui uma conversão (momento da conversão).

Na prática, isso significa que você 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 o OR (v) das principais partes.

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 do anúncio

Na prática, você pode definir várias chaves por evento da 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 do tipo de criativo × campanha.

Confira a Estratégia B para ver outro exemplo.

Codificar dimensões em chaves

Ao solicitar relatórios de resumo, é necessário informar ao serviço de agregação quais métricas você quer acessar. Para isso, solicite 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 a conversão, é preciso definir chaves de maneira confiável 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 maneira confiável as mesmas chaves definidas quando o usuário visualizou ou clicou em um anúncio e fez a conversão, com base nos valores das dimensões que você gostaria de ver os dados agregados.

Como codificar dimensões usando mapas de estrutura de chaves

Para codificar dimensões em chaves, você pode criar e manter um mapa da estrutura de chaves com antecedência, definindo suas chaves (antes do momento da veiculação do anúncio).

Um mapa da estrutura principal 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ê pretenda acompanhar as compras e os valores de compra para campanhas, regiões geográficas e produtos específicos.

A categoria dos produtos, 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} em 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, para seu caso de uso, que você precise rastrear 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 definiria um mapa de dimensão para o ID de geografia para saber a região geográfica que cada valor binário representa. O mapa da dimensão do ID de região geográfica pode ter esta aparência:

  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 teriam 13 bits de comprimento (5 + 1 + 3 + 4).

Para esse exemplo, o mapa da estrutura de chaves dessas chaves ficaria assim:

Você decide a ordem das dimensões na chave.

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.

Dentro de cada dimensão, o bit mais significativo (aquele que carrega o maior valor numérico) é o bit mais à esquerda. O bit menos significativo (aquele que carrega o menor valor numérico) é o bit mais à direita.

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

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

De acordo com o mapa da estrutura de chaves, essa chave seria decodificada em:

`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, é possível usar uma função hash para gerar chaves dinamicamente de maneira consistente e confiável.

Funciona assim:

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 chave do lado da fonte, gere um hash dessa string e considere adicionar um sufixo de zeros de 64 bits para alinhar a chave do lado do acionador e tornar o OR mais fácil de entender.
   • Parte da chave do lado da origem
     = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
   • Observe que COUNT codifica da mesma forma que measurementGoalType=0 na abordagem do mapa da estrutura principal. COUNT é um pouco mais enxuto e mais 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 chave do lado do acionador, gere hash dessa string e adicione um prefixo de zeros de 64 bits:
   • 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 estiver tudo pronto para solicitar um relatório de resumo dessa chave, gere-o imediatamente:
   • 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>

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

• Sempre use a mesma ordem das dimensões. Isso garante que seus hashes possam ser gerados novamente de maneira confiável. "COUNT, CampaignID=12, GeoID=7" não gera o mesmo hash que "COUNT, GeoID=7, CampaignID=12". Uma maneira simples de fazer isso é classificar as dimensões de maneira 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 em termos conceituais do que todas as outras dimensões.
• Acompanhe o conjunto de dimensões que você está usando nas chaves. É recomendável evitar a geração de chaves com base em um conjunto de dimensões que você 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.

Veja como usar chaves baseadas em hash na prática no exemplo de uma conversão por clique ou na 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 no anúncio), nenhum valor pode ser maior que um determinado limite de contribuição.

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

Confira uma discussão mais aprofundada sobre o orçamento de contribuição em 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 as mais valiosas em cada região?
• Quais estratégias de campanha são mais eficazes em cada região?

Também vamos supor que, para seu caso de uso, você precise 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, concentrar-se nas conversões mais importantes, como compras, é uma boa maneira de garantir que os resultados agregados sejam detalhados e precisos para esses eventos de conversão 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 em configurações de campanha que medem somente 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 razoável e garante uma abordagem de escalonamento simples para seu orçamento de contribuição.

E as moedas?

A exibição de campanhas em diferentes regiões implica que as moedas devem ser consideradas. Você pode:

• Torne a moeda uma dimensão dedicada nas chaves de agregação.
• Outra opção é inferir a moeda a partir do ID de uma 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 agregáveis estão na mesma moeda de referência e, portanto, podem ser somados para gerar um valor total de compra agregado, um valor de compra resumido.

Transforme metas em chaves

Com suas 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ê decide definir como uma contagem de compras.
• Tipo de chave 1: tipo de meta de medição = 1, que você decide definir 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 "uma árvore profunda":

• Cada valor de resumo nos relatórios de resumo é associado a todas as dimensões que você está acompanhando.
• É possível agrupar esses valores de resumo com cada uma dessas dimensões, de modo que esses agrupamentos possam ser tão detalhados 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:

"Qual foi a receita de cada produto gerada em cada uma das minhas campanhas em cada região geográfica?"

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 Entender o ruído.

Estratégia B: duas árvores rasas (duas estruturas principais grossas)

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

Divida cada uma dessas estruturas de chave em dois tipos de chave para oferecer suporte a duas metas de medição.

• Tipo de meta de medição = 0, que você decide definir como uma contagem de compras.
• Tipo de meta de medição = 1, que você decide definir como um valor de compra.

Você vai ter quatro tipos de chaves:

• 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-chave II, contagem de compras.
• Tipo de chave II-1: estrutura-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 chave, o que também significa que você só tem uma estrutura de chave para manter.

No entanto, com a estratégia A, você precisa somar os valores resumidos que recebe nos relatórios resumidos para responder a algumas perguntas. Cada um desses valores de resumo tem ruído. 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 existentes, você pode confiar em dados históricos para determinar se o volume de conversões é mais adequado para a estratégia A ou estratégia B. No entanto, para novos anunciantes ou campanhas, você pode decidir:

• Colete dados de um mês usando as chaves granulares (Estratégia A). Como você está estendendo a duração da coleta de dados, os valores de resumo serão 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ê considera aceitável para seu caso de uso.

Como a estratégia A é mais simples e gera um impacto negativo que não afeta sua capacidade de tomar decisões, você decide escolher a estratégia A.

Selecionar um algoritmo de hash

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

Vamos supor que você tenha selecionado o 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 sobre uma estrutura de chave e um algoritmo de hash, já pode registrar chaves e valores quando os usuários clicam ou visualizam anúncios e, consequentemente, fazem a conversão.

A seguir, há 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, você só pode definir a parte da chave, ou peça da chave, que é conhecida no momento da veiculação do anúncio.

Vamos gerar os principais elementos:

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 das chaves 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 do acionador e da origem 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 correspondidos.

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 faz uma conversão

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 (lado 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 as chaves do lado do gatilho para concluir a chave

Vamos gerar as principais partes:

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

Eles não serão definidos 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, então, pode decidir dividir o orçamento de contribuição em duas.

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, seja de US$ 1.500. Pode haver outliers, por exemplo, muito poucos usuários que gastaram mais que essa soma, mas você pode decidir ignorar esses valores atípicos.

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 você pode 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 associa a conversão a uma visualização ou clique anterior e gera um relatório agregável, que inclui o payload criptografado ao lado dos metadados do relatório.

Confira abaixo um exemplo dos dados que poderiam ser encontrados no payload do relatório agregável, se estivessem legíveis 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 conferir os dados. Por exemplo, para conferir os dados resumidos de COUNT (número total de compras) e VALUE (valor total de compra) do ID da campanha 12 × ID da região geográfica 7 × Categoria do produto 25:
  • Gere a parte da chave do lado da origem, como fez ao configurá-la no navegador.
  • Gere a parte da chave do acionador, como fez ao configurá-la no navegador.

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

Gerenciar o relatório de resumo

Você vai receber um relatório resumido que pode ficar assim:

[
  {"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 versus VALUE), elas estão contidas no mesmo relatório.

Reduzir os valores

• 2.558.500 refere-se ao número de compras para essa chave, escalonadas verticalmente pelo fator de escalonamento calculado anteriormente. O fator de escalonamento da 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 de valor total de 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.