Shared Storage API demo

What is Shared Storage?

Shared Storage API is a storage that can be used cross-site, meaning you store a value at a.com, then read a value from b.com at a later point in time. With Shared Storage, you can set data freely, but you are restricted in how you get that data out of the storage. You will not be able to read the actual value that is stored outside of a worklet context, but you can process that value inside the worklet. To extract information from the worklet, Shared Storage uses a concept called “gates” to conduct various operations.

Code for this demo is available on GitHub.

How to run the demo


To run the URL selection demo, follow the instructions for enabling the Privacy Sandbox Ads APIs experiment flag at chrome://flags/#privacy-sandbox-ads-apis and chrome://flags/#privacy-sandbox-enrollment-overrides, using the following value for the latter: https://shared-storage-demo-content-producer.web.app,https://shared-storage-demo-publisher-a.web.app

Common use cases

This section provides demos for some common use cases with Shared Storage

Measuring a hover event inside a fenced frame

When a content is rendered into a fenced frame via selectUrl(), an event-level reports can be created with Fenced Frames Ads Reporting API. This demo shows you how the metadata for a URL can be associated with an event that occurs inside a fenced frame

Top-level navigation

Whenever the fenced frame navigates the top-level frame to another page, the entropy budget is decreased. This demo shows allows you to see how the budget decreases.

Controlling where third-party can write to

When a third-party code is added to the publisher's page, the third-party can write to the shared storage of their own origin, or write to the publisher's origin. This demo illustrates the mechanisms for controlling the document origin that determines whose shared storage that data is written into.

Private aggregation output gate

The Private Aggregation API is available for testing with Shared Storage in Chrome Canary and Dev M107 or later.

The aggregation API is used to report events from a Shared Storage worklet to Aggregation Service to generate summary reports. This demo implements the frontend of the API where the report is generated and sent from the client, but does not integrate with Aggregation Service.

To see the reports transmitted, visit the chrome://private-aggregation-internals page. You can also hover the "Send report" button to send the reports instantly to the server.

Open the DevTools console to see the demo output.

Unique reach measurement

You may want to keep track of how many unique impressions your content has across different sites. In this demo, visiting either Publisher A or B sites will send the aggregatable report, but will not send it on subsequent visits. The ad camaign ID dimension is encoded into the aggregation key (bucket), and the count is used as the aggregatable value. To reset the demo, hover the "Reset impression flag" button on the demo page.

The summary report will contain information such as "Approximately 391 users have seen the ad campaign ID 743."

Demographics measurement

You may want to measure the demographics of the users who has seen some content you have embedded across different sites.

For this demo, visit the survey page to enter your demographic data where the information you enter is added to Shared Storage. Then visit either Publisher A or B sites which will trigger the aggregatable report to be sent once across both sites. The content ID, age group ID, and the geography ID dimensions are encoded into the aggregation key (bucket), and the count is used as the aggregatable value.

The summary report generated will provide information such as "Approximately 391 users who have seen the content ID 743 are between the age of 18-25 and are from Europe."

K+ frequency measurement

You may want to measure the number of users who have seen your content K or more times a given client across different sites.

In this demo, the impression count is added to Shared Storage where it increments by 1 whenever the content is loaded for both publisher A and B. When the impression count has reached 3, the Private Aggregation API is called. The content ID dimension is encoded as the aggregation key, and the count is used as the aggregatable value.

The summary report generated will provide information such as "Approximately 391 users have seen the ad campaign ID 743 at least 3 times."

URL selection output gate

URL selection is used to choose a URL based on the information in Shared Storage.

This demo is mostly constructed from the perspective of a content producer or an advertiser that wants to store information across different publishers. Think of the advertiser as a shoe company, and the publishers as news companies. In this demo, the same advertiser code will run on both Publisher A and Publisher B sites for each use case. Visit both publishers to see how the data is shared between two publishers.

Creative selection by frequency

If an ad creative has been shown to the user too many times, select a different ad.

In this demo, when the user sees the same example ad 5 times across both Publisher A and Publisher B sites, the default ad will be selected. The demo contains a button to reset the frequency back to 5.

A/B testing

To see if an experiment has the desired effect, you can conduct A/B testing across multiple sites. As an advertiser, you can choose to render a different ad based on what group the user is assigned to. This group assignment is stored into Shared Storage and can be used cross-site.

In this demo, the user can be assigned to "Control", "Experiment A", or "Experiment B" groups. The same ad will be rendered across different sites based on what group the user is in. The initial assignment is random, and the demo contains a set of butons to manually add the user to a group.

Creative rotation

An advertiser may want to show different ads of the same campaign to the user to increase effectiveness of the ads.

In this demo, the creative can be rotated with different strategies. In sequential rotation, creatives A, B and C are shown one after another. In even distribution, the creative is selected at random where each creative has an equal chance of being chosen. In weighted distribution, some creatives can be weighted to be chosen more often than another creative.

Known customer

There may be cases where you want to render a different element based on whether the user has been seen before at a different site. A payment provider may want to render a "Register" or "Buy now" button based on whether the user has registered before at the payment provider's site.

In this demo, a different button will be rendered for the publishers based on the user status set from the payment provider page.