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 você pode traduzir 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 cada uma das minhas campanhas gerou em cada região geográfica?
2. Qual foi a receita de cada categoria de produto gerada por cada uma das minhas campanhas em cada região geográfica?

Embora muitas empresas de tecnologia de publicidade incentivem os anunciantes a configurar vários tipos de conversão, concentrar-se nas mais importantes, como compras, é uma boa maneira de verificar se os resultados do resumo são detalhados e precisos para esses eventos importantes.

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

Dimensões, chaves e valores

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

Dimensões

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

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

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

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

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

Os termos "chave de agregação de termos" 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, bem como nas APIs do serviço de agregação.

Uma chave de agregação (ou simplesmente chave) é um dado que representa os valores das dimensões rastreadas. Os dados são agregados posteriormente ao longo de cada chave de agregação.

Por exemplo, suponha 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 geografia 7 vê um anúncio do ID de campanha 12 e depois faz uma conversão comprando um produto na categoria 25, você pode definir uma chave de agregação semelhante à da imagem a seguir:

Você vai ver 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 nela.

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 agregados e disponibilizados em um relatório de resumo, esse 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, essa será a receita total (valor do resumo).

Cada um deles (a contagem de compras 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 geografia 7 vê um anúncio do ID da campanha 12 e depois faz uma conversão comprando um produto da categoria 25 por US $120 (supondo que sua moeda seja o dólar americano), você pode definir uma chave de agregação e valores agregáveis como 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 em 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.

Das chaves e valores aos relatórios

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

Relatórios agregáveis

Quando um usuário clica ou visualiza um anúncio e faz uma conversão depois, 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).

Você vai ver mais tarde que um relatório agregável {chave de agregação, valor agregável} não é exatamente assim, mas, por enquanto, vamos nos concentrar nas informações contidas nele.

Quando você instrui o navegador a gerar duas contribuições, ele gera um relatório agregável (se puder corresponder a conversão com 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 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 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 bytestring.
• value: o valor agregável para essa meta de medição, codificado como uma bytestring.

Veja um exemplo:

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

Na prática, os relatórios agregáveis são codificados de uma forma que faz com que os buckets e valores pareçam diferentes do exemplo anterior. Ou seja, um bucket pode parecer \u0000\u0000\x80\u0000. Bucket e valor são 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 de resumo para um determinado conjunto de chaves e um determinado conjunto de relatórios agregáveis que vêm de muitos 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 bytestring.
• value: o valor do 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 forma que faz com que os buckets e valores pareçam diferentes do que foi declarado no exemplo (ou seja, um bucket pode parecer \u0000\u0000\x80\u0000). Bucket e value são bytestrings.

Chaves de agregação na prática

As chaves de agregação (buckets) são definidas por uma empresa de tecnologia de publicidade, 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 × GeoID × Categoria do produto" é uma estrutura importante.

Tipos de chaves

Os valores agregáveis são somados para uma determinada chave em vários usuários/navegadores. Mas já vimos que os valores agregáveis podem acompanhar diferentes metas de medição, como um valor ou uma contagem de compras. Você quer verificar se o serviço de agregação vai somar valores agregáveis do mesmo tipo.

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

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

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

Você pode pensar 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 geográfica".

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 chaves mais granulares têm mais chances de gerar valores ruidosos. Leia mais sobre ruído em Entender o ruído.

Como apresentado 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?

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, 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 formato binário e são chamadas de buckets.

Definir duas partes principais para uma chave completa

Vamos supor que você use uma chave para rastrear 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 geografia" sejam conhecidas quando o anúncio é veiculado (tempo de veiculação), a categoria do produto será conhecida por um evento de acionamento, quando o usuário concluir uma conversão (tempo de 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 geografia) 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 diferentes partes das chaves são chamadas de partes da chave.

Uma chave é calculada usando o OR (v) das partes dela.

Exemplo:

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

Alinhar peças importantes

Com duas partes de chave de 64 bits estendidas para 128 bits usando preenchimentos ou offsets de 64 bits cuidadosamente posicionados (os dezesseis zeros), a operação OR com partes de chave é equivalente à concatenação delas, o que é mais fácil de entender e verificar:

• Elemento principal 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 origem de atribuição (clique ou visualização do anúncio). Por exemplo, você pode definir:

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

Confira Estratégia B para ver outro exemplo.

Como 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, pedindo relatórios de resumo para um determinado conjunto de chaves de agregação.

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

• Ao definir chaves enquanto o usuário visualiza ou clica em um anúncio e faz uma conversão depois, é necessário 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 uma conversão, com base nos valores das dimensões para as quais você quer ver dados agregados.

Como codificar dimensões usando mapas de estrutura de chave

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

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

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ê planeja rastrear compras e valores de compra para 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 compras), é necessário adicionar uma dimensão à sua chave que acompanhe o tipo de chave. Isso permite definir o que o valor agregável realmente representa ao receber pares {chave, valor agregável} em relatórios de resumo.

Com essas metas de medição, sua 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ê precisa rastrear 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 (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 qual região geográfica cada valor binário representa. O mapa de dimensão para a dimensão "ID geográfico" pode ser assim:

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

Para este exemplo, o mapa de estrutura de chave ficaria assim:

A ordem das dimensões na chave é você quem decide.

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

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

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

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

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

`11001 0 011 1100`

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

Codificação de dimensões usando uma função de hash

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

Isso funciona da seguinte maneira:

1. Selecione um algoritmo de hash.
2. No momento da veiculação de anúncios, gere uma string que inclua todas as dimensões que você quer rastrear e os valores delas. Para gerar a parte da chave do lado da origem, faça o hash dessa string e adicione um sufixo de zeros de 64 bits para alinhar com a parte da chave do lado do gatilho e facilitar o raciocínio sobre OR.
   • Parte principal do lado da origem
     = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
   • Observe que COUNT codifica a mesma coisa que measurementGoalType=0 na abordagem de mapa de estrutura de 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 gatilho, faça hash dessa 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 faz uma operação OR com essas partes 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 na hora:
   • Com base nas dimensões de seu interesse, gere uma parte principal do lado da origem e do lado do acionador, como fez antes.
     • Parte principal do lado da origem
       = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
     • Parte da chave do lado do gatilho
       = <64-bit 00000000…><64-bit hex hash("productCategory=25")>
     • Parte da chave do lado do acionador = toHex(hash("productCategory=25"))
   • Assim como o navegador, faça OR dessas partes principais para gerar a mesma chave que o navegador gerou antes.
     • 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 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 em ordem alfanumérica. É isso que vamos fazer no exemplo, exceto pelo fato de que sempre vamos colocar COUNT ou VALUE como 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 um pouco diferentes 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 hash são raras se uma função de hash adequada for usada, mas a verificação em relação a hashes usados anteriormente (que devem ser armazenados para interpretar os resultados do serviço de agregação) pode evitar a introdução de novas chaves que entrem em conflito 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 tecnologia de publicidade define valores agregáveis quando um usuário faz uma conversão.

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

Vamos nos referir a esse limite como CONTRIBUTION_BUDGET. No explainer, 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 rastrear 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 tecnologia de publicidade incentivem os anunciantes a configurar vários tipos de conversão, concentrar-se nas mais importantes, como compras, é uma boa maneira de verificar se os resultados agregados são detalhados e precisos para esses eventos de conversão importantes. Quanto mais métricas você mede, menor é o orçamento de contribuição por métrica e, portanto, mais ruidoso cada valor tende a ser. 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, além de acessar várias estatísticas agregadas importantes, como o valor total das compras e os detalhamentos geográficos. Isso gerencia o ruído de forma eficaz e confirma um método de escalonamento simples para seu orçamento de contribuição.

E as moedas?

Veicular campanhas em regiões diferentes implica que as moedas precisam ser consideradas. Você pode:

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

Neste exemplo, vamos presumir que você pode inferir a moeda de um ID de campanha. Isso permite converter qualquer valor de compra da moeda local do usuário para uma moeda de referência da sua escolha. Você também pode fazer essa conversão na hora, 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 podem ser somados para gerar um valor total agregado de compra, ou seja, um valor de compra resumido.

Traduzir metas em chaves

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

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

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 em dois tipos de chaves para oferecer 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 esta aparência:

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

• Cada valor de resumo nos relatórios de resumo está associado a todas as dimensões que você está rastreando.
• É possível resumir esses valores com cada uma dessas dimensões, o que permite que os resumo sejam tão detalhados quanto o número de dimensões que você tem.

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

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

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

Mesmo que os valores de resumo sejam ruidosos, é possível 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 de chave aproximadas)

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

Você divide cada uma dessas estruturas principais em dois tipos principais 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ê acaba com 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 da compra.
• Tipo de chave II-0: estrutura de chave II, contagem de compras.
• Tipo de chave II-1: estrutura de chave II, valor da compra.

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

Pense na estratégia B como uma estratégia de "duas árvores superficiais":

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

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

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ó precisa manter uma estrutura de chave.

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

Não é o caso da estratégia B, em que os valores de resumo expostos nos relatórios 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 decidir:

• Colete um mês de dados com as chaves granulares (estratégia A). Como você está aumentando 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 das compras semanais sejam altos o suficiente para que a estratégia A gere uma porcentagem de ruído aceitável para seu caso de uso.

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

Selecionar um algoritmo de hash

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

Vamos supor que você selecionou 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ê decidiu uma estrutura de chave e um algoritmo de hash, está pronto para registrar chaves e valores quando os usuários clicam ou visualizam anúncios e fazem uma conversão.

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

Definir peças-chave do lado da origem

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

Vamos gerar as peças principais:

Agora vamos definir as peças 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 principais não aparecem nos relatórios finais. Elas só são usadas ao definir chaves no navegador para que as partes da chave do lado da origem e do lado 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 e 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 correspondentes.

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

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

• Defina as partes da chave do lado da conversão (lado do acionador) para concluir a chave. Você vai definir essas partes principais usando o 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.

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

Vamos gerar as peças principais:

Agora vamos definir as peças 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 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 aumentar a escala deles 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 agregáveis:

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

Em vez disso, antes de registrar esses valores agregáveis, é preciso escalonar 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 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 para um único usuário, com base no histórico de compras de todos os usuários do site, seja de R $1.500. Pode haver outliers, por exemplo, muito poucos usuários que gastaram mais do que essa soma, mas você pode decidir ignorar esses outliers.

Seu fator de escalonamento para o valor da compra deve 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 rastrear 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ê os definiria da seguinte forma, 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 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 abaixo um exemplo dos dados que podem ser encontrados no payload do relatório agregável, se ele fosse legível em texto simples:

[
  {
    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 ver duas contribuições separadas em um único relatório agregável.

Pedir um relatório de resumo

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

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

Processar o relatório de resumo

Por fim, você recebe um relatório de resumo que pode ser 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 x VALUE), elas estão contidas no mesmo relatório.

Reduzir os valores

• 2.558.500 se refere ao número de compras dessa chave, aumentado 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 = US $31.230 de 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.