Frequency control

The Shared Storage API is a Privacy Sandbox proposal for general purpose, cross-site storage, which supports many possible use cases. One example is frequency control, which is available to test in Chrome Beta 104.0.5086.0 and later.

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. This can be used to select new ads or other content when the frequency cap has been reached.

# Test frequency control

To test frequency control with Shared Storage and Fenced Frames, confirm you're using Chrome 104.0.5086.0 or later. Then enable the Privacy Sandbox Ads APIs experiment flag at chrome://flags/#privacy-sandbox-ads-apis.

You can also enable Shared Storage with the --enable-features=PrivacySandboxAdsAPIsOverride,OverridePrivacySandboxSettingsLocalTesting,SharedStorageAPI,FencedFrames flag in the command line.

# Experiment with code samples

To select and create an opaque URL, register a worklet module to read shared storage data. The worklet class receives a list of up to eight URLs and then returns the index of the chosen URL.

When the client calls sharedStorage.runURLSelectionOperation(), the worklet executes and returns an opaque URL to be rendered into a fenced frame.

Let's say you want to render an ad based on the advertiser's frequency cap (the maximum number of impressions for a user on a single ad over a set period of time). The frequency cap value is stored in shared storage.

The shared storage worklet reads the values in shared storage, and decrements the value with each additional view. If there are available impressions left (the user has not hit their frequency cap), the ad is returned (index 1). If not, the default URL is returned (index 0).

In this example:

• frequency-cap.js is loaded via the advertiser's iframe, and is responsible for loading the shared storage worklet, and rendering the returned opaque source into a fenced frame.
• frequency-cap-worklet.js is the shared storage worklet that reads the frequency cap count value to determine which URL is returned for the ad creative.

frequency-cap.js

// The first URL is the default ad to be rendered when the frequency cap is reached
const AD_URLS = [
  { url: `https://${contentProducerUrl}/ads/default-ad.html` },
  { url: `https://${contentProducerUrl}/ads/example-ad.html` },
];

async function injectAd() {
  // Load the worklet module
  await window.sharedStorage.worklet.addModule('frequency-cap-worklet.js');

  // Set the initial frequency cap to 5
  window.sharedStorage.set('frequency-cap-count', 5, {
    ignoreIfPresent: true,
  });

  // Run the URL selection operation to choose an ad based on the frequency cap in shared storage
  const opaqueURL = await window.sharedStorage.selectURL('frequency-cap', AD_URLS);

  // Render the opaque URL into a fenced frame
  document.getElementById('ad-slot').src = opaqueURL;
}

injectAd();

frequency-cap-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Read the current frequency cap in shared storage
    const count = parseInt(await this.sharedStorage.get('frequency-cap-count'));

    // If the count is 0, the frequency cap has been reached
    if (count === 0) {
      console.log('frequency cap has been reached, and the default ad will be rendered');
      return 0;
    }

    // Set the new frequency count in shared storage
    await this.sharedStorage.set('frequency-cap-count', (count - 1).toString());
    return 1;
  }
}

// Register the operation as 'frequency-cap'
register('frequency-cap', SelectURLOperation);

# Other use cases

Explore other Shared Storage use cases and code samples:

# Generate reports with Private Aggregation

• Unique reach measurement: 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.
• Demographics measurement: 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 first-party site, and use aggregated reporting to report on it across many other sites, such as embedded content.
• K+ frequency measurement: Sometimes described as "effective frequency," there is often a minimum number 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 number of times.

# URL selection

• Frequency control: 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. This has many possible uses, such as selecting new content when a frequency cap is reached.
• A/B testing: You can assign a user to an experiment group, then store that group in Shared Storage to be accessed cross-site.
• Creative rotation: You can store the creative rotation mode, and other metadata, to rotate the creatives across different sites.
• 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.

These are only some of the possible use cases for Shared Storage. We'll continue to add examples as we receive feedback and discover new use cases.

# 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.