Esta página foi traduzida pela API Cloud Translation.

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 os desenvolvedores que criam relatórios no Shared Storage e na API Protected Audience.

Se você for desenvolvedor e estiver criando um sistema de relatórios para vários sites de medida.
Se você é um profissional de marketing, cientista de dados ou outro relatório de resumo consumidor, entender esses mecanismos ajudará você a tomar decisões de design para recuperar um relatório de resumo otimizado.

Termos-chave

Antes de ler este documento, os principais termos e conceitos. Cada um desses termos será descrito detalhadamente aqui.

Uma chave de agregação (também conhecida como bucket) é um uma coleção predeterminada de pontos de dados. Por exemplo, talvez você queira coletam um bucket de dados de local em que o navegador informa o país. nome. 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 coletados em uma chave de agregação. Se você quiser medir quantos usuários da França viram seu conteúdo, então France será uma dimensão na chave de agregação, e o viewCount de 1 é o valor agregável.
Os relatórios agregáveis são gerados e criptografados em um navegador. Para o API Private Aggregate, que 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 é o resultado final do serviço de agregação. contém dados agregados de usuários e dados de conversão detalhados.
Um worklet é uma parte de infraestrutura que permite executar funções JavaScript e retornam informações ao requerente. Em um worklet, é possível executar JavaScript, mas não é possível interagir ou se comunicar com a página externa.

Fluxo de trabalho da 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 enviadas ao seu servidor, que agrupa os relatórios em lotes. Os relatórios em lote são processados posteriormente pelo serviço de agregação e um relatório de resumo é gerado.

Os dados fluem do cliente para o coletor e, em seguida, para a agregação
Serviço para gerar um relatório de resumo.

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

O fluxo de trabalho descrito nesta seção é semelhante ao Relatório de atribuição API. No entanto, a Atribuição Os relatórios associam dados coletados de um evento de impressão e uma conversão que ocorrem em momentos diferentes. A agregação particular mede um único evento entre sites.

Chave de agregação

Uma chave de agregação (abreviada como "chave") representa o bucket em que o os valores agregáveis serão acumulados. Uma ou mais dimensões podem ser codificadas na chave. Uma dimensão representa um aspecto que você quer ganhar mais informações, como a idade dos usuários ou a contagem de impressões de um anúncio campanha.

Por exemplo, você pode ter um widget incorporado em vários sites e quer analisar o país dos usuários que viram seu widget. Você está procurando para responder a perguntas como "Quantos dos usuários que viram meu widget estão do país X?" Para gerar relatórios 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 é uma 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 cada país é mapeado para um número em ordem alfabética como Afeganistão é 1, França é 61 e Zimbábue é '195'. Portanto, a chave agregável teria sete dígitos, em que os primeiros quatro são reservados para o WidgetID e os últimos três caracteres são reservado para CountryID.

Digamos que a chave represente a contagem de usuários da França (ID de país 061) que viram o ID de widget 3276, a chave de agregação será 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} podem ser criptografados com hash e convertidos em um Valor BigInt de 42943797454801331377966796057547478208888578253058197330928948081739249096287n Se o valor de hash tiver mais de 128 bits, é possível truncar para garantir que não haja exceder o valor máximo permitido de bucket de 2^128−1.

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

O exemplo a seguir descreve como gerar uma chave de bucket a partir de uma :

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

Valor agregável

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

Agora, volte ao exemplo de pergunta feita anteriormente: "Quantos dos usuários "Quem viu meu widget veio da França?". A resposta para essa pergunta será algo como "Aproximadamente 4.881 usuários que viram meu ID de widget 3276 estã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 dessa 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

Para este 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 sinal-ruído proporção.

Orçamento de contribuição

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

Quando você somar 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 é delimitado por worker origin, por dia, e separado para a API Protected Audience e os worklets do Armazenamento compartilhado. Um rolo de aproximadamente as últimas 24 horas é usada para o dia. Se uma nova agregável fizer com que o orçamento seja excedido, o relatório não será criados.

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). Consulte 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. Você pode usar esse orçamento para maximizar a relação sinal-ruído nos valores de resumo Isso é discutido em mais detalhes na seção Ruído e escalonamento.

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

Relatórios agregáveis

Quando o usuário invoca a API Private Aggregate, o navegador gera relatórios agregáveis a serem processados pelo serviço de agregação em um momento posterior a tempo de gerar o resumo . Um relatório agregável está no formato JSON e contém uma lista criptografada de contribuições, cada uma sendo um par de {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 de criptografia para o navegador e a chave de descriptografia para a agregação O serviço é emitido pelo coordenador, que atua como o serviço de gerenciamento de chaves. O coordenador mantém uma lista de hashes binários da imagem do serviço para verificar que o autor da chamada tem permissão para receber a chave de descriptografia.

Um exemplo de relatório agregável com debug modo 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 no Página do chrome://private-aggregation-internals:

captura de tela da página interna da API Private Aggregate

Para fins de teste, a opção "Enviar relatórios selecionados" pode ser usado para enviar se comunicar ao servidor imediatamente.

Coletar e agrupar relatórios agregáveis em lote

O navegador envia os relatórios agregáveis para a origem do worklet. que contém a chamada para a API Private Aggregate usando as APIs conhecidas listadas caminho:

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ê precisará operar um servidor, agindo 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 a agregação. Serviço. Criar lotes com base nas informações disponíveis nos payload do relatório agregável, como o campo shared_info. Idealmente, os lotes devem conter 100 ou mais relatórios por lote.

É possível agrupar os dados em lotes diários ou semanais. Essa estratégia é flexível, e você pode mudar a estratégia de lotes para eventos específicos mais volume, por exemplo, dias do ano em que são esperadas mais impressões. Os lotes devem incluir relatórios da mesma versão da API, origem de relatórios e programar o horário do relatório.

Serviço de agregação

O serviço é executado em um TEE, descriptografa os relatórios agregáveis e adiciona
para criar o relatório de resumo final.

O serviço de agregação recebe relatórios agregáveis criptografados do coletor e gera relatórios e detecção de ameaças.

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 fornece um nível de garantia para a integridade e a confidencialidade dos dados, e integridade do código. Embora você seja o proprietário e opere o serviço, você não terá visibilidade dos dados processados no TEE.

Relatórios de resumo

Relatórios de resumo permitem que você veja os dados que coletou com adição de ruído. Você pode 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 contém:

bucket: a chave de agregação como uma string de números binários. Se o chave de agregação usada é "123", o bucket é "1111011".
value: o valor de 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ídos uma vez em cada valor de resumo sempre que um relatório de resumo for solicitado. Os valores de ruído são retirados aleatoriamente de uma probabilidade de Laplace e distribuição. Enquanto estiver não está no controle direto das formas como o ruído é adicionado, você pode influenciar o impacto de ruído nos dados de medição.

A distribuição de ruído é a mesma, independentemente da soma de todos os valores agregáveis e a distribuição dos valores dos dados. Portanto, quanto maiores os valores agregáveis, menor é o impacto no ruído provavelmente terá.

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

Multiplicar o valor agregável por um fator de escalonamento pode ajudar e reduzir o ruído. O fator de escalonamento representa o quanto você quer escalonar em um determinado o valor agregável.

O ruído é constante, independentemente do valor agregado.

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

Ajuste o valor agregável ao orçamento de contribuição.

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

Veja o Orçamento de contribuição documentação para saber mais.

Interaja e compartilhe feedback

A API Private Aggregate está em discussão e sujeita a mudanças em no futuro. Se você testar essa API e tiver algum feedback, conte para nós.

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