The Shared Storage API enables websites to store and access data that's not isolated by the top-level site. This enables and facilitates cross-site use cases while respecting user privacy.
While Chrome has partitioned storage and is moving to a new experience that elevates user choice on third-party cookies, there are a number of legitimate use cases that rely on unpartitioned storage which wouldn't be possible without assistance from new web APIs. For example, a content producer may want to measure content reach across different sites, without reliance on cross-site identifiers. The Shared Storage API addresses this need by providing a more private mechanism for storing and accessing unpartitioned data across sites.
What is the Shared Storage API?
The Shared Storage API is a general-purpose storage facility that is designed to enable privacy preserving cross-site use cases. With features similar to both the localStorage and sessionStorage APIs, Shared Storage is a key-value store in which data can be written to at any time. Unlike other Web Storage APIs, the Shared Storage data can be shared across different top-level sites; however, the Shared Storage data can only be read from a secure environment and output using restricted Output APIs.
In the preceding diagram, the shoes.example site can be embedded into other
publisher sites like news.example and still access the same data.
This Shared Storage capability enables cross-site capabilities while advancing user privacy by preventing tracking individual site visitors and restricting data access. Data can only be accessed within a secure environment with limited output capabilities (worklets).
Shared Storage is the underlying storage infrastructure for a limited number of Output APIs. An Output API is the only way to use Shared Storage data. The Output APIs are:
- Select URL: Select a URL from a provided list, based on the stored data, and then render that content in a fenced frame.
- Private Aggregation: Send cross-site data through the Private Aggregation API to generate a summary report.
Why do we need Shared Storage?
The Shared Storage API is a flexible storage mechanism, which web developers can use in combination with the output APIs to address many use cases, including replacing several existing uses for third-party cookies. See more details about potential use-cases of the output APIs: Select URL and Private Aggregation.
Is your company looking for cross-site storage solutions that haven't yet been addressed? You can share your use case and create an issue on the open-source Shared Storage GitHub repository.
Output APIs and uses cases compatible with Shared Storage
| Output API | Use case | Description |
|---|---|---|
| Select URL | Rotate ad creatives | You can store data, such as creative ID, view counts, and user interaction, to determine which creative users' see across different sites. This lets you balance views and avoid oversaturation of certain content and thus avoid a possible negative user experience. |
| Select URL | Run A/B testing | An A/B test compares two or more versions of a configuration to determine which performs best. You can assign a user to an experiment group, then store that group in Shared Storage for cross site access. |
| Select URL | Customize user experience for known customers | You can share custom content and calls-to-action based on a user's registration status or other user states. |
| Select URL, Private aggregation | Anti-abuse mitigations | 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 in this use case, whether it's using the Select URL API to encode a user trustworthiness rating or using the Private Aggregation API to build datasets for anomaly detection. |
| Private aggregation | Measure unique reach | Many content producers and advertisers often want to know how many unique people have viewed their displayed content. You can use Shared Storage to report on the first time a user sees your ad, embedded video, or publication. You can prevent duplicative counting of that same user on a different site, and generate an aggregated noisy report for your approximate unique content reach. |
| Private aggregation | Measure user demographics | Content producers are eager to understand the demographics of their audience. Shared Storage lets you capture user demographic data on your first-party site and take advantage of aggregated reporting to analyze this information across various other platforms, like embedded content. |
| Private aggregation | Measure K+ frequency reach | 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. |
How does Shared Storage work?
Shared Storage lets you 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, but you can only read the Shared Storage values in a secure environment, known as a worklet.
Shared Storage worklets are where you add your business logic and then read and process a value from Shared Storage without directly returning the exact value to the worklet caller. You can use either the Private Aggregation or Select URL Output APIs to extract information from the worklet. Additional Output APIs may become available as new use cases are reported.
API status
The Shared Storage API is in general availability. Follow the instructions to enroll for the Privacy Sandbox, to use the API or enable for local development.
| Proposal | Status |
|---|---|
| Allow writing from response headers Explainer GitHub Issue |
Available in M124. Can be manually enabled in M119-M123 |
| Debugging Shared Storage worklets with DevTools Section |
Available in M120 |
| Update Shared Storage data storage limit to 5MB Explainer |
Available in M124 |
createWorklet() to create cross-origin worklets without an iframe |
Available in M125 |
Allow cross-origin script in addModule(), and align createWorklet() to match the behavior |
Available in M130 |
Engage and share feedback
Note that the Shared Storage API proposal is under active discussion and development and therefore subject to change.
We're eager to hear your thoughts on the Shared Storage API.
- Proposal: Review the detailed proposal.
- Discussion: Join the ongoing discussion to ask questions and share your insights.
Stay Informed
- Mailing List: Subscribe to our mailing list for the latest updates and announcements related to the Shared Storage API.
Need Help?
- Developer Support: Connect with other developers and get answers to your questions in the Privacy Sandbox Developer Support repository.