Visão geral da API Private Aggregate

Gere relatórios de dados agregados usando dados da API Protected Audience e dados entre sites do armazenamento compartilhado.

Para oferecer os recursos essenciais da Web, a agregação privada A API foi criada para agregar e relatar dados entre sites em um de preservar a privacidade.

Status da implementação

Proposta Status
Evite relatórios inválidos da API Private Aggregate com a verificação de relatórios para o armazenamento compartilhado
Explicação		 Disponível no Chrome
A disponibilidade do modo de depuração da agregação particular depende da qualificação de terceiros
Problema no GitHub		 Disponível no Chrome M119
Como reduzir o atraso no envio de relatórios
Explicação		 Disponível no Chrome M119
Suporte à API Private Aggregation e ao serviço de agregação para o Google Cloud
Explicação		 Disponível no Chrome M121
Padding para payloads de relatório agregáveis
Explicação		 Disponível no Chrome M119
Modo de depuração de agregação privada disponível para relatórios de auctionReportBuyers
Explicação		 Disponível no Chrome M123
Suporte a IDs de filtro
Explicação		 Disponível no Chrome M128
Mesclagem de contribuições do lado do cliente
Explicação		 Disponível no Chrome M129

O que é a API Private Aggregate

Com a API Private Aggregate, os desenvolvedores podem gerar 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 entre os usuários em cada bucket (conhecido na API como chave de agregação) que você definir. Sua chamada de histograma acumula valores e retorna um resultado agregado com ruído em 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 se deparou com um bug em seu script de terceiros. Essa operação é realizada no worklet de outra API.

Por exemplo, se você já registrou dados demográficos e geográficos no Armazenamento compartilhado, use a API Private Aggregate para criar um histograma que informe aproximadamente quantos usuários na cidade de Nova York acessaram seu conteúdo entre 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 Aggregate com uma chave 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 depois pelo serviço de agregação, e um relatório de resumo é gerado.

Consulte o documento Princípios básicos da API Private Aggregate para saber mais sobre os principais conceitos envolvidos.

Diferenças da API Attribution Reporting

A API Private Aggregate tem muitas semelhanças com a API Attribution Reporting. A API Attribution Reporting é uma API independente projetada para medir conversões, enquanto a agregação privada é criada para medições entre sites com APIs como a API Protected Audience e o armazenamento compartilhado. As duas 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 privada mede um único evento entre sites.

Testar esta API

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

Leia mais sobre os testes em experimentos e participação.

Usar a demonstração

A demonstração da API Private Aggregate para armazenamento compartilhado pode ser acessada em goo.gle/shared-storage-demo. 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 seu servidor.

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

Casos de uso

A agregação particular é uma API de uso geral na medição entre sites que está disponível para uso em worklets do Armazenamento compartilhado 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. Com a API Private Aggregate, é possível medir os dados entre sites armazenados no armazenamento compartilhado.

Medição do alcance único

Você pode querer medir quantos usuários únicos viram o conteúdo. A API Private Aggregate pode fornecer uma resposta como "Aproximadamente 317 usuários únicos viram o Content ID 861".

É possível definir uma sinalização no armazenamento compartilhado para indicar se o usuário já viu o conteúdo ou não. Na primeira visita em que a sinalização não existe, é feita uma chamada para a agregação privada e, em seguida, a sinalização é definida. Nas próximas visitas 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 sinalização estiver definida. Para saber mais sobre os métodos de implementação dessas medições, confira nosso artigo de alcance.

Medição demográfica

Talvez você queira medir as informações demográficas dos usuários que viram 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 são da 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 privada 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 particular pode fornecer uma resposta como "Aproximadamente 89 usuários viram o Content ID 581 pelo menos três vezes". Um contador pode ser incrementado no Armazenamento compartilhado de diferentes sites e pode ser lido em um worklet. Quando a contagem atingir K, um relatório poderá ser enviado pela agregação privada.

Atribuição multitoque

Essa orientação será publicada no site para desenvolvedores para que as adtechs possam entender como implementar o MTA no armazenamento compartilhado + agregação privada.

Com a API Protected Audience

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

Com um worklet da API Protected Audience, é possível agregar seus dados diretamente usando contributeToHistogram() e gerar relatórios com base em um acionador usando contributeToHistogramOnEvent(), que é uma extensão especial da API.

Funções disponíveis

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

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.

Veja um exemplo de como ele pode ser chamado no armazenamento compartilhado para 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';

    // Do not 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 acima vai chamar a agregação privada sempre que o conteúdo de iframe entre sites for carregado. O código do iframe carrega o worklet, que chama a API Private Aggregate com o ID do conteúdo convertido em uma chave de agregação (bucket).

contributeToHistogramOnEvent()

Somente nas 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 naquele ponto do leilão.

O método privateAggregation.contributeToHistogramOnEvent(eventType, contribution) usa um eventType que especifica o evento de acionamento e o contribution a ser enviado quando o evento é 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 dele, ou pode vir de um frame isolado 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 frame isolado, defina um tipo de evento personalizado. Para acionar o evento de um frame isolado, 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 a explicação sobre os relatórios de agregação privada estendida para saber mais.

enableDebugMode()

Embora os cookies de terceiros ainda estejam disponíveis, forneceremos 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 as medições baseadas em cookies com as de agregação privada. Além disso, ele 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 não criptografado). Em seguida, processe esses payloads com a ferramenta de teste local do serviço de agregação.

O modo de depuração está disponível apenas para autores de chamadas com permissão para acessar cookies de terceiros. Se o autor da chamada não tiver acesso a cookies de terceiros, O enableDebugMode() falhará silenciosamente. Isso significa que, quando terceiros cookies forem descontinuados, o modo de depuração não estará mais disponível.

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

Eles só podem ser chamados uma vez por contexto. Qualquer chamada subsequente gerará uma exceção.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Verificação de denúncias

No caso do armazenamento compartilhado, é possível verificar se os relatórios agregáveis que você recebeu são legítimos, adicionando um ID de contexto à chamada de operação de armazenamento compartilhado. O ID será anexado ao relatório enviado e, posteriormente, você poderá usá-lo para verificar se ele foi enviado da operação de armazenamento compartilhado.

Para saber mais, consulte a explicação sobre a verificação de relatórios.

Interaja e compartilhe feedback

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