Aggregation Service

The Aggregation Service generates summary reports of detailed conversion data and reach measurements from raw aggregatable reports. As an ad tech, you can use the Attribution Reporting API and the Private Aggregation API, the two main aggregate entry points on the client side, to funnel reports to the Aggregation Service and receive a summary report in response.

This page assumes you are an experienced ad tech. It covers:

• Implementation status
• Key terms and concepts
• Aggregation use cases
• End-to-end flow
• Aggregatable reports batching
• Cloud components

Implementation status

• The Aggregation Service has now moved to general availability.
• The Aggregation Service can be used with the Attribution Reporting API and the Private Aggregation API for Protected Audience API and Shared Storage API.

Availability

Proposal	Status
Cross Cloud Privacy Budget Service Explainer	Available
Aggregation Service support for Amazon Web Services (AWS) across Attribution Reporting API, Private Aggregation API Explainer	Available
Aggregation Service support for Google Cloud across Attribution Reporting API, Private Aggregation API Explainer	Available
Aggregation Service site enrollment and multi-origin aggregation. Site enrollment includes mapping of a site to cloud accounts (AWS, or GCP). To aggregate multiple origins, they must be of the same site. FAQs on GitHub Site aggregation API documentation	Available
The Aggregation Service's epsilon value will be kept as a range of up to 64, to facilitate experimentation and feedback on different parameters. Submit ARA epsilon feedback. Submit PAA epsilon feedback.	Available. We will provide advanced notice to the ecosystem before the epsilon range values are updated.
More flexible contribution filtering for Aggregation Service queries Explainer	Available
Process for budget recovery post-disasters (errors, misconfigurations, and so on) Explainer	Available Mechanism to review the percentage of shared IDs recovered by an ad tech using budget recovery and suspend future recoveries for excessive recoveries planned for H1 2025
Accenture operating as one of the Coordinators on AWS Developer Blog	Available
Independent party operating as one of the Coordinators on Google Cloud Developer blog	Available
Aggregation Service support for Aggregate Debug Reporting on Attribution Reporting API Explainer	Available

Key terms and concepts

If you are considering the Aggregation Service for your workflow, the following terms and concepts may provide insight into what this new aggregation flow can provide for your team.

Glossary of terms

Aggregatable Reports

Aggregatable reports are encrypted reports sent from individual user devices. These reports contain data about cross-site user behavior and conversions. Conversions (sometimes called attribution trigger events) and associated metrics are defined by the advertiser or ad tech. Each report is encrypted to prevent various parties from accessing the underlying data.

Learn more about aggregatable reports.

Aggregatable Report Accounting

A distributed ledger, located in both coordinators, that tracks the allocated privacy budget and enforces the 'No Duplicates' rule. This is the privacy preserving mechanism, located and run within coordinators, that ensures no reports pass through the Aggregation Service beyond the allocated privacy budget.

Read more on how batching strategies relate to aggregatable reports.

Aggregatable Report Accounting Budget

References to the budget that ensures individual reports are not processed more than once.

Aggregation Service

An ad tech-operated service that processes aggregatable reports to create a summary report.

Read more about the Aggregation Service backstory in our explainer and the full terms list.

Attestation

A mechanism to authenticate software identity, usually with cryptographic hashes or signatures. For the aggregation service proposal, attestation matches the code running in your ad tech-operated aggregation service with the open source code.

Read more about attestation.

Contribution Bonding

Coordinator

Entities responsible for key management and aggregatable report accounting. A Coordinator maintains a list of hashes of approved aggregation service configurations and configures access to decryption keys.

Noise and Scaling

Statistical noise that is added to summary reports during the aggregation process to preserve privacy and ensure the final reports provide anonymized measurement information.

Read more about additive noise mechanism, which is drawn from Laplace distribution.

Reporting Origin

The entity that receives aggregatable reports—in other words, you or an ad tech that called the Attribution Reporting API. Aggregatable reports are sent from user devices to a well-known URL associated with the reporting origin. The reporting origin is designated during enrollment.

Shared ID

A computed value that consists of shared_info, reporting_origin, destination_site (for Attribution Reporting API only), source_registration-time (for Attribution Reporting API only), scheduled_report_time, and version.

Multiple reports that share the same attributes in the shared_info field should have the same shared ID. Shared IDs play an important role within Aggregatable Report Accounting.

Read more about Trusted Servers.

Summary Report

An Attribution Reporting API and Private Aggregation API report type. A summary report includes aggregated user data, and can contain detailed conversion data with noise added. Summary reports are made up of aggregate reports. They allow for greater flexibility and provide a richer data model than event-level reporting, particularly for some use-cases like conversion values.

Trusted Execution Environment (TEE)

A secure configuration of computer hardware and software that allows external parties to verify the exact versions of software running on the machine without fear of exposure. TEEs allow external parties to verify that the software does exactly what the software manufacturer claims it does—nothing more or less.

To learn more about TEEs used for the Privacy Sandbox proposals, read the Protected Audience API services explainer and the Aggregation Service explainer.

Aggregation use cases

Consider the following developer journeys for ad measurement and their corresponding measurement client libraries.

Use case	Entry point	Description
Bidding optimization	Attribution Reporting API (Chrome & Android)	Use aggregated reports to ingest conversion signals for bidding optimization purposes.
Cross-platform measurement	Attribution Reporting API (Chrome & Android)	Use the cross-web and app measurement capabilities to get visibility into performance across Chrome & Android.
Conversion reporting	Attribution Reporting API (Chrome & Android)	Create aggregated conversion reporting tailored to customers' campaign needs (includes CTCs and VTCs).
Campaign reach measurement	Shared Storage API & Private Aggregation API (Chrome)	Use cross-site ad view variables to measure campaign reach.
Demographic reporting	Shared Storage API & Private Aggregation API (Chrome)	Use cross-site ad view and demographic information to measure reach by demographics.
Conversion path analysis	Shared Storage API & Private Aggregation API (Chrome)	Store cross-site ad view and conversion variables to perform aggregated conversion path analysis.
Brand and conversion lift	Shared Storage API & Private Aggregation API (Chrome)	Reporting on test/control groups and polling information to measure brand lift and incrementality.
Auction debugging	Protected Audience API & Private Aggregation API (Chrome)	Use aggregated reports for debugging.
Distribution of bids	Protected Audience API & Private Aggregation API (Chrome)	Use aggregated reports to capture the distribution of bid values for auctions.

End-to-end flow

The following diagram shows the Aggregation Service in action. We'll focus on the end-to-end flow from the time the reports are received from web and mobile devices, to the time the summary report is created in the Aggregation Service.

1. Fetch the public key to generate encrypted reports.
2. Encrypted aggregatable reports are sent to ad tech servers to be collected, transformed, and batched.
3. The ad tech server batches reports (in avro format) and sends them to the Aggregation Service. (You must complete this.)
4. An Aggregation Worker retrieves the aggregated reports to decrypt.
5. The Aggregation Worker retrieves decryption keys from a Coordinator.
6. The Aggregation Worker decrypts the reports for aggregation and noising.
7. The Aggregatable Report Accounting Service checks if there is sufficient privacy budget to generate a summary report for the given aggregatable reports.
8. Submit a final summary report.

The diagram shows the high-level relationships that the Aggregation Service has with the main client measurement APIs: the Attribution Reporting API, the Private Aggregation API, and Coordinators.

The flow starts with Measurement APIs, such as the Attribution Reporting API or Private Aggregation API, generating reports from multiple browser instances. Chrome obtains the public key from the Key Hosting Service in the Coordinator to encrypt the reports before it sends them to your ad tech reporting origin. Public keys are rotated every seven days.

Your ad tech reporting origin should be configured to collect and convert incoming reports to avro format, and send them to your Aggregation Service as described in batching strategies.

When you have a batch ready, you send a batch request to the Aggregation Service. The Aggregation Service fetches decryption keys from the Key Hosting Service, decrypts the reports, and aggregates and noises them to create a summary report. Keep in mind that this depends on there being enough privacy budget to create them.

You host the ad tech reporting origin endpoint where the reports are collected, and the Aggregation Service is deployed in your ad tech cloud.

Aggregatable reports batching

The reporting flow wouldn't be complete without the help of the designated reporting origin server. This is the origin you would have submitted in the enrollment process. The reporting origin is responsible for collecting, transforming, and batching aggregatable reports it receives, and preparing them to be sent to your Aggregation Service in either Google Cloud or Amazon Web Services. Read more on how to prepare your aggregatable reports.

Now that you have the general concept, we can take a closer look at the components that are deployed in your Aggregation Service.

Cloud components

The Aggregation Service consists of several cloud service components. You use provided Terraform scripts to provision and configure all necessary cloud service components.

Frontend Service

Managed Cloud Service: Cloud Function (Google Cloud) / API Gateway (Amazon Web Services)

The Frontend Service is a serverless gateway that is the primary entry point for Aggregation API calls for job creation and job state retrieval. It is responsible for receiving requests from Aggregation Service users, validating input parameters, and initiating the aggregation job scheduling process.

The Frontend Service has two available APIs:

Endpoint	Description
createJob	This API triggers an Aggregation Service job. It requires information such as job ID, input storage details, output storage details, reporting origin, and more, to trigger the job.
getJob	This API returns the status of the job having a specified job ID. It provides information about the state of the job, such as "Received," "In Progress," or "Finished." If the job is finished, it also returns the job result, including any error messages encountered during job execution.

Check out the Aggregation Service API Documentation.

Job Queue

Managed Cloud Service: Pub/Sub (Google Cloud) / Amazon SQS (Amazon Web Services)

The Job Queue is a message queue containing job requests for the Aggregation Service. The Frontend Service inserts job requests into the queue, which are then consumed by Aggregation Workers that process them.

Cloud storage

Managed Cloud Service: Google Cloud Storage (Google Cloud) / Amazon S3 (Amazon Web Services)

Input and output files used by the Aggregation Service, such as encrypted report files and output summary reports, are kept in cloud storage.

Job Metadata Database

Managed Cloud Service: Spanner (Google Cloud) / DynamoDB (Amazon Web Services)

The Job Metadata Database is used to store and track the status of aggregation jobs. It records metadata such as creation time, requested time, updated time, and state such as Received, In Progress, or Finished. Aggregation Workers update the Job Metadata Database as jobs progress.

Aggregation Worker

Managed Cloud Service: Compute engine with Confidential space (Google Cloud) / Amazon Web Services EC2 with Nitro Enclave (Amazon Web Services)

An Aggregation Worker processes job requests in the Job Queue, and decrypts the encrypted inputs using keys it fetches from the Key Generation and Distribution Service (KGDS) in Coordinators. To minimize job processing latency, Aggregation Workers cache decryption keys for a period of 8 hours, and use them across jobs they processes.

Aggregation Workers operate within a Trusted Execution Environment (TEE) instance. A worker handles only one job at a time. You can configure multiple workers to process jobs in parallel by setting the auto scaling configuration. If used, auto scaling dynamically adjusts the number of workers according to the number of messages in the job queue. You can configure the minimum and maximum number of workers for auto scaling through the Terraform environment file. More information about autoscaling can be found in these Terraform scripts: Amazon Web Services or Google Cloud.

Aggregation Workers call the Aggregatable Report Accounting Service for aggregatable report accounting. This service ensures that jobs are only run if the privacy budget limit has not been exceeded. (See "No duplicates" rule.) If the budget is available, a summary report is generated using the noisy aggregates. Read additional details regarding the aggregatable report accounting.

Aggregation Workers update job metadata in the Job Metadata Database. This information includes job return codes and report error counters in case of partial report failures. Users can fetch the state using the getJob job state retrieval API.

See this explainer for a more detailed description of the Aggregation Service.

Next steps

Now that you have seen the highlights of the Aggregation Service, it's time for you to deploy your very own instance of the Aggregation Service through Google Cloud or Amazon Web Services. See the getting started section, or follow this link to learn more about operating the Aggregation Service.

Troubleshooting

Refer to the Common error codes and mitigations document for detailed descriptions of error messages, what may have caused an error you're facing, and next steps for mitigation.

Get support and provide feedback

• For product questions, feedback, and feature requests, create an issue in our GitHub repository.
• For requesting technical troubleshooting support if you're facing an error while deploying, maintaining, or running jobs with Aggregation Service, use this Technical Support Form.
• Check the Public Status Dashboard for known issues.