npm npm bundle size NPM GitHub top language

shake-detector

Mobile device shakes detection

Setup
IOS limitation
Options
API
Chaining
Shake event
Documentation
Roadmap
License

Setup

NPM

npm i shake-detector

import ShakeDetector from 'shake-detector';
// ...
const shakeDetector = new ShakeDetector();

CDN

<script src="https://unpkg.com/shake-detector"></script>

const shakeDetector = new window.ShakeDetector();

IOS (since 12.2) requires a user's permission to listen to the motion events, and it could be obtained only in response to user interaction. ShakeDetector will do nothing on IOS 12.2+ in case that such permission was not granted.

There are two options:

Notify ShakeDetector that your page has the permission

shakeDetector.confirmPermissionGranted();
shakeDetector.start();

Request the permission via ShakeDetector

const requestTrigger = document.getElementById('requestTrigger');
// requestPermission argument is optional
// default is document.documentElement
shakeDetector.requestPermission(requestTrigger).then(() => {
    shakeDetector.start();
});

In this case ShakeDetector will set a one-time click event listener and will request the permission on click.

Options

const options = {
    threshold: 8,
    debounceDelay: 500,
};
const shakeDetector = new ShakeDetector(options);

Option	Type	Default	Measure	Description
`threshold`	number	15	m/s²	device acceleration that will be registered as a shake
`debounceDelay`	number	1000	ms	shake won't be registered if this amount of time has not passed after the previous shake

API

Method	Arguments	Return	Description
`subscribe`	listener {function}	`ShakeDetector` instance	Adds a handler to the shake event handlers pool
`unsubscribe`	listener {function}	`ShakeDetector` instance	Removes a handler from the shake event handlers pool
`start`	{void}	`ShakeDetector` instance	Starts monitoring the motion event
`stop`	{void}	`ShakeDetector` instance	Stops monitoring the motion event
`confirmPermissionGranted`	{void}	`ShakeDetector` instance	Notifies the detector that permission to listen to the motion events has already been granted
`requestPermission`	triggerElement {HTMLElement}	Promise	Requests a user's permission to listen to the motion events

Chaining

All ShakeDetector methods except requestPermission return its instance for chaining.

const onShake = () => {
    console.log('shake!');
};
new ShakeDetector().confirmPermissionGranted().subscribe(onShake).start();

Shake event

Once shake is detected, ShakeDetector fire an event on window. One can use it instead of the subscription via subscribe method.

const onShake = () => {
    console.log('shake!');
};
const shakeDetector = new ShakeDetector();
shakeDetector.start();
window.addEventListener(ShakeDetector.SHAKE_EVENT, onShake);

Documentation

Please find the full docs here

Roadmap

demo page with configuration options
provide magnitude of the shake for the shake listeners - how energetic the shake was