Princípios básicos da API Private Aggregate

Principais conceitos da API Private Aggregate

Qual é o público deste documento?

A API Private Aggregate permite a coleta de dados agregados de worklets com acesso a dados entre sites. Os conceitos compartilhados aqui são importantes para desenvolvedores que criam funções de geração de relatórios no armazenamento compartilhado e na API Protected Audience.

• Se você é um desenvolvedor que cria um sistema de relatórios para medição entre sites.
• Se você é profissional de marketing, cientista de dados ou outro consumidor de relatórios de resumo, entender esses mecanismos ajuda a tomar decisões de design para recuperar um relatório de resumo otimizado.

Termos-chave

Antes de ler este documento, será útil se familiarizar com os principais termos e conceitos. Cada um desses termos será descrito em detalhes aqui.

• Uma chave de agregação, também conhecida como bucket, é uma coleção predeterminada de pontos de dados. Por exemplo, é possível coletar um bucket de dados de local em que o navegador informa o nome do país. Uma chave de agregação pode conter mais de uma dimensão (por exemplo, país e ID do widget de conteúdo).
• Um valor agregável é um ponto de dados individual coletado em uma chave de agregação. Se você quiser medir quantos usuários da França visualizaram seu conteúdo, France será uma dimensão na chave de agregação, e o viewCount de 1 será o valor agregável.
• Os relatórios agregáveis são gerados e criptografados em um navegador. Para a API Private Aggregate, esse valor contém dados sobre um único evento.
• O Serviço de agregação processa dados de relatórios agregáveis para criar um relatório de resumo.
• Um relatório de resumo é a saída final do serviço de agregação e contém dados agregados de usuários com ruído e dados de conversão detalhados.
• Um worklet é uma parte da infraestrutura que permite executar funções JavaScript específicas e retornar informações ao solicitante. Em uma worklet, é possível executar o JavaScript, mas não é possível interagir ou se comunicar com a página externa.

Fluxo de trabalho de agregação particular

Quando você chama a API Private Aggregate com uma chave de agregação e um valor agregável, o navegador gera um relatório agregável. Os relatórios são enviados ao seu servidor, que os agrupa. Os relatórios em lote são processados posteriormente pelo serviço de agregação, e um relatório de resumo é gerado.

1. Quando você chama a API Private Aggregate, o cliente (navegador) gera e envia o relatório agregável ao seu servidor para ser coletado.
2. Seu servidor coleta os relatórios dos clientes e os agrupa para ser enviado ao serviço de agregação.
3. Depois de coletar relatórios suficientes, você os envia em lote e ao serviço de agregação, em execução em um ambiente de execução confiável, para gerar um relatório de resumo.

Termo-chave:ambiente de execução confiável é uma configuração especial de hardware e software de computador que permite que partes externas verifiquem as versões exatas do software em execução no computador. Os TEEs permitem que partes externas verifiquem se o software faz exatamente o que o fabricante afirma que faz, nada mais ou menos.

O fluxo de trabalho descrito nesta seção é semelhante à API Attribution Reporting. No entanto, a API Attribution Reporting associa dados coletados de um evento de impressão e de um evento de conversão, que ocorrem em momentos diferentes. A agregação privada mede um único evento entre sites.

Chave de agregação

Uma chave de agregação ("chave", na sigla em inglês) representa o bucket em que os valores agregáveis serão acumulados. Uma ou mais dimensões podem ser codificadas na chave. Uma dimensão representa algum aspecto do qual você quer ter mais insights, como a faixa etária dos usuários ou a contagem de impressões de uma campanha publicitária.

Por exemplo, talvez você tenha um widget incorporado a vários sites e queira analisar o país dos usuários que o visualizaram. Você quer responder a perguntas como "Quantos dos usuários que viram meu widget são do país X?". Para gerar um relatório sobre essa pergunta, configure uma chave de agregação que codifica duas dimensões: ID do widget e ID do país.

A chave fornecida à API Private Aggregate é um BigInt, que consiste em várias dimensões. Neste exemplo, as dimensões são o ID do widget e o ID do país. Digamos que o ID do widget possa ter até quatro dígitos, como 1234, e que cada país seja mapeado para um número em ordem alfabética. Por exemplo, o Afeganistão é 1, a França é 61 e o Zimbábue é "195". Portanto, a chave agregável teria sete dígitos, em que os quatro primeiros caracteres são reservados para o WidgetID e os três últimos são reservados para o CountryID.

Digamos que a chave represente a contagem de usuários da França (ID do país 061) que viram o ID do widget 3276. A chave de agregação é 3276061.

Chave de agregação
ID do widget	ID do país
3276	061

Exemplo:se uma dimensão tiver espaço de chave disponível para vários dígitos, mas o valor tiver menos, adicione zeros à esquerda. Por exemplo, se o ID do país permitir três dígitos, o ID do país da Argélia será 003.

A chave de agregação também pode ser gerada com um mecanismo de hash, como SHA-256. Por exemplo, a string {"WidgetId":3276,"CountryID":67} pode ser criptografada com hash e convertida em um valor BigInt de 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Se o valor de hash tiver mais de 128 bits, será possível truncá-lo para garantir que ele não exceda o valor máximo de bucket permitido de 2^128−1.

Em uma worklet de armazenamento compartilhado, é possível acessar os módulos crypto e TextEncoder, que podem ajudar a gerar um hash. Para saber mais sobre como gerar um hash, consulte SubtleCrypto.digest() no MDN.

O exemplo a seguir descreve como gerar uma chave de bucket a partir de um valor com hash:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

Observação:embora os conceitos sejam semelhantes, a chave é criada de maneira diferente para a API Private Aggregate e a API Attribution Reporting. Na agregação particular, a chave completa é especificada de uma só vez na chamada JavaScript.

Valor agregável

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.

Agora, volte ao exemplo de pergunta: "Quantos dos usuários que viram meu widget são da França?". A resposta será algo como: "Aproximadamente 4.881 usuários que viram meu ID de widget 3276 são da França". O valor agregável é 1 para cada usuário, e "4.881 usuários" é o valor agregado que é a soma de todos os valores agregáveis para essa chave de agregação.

Chave de agregação		Valor agregável
ID do widget	ID do país	Contagem de visualizações
3276	061	1

Nesse exemplo, incrementamos o valor em 1 para cada usuário que vê o widget. Na prática, o valor agregável pode ser escalonado para melhorar a proporção sinal-ruído.

Orçamento de contribuição

Cada chamada para a API Private Aggregate é chamada de contribuição. Para proteger a privacidade do usuário, o número de contribuições que podem ser coletadas de um indivíduo é limitado.

Quando você soma todos os valores agregáveis em todas as chaves de agregação, a soma precisa ser menor que o orçamento de contribuição. O orçamento tem o escopo definido por origem por worklet e por dia. Ele é separado para os workers da API Protected Audience e do armazenamento compartilhado. Uma janela contínua de aproximadamente 24 horas é usada para o dia. Se um novo relatório agregável fizer com que o orçamento seja excedido, ele não será criado.

O orçamento de contribuição é representado pelo parâmetro L₁ e é definido como 2¹⁶ (65.536) por 10 minutos por dia com um backstop de 2²⁰

(1.048.576). Confira a explicação para saber mais sobre esses parâmetros.

O valor do orçamento de contribuição é arbitrário, mas o ruído é dimensionado de acordo com ele. É possível usar esse orçamento para maximizar a proporção sinal-ruído nos valores de resumo (discutidos mais detalhadamente na seção Ruído e escalonamento).

Para saber mais sobre orçamentos de contribuição, consulte a explicação. Além disso, consulte Orçamento de contribuição para mais orientações.

Relatórios agregáveis

Depois que o usuário invoca a API Private Aggregate, o navegador gera relatórios agregáveis para serem processados pelo serviço de agregação posteriormente para gerar relatórios de resumo. Um relatório agregável é formatado em JSON e contém uma lista criptografada de contribuições, cada uma sendo um par {aggregation key, aggregatable value}. Os relatórios agregáveis são enviados com um atraso aleatório de até uma hora.

As contribuições são criptografadas e não podem ser lidas fora do serviço de agregação. O serviço de agregação descriptografa os relatórios e gera um relatório de resumo. A chave de criptografia do navegador e a chave de descriptografia do serviço de agregação são emitidas pelo coordenador, que atua como o serviço de gerenciamento de chaves. O coordenador mantém uma lista de hashes binários da imagem de serviço para verificar se o autor da chamada tem permissão para receber a chave de descriptografia.

Exemplo de relatório agregável com o modo de depuração ativado:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

Os relatórios agregáveis podem ser inspecionados na página chrome://private-aggregation-internals:

Para fins de teste, o botão "Enviar relatórios selecionados" pode ser usado para enviar o relatório ao servidor imediatamente.

Coletar e agrupar relatórios agregáveis

O navegador envia os relatórios agregáveis para a origem do worklet que contém a chamada para a API Private agregação, usando o caminho conhecido listado:

• Para armazenamento compartilhado: /.well-known/private-aggregation/report-shared-storage
• Para a API Protected Audience: /.well-known/private-aggregation/report-protected-audience

Nesses endpoints, você vai precisar operar um servidor, atuando como um coletor, que recebe os relatórios agregáveis enviados dos clientes.

O servidor vai gerar relatórios em lote e enviar o lote para o serviço de agregação. Crie lotes com base nas informações disponíveis no payload não criptografado do relatório agregável, como o campo shared_info. O ideal é que os lotes tenham 100 ou mais relatórios por lote.

Você pode decidir agrupar em uma base diária ou semanal. Essa estratégia é flexível e pode ser alterada para eventos específicos em que se espera mais volume, por exemplo, dias do ano em que mais impressões são esperadas. Os lotes precisam incluir relatórios da mesma versão da API, origem do relatório e horário do relatório programado.

Serviço de agregação

O Serviço de agregação recebe relatórios agregáveis criptografados do coletor e gera relatórios de resumo.

Para descriptografar o payload do relatório, o serviço de agregação busca uma chave de descriptografia do coordenador. O serviço é executado em um ambiente de execução confiável (TEE), que oferece um nível de garantia de integridade dos dados, confidencialidade de dados e integridade do código. Embora você seja o proprietário e o operador do serviço, não terá visibilidade dos dados que estão sendo processados dentro do TEE.

Relatórios de resumo

Os relatórios de resumo permitem ver os dados coletados com o ruído adicionado. É possível solicitar relatórios de resumo para um determinado conjunto de chaves.

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 como uma string de número binário. Se a chave de agregação usada for "123", o bucket será "1111011".
• value: o valor do resumo de uma determinada meta de medição, somado de todos os relatórios agregáveis disponíveis com ruído adicionado.

Exemplo:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Ruído e escalonamento

Para preservar a privacidade do usuário, o serviço de agregação adiciona ruído uma vez a cada valor de resumo sempre que um relatório de resumo é solicitado. Os valores de ruído são extraídos aleatoriamente de uma distribuição de probabilidade de Laplace. Você não está no controle direto das maneiras como o ruído é adicionado, mas pode influenciar o impacto do ruído nos dados de medição dele.

A distribuição de ruído é a mesma, independentemente da soma de todos os valores agregáveis. Portanto, quanto maiores forem os valores agregáveis, menor será o impacto provável do ruído.

Por exemplo, digamos que a distribuição de ruído tenha um desvio padrão de 100 e esteja centralizada em zero. Se o valor do relatório agregável coletado (ou "valor agregável") for de apenas 200, o desvio padrão do ruído será 50% do valor agregado. No entanto, se o valor agregável for 20.000,o desvio padrão do ruído será de apenas 0, 5% do valor agregado. Assim, o valor agregável de 20.000 teria uma proporção sinal-ruído muito maior.

Portanto, multiplicar o valor agregável por um fator de escalonamento pode ajudar a reduzir o ruído. O fator de escalonamento representa o quanto você quer dimensionar um determinado valor agregável.

Aumentar os valores escolhendo um fator de escalonamento maior reduz o ruído relativo. No entanto, isso também faz com que a soma de todas as contribuições em todos os buckets alcance o limite do orçamento de contribuição mais rapidamente. Reduzir os valores escolhendo uma constante de fator de escalonamento menor aumenta o ruído relativo, mas reduz o risco de atingir o limite de orçamento.

Para calcular um fator de escalonamento apropriado, divida o orçamento de contribuição pela soma máxima dos valores agregáveis em todas as chaves.

Consulte a documentação sobre orçamento de contribuição para saber mais.

Interaja e compartilhe feedback

A API Private Aggregate está sendo discutida ativamente e sujeita a mudanças no futuro. Se você testar essa API e quiser enviar seu feedback, adoraríamos saber.

• GitHub: leia a explicação, faça perguntas e participe da discussão. * Suporte ao desenvolvedor: faça perguntas e participe de discussões no repositório de suporte para desenvolvedores do Sandbox de privacidade. * Participe dos grupos da API Shared Storage e da API Protected Audience para conferir os anúncios mais recentes relacionados à agregação privada.