The requestStorageAccess()
method of the Document
interface allows content loaded in a third-party context (i.e., embedded in an <iframe>
) to request access to third-party cookies and unpartitioned state. This is relevant to user agents that, by default, block access to third-party, unpartitioned cookies to improve privacy (e.g., to prevent tracking), and is part of the Storage Access API.
To check whether permission to access third-party cookies has already been granted, you can call Permissions.query()
, specifying the feature name "storage-access"
.
Note: Usage of this feature may be blocked by a storage-access
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 heuristics, or prompting the user for explicit permission.
requestStorageAccess()
requestStorageAccess(types)
A Promise
that fulfills with undefined
if the access to third-party cookies was granted and no types
parameter was provided, fulfills with StorageAccessHandle
if the access to unpartitioned state requested by the types
parameter was provided, 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 (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:
- If the promise resolves (i.e. if permission was granted), then the user gesture has not been consumed, so the script can subsequently call APIs that require a user gesture.
- If the promise rejects (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 is intentional protection against abuse — it prevents scripts from calling
requestStorageAccess()
in a loop until the user accepts the prompt.
document.requestStorageAccess().then(
() => {
console.log("cookie access granted");
},
() => {
console.log("cookie access denied");
},
);
document.requestStorageAccess({ localStorage: true }).then(
(handle) => {
console.log("localStorage access granted");
handle.localStorage.setItem("foo", "bar");
},
() => {
console.log("localStorage access denied");
},
);