Idle and Idleprovider

Idle, once watch() is called, will start a timeout which if expires, will enter a warning state countdown. Once the countdown reaches zero, idle will broadcast a timeout event indicating the user has timed out (where your app should log them out or whatever you like). If the user performs an action that triggers a watched DOM event that bubbles up to document.html, this will reset the idle/warning state and start the process over again.

IdleProvider

The following methods can be used to configure Idle:

• interrupt(events) (string, default 'mousemove keydown DOMMouseScroll mousewheel mousedown'): These are the DOM events the service will watch to reset the idle timeout. Multiple events should be separated by a space. Note: Prior to v1.0, this method is called activeOn.
• idle(seconds) (integer, default is 20min): The idle timeout duration in seconds. After this amount of time passes without the user performing an action that triggers one of the watched DOM events, the user is considered idle. Note: Prior to v1.0, this method is called idleDuration.
• timeout(seconds) (integer, default is 30s): The amount of time the user has to respond (in seconds) before they have been considered timed out. Set to 0 or false to disable this feature, if you want Idle to nothing but detect when a user is idle or not forever. Note: Prior to v1.0, this method is called warningDuration, and could not be disabled; it always had to have a positive integer value.
• autoResume(string) (default is idle): Possible values are off/false, idle/true, or notIdle. When true or idle, user activity will automatically interrupt the warning countdown and reset the idle state. If false or off, you will need to manually call watch() when you want to start watching for idleness again. If notIdle, user activity will only automatically interrupt if the user is not yet idle.
• keepalive(enabled) (boolean, default is true): When true, the Keepalive service is automatically stopped and started as needed.

Idle

• running(): returns whether or not the watch() has been called and it is watching for idleness.
• idling(): returns whether or not the user appears to be idle.
• watch(): starts watching for idleness, or resets the idle/warning state and continues watching.
• unwatch(): stops watching for idleness, and resets the idle/warning state.
• setIdle(int) (new: v1.0.0): updates the idle value (see IdleProvider.idle() above) and restarts the watch if its running.
• setTimeout(int) (new: v1.0.0): updates the timeout value (see IdleProvider.timeout() above) and restarts the watch if its running.
• getIdle() (new: v1.1.0): gets the current idle value.
• getTimeout() (new: v1.1.0): gets the current timeout value.
• interrupt(): manually trigger the idle interrupt that normally occurs during user activity.

DOM Events

The events Idle watches are configurable. It is important to note that if the watched user events are prevented from bubbling up, Idle will not be reset and thus not work properly. Usually this is not a problem.

interrupt() vs watch()

interrupt() is similar to watch() under certain conditions (in fact, it calls watch()). interrupt() will reset the user's idle state (effectively making them "not idle") under the following conditions:

1. The idle service is currently running.
2. The user's session has not already timed out or expired.
3. autoResume is idle/true, or autoResume is notIdle and the user is not yet idle.

The purpose of interrupt is to only reset the user's idle state if the user is allowed to return from idle at that point in time. watch() on the other hand completely ignores the rules and the user's current idle state and makes them active, and starts watching for idleness again. Calling watch() will always make them active and start watching for idleness. Internally, monitored DOM events call interrupt(), which effectively means that DOM events (such as clicking or scrolling) can make a user active if they haven't already timed out and your configuration allows autoResume.

You should only use interrupt() if you have custom events or logic that you want to interrupt idleness according to the rules above. Otherwise, use watch() when you always want idle state reset. In almost all cases, you will likely just use watch().

Integration with Keepalive

By default, Idle will start Keepalive when watch() is called, and stop it when unwatch() is called. It will also stop Keepalive when the user goes idle, and start when they return. It will immediately ping once when they return, and then resume on the usual Keepalive interval after that.