Measure ad conversions aggregated across users, without revealing individual data. Formerly known as aggregate reports.
Implementation status
- Chrome platform status
- Participate and experiment with this API.
- Keep track of the API changes.
What is an Attribution Reporting summary report?
The Attribution Reporting API makes it possible to measure when an ad click or view leads to a conversion on an advertiser site, such as a sale or a sign-up. The API doesn't rely on third-party cookies or mechanisms that can be used to identify individual users across sites.
This API offers two types of reports. Event-level reports are already available for testing in Chrome, which associate a specific ad click or view with less detailed conversion data. The browser delays sending reports to ad tech companies for multiple days to prevent identity connection across sites.
A summary report (formerly known as an aggregate report) is compiled for a group of users so that it cannot be tied to any individual. Summary reports offer detailed conversion data, such as purchase value and cart contents, with flexibility for click and view data. These reports are not delayed to the same extent as event-level reports.
If you haven't already, we recommend you read the general overview of Attribution Reporting before reading the rest of this article.
Why do we need summary reports?
Today, ad conversion measurement often relies on third-party cookies. Browsers are restricting access to third-party cookies to make it more difficult to track users across sites and improve user privacy. The Attribution Reporting API allows ad techs measure conversations in a privacy-preserving way, without third-party cookies.
In contrast to Attribution Reporting API's event-level reports, which associate singular events (such as clicks or views) to coarse data, summary reports provide aggregated data (such as the number of users who converted) attached to detailed conversion data (such as what specific product the users purchased).
Unlike third-party cookies, report types from the Attribution Reporting API don't allow any entity (such as ad tech, buyers, publishers, etc) to "see" a user's browsing behavior across multiple sites, while still making it possible to measure ad conversions.
How is user data captured and aggregated?
With the Attribution Reporting API, an individual user's detailed activity across sites, and potentially the user's identity across sites, is kept private to the user's browser on their device. This data can be collected in an aggregatable report, and each report is encrypted to prevent various parties from accessing the underlying data.
The process to create a summary report is as follows:
- Aggregatable reports are sent to the reporting origin, operated by an
ad tech provider.
- These reports may include location details, number of clicks, value of the conversion (such as a purchase price), or other metrics defined by the ad tech provider. Reports are encrypted, so ad techs cannot see or access the content of any individual report.
- Once the ad tech reporting origin receives the aggregatable reports, the
ad tech sends the reports to an aggregation service.
- In our initial implementation, the aggregation service is operated by the ad tech provider with a trusted execution environment (TEE) hosted in the cloud. The coordinator ensures that only verified entities have access to decryption keys and that no other intermediary (the ad tech, the cloud provider, or any other party) can access and decrypt sensitive data outside of the aggregation process.
- The aggregation service combines the decrypted data and outputs a summary
report to the ad tech provider.
- The summary report includes a summary of the combined data. The ad tech provider can read and use the summary report.
Because individual reports may contain cross-site user behavior information, the aggregation service must treat this information as private. The service will ensure that no other entity can get access to the individual, unencrypted attribution reports. Further, the service itself shouldn't perform any privacy-invasive actions.
To ensure the aggregation service is in fact secure, the service must have technical and organizational safeguards which are verifiable by consumer audit. These safeguards are meaningful to:
- Individual users, who can know their individual data can only be accessed in aggregate and not by any singular entity
- Ad techs, who can verify that the aggregation process uses valid data and can be monitored appropriately
Generate reports with the Aggregation Service
The initial design asks each ad tech provider to operate their own instance of the aggregation service, in a trusted execution environment (TEE) deployed on a cloud service that supports needed security features.
The TEE's code is the only place in the aggregation service which has access to raw reports—this code will be auditable by security researchers, privacy advocates, and ad techs. To confirm that the TEE is running the exact approved software and that data remains secured, the coordinator performs attestation.
The coordinator has several responsibilities:
- Maintain a list of authorized binary images. These images are cryptographic hashes of the aggregation service software builds, which Google will periodically release. This will be reproducible so that any party can verify the images are identical to the aggregation service builds.
- Operate a key management system. Encryption keys are required for the Chrome on a user's device to encrypt aggregatable reports. Decryption keys are necessary for proving the aggregation service code matches the binary images.
- Track the aggregatable reports to prevent reuse in aggregation for summary reports, as reuse may reveal personal identifying information (PII).
To make testing of the aggregation service available in the now-complete origin trial, Google played the role of the coordinator. Longer term, we are working to identify one or more independent entities who can share this role.
What information is captured?
Summary reports offer a combination of aggregated data alongside detailed ad-side and conversion data.
For example, an ad tech provider runs an ad campaign on news.example, where a
conversion represents a user clicking an ad for shoes and completing a
purchase of shoes on shoes.example. The ad tech receives a summary report for
this ad campaign with ID 1234567, which states there were 518
conversions on shoes.example on January 12, 2022, with a total spend of
$38,174. 60% of conversions were from users buying blue sneakers with
product SKU 9872 and 40% were users who bought yellow sandals with
product SKU 2643. The campaign ID is detailed ad-side data, while the
product SKUs are detailed conversion data. The number of conversions and total
spend are aggregated data.
Conversions are defined by the advertiser or ad tech company, and may be different for different ad campaigns. One campaign could measure the number of ad clicks that were followed by a user purchasing the advertised item. Another campaign could measure how many ad views led to advertiser site visits.
How is browser data captured before aggregation?
As summary reports are made up of the data from a group of individuals, let's start with one individual's browser actions.
- A user visits a publisher site and sees or clicks an ad, otherwise known as an attribution source event.
A few minutes or days later the user converts, otherwise known as an attribution trigger event. For example, a conversion can be defined as a product purchase.
The browser software matches the ad click or view with the conversion event. Based on this match, the browser creates an aggregatable report with specific logic created by an ad tech provider.
The browser encrypts this data and, after a small delay, sends it to an ad tech server for collection. The ad tech server must rely on an aggregation service to access the aggregated insights from these aggregatable reports.
Filtering IDs
The Attribution Reporting API & Aggregation Service allows the use of filtering IDs to process measurements at different cadences rather than having to process all measurement contributions in an aggregatable report at once.
Keep in mind that all values must be formatted as strings and are case-sensitive.
You should respond with the attribution trigger metadata in the HTTP header Attribution-Reporting-Register-Trigger.
We recommend the following to get you started:
app.get('/register-trigger', async (req, res) => {
…
res.setHeader('Attribution-Reporting-Register-Trigger',
JSON.stringify({
"filtering_id_max_bytes": 1
"aggregatable_trigger_data": [{
"key_piece": "0x400",
"source_keys": ["campaignCounts"]
}],
"aggregatable_values": {
"campaignCounts": { "value": 32768, "filtering_id": "1" }
}
})
);
res.sendStatus(200);
…
});
Aggregatable reports will be sent to where you have defined endpoint /.well-known/attribution-reporting/report-aggregate-attribution. Once batches of your aggregatable reports have been sent to your Aggregation Service set up and processed, your filtered results should be reflected within your final summary report.
Continue to our filtering IDs guide in Aggregation Service. See also filtering IDs for Private Aggregation API.
Create a summary report
For ad tech providers to retrieve a summary report, the following steps must be taken:
- The ad tech collects aggregatable reports from individual users' browsers.
- The ad tech provider batches the aggregatable reports and sends the batches to the aggregation service.
- The aggregation service schedules a worker to aggregate the data.
- The aggregation worker decrypts and aggregates data from the aggregatable reports, along with noised data (a privacy mechanism for data).
- The aggregation service returns the summary report to the ad tech provider.
The ad tech can use the summary report to inform bidding and to offer reporting to its own customers. A JSON-encoded scheme is the format for summary reports.
Engage and share feedback
You can participate and experiment with this API.
- Read about aggregatable reports and the aggregation service, ask questions, and suggest feedback.
- Read the Attribution reporting guides.
- Ask questions and join discussions on the Privacy Sandbox Developer Support repo.