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
権限ポリシーによってブロックされる場合があります。さらに、文書は、許可リスト、ブロックリスト、端末上の分類、ユーザー設定、クリックジャッキング防止の経験則、またはユーザーに明示的な許可を求めるプロンプトのような、ブラウザー固有の追加のチェックに合格する必要があります。
構文
requestStorageAccess()
requestStorageAccess(types)
引数
types
省略可-
分離されていないどの状態にアクセスするかを制御するプロパティを格納したオブジェクトです。指定しない場合、プロパティの既定値は
false
です。利用できるプロパティは以下のとおりです。all
-
論理値で、利用可能なすべての分離されていない状態をアクセス可能にすべきかどうかを示します。
-
論理値で、サードパーティクッキーをアクセス可能にすべきかどうかを示します。
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()
をアクセス可能にすべきかどうかを示します。 -
論理値で、
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 の使用が拒否された場合。
例
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