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 oviewCount
de1
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.
![Os dados fluem do cliente para o coletor e, em seguida, para o serviço de agregação para gerar um relatório de resumo.](https://developers.google.cn/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=8&hl=pt)
- Quando você chama a API Private Aggregate, o cliente (navegador) gera e envia o relatório agregável ao seu servidor para ser coletado.
- Seu servidor coleta os relatórios dos clientes e os agrupa para ser enviado ao serviço de agregação.
- 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.
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 |
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
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 L1 e é definido como 216 (65.536) por 10 minutos por dia com um backstop de 220
(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
:
![captura de tela da página de aspectos internos da API Private agregação](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=8&hl=pt)
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 é executado em um TEE, descriptografa os relatórios agregáveis e adiciona
ruído para criar o relatório de resumo final.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=8&hl=pt)
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.
![O ruído é constante, independentemente do valor agregado.](https://developers.google.cn/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=8&hl=pt)
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.
![Ajustar o valor agregável para o orçamento de contribuição.](https://developers.google.cn/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=8&hl=pt)
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.