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

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

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

ID da campanha, ID da região geográfica e categoria do produto.
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:

Chave de agregação para uma conversão.

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:

Chaves e valores de agregação.
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.

Gerar insights agregados.

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 clica ou visualiza um anúncio e depois faz a conversão, você instrui o navegador a armazenar um par {aggregation key, aggregatable value}.

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

Gerando duas contribuições.

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 for possível corresponder a conversão a uma visualização ou um clique anterior).

Um relatório agregável contém:

O relatório agregável resultante.

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 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 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.
Os relatórios agregáveis e a agregação, a descriptografia e o ruído resultam em um relatório resumido.

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 que os buckets e os valores pareçam diferentes do indicado no exemplo (ou seja, um bucket pode ser semelhante a \u0000\u0000\x80\u0000). Bucket e value são strings de bytes.

Chaves de agregação na prática

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

Estrutura da chave

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

Por exemplo, ID da campanha × ID geográfico × categoria do produto é uma estrutura principal.

Estrutura da chave.

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.
Metas e tipos de metas 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 2n 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 27 = 128 opções distintas, o que é menos do que os 200 necessários.

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

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.

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

Partes da chave com XOR.

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. O que isso significa:

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

  • ID da região geográfica: 3 bits (23 = 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 (24 = 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:

Mapa da estrutura principal.

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 do lado da origem, gere um hash dessa string e considere adicionar um sufixo de zeros de 64 bits para alinhar a chave do lado do acionador e tornar o XOR mais fácil de entender.
    • Parte da chave da origem
      = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
    • Observe que COUNT codifica da mesma forma que measurementGoalType=0 na abordagem do mapa da estrutura principal. COUNT é um pouco mais enxuto e mais explícito.
  3. No momento da conversão, gere uma string que inclua todas as dimensões que você quer acompanhar e os valores delas. Para gerar uma chave do lado do acionador, gere hash dessa string e adicione um prefixo de zeros de 64 bits:
    • Parte da chave do acionador = <64-bit 00000000…><64-bit hex hash("productCategory=25")>
  4. O navegador 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 origem
        = <64-bit hex hash("COUNT, campaignID=12, geoID=7"))><64-bit 00000000…>
      • Parte da chave do acionador
        = <64-bit 00000000…><64-bit hex hash("productCategory=25")>
      • parte da chave do acionador = toHex(hash("productCategory=25"))
    • Assim como o navegador, 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 gera o mesmo hash que "COUNT, GeoID=7, CampaignID=12". Uma maneira simples de fazer isso é classificar as dimensões de maneira alfanumérica. Isso é 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.

Para uma discussão mais aprofundada 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 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 simples de escalonamento para o 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. É possível:

  • 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 necessárias:

Uma estrutura de chave granular

Todas as chaves usam essa estrutura.

Divida essa estrutura em dois tipos principais 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:

Estratégia Um relatório de resumo.

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

  • Cada valor de resumo nos relatórios de resumo está associado a todas as dimensões rastreadas.
  • É possível agrupar esses valores de resumo ao lado de cada uma dessas dimensões, para que esses agrupamentos possam se aprofundar no 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 nos relatórios de resumo de todas as campanhas.
Isso informa a contagem de compras e o valor por ID geográfico × categoria de 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 as mais eficazes em cada região? Some as contagens e os valores resumidos de compra que estão nos relatórios de resumo de todas as categorias de produtos.
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 diferentes.

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

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

Mesmo que os valores de resumo apresentem ruído, é possível determinar quando as diferenças no valor medido entre cada campanha não se devem apenas ao ruído. 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 das dimensões de que você precisa:

Estrutura de chave 1 e estrutura de chave 2.

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

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

Você 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:

Resumo da estratégia de relatório B.

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

  • Os valores resumidos nos relatórios de resumo são associados a um dos dois pequenos conjuntos de dimensões.
  • Você pode agrupar esses valores de resumo ao lado de 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 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 nos 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 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 de chave para manter.

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

Esse não é o caso da estratégia B, em que os valores resumidos expostos nos relatórios de resumo 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 ou campanhas existentes, você pode confiar em dados históricos para determinar se o volume de conversões é mais adequado para a estratégia A ou estratégia B. No entanto, para novos anunciantes ou campanhas, você pode decidir:

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

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

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

Selecionar um algoritmo de hash

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

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

No navegador: definir chaves e valores

Agora que você decidiu sobre uma estrutura de chave e um algoritmo de hash, já pode registrar chaves e valores quando os usuários clicam ou visualizam anúncios e, consequentemente, fazem a conversão.

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

Registra chaves e valores para uma visualização ou um clique.
Registra chaves e valores para uma conversão.

Definir partes importantes 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. 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 caracteres1) Hash hexadecimal com zeros anexados para simplificar a operação XOR. Esta é a parte da chave no lado da origem.
key_purchaseCount COUNT, CampaignID=12, GeoID=7 0x3cf867903fbb73ec 0x3cf867903fbb73ec0000000000000000
key_purchaseValue VALUE, CampaignID=12, GeoID=7 0x245265f432f16e73 0x245265f432f16e730000000000000000
1Cada 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, de modo que as chaves 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 evento com relatórios agregáveis, verifique se os dados no nível do evento (ID do evento da fonte e dados do acionador) e a chave de agregação são correspondentes.

É 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ê vai definir essas partes importantes pelo cabeçalho Attribution-Reporting-Register-Aggregatable-Trigger-Data.
  • Defina o valor agregável para essa conversão usando o cabeçalho Attribution-Reporting-Register-Aggregatable-Values.

Definir as chaves do lado do gatilho para concluir a chave

Vamos gerar as 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 caracteres1) Hash hexadecimal com zeros anexados para simplify a operação XOR. Esta é a parte da chave no lado da origem.
key_purchaseCount ProductCategory=25 0x1c7ce88c4904bbe2 0x0000000000000000f9e491fe37e55a0c
key_purchaseValue (igual) (igual) (igual)
1Cada 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 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 escaloná-los para reduzir o ruído.

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

Eles não serão definidos diretamente como valores agregáveis:

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

Em vez disso, antes de registrar esses valores agregáveis, você precisa 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 duas.

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

Vamos supor que o valor máximo de compra de um único usuário, com base no histórico de compras de todos os usuários do site, seja de US $1.500. Pode haver outliers, por exemplo, pouquíssimos usuários que gastaram mais que essa soma, mas você pode decidir ignorar esses valores atípicos.

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 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 poderiam ser encontrados no payload do relatório agregável, se estivessem legíveis em texto não criptografado:

[
  {
    key: 0x3cf867903fbb73ecf9e491fe37e55a0c, // = source-side key piece 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 um único relatório agregável.

Solicitar um relatório de resumo

  • Relatórios agregáveis em lote. Siga as recomendações oferecidas em Lote.
  • Gere as chaves das quais você quer ver dados. Por exemplo, para conferir os dados resumidos de COUNT (número total de compras) e VALUE (valor total de compra) do ID da campanha 12 × ID da região geográfica 7 × Categoria do produto 25:
Métrica que você quer solicitar1 Parte principal da fonte Parte importante do gatilho Chave para solicitar o serviço de agregação2
Total de compras (COUNT) 0x3cf867903fbb73ec
0000000000000000		 0x00000000000000
00f9e491fe37e55a0c		 0x3cf867903fbb73
ecf9e491fe37e55a0c.
Valor total da compra (VALUE) 0x245265f432f16e73
0000000000000000		 0x0000000000000000
f9e491fe37e55a0c		 0x245265f432f16e73
f9e491fe37e55a0c
1Métrica que você quer solicitar (ID da campanha 12 × ID de geografia 7 × Categoria do produto 25). 2Chave 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.

Reduzir a escala vertical dos valores

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

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

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