shake-report-sdk

A clean, lightweight, and reliable React Native SDK that adds "Shake to Report" bug reporting to your Android and iOS applications. Inspired by Instabug, it handles shake detection, captures the active screen, collects system & app metadata, and displays an elegant modal to submit reports directly to your server.

Features

• Cross-Platform: Full Android & iOS support.
• Shake Detection: Triggers bug reporting automatically via a physical device shake gesture.
• Automatic Screen Capture: Takes a screenshot of the active screen when triggered, allowing the user to preview and submit it.
• Metadata Harvesting: Safely extracts device details (brand, model, OS version, emulator status) and app bundle properties.
• Customizable UI theme: Adjust colors to align with your app's style.
• Clean Fallbacks: Non-intrusive error boundaries; fails gracefully (e.g. opens modal without a screenshot if capture fails) without crashing the host application.

Installation

Install the package via npm or yarn:

npm install shake-report-sdk
# or
yarn add shake-report-sdk

Peer Dependencies

The SDK relies on native React Native modules for hardware access. Install the following peer dependencies in your host project:

npm install react-native-shake react-native-view-shot react-native-device-info
# or
yarn add react-native-shake react-native-view-shot react-native-device-info

iOS Setup (CocoaPods)

If compiling for iOS, navigate to the ios directory of your project and install the pods:

cd ios
pod install
cd ..

Usage

1. Basic Integration

Wrap your root component (usually App.js or index.js) inside ShakeReportProvider.

import React from 'react';
import { ShakeReportProvider } from 'shake-report-sdk';
import MainApp from './src/MainApp';

export default function App() {
  return (
    <ShakeReportProvider
      apiUrl="https://api.yourdomain.com"
      apiKey="YOUR_CLIENT_SDK_KEY"
      user={{
        id: 'user_12345',
        name: 'John Doe',
        email: '[email protected]',
      }}
      enableShake={true}
    >
      <MainApp />
    </ShakeReportProvider>
  );
}

2. Custom Styling (Themes)

You can customize the appearance of the Modal UI by passing a theme prop to the provider:

<ShakeReportProvider
  apiUrl="https://api.yourdomain.com"
  apiKey="YOUR_CLIENT_SDK_KEY"
  theme={{
    primaryColor: '#8B5CF6',         // Violet accent
    textColor: '#1F2937',            // Custom dark text
    backgroundColor: '#F3F4F6',      // Slate gray background
    inputBackgroundColor: '#FFFFFF',
    borderColor: '#D1D5DB',
  }}
>
  <MainApp />
</ShakeReportProvider>

3. Programmatic Trigger

For cases where a shake is inconvenient or you want to provide a manual feedback button (e.g., in a settings menu), use the useShakeReport hook:

import React from 'react';
import { Button, View, StyleSheet } from 'react-native';
import { useShakeReport } from 'shake-report-sdk';

export default function SettingsScreen() {
  const { openReporter } = useShakeReport();

  return (
    <View style={styles.container}>
      <Button title="Report a Problem" onPress={openReporter} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

Backend API Specification

The SDK submits reports directly to the host application's backend server. Your backend must expose a POST endpoint matching the format below.

Endpoint

POST {apiUrl}/bug-reports

Headers

x-sdk-api-key: <apiKey>
Content-Type: multipart/form-data

Form Fields (Multipart Payload)

• title (string): The summary of the bug.
• description (string): The detailed description typed by the user.
• user (stringified JSON): User info passed down via props.
• deviceInfo (stringified JSON): Device info (brand, model, osName, osVersion, isEmulator).
• appInfo (stringified JSON): Application info (appVersion, buildNumber, bundleId).
• screenshot (binary file, optional): The captured JPEG image file.

Payload JSON Structures:

user field:

{
  "id": "123",
  "name": "Test User",
  "email": "[email protected]"
}

deviceInfo field:

{
  "brand": "Apple",
  "model": "iPhone 13 Pro",
  "osName": "iOS",
  "osVersion": "15.4",
  "isEmulator": false
}

appInfo field:

{
  "appVersion": "1.0.2",
  "buildNumber": "24",
  "bundleId": "com.company.myapp"
}

Configuration Props

ShakeReportProviderProps

| Prop Name | Type | Required | Description | | :--- | :--- | :--- | :--- | | apiUrl | string | Yes | Server base URL (e.g. https://api.domain.com). | | apiKey | string | Yes | Client API key appended to headers as x-sdk-api-key. | | user | ShakeReportUser | No | Logged-in user information (id, name, email). | | enableShake | boolean | No | Toggle shake detection listener. Default is true. | | theme | ShakeReportTheme | No | Override colors (primary, background, success, etc.). | | onReportSubmitted | (response: any) => void | No | Callback invoked on successful report submission. | | onReportFailed | (error: unknown) => void | No | Callback invoked when API request fails. |

Troubleshooting

1. The modal does not open on iOS Simulator / Android Emulator when shaking

Emulators do not always support physical shake events out-of-the-box.

• iOS Simulator: Choose Hardware -> Shake Gesture from the Simulator menu bar.
• Android Emulator: Open the emulator setting menu, or run command adb shell input keyevent 82 to trigger the dev menu, or use the programmatic trigger openReporter() to test.

2. iOS build fails with linker error or missing module

Make sure you ran pod install inside the ios directory. If the issue persists, clear your build folders and rebuild:

watchman watch-del-all
rm -rf node_modules
yarn install
cd ios && pod install && cd ..
react-native run-ios

3. File upload fails / Backend does not parse form fields

Ensure your backend web framework parses multipart/form-data payloads (e.g. using multer in Express/Node.js, or file parsers in LoopBack). The screenshot key contains the binary image upload.