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} | ShakeDetectorinstance | Adds a handler to the shake event handlers pool | | unsubscribe | listener{function} | ShakeDetectorinstance | Removes a handler from the shake event handlers pool | | start | {void} | ShakeDetectorinstance | Starts monitoring the motion event | | stop | {void} | ShakeDetectorinstance | Stops monitoring the motion event | | confirmPermissionGranted | {void} | ShakeDetectorinstance | 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.