shake-report-web-sdk

A clean, lightweight, and reliable React JS web SDK that adds bug reporting features (Shake to Report for PWAs and a floating widget for desktop) to your web applications. It handles device motion detection, captures client-side screenshots via html2canvas, gathers system metadata, and displays an elegant modal to submit reports directly to your server.

Features

• PWA Shake Detection: Triggers bug reporting automatically via a physical device shake gesture on mobile web browsers using DeviceMotionEvent.
• Desktop Widget: Displays a sleek, customizable floating button with a bug icon in the bottom-right corner for non-touch devices.
• Client-Side Screenshots: Automatically grabs a visual snapshot of the page using html2canvas, letting users preview and toggling it inside the feedback form.
• Zero-Config Styles: Dynamically injects style sheets so you don't have to configure special webpack/CSS loaders.
• Metadata Harvesting: Extracts details about the browser version, operating system, current URL, viewport size, and network language.

Installation

Install the package via npm or yarn:

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

Usage

1. Basic Integration

Wrap your React root component inside ShakeReportProvider.

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

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

2. Custom Themes

Customize colors of the floating button and the bug report form by passing a theme prop:

<ShakeReportProvider
  apiUrl="https://api.yourdomain.com"
  apiKey="YOUR_CLIENT_SDK_KEY"
  theme={{
    primaryColor: '#8B5CF6',         // Violet accent
    textColor: '#111827',            // Light mode custom text
    backgroundColor: '#FFFFFF',      // Light mode background
    inputBackgroundColor: '#F3F4F6',
    borderColor: '#E5E7EB',
  }}
>
  <MainApp />
</ShakeReportProvider>

3. Programmatic Trigger

Trigger the bug reporter manually (e.g. from a help desk button) using the useShakeReport hook:

import React from 'react';
import { useShakeReport } from 'shake-report-web-sdk';

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

  return (
    <button onClick={openReporter} className="help-btn">
      Report a Bug
    </button>
  );
}

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 on mobile web/PWA. Default is true. | | showFloatingButton | 'always' \| 'desktop-only' \| 'never' | No | Floating bug icon trigger. Default is 'desktop-only'. | | theme | ShakeReportTheme | No | Override colors (primary, background, success, etc.). | | appVersion | string | No | Version metadata of the host application (default is '1.0.0-web'). | | onReportSubmitted | (response: any) => void | No | Callback invoked on successful report submission. | | onReportFailed | (error: unknown) => void | No | Callback invoked when API request fails. |