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 limitation

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:

1. Notify ShakeDetector that your page has the permission

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

2. 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/s2	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

License

Copyright © 2021, Sergey Chernykh. Released under the MIT License.