User demographic reporting

The Shared Storage API is a Privacy Sandbox proposal for general purpose, cross-site storage, which supports many possible use cases. Private Aggregation API is an output available in Shared Storage that allows you to aggregate cross-site data.

# Try user demographic measurement

To experiment with user demographic measurement with Shared Storage and Private Aggregation, confirm you're using Chrome Canary and Dev M107 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

You may want to measure certain demographics of the users who have seen your content across different sites, for example age range or geographical location. In this example, 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 123 are between the age of 18-39 and are from Europe."

In this example:

• demographic-measurement.js is loaded via a frame, and is responsible for loading the shared storage worklet.
• demographic-measurement-worklet.js is the shared storage worklet that reads the demographics data in shared storage and sends a report via the Private Aggregation API.

store-demographic-data.js

(Runs at some point in time before the measurement is made to set the demographics data into Shared Storage)

function getDemogrationsData() {
  // Collect age group and continent data
  return {
    ageGroup,
    continent
  }
}

async function storeDemographics() {
  const { ageGroup, continent } = getDemographicsData();
  await window.sharedStorage.set('age-group', ageGroup);
  await window.sharedStorage.set('continent', continent);
}

storeDemographics();

demographic-measurement.js

async function measureDemographics() {
  // Load the Shared Storage worklet
  await window.sharedStorage.worklet.addModule('demographics-measurement-worklet.js');

  // Run the demographics measurement operation
  await window.sharedStorage.run('demographics-measurement', { data: { contentId: '123' } });
}

measureDemographics();

demographic-measurement-worklet.js

// Learn more about noise and scaling from the Private Aggregation fundamentals
// documentation on Chrome blog
const SCALE_FACTOR = 65536;

/**
 * The bucket key must be a number, and in this case, it is simply the ad campaign
 * ID itself. For more complex bucket key construction, see other use cases in
 * this demo.
 */

const AGGREGATION_KEY_MAP = {
  ageGroupId: {
    '18-39': '1',
    '40-64': '2',
    '65+': '3',
  },

  continentId: {
    africa: '1',
    antarctica: '2',
    asia: '3',
    australia: '4',
    europe: '5',
    'north-america': '6',
    'south-america': '7',
  },

};

/**
 * The aggregation key will be in the format of:
 * contentId | ageGroupId | continentId
 *
 * For example, a user from Australia between the age of 40-64, who has
 * seen the Content ID 321 will be represented by the key:
 * 321 | 2 | 4 or 32124
 */

function generateAggregationKey(contentId, ageGroup, continent) {
  const ageGroupId = AGGREGATION_KEY_MAP.ageGroupId[ageGroup];
  const continentId = AGGREGATION_KEY_MAP.continentId[continent];
  const aggregationKey = BigInt(`${contentId}${ageGroupId}${continentId}`);

  return aggregationKey;
}

class DemographicsMeasurementOperation {
  async run(data) {
    const { contentId } = data;

    // Read from Shared Storage
    const key = 'has-reported-content';
    const hasReportedContent = (await this.sharedStorage.get(key)) === 'true';
    const ageGroup = await this.sharedStorage.get('age-group');
    const continent = await this.sharedStorage.get('continent');

    // Do not report if a report has been sent already
    if (hasReportedContent) {
      return;
    }

    // Generate the aggregation key and the aggregatable value
    const bucket = generateAggregationKey(contentId, ageGroup, continent);
    const value = 1 * SCALE_FACTOR;

    // Send an aggregatable report via the Private Aggregation API
    privateAggregation.sendHistogramReport({ bucket, value });

    // Set the report submission status flag
    await this.sharedStorage.set(key, true);
  }
}

// Register the operation
register('demographics-measurement', DemographicsMeasurementOperation); \

# Use cases

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.

# Content selection

Select and display different content on different websites in fenced frames based on information collected in Shared Storage. The output gate for these use cases is URL selection.

• Creative rotation: Store data, such as creative ID, view counts, and user interaction, to determine which creative users' see across different sites.
• A/B testing: You can assign a user to an experiment group, then store that group in Shared Storage to be accessed cross-site.
• Custom user experiences: Share custom content and calls-to-action based on a user’s registration status or other user states

# Generate summary reports

Collect information with Shared Storage and generated a noisy, aggregated summary report. The output gate for these use cases is the Private Aggregation API.

• Unique reach measurement: Many content producers and advertisers want to know how many unique people saw their content. Use Shared Storage to record the first time a user saw your ad, embedded video, or publication, and prevent duplicative counting of that same user on different sites. You can then use the Private Aggregation API to output a summary report for your 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.

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