docsreact-native

React Native SDK

v0.6.0beta

Integrate BugScreen into your React Native or Expo app. TypeScript wrapper bridging the native iOS and Android SDKs.

Beta. The React Native SDK is pre-1.0 (v0.6.0) — it is published, functional, and safe to integrate, and works on both the New Architecture (TurboModule) and the legacy bridge. As a 0.x release its API may still change before 1.0, so pin your version. The native Android and iOS SDKs it bridges are generally available.

Installation

Bare React Native

Install the package with your package manager:

bash

npm install @bugscreen/react-native
# or: yarn add @bugscreen/react-native
# or: pnpm add @bugscreen/react-native

Then install the iOS pods. The SDK is autolinked, so no manual native linking is needed:

bash

cd ios && bundle exec pod install

Requires React Native 0.74+, iOS 15+, and Android 7.0+ (API 24).

Expo (managed)

Install the package, then add the config plugin so you don't need to run expo prebuild by hand:

bash

npx expo install @bugscreen/react-native

Add the plugin to your app.json (the photoLibraryUsageDescription sets the iOS Info.plist string used when attaching screenshots):

app.json

json

{
  "expo": {
    "plugins": [
      [
        "@bugscreen/react-native",
        { "photoLibraryUsageDescription": "Used to attach screenshots to bug reports." }
      ]
    ]
  }
}

Then build a dev client — the SDK contains native code, so it does not run in Expo Go:

bash

npx expo prebuild
# then run a development build, e.g.
eas build --profile development

Setup

Initialise the SDK once, early in your app's lifecycle. BugScreen is for dev/QA — gate configure(...) so it doesn't run for end users.

App.tsx

tsx

import { useEffect } from 'react';
import { BugScreen } from '@bugscreen/react-native';

export default function App() {
  useEffect(() => {
    BugScreen.configure({
      apiKey: 'fb_your_api_key_here',
      screenshotDetection: true,
      debug: __DEV__,
    }).catch((err) => console.warn('BugScreen configure failed', err));
  }, []);

  // ...your app
}

Permissions

iOS: add an NSPhotoLibraryUsageDescription string to your Info.plist so the SDK can attach screenshots. The Expo config plugin adds this automatically; for bare React Native, add it yourself:

ios/YourApp/Info.plist

xml

<key>NSPhotoLibraryUsageDescription</key>
<string>Used to attach screenshots to bug reports.</string>

Android: the required permissions merge into your app automatically from the native library — no manifest changes needed. On Android 13 and below, request the media-read permission once at startup so screenshot detection works:

tsx

useEffect(() => {
  BugScreen.shouldRequestPermission().then((needed) =>
    needed ? BugScreen.requestScreenshotPermission() : true
  );
}, []);

Note: on Android 14+ and on iOS these helpers are no-ops that resolve immediately, so you can call them unconditionally without a Platform.OS check.

Usage

Automatic screenshot detection

When users take a screenshot, BugScreen automatically shows the bug report screen. That's it — no extra wiring.

Manual triggering

Open the bug report screen programmatically:

tsx

BugScreen.presentBugReport();

Logging

Add context to bug reports with application logs:

tsx

import { BugScreen, LogLevel } from '@bugscreen/react-native';

BugScreen.log('User tapped checkout button', LogLevel.Info);
BugScreen.log('Payment failed', LogLevel.Error);

Logs are automatically included with every bug report.

Custom data

Attach arbitrary key/value pairs to every subsequent bug report:

tsx

// Replace the whole map:
BugScreen.setCustomData({ env: 'staging', buildType: 'debug', userTier: 'pro' });

// Set or remove a single key:
BugScreen.setCustomDataValue('userId', 'abc-123');
BugScreen.removeCustomData('userId');

// Merge a map without replacing existing keys:
BugScreen.addCustomData({ plan: 'pro', region: 'eu' });

// Remove all custom data:
BugScreen.clearCustomData();

Call any time after configure(). The values are read when the bug report screen opens and appear in the report's metadata.

Configuration

Pass these options to BugScreen.configure(...):

Option	Default	Description
apiKey: string	Required	Your API key from the BugScreen console (must start with "fb_")
screenshotDetection?: boolean	true	Auto-detect screenshots and show the report UI
debug?: boolean	false	Enable verbose debug logging from the SDK (use __DEV__)

What gets collected?

BugScreen automatically collects this information with each report:

•Device model & manufacturer
•OS name & version
•App version & build number
•Screen size & density
•Memory (total & available)
•Device locale
•BugScreen SDK version

Start shipping bug reports

Create an account to start shipping bug reports from your app.

Get started