WorkletSharedStorage
====================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`WorkletSharedStorage`** interface of the Shared Storage API represents the shared storage for a particular origin within a worklet context.

`WorkletSharedStorage` is accessed via `SharedStorageWorkletGlobalScope.sharedStorage`.

SharedStorage

WorkletSharedStorageInstance properties
-------------------

`context` 
Experimental

Non-standard

Contains contextual data passed into the shared storage worklet from the associated browsing context via the `FencedFrameConfig.setSharedStorageContext()` method.

Instance methods
----------------

*`WorkletSharedStorage` inherits properties from its parent interface, `SharedStorage`.*

`get()` 
Experimental

Retrieves a value from the shared storage.

`length()` 
Experimental

Returns the number of entries currently stored in the shared storage for the current origin.

`remainingBudget()` 
Experimental

Returns the remaining navigation budget for the current origin.

`WorkletSharedStorage` also includes the following methods because it has an async iterator defined on it:

`entries()` 
Experimental

Returns a new async iterator for the key-value pairs of a `WorkletSharedStorage` object instance's enumerable properties.

`keys()` 
Experimental

Returns a new async iterator containing the keys for each item in a `WorkletSharedStorage` object instance.

`WorkletSharedStorage[@@asyncIterator]()` 
Experimental

Returns the `entries()` function by default.

Examples
--------

### Passing contextual data via `setSharedStorageContext()`

You can use the Private Aggregation API to create reports that combine event-level data inside fenced frames with contextual data from the embedding document. `setSharedStorageContext()` can be used to pass contextual data from the embedder to shared storage worklets initiated by the Protected Audience API.

In this example, we store data from both the embedding page and the fenced frame using shared storage.

On the embedding page, we set a mock event ID as the shared storage context using `setSharedStorageContext()`:


```js
const frameConfig = await navigator.runAdAuction({ resolveToConfig: true });

// Data from the embedder that you want to pass to the shared storage worklet
frameConfig.setSharedStorageContext("some-event-id");

const frame = document.createElement("fencedframe");
frame.config = frameConfig;
```


Within the fenced frame, after adding the worklet module with `window.sharedStorage.worklet.addModule()`, we send the event-level data into the shared storage worklet module using `window.sharedStorage.run()` (this is unrelated to the contextual data from the embedding document):


```js
const frameData = {
  // Data available only inside the fenced frame
};

await window.sharedStorage.worklet.addModule("reporting-worklet.js");

await window.sharedStorage.run("send-report", {
  data: {
    frameData,
  },
});
```


In the `reporting-worklet.js` worklet, we read the embedding document's event ID from `sharedStorage.context` and the frame's event-level data from the data object. We then report them through Private Aggregation:


```js
class ReportingOperation {
  convertEventIdToBucket(eventId) { ... }
  convertEventPayloadToValue(info) { ... }

  async run(data) {
    // Data from the embedder
    const eventId = sharedStorage.context;

    // Data from the fenced frame
    const eventPayload = data.frameData;

    privateAggregation.sendHistogramReport({
      bucket: convertEventIdToBucket(eventId),
      value: convertEventPayloadToValue(eventPayload)
    });
  }
}

register('send-report', ReportingOperation);
```

Specifications
--------------

| Specification |
| --- |
| Shared Storage API # workletsharedstorage |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Shared Storage API