Home

Awesome

Ember User Activity

Netlify Status Build Status Ember Observer Score Code Climate

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

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:

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 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 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 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:

Two optional parameters may follow:

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.