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

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

Como uma empresa de adtech que veicula campanhas em vários 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 pelas minhas campanhas em cada região geográfica?
2. Quanta receita para cada categoria de produto cada uma das minhas campanhas em cada região geográfica gerou?

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 resumidos sejam detalhados e precisos para esses eventos importantes.

Para fazer isso, será preciso pensar nas perguntas que deseja responder antes de coletar os dados.

Dimensões, chaves e valores

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

Observação:as chaves de agregação discutidas neste documento são específicas da API Attribuion Reporting.

Dimensões

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

• ID da campanha publicitária: o identificador da campanha específica.
• ID de geografia: a região geográfica onde o anúncio foi veiculado.
• Categoria do produto: o tipo de produto conforme definido.

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

Observação:para o diagrama neste documento, vamos mostrar as dimensões da seguinte maneira: - Dimensões conhecidas no momento da veiculação do anúncio em um fundo verde. – dimensões conhecidas no momento da conversão em um fundo amarelo e sublinhadas.

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

Dimensões a serem monitoradas

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 usadas para configurar relatórios. O termo bucket é usado nos relatórios agregáveis e de resumo e nas APIs de serviço de agregação.

Uma chave de agregação (abreviada como chave) é uma parte dos dados que representa os valores das dimensões que estão sendo acompanhadas. Depois, os dados são agregados com cada chave de agregação.

Por exemplo, digamos que você esteja acompanhando as dimensões "Categoria do produto", "ID de região geográfica" e "ID da campanha".

Quando um usuário localizado no ID de geografia 7 vê um anúncio do ID da campanha 12 e depois faz uma conversão comprando um produto na categoria de produto 25, é possível definir uma chave de agregação como a da imagem a seguir:

Mais adiante, você vai notar que uma chave de agregação não se parece exatamente com isso na prática, mas vamos nos concentrar por enquanto nas informações contidas na chave.

O que são valores agregáveis?

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

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

Cada um desses valores (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.

Pergunta	Valor agregável = meta de medição
		Quantas compras...	Número de compras
Quanta receita...	Valor de compra

Quando um usuário localizado no ID de região geográfica 7 vê um anúncio para o ID da campanha 12 e depois faz uma conversão comprando um produto da categoria de produto 25 por US$ 120 (supondo que a moeda seja US$), você pode definir uma chave de agregação e valores agregáveis como estes:

Chave de agregação e valores agregáveis. Os valores agregáveis ficam em negrito em um plano de fundo azul.

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

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

Observe que 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 ver como as chaves e os valores agregáveis se relacionam com os relatórios.

Relatórios agregáveis

Quando um usuário clica ou vê um anúncio e depois faz uma conversão, você instrui o navegador a armazenar um par de {aggregation key, aggregatable value}.

Observação:na <a href="https://github.com/WICG/conversion-measurement-api/blob/main/AGGREGATE.md">explicação</a>, um par de {chave de agregação, valor agregável} também é chamado de contribuição do histograma: ele representa como essa conversão, as dimensões e os valores associados a ela, contribuem

para o resumo.

Em 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 tarde, você verá que um relatório agregável {aggregation key, aggregatable value} não tem exatamente essa aparência. 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 for possível corresponder à conversão com uma visualização ou um clique anterior.

Os relatórios agregáveis contêm o seguinte:

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

Os relatórios agregáveis são formatados em 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 de {chave de agregação, valor agregável}:

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

Confira um exemplo:

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

Na prática, os relatórios agregáveis são codificados para fazer com que os buckets e os valores pareçam diferentes do exemplo anterior (ou seja, um bucket pode se parecer com \u0000\u0000\x80\u0000). Bucket e value são strings de bytes.

Relatórios de resumo

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

• Uma adtech solicita relatórios de resumo sobre um determinado conjunto de chaves e um determinado conjunto de relatórios agregáveis de vários navegadores diferentes (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 resumido com um conjunto de pares de {aggregation key, summary value}.

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 decimal em formato 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 modo a fazer com que os buckets e os valores pareçam diferentes do indicado no exemplo (ou seja, um bucket pode parecer \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 é clicado 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 x ID geográfico x categoria de produto é uma estrutura-chave.

Tipos de chave

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

Para fazer isso, em cada chave, codifique um dado que informe o que o valor de resumo representa, ou seja, a meta de medição a que essa chave está se referindo. Uma maneira de fazer isso é criar uma dimensão adicional para sua chave que represente o tipo de meta de medição.

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

• A contagem de compras é o primeiro tipo de meta de medição.
• O valor de 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 por região geográfica".

Tamanho da chave e da dimensão

O tamanho máximo da chave é definido em bits, ou seja, o número de zeros e um 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 chaves mais granulares têm mais chances de levar a valores mais com ruído. Leia mais sobre ruído em Entender o ruído.

Conforme introduzido 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 a dimensão pode assumir. Dependendo da cardinalidade, cada dimensão precisa ser representada por um determinado número de bits. Com n bits, é possível expressar 2n opções distintas.

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

7 bits armazenariam apenas 27 =128 opções distintas, menos que as 200 opções necessárias.

8 bits armazenariam 28 =256 opções distintas, o que é mais do que os 200 necessários. Portanto, é possível usar n=8 bits para codificar essa dimensão.

Codificação de chaves

Ao definir as chaves no navegador, elas devem ser codificadas em hexadecimal. Nos relatórios de resumo, as chaves aparecerão em binários (e serão nomeados como buckets).

Observação:os dados hexadecimais costumam ter o prefixo 0x ("x" para hexadecimais). Por exemplo, 0x19 é 19 em hexadecimal, ou seja, 25 em decimal, não 19. Os números binários costumam ser prefixados com 0b ("b" para binário). Por exemplo, 0b11001 é 11.001 no binário; 25 em decimal, não 11.001.

Defina duas partes importantes 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 da região geográfica" sejam conhecidas quando o anúncio é veiculado (tempo de veiculação do anúncio), a categoria do produto será conhecida por um evento acionador, quando o usuário concluir uma conversão (data/hora da conversão).

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

1. Você definirá uma parte da chave (ID da campanha x ID de região geográfica) no momento do clique ou da visualização.
2. Você definirá a segunda parte da chave, a categoria dos produtos, no momento da conversão.

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

Uma chave é calculada tomando o XOR (^) de suas partes principais.

Exemplo:

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

Alinhamento das partes mais importantes

Com duas partes-chave de 64 bits estendidas para 128 bits usando preenchimentos/deslocamentos de 64 bits cuidadosamente colocados (os dezesseis zeros), as partes-chave XOR são equivalentes a concatená-las, o que é mais fácil de entender e verificar:

• Parte da chave da origem = 0xa7e297e7c8c8d0540000000000000000
• Parte da chave no lado do acionador = 0x0000000000000000674fbe308a597271
• Tecla =
  • 0xa7e297e7c8c8c8d0540000000000000000 ^ 0x0000000000000000674fbe308a597271 =
  • 0xa7e297e7c8c8d054674fbe308a597271

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

Na prática, é possível 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 ID de geografia x ID da campanha.
• Outra chave que rastreia o tipo de criativo x ID da campanha.

Veja outro exemplo na Estratégia B.

Codificar 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 de {key, summary value} brutos e nenhuma informação adicional sobre a chave. O que isso significa:

• Ao definir chaves conforme o usuário visualiza ou clica em um anúncio e depois faz a conversão, é necessário definir as chaves com base nos valores das dimensões que elas representam.
• Ao definir as chaves para as quais você quer solicitar relatórios de resumo, você precisa gerar ou acessar de maneira confiável as mesmas chaves que as 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 para as quais você deseja ver dados agregados.

Codificar dimensões usando mapas de estrutura de chave

Para codificar dimensões em chaves, você pode criar e manter um mapa de estrutura de chave com antecedência, ao definir suas chaves (antes do horário de veiculação do anúncio).

Esse mapa representa cada uma das suas dimensões e a posição delas na chave.

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

Confira um exemplo:

Vamos supor que você pretenda 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 área 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 da compra), é necessário adicionar uma dimensão na chave que controle o tipo de chave. Isso vai permitir que você defina o que o valor agregável realmente representa ao receber pares de {key, aggregatable value} 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 da região geográfica
• ID da campanha

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

• 29 categorias de produtos diferentes.
• Oito 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.

Este é o número de bits que você precisaria para codificar cada dimensão na sua chave:

• Categoria do produto: 5 bits (25 = 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 o valor.

• ID da região geográfica: 3 bits (23 = 8). Também seria necessário definir um mapa de dimensão para o ID de região geográfica, a fim de saber qual região geográfica cada valor binário representa. O mapa de dimensão para seu 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 (24 = 16)

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

Para este exemplo, o mapa da estrutura de chaves para essas chaves ficaria assim:

A ordem das dimensões na chave cabe a você.

Para ilustrar como as dimensões compõem uma estrutura-chave, vamos usar uma representação binária. É por isso que o ID da campanha (primeiros bits) é o mais à direita e a categoria do produto (últimos bits) é o mais à 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 você usaria um mapa de estrutura de chave para decodificar uma chave.

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

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

11001 0 011 1100

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

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

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 no lado da origem, faça um hash dessa string e considere adicionar um sufixo de zeros de 64 bits para alinhar a parte da chave do lado do acionador e facilitar o entendimento de XOR.
   • Parte da chave da origem
     = <hash hexadecimal de 64 bits("COUNT, campaignID=12, geoID=7"))><64 bits 00000000...>
   • COUNT codifica o mesmo elemento que MeasurementGoalType=0 na abordagem do mapa de estrutura-chave. COUNT é um pouco mais enxuto 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 lado do acionador, gere um hash dessa string e adicione um prefixo de zeros de 64 bits:
   • Parte da chave no lado do acionador = <00000000 de 64 bits...><hash hexadecimal de 64 bits("productCategory=25")>
4. O navegador faz uma XOR dessas partes para gerar uma chave.
   • Chave de agregação de 128 bits
     = <Hash da parte da chave hexadecimal da origem de 64 bits><Hash da parte da chave hexadecimal da origem de 64 bits>
5. Depois, quando estiver tudo pronto para solicitar um relatório de resumo dessa chave, gere-o rapidamente:
   • Com base nas dimensões em que você tem interesse, gere uma chave da fonte e do acionador, como você fez anteriormente.
     • Parte da chave da origem
       = <hash hexadecimal de 64 bits("COUNT, campaignID=12, geoID=7"))><64 bits 00000000...>
     • Parte da chave no lado do acionador
       = <00000000...><hash hexadecimal de 64 bits("productCategory=25")>
     • parte da chave do acionador = toHex(hash("productCategory=25"))
   • Assim como o navegador, faça XOR dessas partes importantes para gerar a mesma chave que o navegador gerou anteriormente.
     • Chave de agregação de 128 bits
       = <hash de chave da chave do lado da origem de 64 bits><Hash da parte da chave do lado da origem de 64 bits>

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

• Sempre use a mesma ordem de 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 em ordem alfanumérica. Isso é o que vamos fazer no exemplo, exceto pelo fato de que sempre faremos COUNT ou VALUE o primeiro item na dimensão. Essa é uma escolha para facilitar a leitura, já que COUNT ou VALUE codifica informações que são conceitualmente diferentes das 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.
• Os conflitos de hashes são raros quando uma função de hash adequada é usada. No entanto, 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 entram em conflito com outras mais antigas.

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

Valores agregáveis na prática

A empresa de adtech define valores agregáveis quando um usuário faz uma conversão.

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 do que um determinado limite de contribuição.

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

Para ver uma discussão mais 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

Para este exemplo, vamos supor que você queira 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.
• Oito 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 de conversão importantes. Na verdade, quanto mais métricas você avaliar, menor será seu orçamento de contribuição por métrica e, portanto, mais ruído poderá ser cada valor. Portanto, você precisa selecionar cuidadosamente 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 medirá a contagem e o valor da compra e acessará várias estatísticas agregadas importantes, como valor total de compra e detalhamentos geográficos. Isso mantém o nível de ruído razoável e garante uma abordagem de escala simples para o seu orçamento de contribuição.

E as moedas?

Veicular campanhas em diferentes regiões significa que as moedas devem ser levadas em conta. É possível:

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

Neste exemplo, vamos supor que você possa inferir a moeda a partir de um ID de 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 ficam na mesma moeda de referência e podem ser somados para gerar um valor de compra total agregado, ou seja, um valor de compra resumido.

Converter 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 principais gerais.

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 chaves usam essa estrutura.

Você divide essa estrutura-chave em dois tipos para dar suporte a duas metas 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 a seguinte 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á rastreando.
• Você pode agrupar esses valores resumidos em cada uma dessas dimensões, para que essas visualizações completas possam ir tão longe quanto os números de dimensões que você tem.

Com a estratégia A, você responderia a suas perguntas da seguinte forma:

Pergunta	Resposta
Quais categorias de produtos são as mais valiosas em cada região?	Some o resumo das contagens e dos valores de compras presentes nos relatórios de resumo em todas as campanhas. Mostra a contagem de compras e o valor por ID geográfico x categoria do produto. Para cada região, compare o valor de compra e a contagem de diferentes categorias de produtos.
Quais estratégias de campanha são mais eficazes em cada região?	Some as contagens e os valores resumidos de compras que estão nos relatórios de resumo em todas as categorias de produtos. Isso informa a contagem de compras e o valor por ID da campanha x ID geográfico. Para cada região, compare o valor de compra e a contagem de campanhas diferentes.

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

"Qual é a receita gerada por cada produto nas minhas campanhas em cada região geográfica?"

Mesmo que haja ruído nos valores de resumo, você pode determinar quando as diferenças no valor medido entre cada campanha não são causadas apenas pelo ruído. Aprenda a fazer isso em Noções básicas sobre ruído.

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

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

Divida cada uma dessas estruturas principais 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 principais:

• 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 de chave II, contagem de compras.
• Tipo de chave II-1: estrutura de chave II, valor de compra.

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

Pense 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, já que há menos dimensões para agrupar.

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

Pergunta	Resposta
Quais categorias de produtos são as mais valiosas em cada região?	Acessar diretamente as contagens e os valores resumidos de compras que estão nos relatórios de resumo.
Quais estratégias de campanha são mais eficazes em cada região?	Acessar diretamente as contagens e os valores resumidos de compras que estão nos relatórios de resumo.

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

No entanto, com a estratégia A, você precisa somar os valores de resumo recebidos em relatórios de resumo para responder a algumas das suas perguntas. Cada um desses valores de resumo é com ruído. Ao somar esses dados, você também está somando o ruído.

Esse não é o caso da 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 terá um impacto menor com base no ruído do que a estratégia A.

Como você deve determinar qual estratégia usar? Para campanhas ou anunciantes 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:

• Coletar o valor de um mês de dados com 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 semanais e o valor de compra.

Observação:não confie em contagens de relatórios ou dados disponíveis apenas nos relatórios de depuração como uma fonte de verdade nos seus designs. No futuro, os dados disponíveis nos relatórios de depuração vão mudar, e os relatórios com ruído serão gerados com relatórios reais. Portanto, esses indicadores só podem ser usados para validar sua estratégia de implementação e teste.

Neste exemplo, suponha que a contagem semanal e o valor da compra 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 significativo que não afeta sua capacidade de tomar decisões, opte pela 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 SHA-256. Também é possível usar um algoritmo mais simples e menos seguro, como o MD5.

No navegador: definir chaves e valores

Agora que você definiu uma estrutura de chave e um algoritmo de hash, está tudo pronto para registrar chaves e valores quando os usuários clicarem ou visualizarem anúncios e, em seguida, realizarem uma conversão.

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

Definir as partes principais da fonte

Quando um usuário clicar ou visualizar um anúncio, defina as chaves de agregação no cabeçalho Attribution-Reporting-Register-Aggregatable-Source. Neste estágio, para cada chave, você só pode definir a parte da chave, ou parte da chave, que é conhecida no momento da veiculação do anúncio.

Vamos gerar as partes principais:

Parte da chave da origem do ID da chave...	String com os valores de dimensão que você quer definir	Hash dessa string como hexadecimal, cortado para os primeiros 64 bits (64/4 = 16 caracteres^1)	Hash hexadecimal com zeros anexados para simplificar o processamento XOR. Essa é a parte da chave no lado da origem.
key_purchaseCount	CONT.NÚM, ID da campanha=12, ID geográfico=7	0x3cf867903fbb73ec	0x3cf867903fbb73ec0000000000000000
key_purchaseValue	VALOR, ID da campanha=12, ID geográfico=7	0x245265f432f16e73	0x245265f432f16e730000000000000000

¹Cada dígito hexadecimal representa quatro bits (dígitos binários).

Agora vamos definir as partes principais:

// 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 aparecerão nos relatórios finais. Elas são usadas apenas ao definir chaves no navegador, para que as partes da chave do lado da fonte 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 eventos com relatórios agregáveis, garanta que os dados nesse nível (ID do evento da fonte e dados do acionador) e da chave de agregação possam ser correspondidos.

Convém usar ambos os relatórios se, por exemplo, você planeja usar relatórios de eventos para gerar 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 normalmente é enviada ao servidor de adtechs. Ao receber a solicitação:

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

Defina as partes da chave do lado do acionador para concluir a chave

Vamos gerar as partes principais:

Parte da chave no lado do acionador para o ID da chave...	String com os valores de dimensão que você quer definir	Hash dessa string como hexadecimal, cortado para os primeiros 64 bits (64/4 = 16 caracteres^1)	Hash hexadecimal com zeros anexados para simplify o processamento XOR. Essa é a parte da chave no lado da origem.
key_purchaseCount	ProductCategory=25	0x1c7ce88c4904bbe2	0x0000000000000000f9e491fe37e55a0c
key_purchaseValue	(igual)	(igual)	(igual)

¹Cada dígito hexadecimal representa quatro bits (dígitos binários).

Agora vamos definir as partes principais:

// 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 diversos 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 escaloná-los para reduzir o ruído.

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

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

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

Em vez disso, antes de registrar esses valores agregáveis, é necessário escaloná-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 dois.

Nesse caso, cada meta recebe no máximo 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 exceções. Por exemplo, poucos usuários que gastaram mais do que essa soma, mas você pode decidir ignorar esses outliers.

Seu fator de escalonamento para o valor de compra precisa ser:

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

Seu 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 no 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ê os definiria da seguinte maneira, usando o cabeçalho dedicado Attribution-Reporting-Register-Aggregatable-Values:

// 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 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 forem legíveis em texto não criptografado:

[ {
  key: 0x3cf867903fbb73ecf9e491fe37e55a0c, // = source-side key piece XOR 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 XOR conversion-side key piece for the key key_purchaseValue 
  value: 1144 // the scaled value for $52, in the context of [CONTRIBUTION_BUDGET/2] 
}]

Aqui, é possível conferir duas contribuições separadas em um único relatório agregável.

Solicitar um relatório de resumo

• Relatórios agregáveis em lote. Siga as recomendações oferecidas em Lotes.
• Gere as chaves para ver os dados. Por exemplo, para ver os dados de resumo de COUNT (número total de compras) e VALUE (valor total de compra) do ID da campanha 12 x ID de região geográfica 7 x categoria de produto 25:
  • Gere a parte da chave no lado da fonte, como você fez ao configurá-la no navegador.
  • Gere a parte da chave no lado do acionador, como você fez ao configurá-la no navegador.

Métrica que você quer solicitar^1	Parte principal da fonte	Parte da chave no lado do gatilho	Chave para solicitar o serviço de agregação^2
Contagem total de compras (COUNT)	0x3cf867903fbb73ec 0000000000000000	0x00000000000000 00f9e491fe37e55a0c	0x3cf867903fbb73 ecf9e491fe37e55a0c
Valor total de compra (VALUE)	0x245265f432f16e73 0000000000000000	0x0000000000000000 f9e491fe37e55a0c	0x245265f432f16e73 f9e491fe37e55a0c

¹Métrica que você quer solicitar (para ID da campanha 12 x ID de região geográfica 7 x categoria de produto 25). ² Chave a ser solicitada ao serviço de agregação = parte da chave do lado da origem XOR parte da chave do acionador.

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

Processar o relatório de resumo

Por fim, você recebe um relatório resumido como este:

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

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

Observação: na prática, os relatórios de resumo são codificados de modo a fazer com que os buckets e valores pareçam diferentes do que você acabou de ver, ou seja, um bucket pode ter esta aparência: \u0000\u0000\x80\u0000. Bucket e value são strings de bytes. Confira um exemplo.

Reduzir os valores

• 2.558.500 refere-se ao número de compras dessa chave, ampliada pelo fator de escalonamento 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 = valor total de compra de US $31.230.

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

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

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