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

使用 Idle Detection 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
}

Idle Detection API 概念

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

  • 用户空闲状态：active 或 idle：用户已有一段时间未与用户代理互动过。
  • 屏幕空闲状态： locked 或 unlocked：系统处于有效的屏幕锁定状态（例如屏保），阻止与用户代理进行交互。

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

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

使用 Idle Detection 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 开始，您无需实际处于空闲状态，即可在 DevTools 中模拟空闲事件。在 DevTools 中，打开 Sensors（传感器）标签页，然后查找 Emulate Idle Detector state（模拟空闲检测器状态）。您可以在下面的视频中查看各种选项。

DevTools 中的空闲检测器状态模拟。

Puppeteer 支持

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

演示

您可以通过短暂画布演示版了解 Idle Detection API 的运作方式，该演示版会在 60 秒无活动后清除其内容。可以想象部署在一家百货公司，供孩子们在上面涂鸦。

临时画布演示

polyfill

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 实现中的 bug？或者，实现是否与规范不同？ 请访问 new.crbug.com 提交 bug。请务必提供尽可能详细的信息、简单的重现说明，并在 Components 框中输入 Blink>Input。Glitch 非常适用于分享轻松快速的重现问题。

表示对 API 的支持

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

实用链接

致谢

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