Document: requestStorageAccess() method

Syntax

requestStorageAccess()
requestStorageAccess(types)

Parameters

types Optional

An object containing properties that control what unpartitioned state is made accessible. If not specified, the default value of the property is false. Available properties are as follows:

all

A boolean specifying all possible unpartitioned states should be made accessible.

cookies

A boolean specifying third-party cookies should be made accessible.

sessionStorage

A boolean specifying StorageAccessHandle.sessionStorage should be made accessible.

localStorage

A boolean specifying StorageAccessHandle.localStorage should be made accessible.

indexedDB

A boolean specifying StorageAccessHandle.indexedDB should be made accessible.

locks

A boolean specifying StorageAccessHandle.locks should be made accessible.

caches

A boolean specifying StorageAccessHandle.caches should be made accessible.

getDirectory

A boolean specifying StorageAccessHandle.getDirectory() should be made accessible.

estimate

A boolean specifying StorageAccessHandle.estimate() should be made accessible.

createObjectURL

A boolean specifying StorageAccessHandle.createObjectURL() should be made accessible.

revokeObjectURL

A boolean specifying StorageAccessHandle.revokeObjectURL() should be made accessible.

BroadcastChannel

A boolean specifying StorageAccessHandle.BroadcastChannel() should be made accessible.

SharedWorker

A boolean specifying StorageAccessHandle.SharedWorker() should be made accessible.

Return value

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.

Exceptions

InvalidStateError DOMException

Thrown if:

• The current Document is not yet active.
• The types parameter is provided and all of its properties are false.

NotAllowedError DOMException

Thrown if:

• The document's window is not a secure context.
• Usage is blocked by a storage-access Permissions Policy.
• The document or the top-level document has a null origin.
• The embedding <iframe> is sandboxed, and the allow-storage-access-by-user-activation token is not set.
• Usage is denied by the user agent's permission request to use the API.

Examples

Basic usage

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");
  },
);

Specifications

Browser compatibility

See also

• Document.hasStorageAccess(), Document.hasUnpartitionedCookieAccess(), Document.requestStorageAccessFor()
• Using the Storage Access API
• Introducing Storage Access API (WebKit blog)