Document: requestStorageAccessFor() メソッド

構文

requestStorageAccessFor(requestedOrigin)

引数

requestedOrigin

サードパーティクッキーへのアクセスをリクエストするオリジンの URL を表す文字列です。

返値

Promise で、サードパーティクッキーへのアクセスが許可された場合は undefined で履行され、拒否された場合は拒否されます。

requestStorageAccessFor() のリクエストは、最上位のコンテンツがタップやクリックなどのユーザージェスチャーを処理中（一時的な有効化）でない限り、または権限がすでに付与されていない限り、自動的に拒否されます。権限が以前に付与されていない場合は、ユーザージェスチャーに基づくイベントハンドラー内で呼び出す必要があります。ユーザージェスチャーの扱いは、プロミスの状態によって異なります。

• プロミスが履行された場合（つまり、権限が許可された場合）、ユーザージェスチャーは消費されていないため、その後もスクリプトからユーザージェスチャーが必要な API を呼び出せます。
• プロミスが拒否された場合（つまり、権限が許可されなかった場合）、ユーザージェスチャーは消費されているため、スクリプトはユーザージェスチャーが必要な操作を行えません。これにより、権限が拒否された後にスクリプトが requestStorageAccessFor() を再度呼び出すことを防ぎます。

例外

InvalidStateError DOMException

現在の Document がまだアクティブでない場合に発生します。

NotAllowedError DOMException

次の場合に発生します。

• 文書のウィンドウが保護されたコンテキストではない場合。
• この文書が最上位の文書でない場合。
• 文書のオリジンが null の場合。
• 指定された requestedOrigin が不透明な場合。
• 最上位のサイトと埋め込み先のサイトが同じ関連ウェブサイトセットに属していない場合。
• 埋め込まれた <iframe> がサンドボックス化されており、allow-storage-access-by-user-activation トークンが設定されていない場合。
• storage-access 権限ポリシーによって使用がブロックされた場合。
• ユーザーエージェントの権限リクエストにより、この API の使用が拒否された場合。

TypeError

requestedOrigin が有効な 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",
});

例

function rSAFor() {
  if ("requestStorageAccessFor" in document) {
    document.requestStorageAccessFor("https://example.com").then(
      (res) => {
        // ストレージアクセスを使用
        doThingsWithCookies();
      },
      (err) => {
        // エラーを処理
      },
    );
  }
}

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) => {
      // 何らかの処理を行う
    });
}

仕様書

ブラウザーの互換性

関連情報

• Document.hasStorageAccess(), Document.hasUnpartitionedCookieAccess(), Document.requestStorageAccess()
• ストレージアクセス API の使用
• Introducing Storage Access API (WebKit blog)