Use the Idle Detection API to find out when the user isn't actively using their device.
What is the Idle Detection API?
The Idle Detection API notifies developers when a user is idle, indicating such things as lack of interaction with the keyboard, mouse, screen, activation of a screensaver, locking of the screen, or moving to a different screen. A developer-defined threshold triggers the notification.
Suggested use cases for the Idle Detection API
Examples of sites that may use this API include:
- Chat applications or online social networking sites can use this API to let the user know if their contacts are currently reachable.
- Publicly exposed kiosk apps, for example in museums, can use this API to return to the "home" view if no one interacts with the kiosk anymore.
- Apps that require expensive calculations, for example to draw charts, can limit these calculations to moments when the user interacts with their device.
Current status
Step | Status |
---|---|
1. Create explainer | Complete |
2. Create initial draft of specification | Complete |
3. Gather feedback & iterate on design | In progress |
4. Origin trial | Completed |
5. Launch | Chromium 94 |
How to use the Idle Detection API
Feature detection
To check if the Idle Detection API is supported, use:
if ('IdleDetector' in window) {
// Idle Detector API supported
}
Idle Detection API concepts
The Idle Detection API assumes that there is some level of engagement between the user, the user agent (that is, the browser), and the operating system of the device in use. This is represented in two dimensions:
- The user idle state:
active
oridle
: the user has or has not interacted with the user agent for some period of time. - The screen idle state:
locked
orunlocked
: the system has an active screen lock (like a screensaver) preventing interaction with the user agent.
Distinguishing active
from idle
requires heuristics that may differ across user, user agent,
and operating system. It should also be a reasonably coarse threshold
(see Security and Permissions).
The model intentionally does not formally distinguish between interaction with particular content (that is, the webpage in a tab using the API), the user agent as a whole, or the operating system; this definition is left to the user agent.
Using the Idle Detection API
The first step when using the Idle Detection API is
to ensure the 'idle-detection'
permission is granted.
If the permission is not granted, you need to
request it via IdleDetector.requestPermission()
.
Note that calling this method requires a user gesture.
// 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.');
}
The second step is then to instantiate the IdleDetector
.
The minimum threshold
is 60,000 milliseconds (1 minute).
You can finally start the idle detection by calling the
IdleDetector
's start()
method.
It takes an object with the desired idle threshold
in milliseconds
and an optional signal
with an
AbortSignal
to abort idle detection as parameters.
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);
}
You can abort the idle detection by calling the
AbortController
's
abort()
method.
controller.abort();
console.log('IdleDetector is stopped.');
DevTools support
Starting in Chromium 94, you can emulate idle events in DevTools without actually being idle. In DevTools, open the Sensors tab and look for Emulate Idle Detector state. You can see the various options in the video below.
Puppeteer support
As of Puppeteer version 5.3.1, you can emulate the various idle states to programmatically test how your web app's behavior changes.
Demo
You can see the Idle Detection API in action with the Ephemeral Canvas demo that erases its contents after 60 seconds of inactivity. You could imagine this being deployed in a department store for kids to doodle on.
Polyfilling
Some aspects of the Idle Detection API are polyfillable and idle detection libraries like idle.ts exist, but these approaches are constrained to a web app's own content area: The library running in the context of the web app needs to expensively poll for input events or listen to visibility changes. More restrictively, though, libraries cannot tell today when a user goes idle outside of its content area (e.g., when a user is on a different tab or logged out of their computer altogether).
Security and permissions
The Chrome team has designed and implemented the Idle Detection API using the core principles
defined in Controlling Access to Powerful Web Platform Features,
including user control, transparency, and ergonomics.
The ability to use this API is controlled by the
'idle-detection'
permission.
In order to use the API, an app also must be running in a
top-level secure context.
User control and privacy
We always want to prevent malicious actors from misusing new APIs. Seemingly independent websites, but that in fact are controlled by the same entity, might obtain user idle information and correlate the data to identify unique users across origins. To mitigate these sort of attacks, the Idle Detection API limits the granularity of the reported idle events.
Feedback
The Chrome team wants to hear about your experiences with the Idle Detection API.
Tell us about the API design
Is there something about the API that doesn't work like you expected? Or are there missing methods or properties that you need to implement your idea? Have a question or comment on the security model? File a spec issue on the corresponding GitHub repo, or add your thoughts to an existing issue.
Report a problem with the implementation
Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?
File a bug at new.crbug.com. Be sure to include as much detail as you can,
simple instructions for reproducing, and enter Blink>Input
in the Components box.
Glitch works great for sharing quick and easy repros.
Show support for the API
Are you planning to use the Idle Detection API? Your public support helps the Chrome team to prioritize features and shows other browser vendors how critical it is to support them.
- Share how you plan to use it on the WICG Discourse thread.
- Send a tweet to @ChromiumDev using the hashtag
#IdleDetection
and let us know where and how you're using it.
Helpful links
- Public explainer
- Draft specification
- Idle Detection API Demo | Idle Detection API Demo source
- Tracking bug
- ChromeStatus.com entry
- Blink Component:
Blink>Input
Acknowledgements
The Idle Detection API was implemented by Sam Goto. DevTools support was added by Maksim Sadym. Thanks to Joe Medley, Kayce Basques, and Reilly Grant for their reviews of this article. The hero image is by Fernando Hernandez on Unsplash.