Document: requestStorageAccessFor() メソッド
Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。
requestStorageAccessFor()
は Document
インターフェイスのメソッドで、最上位のサイトが、同じ一連の関連ウェブサイト内の別のサイトを元とする埋め込みコンテンツに代わって、サードパーティのクッキーへのアクセスをリクエストできるようにします。アクセスが許可された場合は解決されたプロミス (Promise
) を返し、アクセスが拒否された場合は拒否されたプロミスを返します。
構文
requestStorageAccessFor(requestedOrigin)
引数
requestedOrigin
-
文字列で、サードパーティクッキーアクセスをリクエストされたオリジンの URL を表します。
返値
Promise
で、サードパーティクッキーが許可された場合は undefined
で履行され、アクセスが拒否された場合は拒否されます。
requestStorageAccessFor()
のリクエストは、埋め込みコンテンツがタップやクリックなどのユーザージェスチャーを処理中(単発の活性化)でない限り、またはその権限が前回すでに付与されていない限り、自動的に拒否されます。その権限が前回付与されていない場合は、ユーザージェスチャーに基づくイベントハンドラー内で実行する必要があります。ユーザージェスチャーの動作は、プロミスの状態に依存します。
- プロミスが解決され(権限が許可された場合など)、ユーザーのジェスチャーが消費されていない場合、スクリプトはユーザーのジェスチャーを必要とするすべての API を呼び出すことができます。
- プロミスが拒否され(権限が許可されなかった場合など)、ユーザーのジェスチャーが消費されている場合、スクリプトはジェスチャーを必要とする API を呼び出すことができません。権限が拒否された場合に
requestStorageAccessFor()
を再び呼び出すのを防ぐためです。
例外
InvalidStateError
DOMException
-
現在の
Document
がまだアクティブ化されたいない場合に発生します。 NotAllowedError
DOMException
-
Thrown if:
- 文書のウィンドウが安全なコンテキストではない場合。
- この文書が最上位の文書でない場合。
- この文書のオリジンが
null
であった場合。 - 指定された
requestedOrigin
が不透明であった場合。 - 最上位のサイトと埋め込まれたサイトが同じ関連する一連のウェブサイトでない場合。
- 埋め込まれた
<iframe>
がサンドボックス化されており、allow-storage-access-by-user-activation
トークンが設定されていない場合。 storage-access
権限ポリシーによって、使用がブロックされた場合。- ユーザーエージェントの権限リクエストにより、この API の使用が拒否された場合。
TypeError
-
Thrown if
requestedOrigin
is not a valid URL.
解説
requestStorageAccessFor()
メソッドは、クッキーを必要とする別サイトの画像やスクリプトを使用している最上位のサイトでストレージアクセス API を採用する際の課題に対処します。既定ではプライバシーを改善するために(例えばトラッキングを防ぐために)サードパーティの分離されていないクッキーへのアクセスをブロックしているユーザエージェントに関連しており、ストレージアクセス API の拡張提案です。
requestStorageAccessFor()
は、例えば <img>
要素など、ストレージアクセスをリクエストすることができない最上位サイトに直接埋め込まれた別サイトのリソースに対して、サードパーティのクッキーアクセスを有効にすることができます。自分自身でロジックとリソースを保有し、サードパーティのクッキーアクセスを必要とする <iframe>
に埋め込まれた別サイトのコンテンツは、Document.requestStorageAccess()
を介してストレージアクセスをリクエストする必要があります。
サードパーティのクッキーにアクセスする権限が requestStorageAccessFor()
によって既に付与されているかどうかを調べるには、Permissions.query()
を呼び出します。その際、機能名 "top-level-storage-access"
を指定します。これは通常の Document.requestStorageAccess()
メソッドで使用する機能名とは異なり、"storage-access"
です。
Permissions.query()
の呼び出しでは、埋め込みオリジンを指定する必要があります。例えば、次のようにします。
navigator.permissions.query({
name: "top-level-storage-access",
requestedOrigin: "https://www.example.com",
});
メモ:
この機能の使用は、サーバーに設定する storage-access
権限ポリシー(ストレージアクセス API の残りの部分をコントロールするものと同じ)によってブロックされる可能性があります。さらに、許可リスト、ブロックリスト、端末上の分類、ユーザー設定、アンチクリックジャッキングの経験則など、 ブラウザー独自のチェックも通過しなければなりません。
例
function rSAFor() {
if ("requestStorageAccessFor" in document) {
document.requestStorageAccessFor("https://example.com").then(
(res) => {
// Use storage access
doThingsWithCookies();
},
(err) => {
// Handle errors
},
);
}
}
requestStorageAccessFor()
の呼び出しが成功した後、CORS / crossorigin
を含む場合、クロスサイトリクエストはクッキーを入れることができます。このようなリクエストは credentials: "include"
オプションを用い、リソースは crossorigin="use-credentials"
属性を記載しなければなりません。
例えば、次のようにします。
function checkCookie() {
fetch("https://example.com/getcookies.json", {
method: "GET",
credentials: "include",
})
.then((response) => response.json())
.then((json) => {
// Do something
});
}
メモ: より完全な例については、ストレージアクセス API の使用を参照してください。
仕様書
Specification |
---|
requestStorageAccessFor API # dom-document-requeststorageaccessfor |
ブラウザーの互換性
BCD tables only load in the browser