文档:requestStorageAccessFor() 方法
Document 接口的 requestStorageAccessFor() 方法允许顶级站点代表源自同一相关网站集中另一个站点的嵌入内容请求第三方 Cookie 访问权限。它返回一个 Promise,如果访问权限被授予则解析,如果访问权限被拒绝则拒绝。
语法
requestStorageAccessFor(requestedOrigin)
参数
requestedOrigin-
一个字符串,表示你请求第三方 Cookie 访问权限的来源 URL。
返回值
一个 Promise,如果第三方 Cookie 访问权限被授予则以 undefined 履行,如果访问权限被拒绝则拒绝。
除非顶级内容当前正在处理用户手势(例如点击或轻触)(瞬时激活),或者之前已授予权限,否则 requestStorageAccessFor() 请求将自动被拒绝。如果之前未授予权限,则它们必须在基于用户手势的事件处理程序中运行。用户手势行为取决于 Promise 的状态
- 如果 Promise 解析(即,权限已授予),则用户手势未被消耗,因此脚本可以随后调用需要用户手势的 API。
- 如果 Promise 被拒绝(即,权限未授予),则用户手势已被消耗,因此脚本不能执行任何需要手势的操作。这可以防止脚本在权限被拒绝时再次调用
requestStorageAccessFor()。
异常
InvalidStateErrorDOMException-
如果当前的
Document尚未激活,则抛出此错误。 NotAllowedErrorDOMException-
在以下情况下抛出
- 文档的窗口不是安全上下文。
- 文档不是顶级文档。
- 文档的源为
null。 - 提供的
requestedOrigin是不透明的。 - 顶级站点和嵌入式站点不在同一相关网站集中。
- 嵌入的
是沙盒化的,并且未设置allow-storage-access-by-user-activation令牌。 - 用法被
storage-access权限策略阻止。 - 用户代理的 API 使用权限请求拒绝了用法。
TypeError-
如果
requestedOrigin不是有效的 URL,则抛出此错误。
描述
requestStorageAccessFor() 方法解决了在顶级站点上采用 Storage Access API 的挑战,这些站点使用需要 Cookie 的跨站点图像或脚本。它与默认阻止访问第三方、未分区 Cookie 以提高隐私(例如,防止跟踪)的用户代理相关,并且是 Storage Access API 的提议扩展。
requestStorageAccessFor() 可以为直接嵌入到顶级站点中的跨站点资源(例如 元素)启用第三方 Cookie 访问,这些资源无法自行请求存储访问权限。嵌入在 中具有自己的逻辑和资源并需要第三方 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 权限策略阻止(与控制 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
});
}
注意:有关更完整的示例,请参阅使用 Storage Access API。
规范
| 规范 |
|---|
| requestStorageAccessFor API # dom-document-requeststorageaccessfor |
浏览器兼容性
加载中…