Visão geral da API Private Aggregate

Gerar relatórios de dados agregados usando dados de público protegido e dados entre sites do Shared Storage.

Para oferecer recursos essenciais que a Web usa, a API Private Aggregation foi criada para agregar e gerar relatórios sobre dados em sites de uma forma que preserva a privacidade.

Status da implementação

O que é a API Private Aggregation

A API Private Aggregation permite que os desenvolvedores gerem relatórios de dados agregados com dados da API Protected Audience e dados entre sites do Armazenamento compartilhado.

A função principal dessa API é conhecida como contributeToHistogram(). A operação de histograma permite agregar dados de usuários em cada bucket (conhecido na API como uma chave de agregação) que você define. Sua chamada de histograma acumula valores e retorna um resultado agregado com ruídos na forma de um relatório resumido. Por exemplo, o relatório pode mostrar o número de sites em que cada usuário viu seu conteúdo ou encontrar um bug no script de terceiros. Essa operação é realizada em um worklet de outra API.

Por exemplo, se você já tiver registrado dados demográficos e geográficos no Shared Storage, poderá usar a API Private Aggregation para criar um histograma que informa aproximadamente quantos usuários em Nova York acessaram seu conteúdo em vários sites. Para agregar essa medição, você pode codificar a dimensão de geografia na chave de agregação e contar os usuários no valor agregável.

Principais conceitos

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 agregáveis são enviados ao seu servidor para coleta e agrupamento. Os relatórios em lote são processados mais tarde pelo serviço de agregação, e um relatório de resumo é gerado.

Consulte o documento Noções básicas da API Private Aggregation para saber mais sobre os principais conceitos envolvidos na API Private Aggregation.

Diferenças em relação ao Relatório de atribuição

A API Private Aggregation tem muitas semelhanças com a API Attribution Reporting. A API Attribution Reporting é independente e foi projetada para medir conversões. Já a API Private Aggregation foi criada para medições em vários sites em conjunto com APIs como a API Protected Audience e o Shared Storage. Ambas as APIs produzem relatórios agregáveis que são consumidos pelo back-end do serviço de agregação para gerar relatórios de resumo.

Os Relatórios de atribuição associam dados coletados de um evento de impressão e um evento de conversão, que ocorrem em momentos diferentes. A agregação particular mede um único evento entre sites.

Testar esta API

Para testar a API Private Aggregation localmente, ative todas as APIs de privacidade de anúncios em chrome://settings/adPrivacy.

Leia mais sobre os testes em experimentar e participar.

Usar a demonstração

A demonstração da API Private Aggregation para armazenamento compartilhado pode ser acessada em goo.gle/shared-storage-demo, e o código está disponível no GitHub. A demonstração implementa as operações do lado do cliente e produz um relatório agregável que é enviado ao servidor.

Uma demonstração da API Private Aggregation para a API Protected Audience será publicada no futuro.

Casos de uso

A agregação particular é uma API de uso geral para medição entre sites e está disponível para uso em worklets da API Shared Storage e da API Protected Audience. A primeira etapa é decidir especificamente quais informações você quer coletar. Esses pontos de dados são a base das chaves de agregação.

Com armazenamento compartilhado

O Armazenamento compartilhado permite ler e gravar dados entre sites em um ambiente seguro para evitar vazamentos. Já a API Private Aggregation permite medir dados entre sites armazenados no Armazenamento compartilhado.

Medição do alcance único

Você pode medir quantos usuários únicos acessaram o conteúdo. A API Private Aggregation pode fornecer uma resposta como "Aproximadamente 317 usuários únicos acessaram o ID de conteúdo 861".

É possível definir uma flag no Shared Storage para indicar se o usuário já acessou o conteúdo ou não. Na primeira visita em que a sinalização não existe, uma chamada para a agregação particular é feita e, em seguida, a flag é definida. Nas visitas subsequentes do usuário, incluindo visitas entre sites, você pode verificar o armazenamento compartilhado e pular o envio de um relatório para a agregação privada se a flag estiver definida. Para saber mais sobre os métodos para implementar essas medições, consulte nosso whitepaper sobre alcance.

Medição de informações demográficas

Você pode medir as informações demográficas dos usuários que acessaram seu conteúdo em diferentes sites.

A agregação particular pode fornecer uma resposta, como "Aproximadamente 317 usuários únicos têm entre 18 e 45 anos e estão na Alemanha". Use o armazenamento compartilhado para acessar dados demográficos de um contexto de terceiros. Mais tarde, você pode gerar um relatório com a agregação particular codificando as dimensões de grupo de idade e país na chave de agregação.

Medição de frequência de K+

Você pode medir o número de usuários que visualizaram um conteúdo ou anúncio pelo menos K vezes em um determinado navegador, para um valor de K pré-escolhido.

A agregação privada pode fornecer uma resposta como "Aproximadamente 89 usuários visualizaram o ID de conteúdo 581 pelo menos três vezes". Um contador pode ser incrementado no Shared Storage de sites diferentes e lido em um worklet. Quando a contagem chegar a K, um relatório poderá ser enviado usando a agregação privada.

Atribuição multitoque

Essas orientações serão publicadas no site para desenvolvedores para que as adtechs entendam como implementar a MTA na combinação de armazenamento compartilhado e agregação privada.

Com a API Protected Audience

A API Protected Audience permite casos de uso de retargeting e público-alvo personalizado, e a agregação particular permite que você informe eventos de worklets de compradores e vendedores. A API pode ser usada para tarefas como medir a distribuição de lances de leilão.

Em um worklet da API Protected Audience, é possível agregar seus dados diretamente usando contributeToHistogram() e informar os dados com base em um acionador usando contributeToHistogramOnEvent(), que é uma extensão especial para a API Protected Audience.

Funções disponíveis

As funções a seguir estão disponíveis no objeto privateAggregation disponível nos worklets da API Shared Storage e Protected Audience.

contributeToHistogram()

É possível chamar privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), em que a chave de agregação é bucket e o valor agregável é value. Para o parâmetro bucket, é necessário um BigInt. Para o parâmetro value, é necessário um número inteiro.

Confira um exemplo de como ele pode ser chamado no Armazenamento compartilhado para a medição de alcance:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', {
  data: { contentId: '1234' }
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Don't send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId),
      value: 1 * SCALE_FACTOR
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

O exemplo de código anterior vai chamar a agregação particular sempre que o conteúdo do iframe entre sites for carregado. O código do iframe carrega o worklet, que chama a API Private Aggregation com o ID de conteúdo convertido em uma chave de agregação (bucket).

contributeToHistogramOnEvent()

Somente nos worklets da API Protected Audience, fornecemos um mecanismo baseado em gatilho para enviar um relatório somente se um determinado evento ocorrer. Essa função também permite que o bucket e o valor dependam de indicadores que ainda não estão disponíveis nesse ponto do leilão.

O método privateAggregation.contributeToHistogramOnEvent(eventType, contribution) recebe um eventType que especifica o evento de acionamento e o contribution a ser enviado quando o evento for acionado. O evento acionador pode vir do próprio leilão após o término dele, como um evento de vitória ou derrota, ou pode vir de um frame restrito que renderizou o anúncio.

Para enviar um relatório de eventos de leilão, use duas palavras-chave reservadas: reserved.win, reserved.loss e reserved.always. Para enviar um relatório acionado por um evento de um período restrito, defina um tipo de evento personalizado. Para acionar o evento de uma moldura delimitada, use o método fence.reportEvent() disponível na API Fenced Frames Ads Reporting.

O exemplo a seguir envia um relatório de impressão quando o evento de vitória no leilão é acionado e um relatório de clique se um evento click é acionado pelo frame protegido que renderizou o anúncio. Esses dois valores podem ser usados para calcular a taxa de cliques.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Consulte o explicador sobre relatórios de agregação privada estendida para saber mais.

enableDebugMode()

Enquanto os cookies de terceiros ainda estiverem disponíveis, vamos oferecer um mecanismo temporário que facilita a depuração e os testes, ativando o modo de depuração. Um relatório de depuração é útil para comparar suas medições baseadas em cookies com as medições da agregação privada e também permite validar rapidamente a integração da API.

Chamar privateAggregation.enableDebugMode() no worklet ativa o modo de depuração, que faz com que os relatórios agregáveis incluam o payload não criptografado (texto simples). Em seguida, processe esses payloads com a ferramenta de teste local do serviço de agregação.

O modo de depuração só está disponível para autores de chamada com permissão para acessar cookies de terceiros. Se o autor da chamada não tiver acesso a cookies de terceiros, o enableDebugMode() vai falhar silenciosamente.

Também é possível definir a chave de depuração chamando privateAggregation.enableDebugMode({ <debugKey: debugKey> }), em que um BigInt pode ser usado como uma chave de depuração. A chave de depuração pode ser usada para associar dados de uma medição baseada em cookies e dados da medição de agregação privada.

Eles só podem ser chamados uma vez por contexto. Todas as chamadas subsequentes vão gerar uma exceção.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Verificação do relatório

A API Private Aggregation permite a medição em vários sites, protegendo a privacidade do usuário. No entanto, usuários de má-fé podem tentar manipular a precisão dessas medições. Para evitar isso, use um ID de contexto para verificar a autenticidade dos relatórios.

A definição de um ID de contexto ajuda a garantir que os dados sejam precisos ao contribuir para os resultados agregados finais. Para isso, faça o seguinte:

• Evitar relatórios ilegais ou não autênticos:garanta que os relatórios sejam gerados por chamadas de API legítimas e autênticas, dificultando a falsificação de relatórios por atores mal-intencionados.
• Impedir a reprodução de relatórios:detecte e rejeite qualquer tentativa de reutilizar relatórios antigos, garantindo que cada relatório seja enviado apenas uma vez aos resultados agregados.

Armazenamento compartilhado

Ao usar o Shared Storage para executar uma operação que pode enviar um relatório agregável, é possível definir um ID imprevisível fora do worklet.

Esse ID é incorporado ao relatório criado com o worklet. É possível especificar ao chamar os métodos de armazenamento compartilhado run() ou selectURL(), no objeto de opções, na chave privateAggregationConfig.

Exemplo:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Depois que esse ID for definido, ele poderá ser usado para verificar se o relatório foi enviado da sua operação de armazenamento compartilhado. Para evitar o vazamento de informações, exatamente um relatório é enviado por operação de armazenamento compartilhado, mesmo que nenhuma contribuição seja feita, independente do número de chamadas contributeToHistogram().

A API Private Aggregation envia relatórios agregáveis com um atraso aleatório de até uma hora. No entanto, definir um ID de contexto para verificar um relatório reduz esse atraso. Nesse caso, há um atraso fixo menor de 5 segundos desde o início da operação de armazenamento compartilhado.

Um exemplo de fluxo de trabalho (como mostrado no diagrama acima):

1. A operação de armazenamento compartilhado é executada com uma configuração de agregação privada especificando um ID de contexto, e um relatório agregável é gerado.
2. O ID de contexto é incorporado ao relatório agregável gerado e enviado ao seu servidor.
3. Seu servidor coleta os relatórios agregáveis gerados.
4. Os processos no servidor verificam o ID de contexto em cada relatório agregável com os IDs de contexto armazenados para garantir a validade antes de agrupar os relatórios e enviá-los ao serviço de agregação.

Verificação de ID do contexto

Os relatórios recebidos no servidor do coletor podem ser verificados de várias maneiras antes de serem enviados ao serviço de agregação. Os relatórios com IDs de contexto inválidos podem ser rejeitados quando o ID de contexto é:

• Desconhecido:se um relatório chegar com um ID de contexto que seu sistema não criou, ele poderá ser descartado. Isso impede que agentes desconhecidos ou mal-intencionados injetem dados no pipeline de agregação.
• Uma cópia:se você receber dois ou mais relatórios com o mesmo ID de contexto, será necessário escolher qual deles descartar.
• Sinalizado na detecção de spam:
  • Se você detectar uma atividade suspeita de um usuário, por exemplo, uma mudança repentina na atividade dele, enquanto processa o relatório, você pode descartá-lo.
  • É possível armazenar relatórios com os IDs de contexto e todos os indicadores relevantes, como user agent, origem de referência etc. Mais tarde, ao analisar o comportamento do usuário e identificar novos indicadores de spam, você pode reavaliar os relatórios armazenados com base nos IDs de contexto e nos indicadores associados. Isso permite que você descarte relatórios de usuários que mostram atividade suspeita, mesmo que eles não tenham sido sinalizados inicialmente.

Engajamento e compartilhamento de feedback

A API Private Aggregation está em discussão ativa e sujeita a mudanças no futuro. Se você testar essa API e tiver feedback, adoraríamos saber sua opinião.

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