Skip to content

Commit f5cda2b

Browse files
authored
Move two examples from Shared Storage explainer (#162)
These two examples might be better placed in the Private Aggregation explainer instead.
1 parent c7e3daa commit f5cda2b

File tree

1 file changed

+54
-1
lines changed

1 file changed

+54
-1
lines changed

README.md

+54-1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Author: Alex Turner ([email protected])
1212
- [Examples](#examples)
1313
- [Protected Audience reporting](#protected-audience-reporting)
1414
- [Measuring user demographics with cross-site information](#measuring-user-demographics-with-cross-site-information)
15+
- [Cross-site reach measurement](#cross-site-reach-measurement)
16+
- [K+ frequency measurement](#k-frequency-measurement)
1517
- [Goals](#goals)
1618
- [Non-goals](#non-goals)
1719
- [Operations](#operations)
@@ -193,6 +195,57 @@ class SendDemoReportOperation {
193195
register("send-demo-report", SendDemoReportOperation);
194196
```
195197

198+
### Cross-site reach measurement
199+
200+
Measuring the number of users that have seen an ad.
201+
202+
In the ad’s iframe:
203+
204+
```js
205+
await window.sharedStorage.worklet.addModule('reach.js');
206+
await window.sharedStorage.run('send-reach-report', {
207+
// optional one-time context
208+
data: { campaignId: '1234' },
209+
});
210+
```
211+
212+
Worklet script (i.e. `reach.js`):
213+
214+
```js
215+
class SendReachReportOperation {
216+
async run(data) {
217+
const reportSentForCampaign = `report-sent-${data.campaignId}`;
218+
219+
// Compute reach only for users who haven't previously had a report sent for
220+
// this campaign. Users who had a report for this campaign triggered by a
221+
// site other than the current one will be skipped.
222+
if (await sharedStorage.get(reportSentForCampaign) === 'yes') {
223+
return; // Don't send a report.
224+
}
225+
226+
// The user agent will send the report to a default endpoint after a delay.
227+
privateAggregation.contributeToHistogram({
228+
bucket: data.campaignId,
229+
value: 128, // A predetermined fixed value; see Scaling values.
230+
});
231+
232+
await sharedStorage.set(reportSentForCampaign, 'yes');
233+
}
234+
}
235+
register('send-reach-report', SendReachReportOperation);
236+
```
237+
238+
### _K_+ frequency measurement
239+
240+
By instead maintaining a counter in shared storage, the approach for cross-site
241+
reach measurement could be extended to _K_+ frequency measurement, i.e.
242+
measuring the number of users who have seen _K_ or more ads on a given browser,
243+
for a pre-chosen value of _K_. A unary counter can be maintained by calling
244+
`window.sharedStorage.append("freq", "1")` on each ad view. Then, the
245+
`send-reach-report` operation would only send a report if there are more than
246+
_K_ characters stored at the key `"freq"`. This counter could also be used to
247+
filter out ads that have been shown too frequently.
248+
196249
## Goals
197250

198251
This API aims to support a wide range of aggregation use cases, including
@@ -425,7 +478,7 @@ service deployed on AWS, GCP, and other platforms in the future. The specified
425478
origin would need to be on an allowlist maintained by the browser. If none is
426479
specified, a default will be used.
427480

428-
This allowlist matches the Attribution Reporting API's, available
481+
This allowlist matches the Attribution Reporting API's, available
429482
[here](https://github.com/WICG/attribution-reporting-api/blob/main/aggregation_coordinator_origin_allowlist.md).
430483

431484
Shared Storage callers would specify this field when calling the `run()` or

0 commit comments

Comments
 (0)