Gere relatórios de dados agregados usando informações da API Protected Audience e entre sites do armazenamento compartilhado.
Para fornecer recursos essenciais de que a Web depende, a API Private agregação foi criada para agregar e gerar relatórios sobre dados entre sites de uma maneira que preserva a privacidade.
Status da implementação
| Proposta | Status |
|---|---|
| Evitar relatórios inválidos da API Private Aggregate com a verificação de relatórios do armazenamento compartilhado Explainer |
Disponível no Chrome |
| A disponibilidade do modo de depuração da agregação particular depende da qualificação para 3PCs Problema no GitHub |
Disponível no Chrome M119 |
| Redução do atraso no relatório Explicação |
Disponível no Chrome M119 |
| Suporte para a API Private Aggregate e o serviço de agregação do Google Cloud Explainer |
Disponível no Chrome M121 |
| Padding para payloads de relatórios agregáveis Explicação |
Disponível no Chrome M119 |
| O modo de depuração da agregação particular está disponível para os relatórios leilãoReportBuyers Explainer |
Estimado no Chrome M123 |
| Suporte ao ID de filtragem Explicação |
O lançamento inicial está previsto para o Chrome no segundo trimestre de 2024. |
O que é a API Private Aggregate
A API Private Aggregate permite que os desenvolvedores gerem relatórios de dados agregados com dados da API Protected Audience e dados entre sites do Armazenamento compartilhado.
No momento, essa API fornece uma operação, sendHistogramReport(), mas outras podem receber
suporte no futuro. A operação de histograma permite agregar dados dos usuários em cada bucket (conhecido na API como chave de agregação) que você define.
Sua chamada de histograma acumula valores e retorna um resultado agregado com ruído na forma de um relatório de resumo. 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 seu script de terceiros. Esta operação é realizada dentro do worklet de outra API.
Por exemplo, se você já registrou dados demográficos e geográficos no Armazenamento compartilhado, é possível usar a API Private Aggregate para criar um histograma que informa aproximadamente quantos usuários em Nova York viram seu conteúdo entre sites. Para agregar essa medição, codifique a dimensão geográfica na chave de agregação e conte os usuários no valor agregável.
Principais conceitos
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 agregáveis são enviados ao seu servidor para coleta e lote. Os relatórios em lote são processados depois pelo Serviço de agregação, e um relatório resumido é gerado.
Consulte o documento Princípios básicos da API Private Aggregate para saber mais sobre os principais conceitos envolvidos nessa API.
Diferenças do Attribution Reporting
A API Private Aggregate tem muitas semelhanças com a API Attribution Reporting. A API Attribution Reporting é independente e foi projetada para medir conversões, enquanto a agregação privada é criada para medições entre sites em conjunto 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.
A API Attribution Reporting associa dados coletados de um evento de impressão e de conversão, que acontecem em momentos diferentes. A agregação particular mede um único evento entre sites.
Testar esta API
A API Private Aggregate pode ser testada localmente ativando
a flag do experimento das APIs do Sandbox de privacidade em
chrome://flags/#privacy-sandbox-ads-apis.
Leia mais sobre os testes e participe.
Usar a demonstração
Acesse a demonstração da API Private agregação para armazenamento compartilhado 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 em breve.
Casos de uso
A agregação privada é uma API de uso geral para medição entre sites e está disponível para uso nos workers do Armazenamento compartilhado e da API Protected Audience. A primeira etapa é decidir especificamente quais informações você deseja coletar. Esses pontos de dados são a base das suas chaves de agregação.
Com armazenamento compartilhado
O Armazenamento compartilhado permite ler e gravar dados entre sites em um ambiente seguro para evitar vazamentos, e a API Private Aggregate permite medir dados entre sites armazenados no armazenamento compartilhado.
Medição do Unique Reach
Convém medir quantos usuários únicos viram o conteúdo. A API Private agregação pode dar uma resposta como "Aproximadamente 317 usuários únicos viram o Content ID 861".
Você pode definir um flag no armazenamento compartilhado para indicar se o usuário já viu o conteúdo ou não. Na primeira visita em que a flag não existe, é feita uma chamada para a agregação particular e, em seguida, a flag é definida. Nas visitas subsequentes do usuário, incluindo visitas entre sites, será possível marcar "Armazenamento compartilhado" e pular o envio de um relatório para a agregação particular se a flag estiver definida.
Medição de informações demográficas
É recomendável medir as informações demográficas dos usuários que visualizaram seu conteúdo em sites diferentes.
A agregação particular pode dar 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 em um contexto de terceiros. Em um momento posterior, você poderá gerar um relatório com a agregação privada codificando as dimensões de idade e país na chave de agregação.
Medição de frequência K+
Você pode querer medir o número de usuários que visualizaram um conteúdo ou um anúncio pelo menos K vezes em um determinado navegador, para um valor pré-escolhido de K.
A agregação privada pode dar 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 uma worklet. Quando a contagem atingir K, um relatório poderá ser enviado pela agregação privada.
Com a API Protected Audience
A API Protected Audience permite uma nova segmentação e casos de uso de públicos-alvo personalizados, e a agregação privada permite relatar eventos dos worklets do comprador e do vendedor. 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 dados diretamente usando sendHistogramReport() e informar os dados com base em um gatilho usando reportContributionForEvent(), que é uma extensão especial da API Protected Audience.
Funções disponíveis
As seguintes funções estão disponíveis no objeto privateAggregation disponível nos workers do Shared Storage e da API Protected Audience.
contributeToHistogram()
Você pode chamar privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), em que a chave de agregação é bucket e o valor agregável como 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 isso pode ser chamado no armazenamento compartilhado para medição do 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 this.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 this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
O exemplo de código acima chamará a agregação particular sempre que o conteúdo de iframe entre sites for carregado. O código do iframe carrega a worklet, que chama a API Private Aggregate com o ID do conteúdo convertido em uma chave de agregação (bucket).
contributeToHistogramOnEvent()
Somente nos worklets da API Protected Audience, oferecemos 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 momento do leilão.
O método privateAggregation.reportContributionForEvent(eventType, contribution) usa um eventType que especifica o evento de gatilho 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, ou de um frame isolado que renderizou o anúncio.
Para enviar um relatório sobre eventos de leilão, é possível usar 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 de leilão é acionado. Ele também envia um relatório de clique se um evento click for acionado no frame isolado 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
});
Saiba mais na explicação sobre os relatórios de agregação privada estendida.
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 da agregação particular. Ele também permite validar rapidamente a integração da API.
Chamar privateAggregation.enableDebugMode() no worklet ativa o modo de depuração, o que faz com que os relatórios agregáveis incluam o payload não criptografado (texto não criptografado). Você pode processar 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() vai falhar silenciosamente. Isso significa que, quando cookies de terceiros forem descontinuados, o modo de depuração não vai 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 baseada em cookies e da medição de agregação privada. Eles só podem ser chamados uma vez por contexto. Todas as chamadas subsequentes serão ignoradas.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Denunciar verificação
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á usar esse ID para verificar se o relatório foi enviado da operação de armazenamento compartilhado.
O recurso está disponível para testes no Chrome M114 e versões mais recentes. A verificação de relatórios da API Protected Audience ainda não está disponível para testes.
Para saber mais, consulte a explicação sobre a verificação de denúncia.
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 de discussões.
- 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 saber as novidades sobre a agregação particular.