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() の呼び出しのためにその事実を保存。

上記のすべての要件が満たされていると仮定すると、Firefox は、ユーザーセッション存続期間の最大24時間で、現在のセッションのファーストパーティのオリジンのしきい値数まで、要求オリジンへのストレージアクセスを自動的に許可します。 要求オリジンがストレージアクセス許可の最大許容数を超えた後、同じ閲覧セッション中に requestStorageAccess() を呼び出すと、ユーザーにプロンプトします。

オリジンが取得できる同時ストレージアクセス許可の最大数は、現在のセッションでアクセスされた最上位オリジンの数の 1% または 5 のいずれか大きい方として現在定義されている正の整数です。 しきい値は eTLD+1 のレベルで適用されるため、例えば、foo.example.combar.example.com に対する2つのストレージアクセス許可は、制限に対する単一の例外としてのみカウントされます。

requestStorageAccess() 呼び出しの時点で、要求オリジンがストレージアクセスを持っている場合...

...最大値より少ないオリジン:

  • ユーザーにプロンプトしません。
  • オリジンには、現在の最上位オリジンに対する一時的なストレージアクセス許可が与えられます。
  • 要求オリジンのストレージにアクセスできるオリジンの数は、1ずつ増加します。
  • 一時ストレージアクセス許可は次のとおりです。
    • ブラウザーセッションの終了時に無効になります。
    • ディスクに永続化されません(例えば、ブラウザーがクラッシュすると持続しません)。
    • 長時間のブラウザーセッションの場合は、24時間後にリセットします。

...最大値以上のオリジン:

  • ユーザーにプロンプトします。
  • ユーザーが「許可」または「任意のサイトで許可」をクリックすると、要求は解決されます。
  • ユーザーが「許可しない」をクリックすると、ストレージアクセス要求は拒否され、要求オリジンは別のユーザーインタラクションを受け取ると再要求できます。
  • ユーザーがストレージを許可する場合、要求オリジンは現在の最上位オリジンの永続ストレージアクセス許可を与えられます。
  • 要求オリジンのストレージにアクセスできるオリジンの数は、1ずつ増加します。
  • 永続ストレージアクセスのパーミッションは次のとおりです。
    • ディスクに永続化され、将来のブラウザーセッションで有効のままになります。
    • 30日後にリセットします。

一時的または永続的なストレージアクセス許可が期限切れになると、要求オリジンのストレージアクセスを持つオリジンの数が1ずつ減ります。

: 要求オリジンが追跡オリジン(tracking origin)として分類されていない場合、アクセス要求には、ページがリロードされると消滅する一時的なストレージアクセス許可が自動的に付与されます。 この場合、ユーザーにはプロンプトが表示されないため、requestStorageAccess() を呼び出しても、Document.hasStorageAccess() によって返される値を変更する以外に副作用はありません。

デバッグ

ストレージアクセス許可のしきい値により、Firefox がユーザーにアクセスをプロンプトする条件の下でウェブサイトをテストすることがより難しくなる場合があります。 テストを簡単にするために、requestStorageAccess() 呼び出し時のプロンプトを制御する about:config に次の2つの設定を追加しました。

  • dom.storage_access.auto_grantsfalse に設定して、一時ストレージアクセス許可の自動許可を無効にすることができます。 追跡者(trackers)として分類されたオリジンによる requestStorageAccess() の呼び出しはすべて、プロンプトをトリガーします。
  • dom.storage_access.max_concurrent_auto_grants は、ユーザーがプロンプトを受け取り始めるストレージアクセス許可のしきい値数を制御します。 例えば、requestStorageAccess() が呼び出される最初のサイトでアクセスを自動的に許可し、その後プロンプトするように Firefox を構成する場合、dom.storage_access.max_concurrent_auto_grants 設定の値を 1 に調整する必要があります。

構文

var promise = document.requestStorageAccess();

引数

なし。

返値

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

Promise が解決されると、 Promise が満たされたか拒否されたかに関わらず、ユーザージェスチャーが処理されているかのように解決ハンドラーが実行されます。

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

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

仕様書

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

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
requestStorageAccess
実験的非標準
Chrome 完全対応 85Edge 完全対応 85Firefox 完全対応 65IE 未対応 なしOpera 完全対応 71Safari 完全対応 11.1WebView Android 完全対応 85Chrome Android 完全対応 85Firefox 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 完全対応 60Safari iOS 完全対応 11.3Samsung Internet Android 未対応 なし

凡例

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

関連情報

Storage Access API