IdleDetector
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The IdleDetector
interface of the Idle
Detection API provides methods and events for detecting user activity on a device or screen.
This interface requires a secure context.
Constructor
IdleDetector()
Experimental-
Creates a new
IdleDetector
object.
Instance properties
IdleDetector.userState
Read only Experimental-
Returns a string indicating whether the users has interacted with either the screen or the device within the threshold provided to
start()
, one of"active"
or"idle"
. This attribute returnsnull
beforestart()
is called. IdleDetector.screenState
Read only Experimental-
Returns a string indicating whether the screen is locked, one of
"locked"
or"unlocked"
. This attribute returnsnull
beforestart()
is called.
Events
change
Experimental-
Called when the value of
userState
orscreenState
has changed.
Static methods
IdleDetector.requestPermission()
Experimental-
Returns a
Promise
that resolves when the user has chosen whether to grant the origin access to their idle state. Resolves with"granted"
on acceptance and"denied"
on refusal.
Instance methods
IdleDetector.start()
Experimental-
Returns a
Promise
that resolves when the detector starts listening for changes in the user's idle state.userState
andscreenState
are given initial values. This method takes an optionaloptions
object with thethreshold
in milliseconds where inactivity should be reported andsignal
for anAbortSignal
to abort the idle detector.
Examples
The following example shows creating a detector and logging changes to the user's idle state. A button is used to get the necessary user activation before requesting permission.
js
const controller = new AbortController();
const signal = controller.signal;
startButton.addEventListener("click", async () => {
if ((await IdleDetector.requestPermission()) !== "granted") {
console.error("Idle detection permission denied.");
return;
}
try {
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: 60_000,
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);
}
});
stopButton.addEventListener("click", () => {
controller.abort();
console.log("IdleDetector is stopped.");
});
Specifications
Specification |
---|
Idle Detection API # api-idledetector |
Browser compatibility
BCD tables only load in the browser