How to add in-app bug reporting to a React Native app (step-by-step)

React Native teams need bug reports that feel native to testers and useful to developers. A generic form can collect a sentence. A proper in-app bug reporter captures the screenshot, logs, device, build, and account context that make the issue reproducible.

How do you add bug reporting to a React Native app?

To add bug reporting to a React Native app, install @bugscreen/react-native, run CocoaPods for iOS, configure the SDK with your BugScreen API key, enable screenshot detection, and connect your BugScreen app to Jira, GitHub, ClickUp, or Slack. The React Native package wraps native iOS and Android SDKs, so the report UI stays native on each platform. Testers can take a screenshot or open the reporter manually, add a short description, and submit a complete ticket without leaving the app.

What you'll build

You will add a screenshot-triggered bug reporter to a React Native app. The reporter will:

• Open from a screenshot or manual call
• Attach the screenshot to the report
• Include device, OS, app build, logs, and custom context
• File the report to your connected tracker

For the full SDK reference, use the React Native docs.

Step 1: Install the SDK

Install the package:

yarn add @bugscreen/react-native

Then install iOS pods:

cd ios && bundle exec pod install

The SDK requires native code, so Expo Go is not supported. For Expo projects, use a development build with the bundled config plugin.

Step 2: Initialise with your API key

Configure BugScreen once when your app starts:

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

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

  return null;
}

Keep the API key in the same place you store other public mobile configuration. BugScreen validates that the key starts with fb_.

Step 3: Trigger on screenshot

With screenshotDetection: true, BugScreen uses the native iOS and Android SDKs to react when a tester takes a screenshot. You can also open the reporter yourself:

BugScreen.presentBugReport();

That is useful for a "Report a problem" button in a settings or debug menu.

Step 4: Capture logs and custom context

Add logs around flows that often produce bugs:

BugScreen.log('User tapped checkout', LogLevel.Info);
BugScreen.setCustomData({
  environment: 'staging',
  featureFlag: 'new-checkout',
});
BugScreen.setUser({ id: 'test-user-123', role: 'beta' });

This context helps the developer understand which account, role, build, and path produced the issue.

Step 5: Handle Android screenshot permission

On Android 14 and later, no runtime permission is needed. On Android 13 and below, request the required media permission once:

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

Step 6: File to Jira or GitHub

Connect your BugScreen app to the tracker your team already uses. For setup, see the Jira integration docs or GitHub integration docs.

Once connected, a submitted React Native bug report becomes a tracker ticket with the screenshot, description, logs, device context, and account context attached.

Testing your integration

Install a development build on a physical iOS and Android device, configure BugScreen, take a screenshot, submit a report, and confirm the ticket appears in your tracker. Check that the issue has the screenshot, app version, OS, device model, and the custom data you expect.