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 usuário de relatórios de resumo, entender esses mecanismos vai ajudar você a tomar decisões de design para extrair um relatório de resumo otimizado.

Termos-chave

Antes de ler este documento, 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 uma coleção predeterminada de pontos de dados. Por exemplo, você pode 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 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 a API Private Aggregation, ela 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 de usuários agregados com ruídos 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 um worklet, você pode executar JavaScript, mas não pode interagir ou se comunicar com a página externa.

Fluxo de trabalho da agregação particular

Quando você chama a API Private Aggregation 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 Aggregation, o cliente (navegador) gera e envia o relatório agregável para o servidor ser coletado.
Seu servidor coleta os relatórios dos clientes e os agrupa para serem 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 à API Attribution Reporting. No entanto, os Relatórios de atribuição associam dados coletados de um evento de impressão e um evento de conversão, que acontecem 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 sobre o qual você quer ter mais informações, como a faixa etária dos usuários ou a contagem de impressões de uma campanha publicitária.

Por exemplo, você pode ter um widget incorporado em vários sites e querer analisar o país dos usuários que visualizaram o widget. Você quer responder a perguntas como "Quantos dos usuários que viram meu widget sã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 Aggregation é 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 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 quatro primeiros caracteres são reservados para WidgetID e os três últimos são reservados 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() no MDN.

O exemplo a seguir descreve como gerar uma chave de bucket a partir de um valor em 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

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 são da França?". A resposta para essa pergunta vai ser algo como "Aproximadamente 4881 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 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 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 é 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 um novo relatório agregável ultrapassar o orçamento, ele não será criado.

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

(1.048.576). Consulte o texto explicativo 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.

Limite de contribuição por relatório

Dependendo do autor da chamada, o limite de contribuição pode variar. No momento, os relatórios gerados para os autores de chamada da API Shared Storage têm um limite de 20 contribuições por relatório. Por outro lado, os autores de chamadas da API Protected Audience têm um limite de 100 contribuições por relatório. Esses limites foram escolhidos para equilibrar o número de contribuições que podem ser incorporados ao tamanho do payload.

Para o armazenamento compartilhado, as contribuições feitas em uma única operação run() ou selectURL() são agrupadas em um relatório. Para a API Protected Audience, as contribuições feitas por uma única origem em um leilão são agrupados.

Contribuições com padding

As contribuições são modificadas com um recurso de preenchimento. O ato de fazer o padding payload protege informações sobre o verdadeiro número de contribuições incorporadas em no relatório agregável. O padding aumenta o payload com contribuições de null. (ou seja, com valor 0) para atingir um comprimento fixo.

Relatórios agregáveis

Quando o usuário invoca a API Private Aggregation, o navegador gera relatórios agregáveis para serem processados pelo serviço de agregação em um momento posterior para gerar relatórios de 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. O 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 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 no Página do chrome://private-aggregation-internals:

captura de tela da página de elementos internos da API Private Aggregation

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 Aggregation, usando o caminho conhecido listado:

Para armazenamento compartilhado: /.well-known/private-aggregation/report-shared-storage
Para o público-alvo protegido: /.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. 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 cada.

É 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
ruído 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 oferece um nível de garantia de integridade de dados, confidencialidade de dados e integridade do código. Embora você seja o proprietário e operador do serviço, não terá acesso aos dados processados no TEE.

Relatórios de resumo

Os relatórios de resumo mostram os dados coletados com a adição de ruído. É 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 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ído uma vez a cada valor de resumo sempre que um relatório de resumo é solicitado. Os valores de ruído são retirados aleatoriamente de uma probabilidade de Laplace e distribuição. Embora você não tenha controle direto sobre as maneiras como o ruído é adicionado, é possível influenciar o impacto do ruído nos dados de medição.

A distribuição de ruído é a mesma, independentemente da soma de todos os valores agregáveis valores. Portanto, quanto maiores os valores agregáveis, menor será o impacto 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 apenas 200, a variação padrão do ruído será de 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. Portanto, 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 um determinado valor agregável.

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

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

Dimensione o valor agregável para o orçamento de contribuição.

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

Consulte a documentação do orçamento de contribuiçã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 para desenvolvedores: faça perguntas e participe de discussões no repositório de suporte para desenvolvedores do Sandbox de privacidade. * Participe da API Shared Storage grupo e a API Protected Audience grupo para conferir os anúncios mais recentes relacionados à agregação particular.