此页面由 Cloud Translation API 翻译。

使用 Idle Detection API 检测非活跃用户

使用闲置检测 API 可以查明用户何时未主动使用设备。

Thomas Steiner

什么是空闲检测 API？

Idle Detection API 会在用户处于空闲状态时通知开发者，指出设备未与键盘、鼠标、屏幕交互、激活屏保、锁定屏幕或移动到其他屏幕等。开发者定义的阈值会触发通知。

Idle Detection API 的建议用例

可能会使用此 API 的网站示例包括：

聊天应用或在线社交网站可以使用此 API 告知用户其联系人当前是否可以访问。
如果公开提供的自助服务终端应用（例如在博物馆中）没有人与该自助服务终端互动，则可以使用此 API 返回“首页”视图。
如果应用需要进行成本高昂的计算（例如绘制图表），则可以将这些计算限制为仅在用户与设备互动的时刻进行。

当前状态

步骤	状态
1. 创建铺垫消息	完成
2. 创建规范的初始草稿	完成
3. 收集反馈并不断改进设计	进行中
4. 源试用	已完成
5. 发布	Chromium 94

如何使用 Idle Detection API

功能检测

如需检查是否支持 Idle Detection API，请使用以下命令：

if ('IdleDetector' in window) {
  // Idle Detector API supported
}

空闲检测 API 概念

Idle Detection API 假定用户、用户代理（即浏览器）和所用设备的操作系统之间存在一定程度的互动。具体表现在以下两个维度上：

用户闲置状态：active 或 idle：用户在一段时间内有或未与用户代理互动过一段时间。
屏幕闲置状态：locked 或 unlocked：系统设置了有效的屏幕锁定（如屏保），阻止与用户代理互动。

区分 active 与 idle 需要采用可能因用户、用户代理和操作系统而异的启发法。它还应该是一个相对粗略的阈值（请参阅安全与权限）。

此模型没有正式区分与特定内容（即使用 API 的标签页中的网页）、整个用户代理或操作系统的互动；此定义由用户代理负责。

使用空闲检测 API

使用 Idle Detection API 时，第一步是确保已授予 'idle-detection' 权限。如果未授予权限，您需要通过 IdleDetector.requestPermission() 请求权限。请注意，调用此方法需要用户手势。

// Make sure 'idle-detection' permission is granted.
const state = await IdleDetector.requestPermission();
if (state !== 'granted') {
  // Need to request permission first.
  return console.log('Idle detection permission not granted.');
}

第二步是实例化 IdleDetector。threshold 的最小值为 60,000 毫秒（1 分钟）。最后，您可以通过调用 IdleDetector 的 start() 方法来启动空闲状态检测。它接受具有所需空闲 threshold（以毫秒为单位）和可选 signal 和 AbortSignal 的对象作为参数来中止空闲检测。

try {
  const controller = new AbortController();
  const signal = controller.signal;

  const idleDetector = new IdleDetector();
  idleDetector.addEventListener('change', () => {
    const userState = idleDetector.userState;
    const screenState = idleDetector.screenState;
    console.log(`Idle change: ${userState}, ${screenState}.`);
  });

  await idleDetector.start({
    threshold: 60000,
    signal,
  });
  console.log('IdleDetector is active.');
} catch (err) {
  // Deal with initialization errors like permission denied,
  // running outside of top-level frame, etc.
  console.error(err.name, err.message);
}

您可以通过调用 AbortController 的 abort() 方法来中止空闲状态检测。

controller.abort();
console.log('IdleDetector is stopped.');

开发者工具支持

从 Chromium 94 开始，您可以在开发者工具中模拟空闲事件，而无需实际处于空闲状态。在开发者工具中，打开传感器标签页，然后查找模拟空闲检测器状态。您可以在下面的视频中看到各种选项。

在开发者工具中模拟空闲检测器状态。

Puppeteer 支持

从 Puppeteer 版本 5.3.1 开始，您可以模拟各种空闲状态，以编程方式测试 Web 应用行为的变化情况。

演示

您可以通过临时画布演示查看 Idle Detection API 的实际运用，该演示会在用户处于不活动状态 60 秒后清除其内容。可以想象，在一家供儿童涂鸦的百货商店中，会部署这种模型。

临时画布演示

聚酯纤维

Idle Detection API 的某些方面是可 polyfill 并且存在空闲检测库（例如 idle.ts），但这些方法仅限于 Web 应用自己的内容区域：在 Web 应用环境中运行的库需要耗费大量资源来轮询输入事件或监听可见性更改。但较为严格，库无法判断用户当前何时在内容区域之外空闲（例如，用户在其他标签页上或完全退出计算机）。

安全与权限

Chrome 团队按照控制对强大的 Web 平台功能的访问权限中定义的核心原则（包括用户控制、透明度和工效学设计）设计和实现了 Idle Detection API。能否使用此 API 由 'idle-detection' 权限控制。为了使用该 API，应用还必须在顶级安全上下文中运行。

用户控制和隐私

我们始终希望防止恶意操作者滥用新 API。看似独立但实际上由同一实体控制的网站可能会获取用户空闲信息，并关联这些数据以识别不同源的唯一身份用户。为了缓解此类攻击，Idle Detection API 会限制所报告的空闲事件的粒度。

反馈

Chrome 团队希望了解您使用 Idle Detection API 的体验。

向我们介绍 API 设计

是否存在 API 行为不符合您预期的情况？或者，是否缺少某些方法或属性来实现您的想法？对安全模型有疑问或意见？在相应的 GitHub 代码库中提交规范问题，或将您的想法添加到现有问题中。

报告实施方面的问题

您是否发现了 Chrome 实现方面的错误？或者，实现方式是否不同于规范？请在 new.crbug.com 提交 bug。请务必提供尽可能多的详情和简单的重现说明，并在组件框中输入 Blink>Input。Glitch 非常适合快速轻松地分享重现的视频。

显示对该 API 的支持

您打算使用 Idle Detection API 吗？您的公开支持有助于 Chrome 团队确定功能优先级，并向其他浏览器供应商表明支持这些功能的重要性。

请在 WICG Discourse 会话中说明您打算如何使用该工具。
请使用 # 标签 #IdleDetection 向 @ChromiumDev 发送一条推文，并告诉我们您使用该产品的位置和方式。

实用链接

致谢

Idle Detection API 由 Sam Goto 实现。Maksim Sadym 添加了开发者工具支持。感谢 Joe Medley、Kayce Basques 和 Reilly Grant 对本文的评价。主打图片由 Fernando Hernandez 制作，作者是 Unsplash 用户。