Document: requestStorageAccessFor() メソッド

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",
});

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
    });
}

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