Serviço de agregação

O serviço de agregação gera relatórios de resumo com dados detalhados de conversão e medições de alcance de relatórios agregáveis brutos. Como adtech, você pode usar a API Attribution Reporting e a API Private Aggregation, os dois principais pontos de entrada de agregação do lado do cliente, para direcionar relatórios ao serviço de agregação e receber um relatório de resumo em resposta.

Nesta página, presumimos que você tenha experiência em adtech. Ela abrange:

• Status da implementação
• Principais termos e conceitos
• Casos de uso de agregação
• Fluxo completo
• Agrupamento de relatórios agregáveis
• Componentes do Cloud

Status da implementação

• O Serviço de agregação agora está com disponibilidade geral.
• O serviço de agregação pode ser usado com a API Attribution Reporting e a API Private Aggregation para a API Protected Audience e a API Shared Storage.

Disponibilidade

Proposta	Status
Serviço de orçamento de privacidade entre nuvens Explicação	Disponível
Suporte do serviço de agregação para a Amazon Web Services (AWS) na API Attribution Reporting e na API Private Aggregation Explicação	Disponível
Suporte do serviço de agregação para o Google Cloud na API Attribution Reporting e na API Private Aggregation Explicação	Disponível
Inscrição no site do serviço de agregação e agregação de várias origens. A inscrição de site inclui o mapeamento de um site para contas de nuvem (AWS ou GCP). Para agregar várias origens, elas precisam ser do mesmo site. Perguntas frequentes no GitHub Documentação da API de agregação de sites	Disponível
O valor de epsilon do serviço de agregação será mantido como um intervalo de até 64 para facilitar a experimentação e o feedback em diferentes parâmetros. Envie feedback sobre a ARA epsilon. Enviar feedback sobre a PAA epsilon.	Disponível. Vamos avisar com antecedência ao ecossistema antes que os valores do intervalo de epsilon sejam atualizados.
Filtragem de contribuição mais flexível para consultas do serviço de agregação Explicação	Disponível
Processo de recuperação de orçamento após desastres (erros, configurações incorretas etc.) Explicação	Mecanismo disponível para analisar a porcentagem de IDs compartilhados recuperados por uma adtech usando a recuperação de orçamento e suspender recuperações futuras para recuperações excessivas planejadas para o primeiro semestre de 2025
Accenture operando como um dos coordenadores na AWS Blog para desenvolvedores	Disponível
Parte independente que atua como um dos coordenadores no Google Cloud Blog para desenvolvedores	Disponível
Suporte do serviço de agregação para relatórios de depuração agregados na API Attribution Reporting Explicação	Disponível

Principais termos e conceitos

Se você está considerando o serviço de agregação para seu fluxo de trabalho, os termos e conceitos a seguir podem dar insights sobre o que esse novo fluxo de agregação pode oferecer à sua equipe.

Glossário de termos

Relatórios agregáveis

Os relatórios criptografados são enviados de dispositivos de usuários individuais. Esses relatórios contêm dados sobre o comportamento do usuário entre sites e as conversões. As conversões (às vezes chamadas de eventos acionador de atribuição) e as métricas associadas são definidas pelo anunciante ou pela adtech. Cada relatório é criptografado para impedir que várias partes acessem os dados.

Saiba mais sobre os relatórios com agregação.

Contabilização de relatórios agregáveis

Um ledger distribuído, localizado nos dois coordenadores, que rastreia o orçamento de privacidade alocado e aplica a regra "Sem duplicações". Esse é o mecanismo de preservação da privacidade, localizado e executado em coordenadores, que garante que nenhum relatório passe pelo serviço de agregação além do orçamento de privacidade alocado.

Saiba mais sobre como as estratégias de lote se relacionam com os relatórios agregáveis.

Orçamento de contabilidade de relatórios agregáveis

Referências ao orçamento que garantem que os relatórios individuais não sejam processados mais de uma vez.

Serviço de agregação

Um serviço operado por adtech que processa relatórios agregáveis para criar um relatório de resumo.

Leia mais sobre o histórico do serviço de agregação em nosso texto explicativo e na lista completa de termos.

Declaração

Um mecanismo para autenticar a identidade do software, geralmente com hashes criptográficos ou assinaturas. Para a proposta de serviço de agregação, o atestado corresponde ao código executado no serviço de agregação operado pela adtech com o código de código aberto.

Leia mais sobre atestados.

Vinculação de contribuições

Coordenador

Entidades responsáveis pelo gerenciamento de chaves e pela contabilidade de relatórios agregáveis. Um coordenador mantém uma lista de hashes de configurações de serviço de agregação aprovadas e configura o acesso às chaves de descriptografia.

Ruído e escalonamento

Ruído estatístico adicionado aos relatórios de resumo durante o processo de agregação para preservar a privacidade e garantir que os relatórios finais forneçam informações de medição anônimas.

Leia mais sobre o mecanismo de ruído aditivo, que é extraído da distribuição de Laplace.

Origem da denúncia

A entidade que recebe relatórios agregáveis, ou seja, você ou uma adtech que chamou a API Attribution Reporting. Os relatórios agregáveis são enviados dos dispositivos dos usuários para um URL conhecido associado à origem do relatório. A origem do relatório é designada durante o registro.

ID compartilhado

Um valor computado que consiste em shared_info, reporting_origin, destination_site (somente para a API Attribution Reporting), source_registration-time (somente para a API Attribution Reporting), scheduled_report_time e versão.

Vários relatórios que compartilham os mesmos atributos no campo shared_info precisam ter o mesmo ID compartilhado. Os IDs compartilhados desempenham um papel importante na contabilização de relatórios agregáveis.

Saiba mais sobre servidores confiáveis.

Relatório de resumo

Um tipo de relatório da API Attribution Reporting e da API Private Aggregation. Um relatório de resumo inclui dados agregados do usuário e pode conter dados de conversão detalhados com ruído adicionado. Os relatórios de resumo são compostos por relatórios agregados. Eles permitem mais flexibilidade e oferecem um modelo de dados mais rico do que os relatórios no nível do evento, principalmente para alguns casos de uso, como valores de conversão.

Ambiente de execução confiável (TEE)

Uma configuração segura de hardware e software de computador que permite que partes externas verifiquem as versões exatas do software em execução na máquina sem medo de exposição. Os TEEs permitem que terceiros verifiquem se o software faz exatamente o que o fabricante afirma.

Para saber mais sobre os TEEs usados para as propostas do Sandbox de privacidade, leia a explicação dos serviços da API Protected Audience e a explicação do serviço de agregação.

Casos de uso de agregação

Considere as seguintes jornadas de desenvolvedores para a medição de anúncios e as bibliotecas de cliente de medição correspondentes.

Caso de uso	Ponto de entrada	Descrição
Otimização de lances	API Attribution Reporting (Chrome e Android)	Use relatórios agregados para importar indicadores de conversão para otimizar os lances.
Medição em várias plataformas	API Attribution Reporting (Chrome e Android)	Use os recursos de medição em vários apps e na Web para ter visibilidade da performance no Chrome e no Android.
Relatórios de conversão	API Attribution Reporting (Chrome e Android)	Crie relatórios de conversão agregados adaptados às necessidades da campanha dos clientes (incluindo CTCs e VTCs).
Medição do alcance da campanha	API Shared Storage e API Private Aggregation (Chrome)	Use variáveis de visualização de anúncios entre sites para medir o alcance da campanha.
Relatórios demográficos	API Shared Storage e API Private Aggregation (Chrome)	Use a visualização de anúncios entre sites e as informações demográficas para medir o alcance por demografia.
Análise do caminho de conversão	API Shared Storage e API Private Aggregation (Chrome)	Armazene as variáveis de visualização de anúncios entre sites e de conversão para realizar a análise agregada do caminho de conversão.
Brand Lift e Conversion Lift	API Shared Storage e API Private Aggregation (Chrome)	Relatórios sobre grupos de teste/controle e informações de pesquisa para medir o aumento da marca e a incrementabilidade.
Depuração de leilões	API Protected Audience e API Private Aggregation (Chrome)	Use relatórios agregados para depuração.
Distribuição de lances	API Protected Audience e API Private Aggregation (Chrome)	Use relatórios agregados para capturar a distribuição dos valores de lances para leilões.

Fluxo completo

O diagrama a seguir mostra o serviço de agregação em ação. Vamos nos concentrar no fluxo completo desde o momento em que os relatórios são recebidos de dispositivos móveis e da Web até a criação do relatório de resumo no serviço de agregação.

Fluxo de serviço de agregação de ponta a ponta

1. Buscar a chave pública para gerar relatórios criptografados.
2. Os relatórios agregáveis criptografados são enviados aos servidores de adtechs para coleta, transformação e agrupamento.
3. O servidor de adtech agrupa relatórios (no formato avro) e os envia para o serviço de agregação. (Você precisa concluir isso.)
4. Um worker de agregação recupera os relatórios agregados para descriptografar.
5. O worker de agregação recupera chaves de descriptografia de um coordenador.
6. O worker de agregação descriptografa os relatórios para agregação e geração de ruídos.
7. O serviço de contabilidade de relatórios agregáveis verifica se há orçamento de privacidade suficiente para gerar um relatório de resumo para os relatórios agregáveis fornecidos.
8. Envie um relatório de resumo final.

O diagrama mostra as relações de alto nível que o serviço de agregação tem com as principais APIs de medição de clientes: a API Attribution Reporting, a API Private Aggregation e os coordenadores.

O fluxo começa com as APIs Measurement, como a API Attribution Reporting ou a API Private Aggregation, que geram relatórios de várias instâncias do navegador. O Chrome recebe a chave pública do serviço de hospedagem de chaves no coordenador para criptografar os relatórios antes de enviá-los à origem de relatórios da adtech. As chaves públicas são alternadas a cada sete dias.

A origem de relatórios da adtech precisa ser configurada para coletar e converter os relatórios recebidos para o formato avro e enviá-los ao serviço de agregação, conforme descrito nas estratégias de lote.

Quando você tiver um lote pronto, envie uma solicitação em lote para o serviço de agregação. O serviço de agregação busca chaves de descriptografia do serviço de hospedagem de chaves, descriptografa os relatórios e os agrega e gera ruídos para criar um relatório de resumo. Isso depende de ter orçamento de privacidade suficiente para criá-los.

Você hospeda o endpoint de origem de relatórios da adtech, onde os relatórios são coletados, e o serviço de agregação é implantado na nuvem da adtech.

Relatórios agregáveis em lote

O fluxo de relatórios não seria concluído sem a ajuda do servidor de origem de relatórios designado. Essa é a origem que você teria enviado no processo de inscrição. A origem de relatórios é responsável por coletar, transformar e agrupar os relatórios agregados recebidos e prepará-los para envio ao serviço de agregação no Google Cloud ou na Amazon Web Services. Saiba como preparar seus relatórios agregáveis.

Agora que você já tem o conceito geral, podemos analisar melhor os componentes implantados no serviço de agregação.

Componentes do Cloud

O serviço de agregação consiste em vários componentes de serviço em nuvem. Você usa os scripts do Terraform fornecidos para provisionar e configurar todos os componentes necessários do serviço de nuvem.

Componentes de nuvem do serviço de agregação

Serviço de front-end

Serviço gerenciado do Cloud:Cloud Function (Google Cloud) / API Gateway (Amazon Web Services)

O serviço de front-end é um gateway sem servidor que é o ponto de entrada principal para chamadas da API Aggregation para criação e recuperação do estado de jobs. Ele é responsável por receber solicitações dos usuários do serviço de agregação, validar parâmetros de entrada e iniciar o processo de programação de jobs de agregação.

O serviço de front-end tem duas APIs disponíveis:

Endpoint	Descrição
createJob	Essa API aciona um job do serviço de agregação. Para acionar o job, são necessárias informações como ID do job, detalhes de armazenamento de entrada, detalhes de armazenamento de saída, origem do relatório e muito mais.
getJob	Essa API retorna o status do job com um ID especificado. Ele fornece informações sobre o estado do job, como "Recebido", "Em andamento" ou "Concluído". Se o job for concluído, ele também vai retornar o resultado, incluindo as mensagens de erro encontradas durante a execução.

Confira a documentação da API Aggregation Service.

Fila de jobs

Serviço de nuvem gerenciado:Pub/Sub (Google Cloud) / Amazon SQS (Amazon Web Services)

A fila de jobs é uma fila de mensagens que contém solicitações de jobs para o serviço de agregação. O serviço de front-end insere solicitações de trabalho na fila, que são consumidas por workers de agregação que as processam.

Cloud Storage

Serviço de nuvem gerenciado:Google Cloud Storage (Google Cloud) / Amazon S3 (Amazon Web Services)

Os arquivos de entrada e saída usados pelo serviço de agregação, como arquivos de relatório criptografados e relatórios de resumo de saída, são mantidos no armazenamento em nuvem.

Banco de dados de metadados do job

Serviço de nuvem gerenciado:Spanner (Google Cloud) / DynamoDB (Amazon Web Services)

O banco de dados de metadados de jobs é usado para armazenar e acompanhar o status dos jobs de agregação. Ele registra metadados, como hora da criação, hora da solicitação, hora da atualização e estado, como "Recebido", "Em andamento" ou "Concluído". Os workers de agregação atualizam o banco de dados de metadados de jobs conforme os jobs avançam.

Worker de agregação

Serviço de nuvem gerenciado:Compute Engine com espaço confidencial (Google Cloud) / Amazon Web Services EC2 com Nitro Enclave (Amazon Web Services).

Um worker de agregação processa as solicitações de job na fila de jobs e descriptografa as entradas criptografadas usando chaves extraídas do serviço de geração e distribuição de chaves (KGDS, na sigla em inglês) nos coordenadores. Para minimizar a latência de processamento de jobs, os workers de agregação armazenam em cache as chaves de descriptografia por um período de 8 horas e as usam nos jobs que processam.

Os workers de agregação operam em uma instância do ambiente de execução confiável (TEE). Um worker processa apenas um job por vez. É possível configurar vários workers para processar jobs em paralelo definindo a configuração de escalonamento automático. Se usado, o escalonamento automático ajusta dinamicamente o número de workers de acordo com o número de mensagens na fila de jobs. É possível configurar o número mínimo e máximo de workers para o escalonamento automático no arquivo de ambiente do Terraform. Para mais informações sobre o escalonamento automático, consulte estes scripts do Terraform: Amazon Web Services ou Google Cloud.

Os workers de agregação chamam o serviço de contabilidade de relatórios agregáveis para a contabilidade de relatórios agregáveis. Esse serviço garante que os jobs só sejam executados se o limite do orçamento de privacidade não tiver sido excedido. Consulte a regra"Sem duplicações". Se o orçamento estiver disponível, um relatório resumido será gerado usando os agregados com ruído. Leia mais detalhes sobre a contabilização de relatórios agregáveis.

Os workers de agregação atualizam os metadados do job no banco de dados de metadados do job. Essas informações incluem códigos de retorno do job e contadores de erros de relatório em caso de falhas parciais. Os usuários podem buscar o estado usando a API de recuperação de estado de jobs getJob.

Consulte este texto explicativo para uma descrição mais detalhada do serviço de agregação.

Próximas etapas

Agora que você já conhece os destaques do serviço de agregação, é hora de implantar sua própria instância dele no Google Cloud ou na Amazon Web Services. Consulte a seção de início ou acesse este link para saber mais sobre como operar o serviço de agregação.

Solução de problemas

Consulte o documento Códigos de erro e mitigações comuns para ver descrições detalhadas das mensagens de erro, o que pode ter causado um erro que você está enfrentando e as próximas etapas para mitigação.

Receber suporte e enviar feedback

• Para perguntas sobre o produto, feedback e solicitações de recursos, crie um problema no nosso repositório do GitHub.
• Se você estiver com um erro ao implantar, manter ou executar trabalhos com o serviço de agregação, use este formulário de suporte técnico para solicitar suporte técnico.
• Verifique se há problemas conhecidos no Painel de status público.