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 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 fazer isso, você precisará pensar em quais perguntas deseja responder antes que os dados sejam coletados.

Dimensões, chaves e valores

Para responder a essas perguntas, vamos dar uma olhada nas 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, acompanhe 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 por você.

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 "Produto" é conhecida por um evento acionador, quando o usuário conclui uma conversão (momento da conversão).

Observação:para o diagrama neste documento, vamos mostrar as dimensões da seguinte forma:

• Dimensões conhecidas no momento da veiculação do anúncio em um plano de fundo verde.
• Dimensões conhecidas no momento da conversão em um fundo amarelo e sublinhadas.

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

Dimensões a serem acompanhadas

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 (chave) é um dado que representa os valores das dimensões que estão sendo rastreadas. Depois, os dados são agregados em cada chave de agregação.

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

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 uma conversão comprando um produto da categoria 25, é possível definir uma chave de agregação semelhante à da 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, esse será o número total de compras (valor resumido).
• 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.

Pergunta	Valor agregável = meta de medição
		Quantas compras...	Contagem de compras
Qual é a receita...	Valor de compra

Quando um usuário localizado no ID da região 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:

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

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

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

Esse diagrama omite a descriptografia e representa um exemplo simplificado sem aplicação de ruído. 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 visualiza ou clica em um anúncio e depois faz a conversão, você instrui o navegador a armazenar um par {chave de agregação, valor agregável}.

Observação:na explicação, um par {aggregation key, aggregatable value} 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 relatório de resumo.

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

Mais adiante, você verá que um relatório agregável {aggregation key, aggregatable value} não tem essa aparência. 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 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. 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 {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 forma a fazer com que os buckets e valores pareçam diferentes do exemplo anterior (ou seja, um bucket pode ser semelhante a \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 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 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 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 a fazer com que os buckets e 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 principal.

Tipos de chaves

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 fazer isso, dentro de 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 a 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, 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 probabilidade de gerar valores mais ruidosos. Leia mais sobre ruídos em Entender ruídos.

Como já mencionamos, 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 diferentes 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 2ⁿ opções distintas.

Por exemplo, a 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 esta 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 os 200 necessários. Portanto, é possível usar n=8 bits para codificar essa dimensão.

Codificação de teclas

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

Observação:os dados hexadecimais geralmente têm o prefixo 0x. Por exemplo, 0x19 é 19 em hexadecimal; que seja 25 em decimal, não 19. Os números binários normalmente têm o prefixo 0b. Por exemplo, 0b11001 é 11001 em binário. que seja 25 em decimal, não 11.001.

Definir duas partes de 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 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ê definirá uma parte da chave (ID da campanha × ID de geografia) no momento do clique ou da visualização.
2. Você definirá a segunda parte da chave, a categoria do produto, no momento da conversão.

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

Aviso: este documento descreve erroneamente as partes principais como combinadas usando XOR bit a bit quando, na verdade, são combinados usando bit a bit OU.

Uma chave é calculada usando o XOR (^) das principais partes dela.

Exemplo:

• Parte da chave da fonte = 0x159
• Parte da chave do acionador = 0x400
• Tecla = 0x159 ^ 0x400 = 0x559

Alinhar as partes principais

Com duas partes de chave de 64 bits estendidas para 128 bits usando preenchimentos/deslocamentos de 64 bits cuidadosamente colocados (os 16 zeros), as partes de chave XOR são equivalentes à concatenação, o que é mais fácil de analisar e verificar:

• Parte da chave da fonte = 0xa7e297e7c8c8d0540000000000000000
• Parte da chave do acionador = 0x0000000000000000674fbe308a597271
• Tecla = 0xa7e297e7c8c8d0540000000000000000 ^ 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 de geografia × ID da campanha.
• Outra chave que rastreia o tipo de criativo × o ID da 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 de {chave, valor de 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.

Codificar dimensões usando mapas da 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 chave significa que você precisa implementar e manter a lógica do decodificador. Se você está procurando um método que não exija isso, considere usar 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 sua chave que acompanhe o tipo de chave. Isso vai permitir que você defina o que o valor agregável representa ao receber pares {key, aggregatable value} nos 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, para seu caso de uso, que você precise 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.

Veja o número de bits que você precisaria para codificar cada dimensão em 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 armazená-lo.

• 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 a estrutura da 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) é a 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 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 0b1100100111100 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.

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 chave da fonte, gerar hash dessa string e adicionar um sufixo de zeros de 64 bits para align; com a chave do lado do acionador e tornar o XOR mais fácil de entender.
   • Parte da chave da fonte
     = <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 rastrear. os valores delas. Para gerar uma chave do lado do acionador, gere uma hash dessa string e adicione um prefixo de zeros de 64 bits:
   • Parte importante do gatilho = <64-bit 00000000…><64-bit hex hash("productCategory=25")>
4. O navegador faz um XOR dessas 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 estiver tudo pronto para solicitar um relatório de resumo dessa chave, gere-o imediatamente:
   • Com base nas dimensões do seu interesse, gere uma parte-chave do lado da fonte e do acionador, como você fez anteriormente.
     • Parte da chave da fonte
       = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
     • Parte principal do gatilho
       = <64-bit 00000000…><64-bit hex hash("productCategory=25")>
     • parte da chave do acionador = toHex(hash("productCategory=25"))
   • Assim como o navegador, faça XOR dessas peças 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 gerados novamente de maneira confiável. "COUNT, CampaignID=12, GeoID=7" não vai gerar o mesmo hash que "COUNT, GeoID=7, CampaignID=12". Uma maneira simples de conseguir isso é classificar as dimensões de forma alfanumérica. Isso é o que faremos no exemplo, exceto pelo fato de sempre tornarmos COUNT ou VALUE o primeiro item na dimensão. Essa é uma opção para facilitar a leitura, já que COUNT ou VALUE codifica informações que são conceitualmente um pouco diferente de 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.
• Colisões de hashes são raras quando uma função hash adequada é usada, mas a verificação dos 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 as mais antigas.

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

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, há um limite máximo para as contribuições de cada usuário. Em todos os valores agregáveis associados a uma única origem (clique ou visualização do anúncio), nenhum valor pode ser maior que um determinado limite de contribuição.

Chamaremos esse limite de CONTRIBUTION_BUDGET. Na explicação, esse limite é chamado de orçamento L1, mas é igual ao 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

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 as 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. De fato, quanto mais métricas você medir, menor será seu orçamento de contribuição por métrica e, portanto, mais ruído provavelmente será cada valor. Por isso, você precisa 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 valor total de compra e detalhamentos geográficos. Isso mantém o ruído razoável e garante uma abordagem de escalonamento simples para seu orçamento de contribuição.

E quanto às moedas?

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

• Transforme a moeda em 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, presumimos 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 a moeda de referência de sua escolha. Você também pode realizar essa conversão imediatamente, quando o usuário comprar 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 de compra total agregado, ou seja, um resumo do valor de compra.

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 principais 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 de que você precisa:

Todas as chaves usam essa estrutura.

Divida essa estrutura de chave em dois tipos de chave para oferecer suporte a dois tipos metas.

• 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 uma valor de compra.

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

Você pode pensar na estratégia A como uma "árvore profunda" estratégia:

• Cada valor de resumo nos relatórios de resumo está associado a todos os as dimensões que você está acompanhando.
• É possível agrupar esses valores de resumo ao lado de cada uma dessas dimensões, para que esses agrupamentos possam se aprofundar até o número de dimensões que você tem.

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

Pergunta	Resposta
Quais categorias de produtos são as mais valiosas em cada região?	Some as contagens e os valores resumidos de compra que estão no resumo em todas as campanhas. Isso fornece a contagem e o valor de compras por ID geográfico × produto categoria. Para cada região, compare o valor de compra e a contagem de categorias de produtos.
Quais estratégias de campanha são as mais eficazes em cada região?	Some as contagens e os valores resumidos de compra que estão no resumo em todas as categorias de produtos. Isso fornece a contagem de compras e o valor por ID da campanha × ID geográfico. Para cada região, compare o valor de compra e a contagem de campanhas.

Com a estratégia A, também é possível responder diretamente a esta terceira pergunta:

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

Mesmo que os valores de resumo sejam ruidosos, é possível determinar quando as diferenças no valor medido entre cada campanha não se devem ao ruído sozinhos. Aprenda a fazer isso em Noções básicas sobre 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 de as dimensões de que você precisa:

Você divide cada uma dessas estruturas-chave em dois tipos para dar suporte a dois metas de medição.

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

Você terá quatro tipos de chave:

• Tipo de chave I-0: estrutura de chave I, contagem de compras.
• Tipo de chave I-1: estrutura-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 a seguinte aparência:

Pense na estratégia B como "duas árvores rasas" estratégia:

• Os valores de resumo nos relatórios de resumo mapeiam para um de dois pequenos conjuntos de dimensões.
• Você pode agrupar esses valores de resumo ao lado de cada uma das dimensões em desses 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 acumular.

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

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

Decisão: estratégia A

A estratégia A é mais simples, todos os dados seguem a mesma estrutura de chave, que também significa que você só tem uma estrutura-chave para manter.

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

Esse não é o caso da estratégia B, em que os valores do resumo expostos no resumo os relatórios já fornecem as informações necessárias. Isso significa que a estratégia B provavelmente levará a um impacto menor do ruído do que a estratégia A.

Como determinar qual estratégia usar? Para anunciantes existentes ou em duas campanhas, use os dados históricos para determinar se o volume é mais adequada para a estratégia A ou a 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á maior e o ruído será relativamente menor.
• Avaliar com precisão razoável a contagem semanal de conversões e valor de compra.

.

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

Neste exemplo, vamos supor que a contagem semanal de compras e o valor de compra são altas o suficiente para que a estratégia A leve a uma porcentagem de ruído que você considera aceitáveis para seu caso de uso.

Porque a estratégia A é mais simples e gera um impacto no ruído que não afetar 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 as chaves. Para isso, você precisa selecionar um algoritmo de hash para apoiar essa abordagem.

Vamos supor que você tenha selecionado o SHA-256. Você também pode usar uma abordagem algoritmo seguro, como o MD5.

No navegador: definir chaves e valores

Agora que você definiu uma estrutura de chave e um algoritmo de hash, prontos para registrar chaves e valores quando os usuários clicam ou visualizam anúncios e, converter.

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

Definir partes importantes da origem

Aviso: os formatos de cabeçalho desta seção estão obsoletos. Consulte o Explicação sobre o relatório agregável para orientações até que esta seção seja atualizada.

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, só é possível definir a parte da chave, ou parte-chave, que é conhecida no momento da veiculação do anúncio.

Vamos gerar as peças principais:

Parte da chave do lado da fonte 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 simplificar XOR. Essa é a chave do lado da origem.
key_purchaseCount	COUNT, CampaignID=12, GeoID=7	0x3cf867903fbb73ec	0x3cf867903fbb73ec0000000000000000
key_purchaseValue	VALUE, CampaignID=12, GeoID=7	0x245265f432f16e73	0x245265f432f16e730000000000000000

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

Agora, vamos definir as principais partes:

// 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 chaves do lado da fonte e do acionador peças podem 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 fonte, os dados no nível do evento (ID do evento da fonte e dados do acionador) e o chave de agregação podem ser correspondidas.

É possível usar ambos os relatórios se, por exemplo, você planeja usar relatórios de eventos 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 da adtech. Ao receber a solicitação:

• Defina as partes da chave do lado da conversão (lado do acionador) para concluir a chave. Você definirá essas partes importantes por meio do cabeçalho Attribution-Reporting-Register-Aggregatable-Trigger-Data:
• Definir 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

Aviso: os formatos de cabeçalho desta seção estão obsoletos. Consulte o Explicação sobre o relatório agregável para orientações até que esta seção seja atualizada.

Vamos gerar as peças principais:

Parte da chave 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 simplificar a operação XOR. Essa é a chave do 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 principais partes:

// 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 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, você precisa escaloná-los verticalmente e 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: R$ 52

Em vez disso, antes de registrar esses valores agregáveis, é preciso escala para minimizar o ruído.

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

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

Vamos supor o valor máximo de compra para um único usuário, com base na compra histórico de todos os usuários do site é de US $1.500. Pode haver outliers, exemplo de pouquíssimos usuários que gastaram mais que essa quantia, mas você pode decidir ignorar esses outliers.

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

((CONTRIBUTION_BUDGET/2) / 1.500) = 32.768/1.500 = 21,8 Value 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 no anúncio ou visualização (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ê 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 faz a correspondência da conversão com uma visualização ou clique anterior e gera uma relatório agregável, que inclui o payload criptografado ao lado do report metadados.

Este é um exemplo dos dados que podem ser encontrados no payload do relatório agregável, se estiver legível 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 ver duas contribuições separadas em uma única tabela agregável. no relatório.

Solicitar um relatório de resumo

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

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

¹A métrica que você quer solicitar (ID da campanha 12 × ID de geografia 7 × categoria 25 do produto). ²Chave para solicitar o serviço de agregação = Chave XOR do lado do acionador do lado da origem.

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

Gerenciar o relatório de resumo

Ao final, você recebe um relatório resumido 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.

Observação:na prática, os relatórios de resumo são codificados de forma a tornar buckets e valores são 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 a escala vertical dos valores

• 2.558.500 refere-se ao número de compras desta chave, aumentada por fator de escalonamento calculado anteriormente. O fator de escalonamento foi 32.768. Divida 2.558.500 pela contribuição da meta Orçamento: 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 fornecem os seguintes insights:

• Dentro do período do relatório, a campanha 12 exibidos na Europa geraram cerca de 156 compras (± ruído) para a categoria de produto 25.
• Dentro do período do relatório, a campanha 12 exibido na Europa gerou US $31.230 em compras (± ruído) para a categoria de produto 25.