Document: requestStorageAccessFor() メソッド

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

requestStorageAccessFor()Document インターフェイスのメソッドで、最上位のサイトが、同じ一連の関連ウェブサイト内の別のサイトを元とする埋め込みコンテンツに代わって、サードパーティのクッキーへのアクセスをリクエストできるようにします。アクセスが許可された場合は解決されたプロミス (Promise) を返し、アクセスが拒否された場合は拒否されたプロミスを返します。

構文

js
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() の呼び出しでは、埋め込みオリジンを指定する必要があります。例えば、次のようにします。

js
navigator.permissions.query({
  name: "top-level-storage-access",
  requestedOrigin: "https://www.example.com",
});

メモ: この機能の使用は、サーバーに設定する storage-access 権限ポリシー(ストレージアクセス API の残りの部分をコントロールするものと同じ)によってブロックされる可能性があります。さらに、許可リスト、ブロックリスト、端末上の分類、ユーザー設定、アンチクリックジャッキングの経験則など、 ブラウザー独自のチェックも通過しなければなりません。

js
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" 属性を記載しなければなりません。

例えば、次のようにします。

js
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

関連情報