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 number of times.
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 lets you to aggregate cross-site data.
Try K+ frequency measurement
To experiment with K+ frequency measurement with Shared Storage and Private Aggregation, confirm you're using Chrome M107 or later. Enable all the Ad privacy APIs under chrome://settings/adPrivacy
.
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 the number of users who have seen your content K or more times a given client across different sites. In this example, the impression count is added to shared storage where it increments by 1 whenever the content is loaded. 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 will provide information such as "Approximately 391 users have seen the ad campaign ID 123 at least 3 times."
In this example:
-
k-frequency-measurement.jsis loaded using a frame, and is responsible for loading the shared storage worklet. -
k-frequency-measurement-worklet.jsis the shared storage worklet that reads the impression count in shared storage and sends a report using the Private Aggregation API.
k-frequency-measurement.js
async
function
injectContent
()
{
// Load the Shared Storage worklet
await
window
.
sharedStorage
.
worklet
.
addModule
(
'k-freq-measurement-worklet.js'
);
// Run the K-frequency measurement operation
await
window
.
sharedStorage
.
run
(
'k-freq-measurement'
,
{
data
:
{
kFreq
:
3
,
contentId
:
123
});
}
injectContent
();
kuency-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 just the content
* ID itself. For more complex bucket key construction, see other use cases in
* this demo.
*/
function
convertContentIdToBucket
(
contentId
)
{
return
BigInt
(
contentId
);
}
class
KFreqMeasurementOperation
{
async
run
(
data
)
{
const
{
kFreq
,
contentId
}
=
data
;
// Read from Shared Storage
const
hasReportedContentKey
=
'has-reported-content'
;
const
impressionCountKey
=
'impression-count'
;
const
hasReportedContent
=
(
await
sharedStorage
.
get
(
hasReportedContentKey
))
===
'true'
;
const
impressionCount
=
parseInt
((
await
sharedStorage
.
get
(
impressionCountKey
))
||
0
);
// Don't report if a report has been sent already
if
(
hasReportedContent
)
{
return
;
}
// Check impression count against frequency limit
if
(
impressionCount
<
kFreq
)
{
await
sharedStorage
.
set
(
impressionCountKey
,
impressionCount
+
1
);
return
;
}
// Generate the aggregation key and the aggregatable value
const
bucket
=
convertContentIdToBucket
(
contentId
);
const
value
=
1
*
SCALE_FACTOR
;
// Send an aggregatable report using the Private Aggregation API
privateAggregation
.
contributeToHistogram
({
bucket
,
value
});
// Set the report submission status flag
await
sharedStorage
.
set
(
hasReportedContentKey
,
'true'
);
}
}
// Register the operation
register
(
'k-freq-measurement'
,
KFreqMeasurementOperation
);
\
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 .
