Document: requestStorageAccessFor() 方法

实验性： 这是一个实验性技术
在生产环境中使用此功能之前，请仔细查看浏览器兼容性表。

Document 接口的 requestStorageAccessFor() 方法允许顶级站点代表来自同一相关网站集中其他站点的嵌入内容请求第三方 Cookie 访问权限。它返回一个Promise，如果访问权限被授予则解析，如果访问权限被拒绝则拒绝。

语法

requestStorageAccessFor(requestedOrigin)

参数

requestedOrigin: 表示您正在请求第三方 Cookie 访问权限的源的 URL 的字符串。

返回值

一个Promise，如果授予了对第三方 Cookie 的访问权限，则以undefined完成，如果拒绝访问则拒绝。

除非顶级内容当前正在处理用户手势（例如点击或轻触）（瞬时激活），或者除非之前已授予权限，否则requestStorageAccessFor()请求会自动被拒绝。如果之前未授予权限，则它们必须在基于用户手势的事件处理程序内运行。用户手势行为取决于 promise 的状态

如果 promise 解析（即授予了权限），则用户手势尚未被使用，因此脚本随后可以调用需要用户手势的 API。
如果 promise 被拒绝（即未授予权限），则用户手势已被使用，因此脚本无法执行任何需要手势的操作。这可以防止脚本在权限被拒绝时再次调用requestStorageAccessFor()。

异常

InvalidStateError DOMException

如果当前Document尚未激活，则抛出此异常。

NotAllowedError DOMException

如果

文档的窗口不是安全上下文。
文档不是顶级文档。
文档具有null源。
提供的requestedOrigin是不透明的。
顶级站点和嵌入式站点不在同一相关网站集中。
嵌入的<iframe>已沙盒化，并且未设置allow-storage-access-by-user-activation令牌。
使用被storage-access 权限策略阻止。
用户代理对使用 API 的权限请求予以拒绝。

TypeError

如果requestedOrigin不是有效的 URL，则抛出此异常。

描述

requestStorageAccessFor()方法解决了在使用跨站点图像或需要 Cookie 的脚本的顶级站点上采用存储访问 API 时遇到的挑战。它与默认情况下阻止访问第三方、未分区 Cookie 以提高隐私（例如，为了防止跟踪）的用户代理相关，并且是存储访问 API的提议扩展。

requestStorageAccessFor()可以为直接嵌入到顶级站点中的跨站点资源启用第三方 Cookie 访问权限，这些资源本身无法请求存储访问权限，例如<img>元素。嵌入在<iframe>中的跨站点内容具有其自身的逻辑和资源，并且需要第三方 Cookie 访问权限，应通过Document.requestStorageAccess()请求存储访问权限。

要检查是否已通过requestStorageAccessFor()授予访问第三方 Cookie 的权限，您可以调用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，则它们将包含 Cookie，因此站点可能需要等待然后再触发请求。此类请求必须使用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。

规范

规范
requestStorageAccessFor API # dom-document-requeststorageaccessfor

浏览器兼容性

BCD 表仅在启用 JavaScript 的浏览器中加载。

另请参阅

Document.hasStorageAccess()、Document.hasUnpartitionedCookieAccess()、Document.requestStorageAccess()
使用存储访问 API
介绍存储访问 API（WebKit 博客）