ember-user-activity
v8.0.0
Published
Ember Addon for tracking user activity & idling
Downloads
31,303
Readme
This addon provides services for detecting user activity & idling across the entire application.
Check out the Demo!
We adhere to the Ember Community Guidelines for our Code of Conduct.
Compatibility
- Ember.js v4.8 or above
- Ember CLI v4.8 or above
- Node.js v18 or above
Installation
ember install ember-user-activity
Usage
User Activity Service
This service fires events from global window listeners. These listeners trigger on capture, meaning they are not affected by event cancellation.
These window
events are enabled by default:
keydown
- Fires when a key is pressedmousedown
- Fires when a mouse is clickedscroll
- Fires when the user scrollstouchstart
- Fires when a touch point is placed on the touch surface [Mobile-Friendly]storage
- Fires when any activity event is triggered on another tab of the same website. This avoids problems when a user opens up serveral tabs to the same application.- ~~
mousemove
- Fires when the user moves the mouse~~ Removed as of v0.2.0
A custom event, userActive
is fired for ALL enabled events.
To catch these events, simply inject the service and subscribe to the events you care about:
import Component from '@glimmer/component';
import { service } from '@ember/service';
// any file where services can be injected
export default class MyComponent extends Component {
@service('ember-user-activity@user-activity')
userActivity;
setupListeners() {
this.userActivity.on('userActive', this, this.activeHandler);
}
activeHandler(event) {
// do stuff
}
}
Each event handler will receive the standard DOM event
object
(ex: mousemove).
Unsubscribe from any event by calling off
:
this.userActivity.off('userActive', this, this.activeHandler);
Note: While our event dispatch system mirrors Ember.Evented, it does not include the one
method.
Only on
, off
, and trigger
have been implemented. If you feel one
is necessary for you,
we're happy to accept PRs!
Event Configuration
If you would like to listen to a different set of events, extend the service in your app:
// app/services/user-activity.js
import UserActivityService from 'ember-user-activity/services/user-activity';
export default class UserActivity extends UserActivityService {
defaultEvents = ['keypress', 'mouseenter', 'mousemove'];
}
Additionally, you can enable/disable events after the service has been initialized.
this.userActivity.enableEvent('keyup');
this.userActivity.disableEvent('mousedown');
Event names must be from the DOM Event list. Custom events are not currently supported. If you enable an event name that was not set up by default, a new listener will be created automatically.
You can find out if an event is currently enabled:
this.userActivity.isEnabled('foo'); // false
this.userActivity.isEnabled('keydown'); // true
Performance Configuration
Each individual event is throttled by 100ms for performance reasons,
to avoid clogging apps with a firehose of activity events. The length of
the throttling can be configured by setting EVENT_THROTTLE
on the activity service.
// app/services/user-activity.js
import UserActivityService from 'ember-user-activity/services/user-activity';
export default class UserActivity extends UserActivityService {
EVENT_THROTTLE = 200; // 200 ms
}
Setting EVENT_THROTTLE
to 0 will enable the full firehose of events.
This may cause performance issues in your application if non-trivial
amounts of code are being executed for each event being fired.
User Idle Service
This service tracks user activity to decide when a user has gone idle by not interacting with the page for a set amount of time.
import Component from '@glimmer/component';
import { service } from '@ember/service';
import { readOnly } from '@ember/object/computed'
export default class MyComponent extends Component {
@service('ember-user-activity@user-idle')
userIdle;
@readOnly('userIdle.isIdle')
isIdle;
}
The default timeout is set for 10 minutes but can be overridden by extending the service:
// app/services/user-idle.js
import UserIdleService from 'ember-user-activity/services/user-idle';
export default class UserIdle extends UserIdleService {
IDLE_TIMEOUT = 300000 // 5 minutes
}
By default, the idle service listens to the userActive
event, but it can be
configured to listen to a custom set of events from the user-activity
service:
// app/services/user-idle.js
import UserIdleService from 'ember-user-activity/services/user-idle';
export default class UserIdle extends UserIdleService {
activeEvents = ['mousedown', 'keydown'];
}
Note that the userActive
event is a superset of all events fired from user-activity
,
so in most cases you won't need to change this.
The idle service has a idleChanged
event when isIdle
gets changed.
import Component from '@glimmer/component';
import { service } from '@ember/service';
export default class MyComponent extends Component {
@service('ember-user-activity@user-idle')
userIdle;
constructor() {
this.userIdle.on('idleChanged', (isIdle) => {
// isIdle is true if idle. False otherwise.
});
}
}
Scroll Activity Service
This service tracks scrolling within the application by periodically checking
(via requestAnimationFrame)
for changes in scroll position for the various scrollable elements in the page. By default, it only
checks document
, but the Scroll Activity Mixin provides an easy
way to register your components as well. The User Activity Service subscribes to these scrolling events by default, so you do not need to do anything to use this service for global scroll events if you are already injecting the user-activity service.
Any elements can be subscribed to this service:
this.scrollActivity.subscribe(this, element);
subscribe
requires at least two parameters:
target
- Usuallythis
, target just needs to be a unique identifier/object that can be used to unsubscribe from the serviceelement
- The scrollable element (can be a DOM or jQuery element - jQuery not required!)
Two optional parameters may follow:
callback
- A callback to execute when scrolling has been detected in the elementhighPriority
- A boolean (defaulttrue
) specifying this subscriber should eagerly check scroll positions on each animation frame. Whenfalse
, it will instead use an approximation of idle checking on the UI thread to avoid performing measurements at sensitive times for other work (like rendering).
Conversely, elements can also be unsubscribed:
this.scrollActivity.unsubscribe(this);
unsubscribe
only requires the target
parameter that was initially used to subscribe
.
Cleanup
Please remember that subscribing to events can cause memory leaks if they are not properly cleaned up. Make sure to remove any listeners before destroying their parent objects.
// app/components/foo-bar.js
export default class FooBar extends Component {
willDestroy() {
this.userActivity.off('keydown', this, this.keydownHandler);
}
}
Using in an Addon
Building your own addon to extend Ember User Activity? No problem!
// my-addon/addon/services/user-idle.js
import UserIdleService from 'ember-user-activity/services/user-idle';
export default class UserIdle extends UserIdleService {
IDLE_TIMEOUT = 3000; // 3 minutes
}
Contributing
See the Contributing guide for details.
License
This project is licensed under the MIT License.