Document: requestStorageAccess() メソッド

Baseline 2023

Newly available

Since December 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

requestStorageAccess() は Document インターフェイスのメソッドで、サードパーティコンテキスト（つまり <iframe> に埋め込まれたもの）に読み込まれたコンテンツが、サードパーティクッキーと分離されていない状態へのアクセスをリクエストできるようになります。これは、既定ではプライバシーを向上させるために（例えば、トラッキングを防ぐために）サードパーティの分離されていないクッキーへのアクセスをブロックしているユーザーエージェントに関連しており、ストレージアクセス API の一部です。

サードパーティクッキーにアクセスする権限が既に与えられているかどうかを調べるには、Permissions.query() を呼び出して、特性名 "storage-access"を指定してください。

メモ: この機能の使用は、サーバーに設定する storage-access 権限ポリシーによってブロックされる場合があります。さらに、文書は、許可リスト、ブロックリスト、端末上の分類、ユーザー設定、クリックジャッキング防止の経験則、またはユーザーに明示的な許可を求めるプロンプトのような、ブラウザー固有の追加のチェックに合格する必要があります。

構文

js
requestStorageAccess()
requestStorageAccess(types)

引数

types 省略可

分離されていないどの状態にアクセスするかを制御するプロパティを格納したオブジェクトです。指定しない場合、プロパティの既定値は false です。利用できるプロパティは以下のとおりです。

all

論理値で、利用可能なすべての分離されていない状態をアクセス可能にすべきかどうかを示します。

cookies

論理値で、サードパーティクッキーをアクセス可能にすべきかどうかを示します。

sessionStorage

論理値で、StorageAccessHandle.sessionStorage をアクセス可能にすべきかどうかを示します。

localStorage

論理値で、StorageAccessHandle.localStorage をアクセス可能にすべきかどうかを示します。

indexedDB

論理値で、StorageAccessHandle.indexedDB をアクセス可能にすべきかどうかを示します。

locks

論理値で、StorageAccessHandle.locks をアクセス可能にすべきかどうかを示します。

caches

論理値で、StorageAccessHandle.caches をアクセス可能にすべきかどうかを示します。

getDirectory

論理値で、StorageAccessHandle.getDirectory() をアクセス可能にすべきかどうかを示します。

estimate

論理値で、StorageAccessHandle.estimate() をアクセス可能にすべきかどうかを示します。

createObjectURL

論理値で、StorageAccessHandle.createObjectURL() をアクセス可能にすべきかどうかを示します。

revokeObjectURL

論理値で、StorageAccessHandle.revokeObjectURL() をアクセス可能にすべきかどうかを示します。

BroadcastChannel

論理値で、StorageAccessHandle.BroadcastChannel() をアクセス可能にすべきかどうかを示します。

SharedWorker

論理値で、StorageAccessHandle.SharedWorker() をアクセス可能にすべきかどうかを示します。

返値

Promise で、サードパーティクッキーへのアクセスが許可され、 types 引数が提供されていない場合は undefined で履行され、types 引数でリクエストされた分離されていない状態へのアクセスが提供された場合は StorageAccessHandle で履行され、アクセスが拒否された場合は拒否されます。

requestStorageAccess() のリクエストは、埋め込みコンテンツがタップやクリックなどのユーザージェスチャーを処理中（単発の活性化）でない限り、またはその権限が前回すでに付与されていない限り、自動的に拒否されます。その権限が前回付与されていない場合は、ユーザージェスチャーに基づくイベントハンドラー内で実行する必要があります。ユーザージェスチャーの動作は、プロミスの状態に依存します。

  • プロミスが解決され（権限が許可された場合など）、ユーザーのジェスチャーが消費されていない場合、スクリプトはユーザーのジェスチャーを必要とするすべての API を呼び出すことができます。
  • プロミスが拒否され（権限が許可されなかった場合など）、ユーザーのジェスチャーが消費されている場合、スクリプトはジェスチャーを必要とする API を呼び出すことができません。これは悪用に対する意図的な保護であり、ユーザーがプロンプトを受け入れるまで、スクリプトが requestStorageAccess() をループで呼び出すのを防ぐためです。

例外

InvalidStateError DOMException

次のような場合に発生します。

  • 現在の Document がまだアクティブではない場合。
  • types 引数が与えられており、すべてのプロパティが false である場合。
NotAllowedError DOMException

次のような場合に発生します。

  • 文書のウィンドウが安全なコンテキストではない場合。
  • storage-access 権限ポリシーによって、使用がブロックされた場合。
  • この文書または最上位の文書のオリジンが null である場合。
  • 埋め込まれた <iframe> がサンドボックス化されており、allow-storage-access-by-user-activation トークンが設定されていない場合。
  • ユーザーエージェントの権限リクエストにより、この API の使用が拒否された場合。

例

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

メモ: より完全な例については、ストレージアクセス API の使用を参照してください。

仕様書

Specification
The Storage Access API
# dom-document-requeststorageaccess

ブラウザーの互換性

BCD tables only load in the browser

関連情報