Document.requestStorageAccess()

requestStorageAccess()Document インターフェイスのメソッドで、ファーストパーティのストレージへのアクセスが許可されたら解決し、アクセスが拒否されたら拒絶される Promise を返します。

ストレージへのアクセスが許可される条件

ストレージへのアクセスは、以下の一連のチェックに基づいて許可されます。

  1. 文書がすでにアクセスを許可されていれば、解決。
  2. 文書にのオリジンが null であれば、拒絶。
  3. 文書のフレームが主フレームであれば、解決。
  4. 副フレームのオリジンが主フレームのものと同じであれば、解決。
  5. 副フレームがサンドボックス化されていなければ、7へ飛ぶ。
  6. 副フレームにトークン allow-storage-access-by-user-activation がなければ、拒絶。
  7. 副フレームの親フレームが最上位フレームでなければ、拒絶。
  8. ブラウザーがユーザー操作を処理中でなければ、拒絶。
  9. ブラウザーが持っている追加の規則をチェック。例えば、ホワイトリスト、ブラックリスト、端末上の分類、ユーザー設定、クリックジャック防止の推測、ユーザーへの明示的な許可の確認など。いくつかの規則が満たされていなければ、拒絶。
  10. 文書にクッキーやその他のサイトストレージへのアクセスを許可し、将来の Document.hasStorageAccess() および requestStorageAccess() の呼び出しのためにその事実を保存。

Assuming all of the requirements above are satisfied, Firefox will automatically grant storage access to the requesting origin on up to a threshold number of first-party origins in the current session for the duration of user’s session, up to a maximum of 24 hours. After the requesting origin has exceeded the maximum allowable number of storage access grants, any future call to requestStorageAccess() during the same browsing session will prompt the user.

The maximum number of concurrent storage access grants an origin can obtain is a positive integer currently defined as one percent of the number of top-level origins visited in the current session or 5, whichever is higher. The threshold is enforced on the level of eTLD+1, so for example two storage access grants for foo.example.com and bar.example.com will only count as a single exception against the limit.

At the time of a requestStorageAccess() call, if the requesting origin has storage access to...

...fewer origins than the maximum:

  • The user is not prompted.
  • The origin is given an ephemeral storage access grant for the current top-level origin.
  • The number of origins the requesting origin has storage access to is incremented by one.
  • The ephemeral storage access grant is:
    • Invalidated at the end of the browser session.
    • Not persisted to disk (e.g. will not persist if the browser crashes).
    • Reset after 24 hours in the case of a long-running browser session.

...equal or more origins than the maximum:

  • The user is prompted
  • If the user clicks “Allow” or “Allow on any site” the request is resolved.
  • If the user clicks “Don’t Allow”, the storage access request is rejected and the requesting origin can re-request once it receives another user interaction.
  • If the user allows storage the requesting origin is given a persistent storage access grant on the current top-level origin.
  • The number of origins the requesting origin has storage access to is incremented by one.
  • The persistent storage access permission is:
    • Persisted to disk and will remain valid in future browser sessions.
    • Reset after 30 days.

When an ephemeral or persistent storage access grant expires, the number of origins the requesting origin has storage access to is decremented by one.

Note: If the requesting origin is not classified as a tracking origin, the access request is automatically given an ephemeral storage access grant, which will go away when the page is reloaded. The user is never shown a prompt in this case, and calling requestStorageAccess() won’t have any side effects besides changing the value returned by Document.hasStorageAccess().

デバッグ

The storage access grant threshold may make it more difficult to test your website under the condition where Firefox prompts the user for access. To make testing easier, we have added two preferences in about:config that control prompting upon requestStorageAccess() calls:

  • dom.storage_access.auto_grants can be set to false to disable the automatic granting of ephemeral storage access grants. All calls to requestStorageAccess() by origins classified as trackers will trigger a prompt.
  • dom.storage_access.max_concurrent_auto_grants controls the threshold number of storage access grants at which users will begin to receive prompts. For example, if you want to configure Firefox to automatically grant access on the first site where requestStorageAccess() is called and then prompt afterwards, you should adjust the value of the dom.storage_access.max_concurrent_auto_grants preference to 1.

構文

Promise<void> requestStorageAccess()

引数

なし。

返値

ファーストパーティのストレージへのアクセスが許可されたら満たされ、アクセスが拒否されたら拒絶される Promise です。

Promise が解決されると、 Promise が満たされた場合にも拒否された場合にも、ユーザー操作が処理された時のような解決ハンドラーが実行されます。

  • 前者の場合、コードがユーザーのアクティベーションが必要な API を呼び出し始め、物事を前に進めることができます。
  • 後者の場合、コードはユーザーになぜリクエストに失敗したのか、何を続けることができるかを知らせるために実行することができます (例えば、必要な場合はログインを促すなど)。

document.requestStorageAccess().then(
  () => { console.log('access granted') },
  () => { console.log('access denied') }
);

仕様書

この API はまだ提案段階にあります。 — 標準化プロセスはまだ始まっていません。現在のところ、この API の詳細の仕様書は、アップルのブログ投稿の Introducing Storage Access API、および WHATWG HTML issue 338 — Proposal: Storage Access API で見ることができます。

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
requestStorageAccess
実験的非標準
Chrome 未対応 なしEdge 未対応 なしFirefox 完全対応 65IE 未対応 なしOpera 未対応 なしSafari 完全対応 11.1
補足
完全対応 11.1
補足
補足 Currently only available on macOS High Sierra 10.13.4 beta, and in Safari Technology Preview 47+.
WebView Android 未対応 なしChrome Android 未対応 なしFirefox Android 完全対応 65
無効
完全対応 65
無効
無効 From version 65: this feature is behind the dom.storage_access.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android 未対応 なしSafari iOS 完全対応 11.1
補足
完全対応 11.1
補足
補足 Currently only available on iOS 11.3 beta.
Samsung Internet Android ?

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
実験的。動作が変更される可能性があります。
実験的。動作が変更される可能性があります。
非標準。ブラウザー間の互換性が低い可能性があります。
非標準。ブラウザー間の互換性が低い可能性があります。
実装ノートを参照してください。
実装ノートを参照してください。
ユーザーが明示的にこの機能を有効にしなければなりません。
ユーザーが明示的にこの機能を有効にしなければなりません。

関連情報

Storage Access API