Shared Storage
Allow access to unpartitioned cross-site data in a secure environment.
Published on • Updated on
Technical Writer, Google Chrome
Developer Relations Engineer, Google Chrome
Implementation status
This document outlines a proposal for unpartitioned, cross-site storage: the Shared Storage API.
- The Shared Storage proposal has entered public discussion.
- A live demo is available, as is testing:
- URL selection output gate is available for local testing from Chrome M105+.
- Private Aggregation output gate is available for local testing from Chrome M107+.
- Measurement with the Private Aggregation API is available in the Privacy Sandbox Unified Origin Trial from Chrome M107+ Beta.
- Chrome platform status
| Proposal | Status |
|---|---|
| Support for debug mode and testing of Aggregation Service with the local testing tool Private Aggregation API documentation | Available in Chrome Beta for origin trial in Q1 2023 |
| Private Aggregation API available for origin trial testing in Chrome stable channel Explainer | Expected in Chrome for origin trial in Q2 2023 |
| Prevent invalid Private Aggregation API reports with report verification for Shared Storage Explainer | Expected in Chrome for origin trial in Q2 2023 |
Why do we need this API?
To prevent cross-site user tracking, browsers are partitioning all forms of storage (cookies, localStorage, caches, etc). However, there are a number of legitimate use cases that rely on unpartitioned storage which would be impossible without help from new web APIs. For example, a content producer may want to measure reach across different sites, without relying on cross-site identifiers.
The Shared Storage API allows sites to store and access unpartitioned cross-site data. This data must be read in a secure environment to prevent leakage.
Who is this for?
There are many different kinds of companies which may benefit from using the Shared Storage API. For example:
- Ad techs could measure campaign reach, set frequency caps, and rotate creatives, all of which currently rely on third-party cookies.
- Payments providers could determine if a user is an existing customer and tailor the checkout experience.
- Web security companies can build custom logic to flag suspicious or dangerous behavior.
Is your company looking for cross-site storage solutions that haven’t yet been addressed? Share your use case.
Use cases
The Shared Storage API intends to support many use cases, replacing several existing uses for third-party cookies. This may include:
| Use case | Description | Output gate |
|---|---|---|
| Frequency Controls | The opposite side of the pendulum to effective frequency is oversaturation, showing users the same content too often leading to poor user experience. To balance and control for the number of views, organizations can record a user’s view counts in shared storage and display different content once the user has reached a predefined and customizable limit. | URL Selection |
| A/B testing | You can assign a user to an experiment group, then store that group in shared storage to be accessed cross-site. | URL Selection |
| Creative rotation | You can store the creative rotation mode, and other metadata, to rotate the creatives across different sites. | URL Selection |
| Known customer for payment provider | You can store whether the user has registered on your site into shared storage, then render a different element based on that stored status. | URL Selection |
| Anti-abuse mitigation | Anti-abuse, anti-fraud, and web security organizations often use proprietary techniques to detect malicious users, whether automated bots or real humans trying to cause harm. It’s possible to test many different strategies here, whether it’s using URL Selection output gate to encode a user trustworthiness rating or using the Private Aggregation output gate to build datasets for anomaly detection. | URL Selection, Private Aggregation API |
| Unique Reach Reporting | Many content producers and advertisers often want to know how many unique people saw their content. You can use shared storage to report on the first time a user saw your ad, embedded video, publication, and prevent duplicative counting of that same user on a different site, giving you an aggregated noisy report of your approximate unique reach. | Private Aggregation API |
| User Demographics Reporting | Content producers often want to understand the demographics of their audience. You can use shared storage to record user demographic data in a context where you have it, such as your 1P site, and use aggregated reporting to report on it across many other sites, such as embedded content. | Private Aggregation API |
| K+ Frequency Reach Reporting | Sometimes described as “effective frequency,” there is often a minimum number of views before a user will recognize or recall certain content (often in the context of advertisement views). You can use Shared Storage to build reports of unique users that have seen a piece of content at least K times. | Private Aggregation API |
The proposal intends to create a general purpose API which supports many possible future use cases. This allows for further experimentation and change, to grow alongside the web ecosystem.
How does shared storage work?
Shared storage allows you to make informed decisions based on cross-site data, without sharing user information (such as browser history or other personal details) with an embedding site or exfiltrating data to your own servers.
You can write to shared storage at any time, like other JavaScript storage APIs (like localStorage or indexedDB). Unlike the other storage APIs, you can only read the shared storage values in a secure environment, known as a shared storage worklet.
A worklet allows you to run specific JavaScript functions and return information back to the requester. Within a worklet, you can execute JavaScript but you cannot interact or communicate with the outside page.
Worklets are where you add your business logic. Inside the worklet, you are allowed to read and process a value from Shared Storage, but you cannot directly return the exact value to the worklet caller. To extract useful information from the worklet, a set of “gates” are available. There are two gates available, but more may be added in the future.
Available Shared Storage API output gates:
- URL selection: You can run a worklet script to select a URL from a provided list, based on the stored data, and then render that URL in a fenced frame.
- For example: You may want to conduct A/B testing. You can assign a user to an experiment group when you see that user on your site, then store that group in shared storage to be accessed cross-site. Later, on another site, a frame (e.g., a payment button or ad creative) can be chosen to show the user based on the user’s experiment group stored in shared storage.
- Noisy aggregation of cross-site data: You can run a worklet to send cross-site data through the Private Aggregation API, which returns a summary report.
- For example: You may want to know how many unique users saw your content across different sites. Use shared storage to store the first time a user saw your ad, embedded video, publication, or other content. Then run a worklet with the Private Aggregation API to aggregate the data across all users’ first time views and generate an aggregated noisy report of your approximate unique reach.
Try the Shared Storage API
Shared Storage API for URL selection output gate and Private Aggregation output gate are available for testing. URL selection can be tested in Chrome Canary/Dev/Beta M105+ and Private Aggregation API is available for testing in Chrome M107+ Canary and Dev. The API can be tested by enabling the Privacy Sandbox Ads APIs experiment flag at chrome://flags/#privacy-sandbox-ads-apis.
Use the demo
A demo is available, and you can review the code on GitHub.
This demo is constructed from the perspective of an advertiser, ad tech, content distributor or other third party service that wants to store information across different publishers’ sites. In the demo, the same third party’s code will run on both Publisher A and Publisher B sites for each use case. Visit the publisher’s pages to see how the data is shared in a cross-site context.
The demo contains use cases for URL selection and Private Aggregation.
For the URL selection demo, frequency control, creative rotation, known customer, and A/B testing use cases are available.
For the Private Aggregation demo, you can preview unique reach measurement, demographics measurement, and K-frequency measurement.
Engage and share feedback
The Shared Storage proposal is under active discussion and subject to change in the future. If you try this API and have feedback, we'd love to hear it.
- GitHub: Read the proposal, raise questions and participate in discussion.
- Shared Storage API announcements: Join or view past announcements on our mailing list
- Developer support: Ask questions and join discussions on the Privacy Sandbox Developer Support repo.
Updated on • Improve article