Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DO NOT MERGE: Technical review for Shared Storage API docs #28051

Closed
wants to merge 26 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
09f74e0
Add first draft of Shared Storage API landing page
chrisdavidmills Jul 19, 2023
7a1984e
Add sharedstorage class
chrisdavidmills Jul 19, 2023
d4dced4
Lots more progress on documenting the interfaces
chrisdavidmills Jul 23, 2023
1928e17
final bits of content
chrisdavidmills Jul 24, 2023
ce9e2d1
Merge branch 'main' into shared-storage-api
chrisdavidmills Jul 24, 2023
c2fff8a
Update files/en-us/web/api/shared_storage_api/index.md
chrisdavidmills Jul 25, 2023
702386f
Update files/en-us/web/api/shared_storage_api/index.md
chrisdavidmills Jul 25, 2023
b3ee6b7
Update files/en-us/web/api/sharedstorage/index.md
chrisdavidmills Jul 25, 2023
a994416
Update files/en-us/web/api/sharedstorage/set/index.md
chrisdavidmills Jul 25, 2023
6a17946
small tweak
chrisdavidmills Jul 25, 2023
f2af72d
Merge branch 'main' into shared-storage-api
chrisdavidmills Jul 26, 2023
4dc61f8
Change Select URL gate name to Content Selection
chrisdavidmills Jul 26, 2023
3ac68d5
Merge branch 'shared-storage-api' of github.com:chrisdavidmills/conte…
chrisdavidmills Jul 26, 2023
8a3b64f
Add multiple operations example
chrisdavidmills Jul 26, 2023
11e3ee4
Fixes according to pythagoraskitty comments
chrisdavidmills Aug 3, 2023
82fc773
Merge branch 'main' into shared-storage-api
chrisdavidmills Aug 11, 2023
d6eab15
Update Content Selection to URL Selection
chrisdavidmills Aug 11, 2023
61420ea
Merge branch 'main' into shared-storage-api
chrisdavidmills Sep 28, 2023
62162fe
Fixes make for pythagoraskitty 2nd tech review
chrisdavidmills Sep 28, 2023
1fb0ac3
Merge branch 'main' into shared-storage-api
chrisdavidmills Oct 16, 2023
c983300
Add note and fix error on SharedStorage.delete() page
chrisdavidmills Oct 27, 2023
1de28cc
Merge branch 'main' into shared-storage-api
chrisdavidmills Nov 17, 2023
603ae92
Add enrollment information
chrisdavidmills Nov 17, 2023
c95f524
Update enrollment information in light of pythagoraskitty review
chrisdavidmills Nov 20, 2023
2356250
Remove enrollment exception criteria from register() as per review
chrisdavidmills Nov 21, 2023
502c2f3
Merge branch 'main' into shared-storage-api
chrisdavidmills Nov 21, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 1 addition & 6 deletions files/en-us/web/api/shared_storage_api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,12 +243,7 @@ Last, data in `localStorage` persists until manually cleared (`sessionStorage` i

## Enrollment and local testing

To use the Shared API in your sites, you must specify it in the [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment). If you don't do this, numerous sub-features will fail to run. Specifically:

- The {{domxref("WorkletSharedStorage.remainingBudget()")}} method
- : The promise returned by `remainingBudget()` rejects with a `TypeError` {{domxref("DOMException")}}.
- The {{domxref("WindowSharedStorage.run()")}} and {{domxref("WindowSharedStorage.selectURL()")}} methods
- : Promises returned by run and URL selection operations will reject with a `TypeError` {{domxref("DOMException")}}.
To use the Shared Storage API in your sites, you must specify it in the [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment). If you don't do this, none of the methods of the Shared Storage API will run successfully.

You can still test your Shared Storage API code locally without enrollment. To allow local testing, enable the following Chrome developer flag:

Expand Down
1 change: 1 addition & 0 deletions files/en-us/web/api/sharedstorage/append/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ A {{jsxref("Promise")}} that fulfills with `undefined`.
- In both cases, the `Promise` rejects with a {{jsxref("TypeError")}} if:
- The appended entry was not successfully stored in the database due to shared storage not being available (for example it is disabled using a browser setting).
- `key` and/or `value` exceed the browser-defined maximum length.
- The calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

> **Note:** In the case of {{domxref("WindowSharedStorage")}}, if the `append()` operation doesn't successfully write to the database for a reason other than shared storage not being available, no error is thrown — the operation still fulfills with `undefined`.

Expand Down
4 changes: 3 additions & 1 deletion files/en-us/web/api/sharedstorage/clear/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,9 @@ A {{jsxref("Promise")}} that fulfills with `undefined`.
### Exceptions

- In the case of {{domxref("WorkletSharedStorage")}}, the `Promise` rejects with a {{jsxref("TypeError")}} if the worklet module has not been added with {{domxref("Worklet.addModule", "SharedStorageWorklet.addModule()")}}.
- In both cases, the `Promise` rejects with a {{jsxref("TypeError")}} if the database was not cleared successfully due to shared storage not being available (for example it is disabled using a browser setting).
- In both cases, the `Promise` rejects with a {{jsxref("TypeError")}} if:
- The database was not cleared successfully due to shared storage not being available (for example it is disabled using a browser setting).
- The calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

> **Note:** In the case of {{domxref("WindowSharedStorage")}}, if the `clear()` operation doesn't successfully write to the database for a reason other than shared storage not being available, no error is thrown — the operation still fulfills with `undefined`.

Expand Down
1 change: 1 addition & 0 deletions files/en-us/web/api/sharedstorage/delete/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ A {{jsxref("Promise")}} that fulfills with `undefined`.
- In both cases, the `Promise` rejects with a {{jsxref("TypeError")}} if:
- The database was not cleared successfully due to shared storage not being available (for example it is disabled using a browser setting).
- `key` exceeds the browser-defined maximum length.
- The calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

> **Note:** If the key/value pair doesn't exist in the shared storage, no error is thrown — the operation still fulfills with `undefined`.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you want to put another note here like to match the notes in the three other setter/deleter methods, e.g.

> **Note:** In the case of {{domxref("WindowSharedStorage")}}, if the `delete()` operation doesn't successfully write to the database for a reason other than shared storage not being available, no error is thrown — the operation still fulfills with `undefined`.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pythagoraskitty Yes, good idea. I have done so.

Can you let me know if there are any other changes you think this PR needs? If not, give me an "LGTM", and I will consider it signed off on technical review, after which I can get someone on the MDN content team to give it a final editorial review.

Thanks!

Expand Down
1 change: 1 addition & 0 deletions files/en-us/web/api/sharedstorage/set/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ A {{jsxref("Promise")}} that fulfills with `undefined`.
- In both cases, the `Promise` rejects with a {{jsxref("TypeError")}} if:
- The created entry was not successfully stored in the database due to shared storage not being available (for example it is disabled using a browser setting).
- `key` and/or `value` exceed the browser-defined maximum length.
- The calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

> **Note:** In the case of {{domxref("WindowSharedStorage")}}, if the `set()` operation doesn't successfully write to the database for a reason other than shared storage not being available, no error is thrown — the operation still fulfills with `undefined`.

Expand Down
7 changes: 6 additions & 1 deletion files/en-us/web/api/sharedstorageworklet/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,12 @@ browser-compat: api.SharedStorageWorklet

The **`SharedStorageWorklet`** interface of the {{domxref("Shared Storage API", "Shared Storage API", "", "nocode")}} represents the current origin's shared storage worklet.

`SharedStorageWorklet` has no properties or methods directly defined on it; it inherits the {{domxref("Worklet.addModule", "addModule()")}} method from the {{domxref("Worklet")}} interface, which is used to add a module to it. Unlike a regular {{domxref("Worklet")}}, `SharedStorageWorklet` can only have a single module added to it, for privacy reasons. Subsequent calls to `addModule()` will reject.
`SharedStorageWorklet` has no properties or methods directly defined on it; it inherits the {{domxref("Worklet.addModule", "addModule()")}} method from the {{domxref("Worklet")}} interface, which is used to add a module to it. Unlike a regular {{domxref("Worklet")}}.

Note that:

- If the calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment), calls to `addModule()` will reject.
- `SharedStorageWorklet` can only have a single module added to it, for privacy reasons. Even with a successful enrollment, repeated calls to `addModule()` on the same shared storage worklet will reject.

`SharedStorageWorklet` is accessed via {{domxref("WindowSharedStorage.worklet")}}.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ None (`undefined`).
- An operation has already been registered with the specified name.
- The `operationCtor` is not a valid constructor.
- The class does not contain a valid `run()` method.
- The calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We actually don't check for register(), which won't get to run in any case if addModule() is rejected due to lack of enrollment. So you can leave this one out.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, removed.

- The worklet module has not been added with {{domxref("Worklet.addModule", "SharedStorageWorklet.addModule()")}}.

## Examples
Expand Down
5 changes: 5 additions & 0 deletions files/en-us/web/api/workletsharedstorage/entries/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@ None.

An array of the `WorkletSharedStorage`'s enumerable property key/value pairs.

### Exceptions

- {{jsxref("TypeError")}}
- : Thrown if the calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

## Examples

```js
Expand Down
1 change: 1 addition & 0 deletions files/en-us/web/api/workletsharedstorage/get/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ A {{jsxref("Promise")}} that fulfills with a string equal to the value of the re
- : Thrown if:
- The worklet module has not yet been added with {{domxref("Worklet.addModule", "addModule()")}}.
- `key` exceeds the browser-defined maximum length.
- The calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

## Examples

Expand Down
5 changes: 5 additions & 0 deletions files/en-us/web/api/workletsharedstorage/keys/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@ None.

An array of the `WorkletSharedStorage`'s enumerable property keys.

### Exceptions

- {{jsxref("TypeError")}}
- : Thrown if the calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).

## Examples

```js
Expand Down
1 change: 1 addition & 0 deletions files/en-us/web/api/workletsharedstorage/length/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ A {{jsxref("Promise")}} that fulfills with a number representing the number of k
- {{jsxref("TypeError")}}
- : Thrown if:
- The worklet module has not yet been added with {{domxref("Worklet.addModule", "addModule()")}}.
- The calling site does not have the Shared Storage API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).
- The browser fails to retrieve the number of entries for some other reason.

## Examples
Expand Down