排查 Chrome 源试用问题

解决元标记、标头和脚本中试用令牌的常见问题。

核对清单

如需排查源试用问题,请使用提供的链接解决以下各个问题。

试试看!

以下演示显示了提供源试用令牌和使用试用功能的每种方法:

使用 Chrome 开发者工具检查令牌

从 Chrome 93 开始,开发者工具会在 所选框架的应用面板。

Chrome 开发者工具 
源试用信息。

展开顶部帧,以检查可用于子帧的源试用令牌。例如,对于 ot-iframe.glitch.me 处的演示页面,您可以看到 iframe 会提供一个令牌。

Chrome 开发者工具 
  “应用”面板,其中显示了 iframe 中网页的源试用令牌。

  • 令牌状态:页面是否拥有有效令牌。请注意,对于某些源试用,可能会有 其他因素(例如地理区域限制), 即使存在有效令牌,请求也始终可用。Chrome 开发者工具状态代码 解释了每个源试用代码的含义。
  • 来源:针对 令牌。
  • 过期时间:令牌可能的最长(最新)过期日期/时间,通常不会 与试玩结束时的差距保持一致。此日期与所显示令牌的“有效期”日期不同 在 My Registrations(我的报名)中, 显示令牌当前的有效期,以及 可以扩展
  • 使用限制:使用限制,可以设置为某些试验。
  • 第三方:是否进行第三方匹配 已启用该令牌。此功能适用于部分源试用。试用功能需要 可通过第三方脚本在多个网站上访问。
  • 匹配子网域:是否子网域匹配 已启用该令牌。这样就可以在多个平台上测试源试用功能 子网域,而无需为每个子网域使用不同的令牌。

如果实验不可用,Chrome 开发者工具会在实验名称旁边显示警告 令牌已过期或者存在其他限制。

Chrome 开发者工具 
“Application”面板中显示过期令牌的源试用信息

Chrome 开发者工具状态代码

  • 已过期:令牌已过其到期日期。您需要续用该令牌 并生成具有新失效日期的新令牌。
    源代码

  • FeatureDisabled:试用版目前已停用。
    源代码

  • FeatureDisabledForUser:已通过 备选使用限制。请参阅“用户子集排除”部分。
    源代码 1
    源代码 2

  • 不安全:请求来源不安全,系统不会为不安全的来源启用试用。 如源试用令牌验证程序代码中所述: 对于第三方令牌,当前源和脚本源都必须是安全的。由于 子网域匹配,令牌来源可能与所提供的某个脚本不完全匹配 来源,并且结果不会指明匹配了哪个特定来源。也就是说,它不是 直接查找相应的脚本来源。为避免重复进行所有与来源的比较 还有一些快捷方式,具体取决于提供的脚本源的数量。其中必须至少有 否则第三方令牌将无法成功验证。”
    源代码

  • InvalidSignature:令牌的签名无效或格式错误。
    源代码

  • 格式错误:令牌格式错误,无法解析。
    源代码

  • NotSupported:Chromium 不支持令牌定义的源试用 “embedder”:浏览器(例如 Chrome 或 Edge)、WebView 或其他用户代理。
    源代码

  • 成功:令牌格式正确、未过期、与源试用功能匹配且为 请求来源。
    源代码

  • TokenDisabled:令牌被标记为已停用,因此无法使用。
    源代码

  • TrialNotAllowed当前用户无法进行源试用。
    源代码

  • UnknownTrial:令牌指定的功能名称与任何已知试验都不匹配。
    源代码

  • WrongOrigin:请求来源与令牌中指定的来源不匹配。这可以 包括协议、主机名或端口如果有第三方令牌,系统也会显示此状态。 通过 HTTP 标头、元标记或内嵌脚本提供,而不是通过外部 JavaScript 文件提供。
    源代码

  • WrongVersion:令牌版本错误:目前仅支持令牌版本 2 和 3。
    源代码


它不起作用!🤔

如果您的源试用未按预期运行,请确保您已满足以下条件。

您正在 Chrome 中进行测试,而非在 Chromium 或其他浏览器中进行测试

Chrome 源试用专为 Chrome 用户而设计。请勿依赖 Chrome 源试用令牌 ,以便在其他浏览器(包括 Chromium 和其他基于 Chromium 的浏览器)中启用试用功能。 这是因为 Chrome 源试用专门针对 Chrome 中提供的功能, 。

FirefoxMicrosoft Edge 也可进行源试用。在 Firefox 或 Edge 源试用中注册不会在 Chrome 中启用该功能。

已针对访问您网站的 Chrome 版本启用源试用

只有特定版本的 Chrome 才能访问试用。在某些情况下,这可能意味着 功能仅在 Chrome 稳定版(Canary 版、开发者版和 Beta 版)中提供。

您可以在注册页面查看版本供应情况 :

Chrome 源试用
“First Party Set”和SameParty(突出显示了 Chrome 可用性)

您可以访问 chrome://version 查看您当前使用的 Chrome 版本。

Chrome 设置未停用源试用

如果有用户报告某项功能不适合他们,请检查该功能是否 在其 Chrome 设置中停用。例如,Privacy Sandbox 功能可以在 chrome://settings/privacySandbox 页面中停用。

关键字和语法正确

请务必为源试用令牌使用合适的关键字和语法。

对于第一方用途,可以在 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 作为网络来源

Chrome 源试用 
页面显示选择为 Web 源的 https://example.com。

您可能会获得如下所示的令牌值:

Chrome 源试用 
显示令牌值的页面。

请检查此值是否与您要排查问题的页面中使用的令牌一致。

对于元标记中提供的令牌,请检查 HTML:

  <meta http-equiv="origin-trial" content="Aj4DysCv3VjknU3...">

对于标头中提供的令牌,您可以从 Response Headers 下的 Chrome DevTools Network 面板

Chrome 开发者工具 
显示源试用响应标头的 Network 面板。

第一方令牌由使用该令牌的来源提供

如需为您的源站提供的网页中包含的代码启用源试用功能,请执行以下操作: 通过同源的元标记、标头或通过 JavaScript 提供试用令牌。

为令牌注册的来源必须与提供令牌的来源一致。

第三方令牌来源与脚本来源匹配

对于在其他源上注入的脚本,您可以注册参与源试用。

例如,如果您希望 javascript-library.example 提供的脚本参与 源试用,您需要通过第三方匹配为 javascript-library.example 注册一个令牌。

Chrome 源试用 
显示已选择的第三方匹配注册页面。

第三方令牌的来源值必须与注入该令牌的脚本的来源一致。

第三方脚本使用了第三方令牌

您无法仅通过启用第三方脚本 为您的源(而不是脚本)注册令牌。

第三方脚本需要使用启用了第三方匹配功能的令牌,并通过脚本注入 (不包含在网站的元标记或标头中),请使用如下代码:

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 和共享 Worker 启用源试用访问权限,唯一的方法是 在 Origin-Trial 标头中提供令牌。

已为子网域上使用的令牌启用子网域匹配

如果您网站上的某些网页不支持源试用功能,请检查 正确设置了令牌的子网域。

在注册参与源试用时,您可以选择匹配 来源:

Chrome 源试用 
显示已选择子网域匹配的注册页面

您还可以为第三方令牌匹配子网域:

Chrome 源试用 
显示已选中第三方匹配和子域名匹配的注册页面

子网域令牌不会颁发 公共后缀列表中列出的来源。例如,您无法注册 https://appspot.com 或 https://github.io 之类的源站,但您可以注册网域 例如 https://example.appspot.com 或 https://example.github.io。

令牌仍然有效

令牌的有效期为六周。除此之外,您还必须按顺序提交反馈。 延长有效期。面向 Web 开发者的源试用指南介绍了如何确保 您的令牌在整个源试用期间有效。

您可以在 Chrome 源试用的“我的注册”页面上查看有效令牌:

Chrome 源试用 
显示“失效前”的“我的注册”页面

如果令牌仍然有效,Chrome 开发者工具会显示状态 Success

Chrome 开发者工具 
“Application”(应用)面板中显示源试用信息,其中突出显示了“Status: Success”(状态:成功)。

如果令牌已过期,开发者工具会显示状态 Expired 以及您的 “My Registrations”(我的注册)页面会显示 Expired Tokens(令牌过期)部分。

Chrome 源试用 
“My Registrations”(我的注册)页面显示了过期的令牌。

源试用尚未结束

您可以在注册页面中查看源试用的结束日期:

Chrome 源试用
“First Party Set”和SameParty,其中突出显示了可试用的详细信息。

对于已结束的试用,开发者工具会显示如下内容:

Chrome 开发者工具 
Application 面板中显示 ValidTokenNotProvided 和 Status Expired 的源试用信息

尽管如此,但是当需要您提供反馈或令牌即将过期时,系统会向您发送电子邮件 不会。

当前用户可进行源试用

某些用户无法进行部分源试用,即使提供了有效令牌也是如此。

如果当前用户无法进行试用,Chrome 开发者工具会显示 TrialNotAllowed 警告:

“Application”面板中显示 TrialNotAllowed 警告的 Chrome DevTools 源试用信息。

对于每次源试用,系统都会提供使用限制和适用地区的相关信息。

与任何网络平台功能一样,您应该使用功能检测 以确认某项源试用功能是否受支持,然后再使用该功能。

尚未超出源试用使用限制

默认情况下,具有有效试用令牌的所有网页都会启用源试用功能。

不过,除了极少数情况下,源试用最多可占所有 Chrome 网页加载的 0.5%。 如果所有 Chrome 用户的总用量超过该上限,系统会停用源试用功能。 DevTools 会将令牌状态显示为已停用。

弃用试用没有用量限额,因为这些限制不会引入 因此也就不大 依赖试用功能。

部分试用版还提供限制用量的选项,这意味着源试用功能将 已为部分用户停用此选项可从源的注册页面提供 提供以下功能的试用版:

Chrome 源试用 
显示使用限制的注册页面。

如果您发现用户对源试用功能的访问权限低于预期, 请务必选择“标准限制”。

iframe 会提供自己的令牌

要允许对源试用功能的访问权限,iframe 必须在元标记中提供令牌,即 HTTP 标头,也可以以编程方式使用。iframe 不会继承针对以下各项启用的功能的访问权限: 包含这些标记的网页。

ot-iframe.glitch.me 演示了如何使用源试用功能 。ot-iframe-3p.glitch.me 提供多种 跨域 iframe 示例。

已正确配置权限政策

部分源试用功能可能会受 Permissions-Policy影响 标头(以前称为 Feature-Policy 标头)。您可以在 愿意进行实验 ,或在 web.dev 上查看有关此功能的开发者文档 或 developer.chrome.com/blog

请确保您尝试访问的功能未被Permissions-Policy屏蔽 指令。您可以在 Chrome 开发者工具的 Network 面板中查看响应标头,并查看 “应用程序”面板中允许的功能的完整列表。

Chrome 开发者工具 
  “Application”面板,显示了“Permissions Policy Allowed Feature”。

那工作器呢?

源试用功能可提供给 Service Worker、共享 Worker 和 worker。但是,为 Service Worker 和共享 Worker 启用访问权限的唯一方法是 Origin-Trial 标头中的令牌。

专用工作器会继承其父级文档启用的功能的访问权限。

在访问功能之前提供令牌

在使用试用功能之前,请确保先提供源试用令牌。 例如,如果网页通过 JavaScript 提供令牌,请确保用于提供令牌的代码 在尝试访问试用功能的代码之前运行。

源试用演示

了解详情