Skip to main content

Use the Idle Detection API to find out when the user is not actively using their device.


Updated

The idle detection API is part of
capabilities project
and is currently under development. This post will be updated as implementation progresses.

What is the idle detection API?

The Idle Detection API notifies developers when a user is idle, indicating things like lack of keyboard, mouse, screen interaction, activation of a screen saver, screen lock, or switching to a screen different. A developer-defined threshold triggers the notification.

Suggested Use Cases for the Idle Detection API

Examples of sites that can 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 available.
  • Publicly displayed kiosk applications, for example in museums, can use this API to return to the "home" view if no one is interacting with the kiosk anymore.
  • Applications that require expensive calculations, for example to draw graphics, can limit these calculations to times when the user interacts with their device.

Actual state

He passed Condition
1. Create an explainer To complete
2. Create initial draft specification Not started
3. Collect feedback and repeat the design In progress
4. Proof of origin In progress
5. Launch Not started

How to use the idle detection API

Enabling via chrome: // flags

To experiment with the idle detection API locally, without a source test token, enable the
#enable-experimental-web-platform-features flag on chrome://flags.

Enabling support during the proof of origin phase

Starting with Chrome 84, the Idle Detection API will be available as proof of origin. The proof of origin is expected to finish on Chrome 86.

Origin testing allows you to test new features and provide feedback on their usability, practicality, and effectiveness to the web standards community. For more information, see the Origin testing guide for web developers. To enroll in this or any other proof of origin, visit the registration page.

Register for proof of origin

  1. Request a token by your origin.
  2. Add the token to your pages. There are two ways to do it:
    • Add a origin-trial tag to the header of each page. For example, this might look like this:
    • If you can configure your server, you can also add the token using a Origin-Trial HTTP header. The resulting response header should look like this:
      Origin-Trial: TOKEN_GOES_HERE

Feature detection

To check if the idle detection API is supported, use:

if ( 'IdleDetector' in window ) {
}

Idle Detection API Concepts

The Idle Detection API assumes that there is some level of interaction 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 idle state of the user:
    active or idle- The user has or has not interacted with the user agent for a period of time.
  • The idle state of the screen:
    locked or unlocked- The system has an active screen lock (such as a screen saver) that prevents interaction with the user agent.

Distinctive active since idle requires heuristics that may differ by user, user agent, and operating system. It should also be a fairly rough threshold (see Security and permissions).

The model intentionally does not formally distinguish between interaction with a particular content (that is, the web page 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 make sure that 'idle-detection' permission is granted. If permission is not granted, you must request it through IdleDetector.requestPermission (). Note that calling this method requires a user gesture.


const state = await IdleDetector . requestPermission ( ) ;
if ( state ! == 'granted' ) {
return console . log ( 'Idle detection permission not granted.' ) ;
}

Initially, the inactive detection was blocked behind the notifications permission. While many, but not all, use cases for this API involve notifications, the Idle Detection spec editors have decided to block it with a dedicated idle detection permission.

The second step is then to instantiate the IdleDetector. The minimum threshold is 60,000 milliseconds (1 minute). You can finally start the inactive detection by calling
IdleDetectorit is start () method. Take an object with the desired idle threshold in milliseconds and optional signal with a
AbortSignal

to abort inactive 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 ) {
console . error ( err . name , err . message ) ;
}

You can abort inactive detection by calling
AbortControllerit is
abort ()

method.

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

DevTools support

Starting with Chrome 86, you can emulate idle events in Chrome DevTools without actually being idle. In DevTools, open the Sensors tab and search Emulate Idle Detector State. You can see the various options in the video below.

Idle Detector state emulation in DevTools.

Puppeteer stand

Starting with version 5.3.1 of Puppeteer, you can
emulate the various idle states
to programmatically test how the behavior of your web application changes.

Manifestation

You can see the idle detection API in action with the Ephemeral Canvas Demo which deletes its content after 60 seconds of inactivity. You could imagine that this will be implemented in a department store for children to doodle.

demo-2611166

Polyfilling

Some aspects of the idle detection API are multi-purpose and idle detection libraries such as inactive.ts They exist, but these approaches are limited to the content area of a web application itself - the library running in the context of the web application needs to perform expensive polling for input events or listen for visibility changes. However, more restrictively, libraries cannot tell today when a user remains inactive outside of their content area (for example, when a user is on a different tab or logs out of their computer).

Security and permissions

The Chrome team has designed and implemented the Idle Detection API using the basic principles defined in Control access to powerful features of the web platform, including user control, transparency and ergonomics. The ability to use this API is controlled by the
'idle-detection' Excuse me. To use the API, an application must also be running on a
top-level secure context.

User control and privacy

We always want to prevent malicious actors from misusing new APIs. Seemingly independent websites, but in fact controlled by the same entity, can obtain inactive information from the user and correlate the data to identify unique users across all sources. To mitigate these types of attacks, the idle detection API limits the granularity of 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 in the API that is not working as you expected? Or are you missing any methods or properties you need to implement your idea? Have a question or comment about the security model? File a spec issue in the corresponding GitHub repositoryor add your thoughts to an existing problem.

Report a problem with the deployment

Found a bug with the Chrome implementation? Or is the implementation different from the specification? File a bug in new.crbug.com. Be sure to include as much detail as you can, simple instructions to reproduce, and enter Blink> Input at Components box.
Failure works great for quick and easy sharing of reps.

Show API support

Thinking of using the idle detection API? Your public support helps the Chrome team prioritize features and shows other browser vendors how important it is to support them.

Share how you plan to use it in the WICG Speech Thread
Send a tweet to @Cromodev with the #idledetection hashtag and let us know where and how you are using it.

Helpful Links

Thanks

The idle detection API was implemented by Sam goto. DevTools support was added by Maksim Sadym. Thanks to Joe medley,
Kayce Basquesand
Reilly Scholarship for their reviews of this article. The image of the hero is of Fernando Hernandez in
Unsplash.

R Marketing Digital