@ruttl/mobile-sdk

React Native SDK for in-app bug reporting. Drop a floating bug-report button into your app users capture the current screen, annotate it, fill in ticket details, and submit straight to Ruttl. One integration, identical experience on Android and iOS.

Features

• One-tap bug reports — a floating button lets users report bugs from anywhere in your app.
• Screenshot + annotation — tap to capture the current screen, or long-press to pick a photo from the library, then draw on it to point out the issue.
• Android & iOS — one integration, identical experience on both platforms.
• Automatic screen context — every report is tagged with the screen it came from.
• Offline queue: Failed submissions persisted in AsyncStorage and flushed when connectivity returns

Installation

1. Install the SDK

Under your app's root directory, run:

npm install @ruttl/mobile-sdk

2. Install peer dependencies

npm install react-native-view-shot react-native-gesture-handler react-native-svg \
  react-native-reanimated react-native-device-info react-native-image-picker \
  react-native-calendars toastify-react-native expo-constants expo-file-system \
  @react-native-async-storage/async-storage react-native-safe-area-context \
  @react-native-community/netinfo

3. Add to your app

The following code snippet shows how to integrate the SDK at your app's root.

Option A — layouts (Expo Router)

// app/_layout.tsx
import { Stack } from "expo-router";
import { BugTrackingRoot } from "@ruttl/mobile-sdk";

export default function RootLayout() {
  return (
    <BugTrackingRoot projectID="your-project-id" token="your-plugin-token">
      <Stack />
    </BugTrackingRoot>
  );
}

Option B — AppRegistry (bare React Native)

import {
  wrapWithBugTracking,
  BugTrackingInstrumentation,
} from "@ruttl/mobile-sdk";

const instrumentation = new BugTrackingInstrumentation();

AppRegistry.registerComponent("MyApp", () =>
  wrapWithBugTracking(App, {
    projectID: "your-project-id",
    token: "your-plugin-token",
    instrumentation,
  }),
);

// React Navigation — attach screen name to tickets
instrumentation.registerNavigationContainer(navigationRef);

Option C — React Navigation (without Expo Router)

BugTrackingInstrumentation is required — pass it to BugTrackingRoot and wire the navigation ref so tickets are tagged with the active screen:

const instrumentation = new BugTrackingInstrumentation();

export default function RootLayout() {
  return (
    <BugTrackingRoot instrumentation={instrumentation} projectID="..." token="...">
      <NavigationContainer ref={(ref) => instrumentation.registerNavigationContainer(ref)}>
        {/* screens */}
      </NavigationContainer>
    </BugTrackingRoot>
  );
}

Note: GestureHandlerRootView is provided automatically by BugTrackingRoot / wrapWithBugTracking — no manual wrapping needed.

4. iOS setup

Install native pods:

npx pod-install

Add to Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>Upload a screenshot from the photo library, or when screen capture is unavailable</string>

5. Android setup

No additional native configuration required. Ensure minSdkVersion is 21 or higher in android/build.gradle. FAB long-press and capture-failure upload use the system photo picker (react-native-image-picker); Android 13+ typically needs no extra permission.

6. Add screen instrumentation (required)

Every report is tagged with the screen it came from, so each integration must tell the SDK the current screen name. Choose the option that matches your app:

| Host app | Setup (from step 3) | Setup | | -------- | ------------------- | ----- | | Expo Router | Option A | None — BugTrackingRoot tracks the screen automatically | | React Navigation | Option B or C | BugTrackingInstrumentation + registerNavigationContainer(ref) | | Custom router | — | useBugTrackingScreen(name) (advanced) |

In development builds, the SDK surfaces an error if none of these is configured, so you catch a missing setup early.

7. Use the widget

Once setup is complete, a floating bug icon appears in your app.

• Tap to capture a screenshot of the current screen.
• Long-press to pick a photo from the library instead (same annotate-and-submit flow).

Draw to annotate the bug, fill in the ticket details, and submit. You can change the highlight colour while annotating. If automatic capture fails, an Upload button also opens the photo library.