解决元标记、标头和脚本中试用令牌的常见问题。
核对清单
如需排查源试用问题,请使用所提供的链接解决以下问题。
试试看!
以下演示显示了提供源试用令牌和访问试用功能的各种方法:
- ot-meta.glitch.me:
origin-trial
元标记中的令牌 - ot-header.glitch.me:
Origin-Trial
响应标头中的令牌 - ot-3p.glitch.me:由第三方脚本注入的令牌
- ot-iframe.glitch.me:可在 iframe 中访问的源试用功能
- ot-iframe-3p.glitch.me:跨源 iframe 示例
使用 Chrome 开发者工具检查令牌
从 Chrome 93 开始,开发者工具会在“应用”面板中为所选帧提供源试用信息。
展开顶部帧以检查可用于子帧的源试用令牌。例如,对于 ot-iframe.glitch.me 演示页面,您可以看到 iframe 中的页面提供了一个令牌。
- 令牌状态:相应网页是否具备有效的令牌。请注意,对于某些源试用,可能还有其他因素(例如地理位置限制)。这意味着,即使存在有效的令牌,源试用功能仍不可用。Chrome 开发者工具状态代码说明了源试用每个代码的含义。
- 来源:为令牌注册的网络来源。
- Expiry Time:令牌的可能最远(最晚)到期日/时间,通常与试验的结束时间相一致。此日期与我的注册中显示的令牌的“有效期”日期不同,后者显示令牌当前的有效时长,可以延长。
- 使用限制:使用限制,可以为某些试验设置。
- 第三方:是否为令牌启用了第三方匹配。这适用于某些源试用(需要通过第三方脚本在多个网站上使用试用功能)。
- Match Sub-Domains(匹配子网域):是否为令牌启用了子网域匹配。这样,就可以在源站的多个子网域上测试源试用功能,而无需为每个子网域使用不同的令牌。
如果试用版不适用于当前用户、令牌已过期或存在其他限制,Chrome 开发者工具会在试用版名称旁边显示一条警告。
Chrome 开发者工具状态代码
已过期:令牌的到期日期已过。需要续期令牌以生成具有新到期日期的新令牌。
源代码FeatureDisabled:目前已停用试用版。
源代码FeatureDisabledForUser:已通过替代使用限制将此令牌指定为对当前用户停用。请参阅设计文档的“用户子集排除”部分。
源代码 1
源代码 2不安全:请求来源不安全,并且无法针对不安全的来源启用试用。 如源试用令牌验证器代码中所述:“对于第三方令牌,当前源和脚本源都必须是安全的。由于子网域匹配,令牌来源可能与提供的脚本来源之一不完全匹配,并且结果不会指明匹配的特定来源。也就是说,查找适当的脚本来源并不是直接查找,为避免重复执行所有源站比较,一些快捷方式取决于所提供的脚本源数量。必须至少有一个,否则第三方令牌将无法成功验证。
源代码InvalidSignature:令牌的签名无效或格式错误。
源代码格式错误:令牌格式错误,无法解析。
源代码
NotSupported:由令牌定义的源试用在 Chromium“embedder”(Chrome 或 Edge 等浏览器、WebView 或其他一些用户代理)中不受支持。
源代码成功:令牌格式正确、未过期、与源试用功能匹配,并且是从预期源请求的。
源代码TokenDisabled:令牌已被标记为已停用,无法使用。
源代码UnknownTrial:该令牌指定的功能名称与任何已知试验都不匹配。
源代码WrongOrigin:请求来源与令牌中指定的来源不匹配。这可以包括架构、主机名或端口。如果在 HTTP 标头、元标记或内嵌脚本中提供第三方令牌,而不是通过外部 JavaScript 文件提供,则系统也会显示此状态。
源代码WrongVersion:令牌版本错误:目前仅支持令牌版本 2 和 3。
源代码
无法正常运行!🤔
如果您的源试用无法按预期运行,请确保您已满足以下条件。
您在 Chrome(而非 Chromium 或其他浏览器)中进行测试
Chrome 源试用面向 Chrome 用户。请勿依赖 Chrome 源试用令牌在其他浏览器(包括 Chromium 和其他基于 Chromium 的浏览器)中启用试用功能。这是因为 Chrome 源试用专门针对 Chrome 中提供的用于实验的功能。
您还可在 Firefox 和 Microsoft Edge 中使用源试用。注册 Firefox 或 Edge 源试用不会启用 Chrome 中的功能。
已针对访问您网站的 Chrome 版本启用源试用
仅特定版本的 Chrome 可以参与试用。在某些情况下,这可能意味着试用功能仅面向稳定版 Chrome 渠道提供:Canary 版、开发版和 Beta 版。
您可以在此试用的注册页面查看版本可用性:
您可以访问 chrome://version 查看您当前使用的 Chrome 版本。
Chrome 设置未停用源试用
如果个别用户报告某项功能对他们没有帮助,请检查其 Chrome 设置中是否停用了该功能。例如,您可以从 chrome://settings/privacySandbox
页面停用 Privacy Sandbox 功能。
关键字和语法正确
请确保为源试用令牌使用合适的关键字和语法。
对于第一方使用情形,可以在 origin-trial
元标记中提供令牌:
<meta http-equiv="origin-trial" content="Aj4DysCv3VjknU3...">
或者,您也可以在 Origin-Trial
响应标头中提供令牌。以下是在 Node.js 中使用 Express 的示例:
app.use(function(req, res, next) {
res.setHeader('Origin-Trial', 'Aj4DysCv3VjknU3...')
next();
});
也可以使用 JavaScript 提供令牌:
function addTrialToken(tokenContents) {
const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = tokenContents;
document.head.appendChild(tokenElement);
}
第一方令牌来源与网页来源匹配
请确保在注册试用时选择的 Web Origin 值与具有提供令牌的元标记或标头的网页的来源一致。
例如,如果您选择 https://example.com
作为网络来源:
您可能会获得如下令牌值:
检查此值是否与您要排查问题的页面上使用的令牌一致。
有关元标记中提供的令牌,请查看 HTML:
<meta http-equiv="origin-trial" content="Aj4DysCv3VjknU3...">
对于标头中提供的令牌,您可以在 Chrome 开发者工具 Network 面板中的 Response Headers 下查看令牌值:
第一方令牌由使用该令牌的来源提供
若要针对由您的来源提供的网页中所含的代码启用源试用功能的访问权限,请在元标记、标头中或通过同一来源的 JavaScript 提供试用令牌。
为令牌注册的来源必须与提供该令牌的来源一致。
第三方令牌来源与脚本来源匹配
对于已注入到其他来源的脚本,您可以注册参与源试用。
例如,如果您希望通过 javascript-library.example
提供的脚本参与源试用,则需要通过第三方匹配功能为 javascript-library.example
注册令牌。
第三方令牌的来源值必须与注入该令牌的脚本的来源一致。
第三方脚本使用了第三方令牌
仅仅为您的源(而非该脚本)注册令牌,就不能让第三方脚本在您的网站上参与源试用。
第三方脚本需要使用启用了第三方匹配功能的令牌,这些令牌使用如下代码通过脚本本身注入(不包含在网站的元标记或标头中):
function addTrialToken(tokenContents) {
const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = tokenContents;
document.head.appendChild(tokenElement);
}
第三方令牌通过外部脚本提供,而非通过元标记、HTTP 标头或内嵌脚本提供
第三方令牌根据注入这些令牌的脚本的来源进行验证,但静态标记中的内嵌脚本和 <meta>
标记没有来源(即来源网址)。
这意味着第三方令牌必须通过外部脚本提供,而不是通过 <meta>
标记或内嵌脚本提供。注入令牌的外部脚本与包含网页的来源相同,还是不同的来源无关紧要,只要脚本的来源与针对试验注册的来源匹配即可。
您可以在 ot-iframe-3p.glitch.me 上观看相关演示。
用于提供试用令牌的方法支持源试用功能访问权限
如要使用某些类型的源试用功能,您必须以特定方式提供试用令牌。
例如,为 Service Worker 和共享工作器启用源试用访问权限的唯一方法是在 Origin-Trial
标头中提供令牌。
已为子网域使用的令牌启用子网域匹配
如果源试用功能似乎无法用于您网站上的某些网页,请检查提供令牌的子网域是否设置正确。
在注册参与源试用时,您可以选择匹配源网域的所有子网域:
您还可以为第三方令牌匹配子网域:
对于公共后缀列表中的源,不会颁发子网域令牌。例如,您无法注册 https://appspot.com 或 https://github.io 之类的来源,但您可以注册该来源中的网域(例如 https://example.appspot.com 或 https://example.github.io)。
该令牌仍然有效
令牌的有效期为创建六周。除此之外,您必须提交反馈才能将有效期延长至。面向 Web 开发者的源试用指南介绍了如何确保您的令牌在整个源试用内有效。
您可以在 Chrome 源试用的“我的注册”页面上查看有效令牌:
如果令牌仍然有效,Chrome 开发者工具会显示状态 Success
:
如果您的令牌已过期,开发者工具将显示 Expired
状态,“我的注册”页面将显示 Expired Tokens 部分。
源试用尚未结束
您可以在注册页面查看源试用的结束日期:
对于已结束的试验,开发者工具会显示如下内容:
当需要提供反馈或令牌即将过期时,系统会自动向您发送一封电子邮件,但并非试用结束时。
当前用户可进行源试用
即使提供了有效的令牌,某些用户也无法使用部分源试用。
如果当前用户无法试用,Chrome 开发者工具会显示 TrialNotAllowed
警告:
我们会针对每个源试用提供有关使用限制和可用情况的信息。
与任何网络平台功能一样,您应该使用功能检测功能来确认源试用功能是否受支持,然后再使用该功能。
未超出源试用使用限制
默认情况下,只要网页具有有效的试用令牌,系统就会启用源试用功能。
不过,除非在极少数情况下,否则源试用的用量最多只能占 Chrome 网页加载的 0.5%。 如果所有 Chrome 用户的总用量超过此限额,源试用功能将停用。 开发者工具会将令牌状态显示为“已停用”。
弃用试用功能没有用量限制,因为这类功能不会引入新功能,因此不会造成很大比例的网页依赖于试用功能。
某些试用版还提供限制用量的选项,这意味着系统会为某些用户停用源试用功能。此选项在源试用的注册页面上提供:
如果您发现用户对源试用功能的使用权限低于预期,请确保已选择“标准限制”。
iframe 提供自己的令牌
要允许对源试用功能的访问权限,iframe 必须在元标记、HTTP 标头或以编程方式提供令牌。iframe 不会继承对包含它们的网页所启用功能的访问权限。
ot-iframe.glitch.me 演示了如何从 iframe 访问源试用功能。ot-iframe-3p.glitch.me 提供了多个跨源 iframe 示例。
权限政策已正确配置
某些源试用功能可能会受到 Permissions-Policy
标头(以前称为 Feature-Policy
标头)的影响。您可以在试用功能的意图实验中了解这一点,或者在 web.dev 或 developer.chrome.com/blog 上查看有关此功能的开发者文档。
请确保您尝试访问的功能未被 Permissions-Policy
指令阻止。您可以在 Chrome DevTools 的 Network 面板中检查响应标头,并在 Application 面板中查看允许的功能的完整列表。
工作器呢?
源试用功能可供 Service Worker、共享工作器和专用工作器使用。但是,启用 Service Worker 和共享工作器访问权限的唯一方法是在 Origin-Trial
标头中提供令牌。
专用工作器会继承对其父文档所启用功能的访问权限。
在访问功能之前提供令牌
请确保在试用功能之前提供源试用令牌。例如,如果网页通过 JavaScript 提供令牌,请确保提供令牌的代码先于尝试访问试用功能的代码运行。
源试用演示
- 元标记中的令牌
- 标头中的令牌
- 在 iframe 中访问的功能
- 由第三方脚本注入的令牌
- ot-iframe-3p.glitch.me:跨源 iframe 示例