diff --git a/files/en-us/web/api/document/hasstorageaccess/index.md b/files/en-us/web/api/document/hasstorageaccess/index.md index 3ac71359508e0c3..c9259cad9519126 100644 --- a/files/en-us/web/api/document/hasstorageaccess/index.md +++ b/files/en-us/web/api/document/hasstorageaccess/index.md @@ -8,7 +8,7 @@ browser-compat: api.Document.hasStorageAccess {{APIRef("Storage Access API")}} -The **`hasStorageAccess()`** method of the {{domxref("Document")}} interface returns a {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to unpartitioned cookies. +The **`hasStorageAccess()`** method of the {{domxref("Document")}} interface returns a {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to [third-party](/en-US/docs/Web/HTTP/Cookies#third-party_cookies), [unpartitioned](/en-US/docs/Web/API/Storage_Access_API#unpartitioned_versus_partitioned_cookies) cookies. This method is part of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API). @@ -24,12 +24,12 @@ None. ### Return value -A {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to unpartitioned cookies — `true` if it does, and `false` if not. +A {{jsxref("Promise")}} that resolves with a boolean value indicating whether the document has access to third-party cookies — `true` if it does, and `false` if not. The result returned by this method can be inaccurate in a couple of circumstances: -1. The user may have browser settings active that block unpartitioned cookies entirely — in this case `true` may be returned even though unpartitioned cookies are still inaccessible. To handle such a situation, you should gracefully handle any errors resulting in cookie values being unretrievable; for example, inform the user that access to their personalized settings is blocked and invite them to sign in again to use them. -2. The browser might not block third-party cookie access by default — in this case `false` may be returned even though unpartitioned cookies are accessible, and storage access wouldn't need to be requested (i.e. via {{domxref("Document.requestStorageAccess()")}}). To get around this issue, you could query {{domxref("Document.cookie")}} to find out whether your cookies are accessible, and call {{domxref("Document.requestStorageAccess()")}} if they are not. +1. The user may have active browser settings that block third-party cookies; in this case, `true` may be returned even though third-party cookies are still inaccessible. To handle such a situation, you should gracefully handle any errors resulting in cookie values being unretrievable; for example, inform the user that access to their personalized settings is blocked and invite them to sign in again to use them. +2. The browser might not block third-party cookie access by default; in this case, `false` may be returned even though third-party cookies are accessible, and storage access wouldn't need to be requested (i.e., via {{domxref("Document.requestStorageAccess()")}}). To get around this issue, you could query {{domxref("Document.cookie")}} to find out whether your cookies are accessible, and call {{domxref("Document.requestStorageAccess()")}} if they are not. > **Note:** If the promise gets resolved and a user gesture event was being processed when the function was originally called, the resolve handler will run as if a user gesture was being processed, so it will be able to call APIs that require user activation. @@ -63,5 +63,6 @@ document.hasStorageAccess().then((hasAccess) => { ## See also +- {{domxref("Document.requestStorageAccess()")}}, {{domxref("Document.requestStorageAccessFor()")}} - [Using the Storage Access API](/en-US/docs/Web/API/Storage_Access_API/Using) - [Introducing Storage Access API](https://webkit.org/blog/8124/introducing-storage-access-api/) (WebKit blog) diff --git a/files/en-us/web/api/document/index.md b/files/en-us/web/api/document/index.md index 64fb98e65c14255..7759df1ba63e1e0 100644 --- a/files/en-us/web/api/document/index.md +++ b/files/en-us/web/api/document/index.md @@ -256,6 +256,8 @@ _This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventT - : Replaces the existing children of a document with a specified new set of children. - {{DOMxRef("Document.requestStorageAccess()")}} - : Allows a document loaded in a third-party context (i.e. embedded in an {{htmlelement("iframe")}}) to request access to unpartitioned cookies, in cases where user agents by default block access to unpartitioned cookies by sites loaded in a third-party context to improve privacy. +- {{DOMxRef("Document.requestStorageAccessFor()")}} {{Non-standard_Inline}} + - : Allows top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same [related website set](/en-US/docs/Web/API/Storage_Access_API/Related_website_sets). - {{domxref("Document.startViewTransition()")}} {{Experimental_Inline}} - : Starts a new {{domxref("View Transitions API", "view transition", "", "nocode")}} and returns a {{domxref("ViewTransition")}} object to represent it. diff --git a/files/en-us/web/api/document/requeststorageaccess/index.md b/files/en-us/web/api/document/requeststorageaccess/index.md index 4fcb7225b83256b..1a96b61f79d78f3 100644 --- a/files/en-us/web/api/document/requeststorageaccess/index.md +++ b/files/en-us/web/api/document/requeststorageaccess/index.md @@ -8,9 +8,9 @@ browser-compat: api.Document.requestStorageAccess {{APIRef("Storage Access API")}} -The **`requestStorageAccess()`** method of the {{domxref("Document")}} interface allows a document loaded in a third-party context (i.e. embedded in an {{htmlelement("iframe")}}) to request access to unpartitioned cookies. +The **`requestStorageAccess()`** method of the {{domxref("Document")}} interface allows content loaded in a third-party context (i.e., embedded in an {{htmlelement("iframe")}}) to request access to third-party cookies. This is relevant to user agents that, by default, block access to [third-party](/en-US/docs/Web/HTTP/Cookies#third-party_cookies), [unpartitioned](/en-US/docs/Web/API/Storage_Access_API#unpartitioned_versus_partitioned_cookies) cookies to improve privacy (e.g., to prevent tracking), and is part of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API). -This is relevant to user agents that by default block access to unpartitioned cookies by sites loaded in a third-party context to improve privacy (e.g. to prevent tracking), and is part of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API). +To check whether permission to access third-party cookies has already been granted, you can call {{domxref("Permissions.query()")}}, specifying the feature name `"storage-access"`. > **Note:** Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, anti-[clickjacking](/en-US/docs/Glossary/Clickjacking) heuristics, or prompting the user for explicit permission. @@ -26,7 +26,7 @@ None. ### Return value -A {{jsxref("Promise")}} that fulfills with `undefined` if the access to unpartitioned cookies was granted, and rejects if access was denied. +A {{jsxref("Promise")}} that fulfills with `undefined` if the access to third-party cookies was granted, and rejects if access was denied. `requestStorageAccess()` requests are automatically denied unless the embedded content is currently processing a user gesture such as a tap or click ({{Glossary("transient activation")}}), or unless permission was already granted previously. If permission was not previously granted, they need to be run inside a user gesture-based event handler. The user gesture behavior depends on the state of the promise: @@ -70,5 +70,6 @@ document.requestStorageAccess().then( ## See also +- {{domxref("Document.hasStorageAccess()")}}, {{domxref("Document.requestStorageAccessFor()")}} - [Using the Storage Access API](/en-US/docs/Web/API/Storage_Access_API/Using) - [Introducing Storage Access API](https://webkit.org/blog/8124/introducing-storage-access-api/) (WebKit blog) diff --git a/files/en-us/web/api/document/requeststorageaccessfor/index.md b/files/en-us/web/api/document/requeststorageaccessfor/index.md new file mode 100644 index 000000000000000..236fb45c1d5fdff --- /dev/null +++ b/files/en-us/web/api/document/requeststorageaccessfor/index.md @@ -0,0 +1,120 @@ +--- +title: "Document: requestStorageAccessFor() method" +short-title: requestStorageAccessFor() +slug: Web/API/Document/requestStorageAccessFor +page-type: web-api-instance-method +status: + - non-standard +browser-compat: api.Document.requestStorageAccessFor +--- + +{{APIRef("Storage Access API")}}{{non-standard_header}} + +The **`requestStorageAccessFor()`** method of the {{domxref("Document")}} interface allows top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same [related website set](/en-US/docs/Web/API/Storage_Access_API/Related_website_sets). It returns a {{jsxref("Promise")}} that resolves if the access was granted, and rejects if access was denied. + +## Syntax + +```js-nolint +requestStorageAccessFor(requestedOrigin) +``` + +### Parameters + +- `requestedOrigin` + - : A string representing the URL of the origin you are requesting third-party cookie access for. + +### Return value + +A {{jsxref("Promise")}} that fulfills with `undefined` if the access to third-party cookies was granted and rejects if access was denied. + +`requestStorageAccessFor()` requests are automatically denied unless the embedded content is currently processing a user gesture such as a tap or click ({{Glossary("transient activation")}}), or unless permission was already granted previously. If permission was not previously granted, they must run inside a user gesture-based event handler. The user gesture behavior depends on the state of the promise: + +- If the promise resolves (i.e., permission was granted), then the user gesture has not been consumed, so the script can subsequently call APIs requiring a user gesture. +- If the promise is rejected (i.e., permission was not granted), then the user gesture has been consumed, so the script can't do anything that requires a gesture. This prevents scripts from calling `requestStorageAccessFor()` again if permission is denied. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the current {{domxref("Document")}} is not yet active. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if: + - The document's window is not a [secure context](/en-US/docs/Web/Security/Secure_Contexts). + - The document is not the top-level document. + - The document has a `null` origin. + - The supplied `requestedOrigin` is [opaque](https://html.spec.whatwg.org/multipage/browsers.html#concept-origin-opaque). + - The top-level and embedded sites are not in the same [related website set](/en-US/docs/Web/API/Storage_Access_API/Related_website_sets). + - The embedding {{htmlelement("iframe")}} is sandboxed, and the `allow-storage-access-by-user-activation` token is not set. + - Usage is blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - Usage is denied by the user agent's permission request to use the API. +- `TypeError` + - : Thrown if `requestedOrigin` is not a valid URL. + +## Description + +The `requestStorageAccessFor()` method addresses challenges in adopting the Storage Access API on top-level sites that use cross-site images or scripts requiring cookies. It is relevant to user agents that by default block access to [third-party](/en-US/docs/Web/HTTP/Cookies#third-party_cookies), [unpartitioned](/en-US/docs/Web/API/Storage_Access_API#unpartitioned_versus_partitioned_cookies) cookies to improve privacy (e.g. to prevent tracking), and is a proposed extension of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API). + +`requestStorageAccessFor()` can enable third-party cookie access for cross-site resources directly embedded into a top-level site that are unable to request storage access themselves, for example {{htmlelement("img")}} elements. Cross-site content embedded in `