Getting Started

1. Install the package

   npm

   npm i @capgo/capacitor-shake

   pnpm

   pnpm add @capgo/capacitor-shake

   yarn

   yarn add @capgo/capacitor-shake

   bun

   bun add @capgo/capacitor-shake

2. Sync with native projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configure the plugin

   import { Shake } from '@capgo/capacitor-shake';
   
   // Start listening for shake gestures
   await Shake.start();
   
   // Listen for shake events
   Shake.addListener('shake', () => {
     console.log('Device was shaken!');
     // Perform your action here
   });

   // Configure shake sensitivity
   await Shake.start({
     threshold: 3.5 // Adjust sensitivity (default: 3.5)
   });

   iOS

   No additional setup required for iOS.

   Android

   No additional setup required for Android.

4. Stop listening for shakes

   // Stop shake detection when not needed
   await Shake.stop();
   
   // Remove specific listener
   const handle = await Shake.addListener('shake', () => {
     console.log('Shaken!');
   });
   handle.remove();

5. Example implementation

   import { Shake } from '@capgo/capacitor-shake';
   import { App } from '@capacitor/app';
   
   export class ShakeService {
     private shakeListener: any;
   
     async initialize() {
       // Start shake detection
       await Shake.start({ threshold: 4.0 });
   
       // Add shake listener
       this.shakeListener = await Shake.addListener('shake', () => {
         this.handleShake();
       });
   
       // Clean up on app pause
       App.addListener('pause', () => {
         Shake.stop();
       });
   
       // Resume on app resume
       App.addListener('resume', () => {
         Shake.start({ threshold: 4.0 });
       });
     }
   
     private handleShake() {
       console.log('Shake detected!');
       // Show debug menu, refresh data, or trigger any action
     }
   
     async cleanup() {
       if (this.shakeListener) {
         this.shakeListener.remove();
       }
       await Shake.stop();
     }
   }

API Reference

Methods

start(options?: ShakeOptions)

Start listening for shake gestures.

Parameters:

• options (optional): Configuration object
  • threshold: number - Sensitivity threshold (default: 3.5)

stop()

Stop listening for shake gestures.

addListener('shake', callback: () => void)

Add a listener for shake events.

Returns: Promise with a handle to remove the listener

Interfaces

interface ShakeOptions {
  threshold?: number; // Shake sensitivity threshold
}

Platform Notes

iOS

• Uses the device’s accelerometer to detect shake gestures
• Works in both foreground and background (if app has background permissions)

Android

• Uses the SensorManager to detect shake events
• Requires no special permissions
• Works when app is in foreground

Common Use Cases

1. Debug Menu: Show developer options when device is shaken
2. Feedback: Trigger feedback form or bug report
3. Refresh: Refresh app data or clear cache
4. Games: Use shake as a game control mechanism
5. Undo: Implement shake-to-undo functionality

Troubleshooting

Shake not detected:

• Ensure the plugin is started with Shake.start()
• Try adjusting the threshold value (lower = more sensitive)
• Check that listeners are properly registered

Too sensitive/not sensitive enough:

• Adjust the threshold parameter in start() options
• Values typically range from 2.0 (very sensitive) to 5.0 (less sensitive)