@bugsession/react-native
v0.1.0-beta.7
Published
Opt-in React Native runtime evidence SDK
Readme
@bugsession/react-native — beta
Opt-in screen recording, microphone narration and bounded runtime telemetry for React Native. This beta is for invited testers using non-sensitive test data. It is not ready for general production use. This SDK is proprietary (UNLICENSED), with all rights reserved. Beta use requires authorization from the package owner; see LICENSE.
Compatibility
The SDK supports React 18.3.1–19.x and React Native 0.76–0.88. Expo SDK 54–58 are supported; SDK 52–53 are best effort. CI builds Android against SDK 52–58 and iOS simulators against SDK 52 and 54–58. Each Expo SDK selects its matching React and React Native versions; do not mix versions manually. iOS and Android require a native build and @bugsession/capture-native; Expo Go cannot capture screen video. Android uses MediaProjection and asks for screen-capture consent every session. The hosted recorder admits one session at a time.
Install
After publication:
npm install @bugsession/react-native@beta @bugsession/capture-native@beta
npx expo install expo-audio expo-file-systemFor local evaluation, install the generated .tgz files instead. Configure microphone permission through your audio library and rebuild the native app. Explain recording to the tester and start only after their explicit action.
iOS example
import { BugSession } from '@bugsession/react-native';
import { IOSCapture } from '@bugsession/capture-native';
import * as FileSystem from 'expo-file-system/legacy';
BugSession.configure({
recorderUrl: 'https://beta.bugsession.dev',
recorderToken: projectIngestionKey, // Generate in dashboard → project → Connect your SDK.
device: { platform: 'ios', model: 'tester-device' },
application: { version: '1.0.0', gitCommit: appSourceCommit },
capture: {
...IOSCapture,
async upload(url, uri, headers = {}) {
const response = await FileSystem.uploadAsync(url, uri, {
httpMethod: 'POST',
uploadType: FileSystem.FileSystemUploadType.BINARY_CONTENT,
headers,
});
if (response.status !== 200) throw new Error(`Upload failed: ${response.status}`);
},
},
});
// Or render <BugSession.Trigger /> for a floating bottom-right record button.
// Set position to bottom-left, top-right, or top-left; offset defaults to 24.
// Render it above your navigator, and provide onError to display failures.
// Stop within 160 seconds.
await BugSession.start();
BugSession.trackAction({ name: 'save-profile', screen: 'Profile' });
BugSession.trackNavigation('Settings');
const { id } = await BugSession.stop({ note: 'Tapped Save; expected the name to stay, it reverted.' }); // note is optional; a promise also worksConfigure once while idle. Wire an automatic stop timer into your recording UI, keep the app foregrounded through upload, and display recording/upload failures. BugSession.stop() acknowledges queued processing; it does not promise completed analysis. Poll authenticated GET /sessions/{id}/status until status is complete, processing-failed, or interrupted, and inspect processing.warnings. complete with partial processing can mean missing narration.
React Navigation integration: call the function returned by BugSession.navigationListener(navigationRef) from both NavigationContainer.onReady and onStateChange. Expo Router apps can call trackNavigation when the committed pathname changes. Use BugSession.Touchable to instrument a Pressable, or trackAction directly. Send caught errors through BugSession.captureError(error).
Render errors are caught by Expo Router before they reach the global handler. Export the SDK's boundary from your root layout so they are captured: export const ErrorBoundary = BugSession.ErrorBoundary;. Unhandled promise rejections are captured in every build; in development they still reach LogBox.
configure() installs fetch, XMLHttpRequest (axios and most HTTP clients), console (log, info, debug, warn, error), error and rejection hooks for the app's lifetime; each request is recorded once, and the SDK's own uploads are skipped. By default the SDK keeps the last 60 seconds of these app events (at most 500; never video or audio) in memory. When a recording starts, they are attached with negative timestamps and preRecording: true, so a bug that happened just before the tester pressed record keeps its context. After Stop, events keep being collected for postRecordSeconds (default 5, maximum 30, 0 disables) while the video uploads, and are attached with postRecording: true, so the response to the tester's last tap is kept. Nothing leaves the device unless a recording starts. Set preRecordSeconds (maximum 300) to change the earlier window, or 0 to collect only while recording. Recorders deployed before pre- or post-record support accept the recording and ignore these events.
Failed requests (status 400 or higher, text or JSON responses) include responseExcerpt: the first 1,000 characters of the response body, with JSON fields named like passwords, tokens, secrets, keys, cookies and sessions masked, plus the usual bearer and URL redaction. Successful responses and request bodies are never captured.
Wrap your navigator once in <BugSession.Capture> to record every tap as an action event with auto: true, the tap position in points, the current screen and, when one can be read, the touched element's label (accessibility label, aria-label, title, placeholder, visible text or testID; never a text field's value). It only observes touches and never blocks gestures. BugSession.Touchable and trackAction remain available for explicit names.
<BugSession.Trigger /> renders a slim tab docked to a screen edge, so it never covers bottom buttons or tab bars. Tap it to start recording. Drag it along the edge or across to the other side; it remembers its placement while the app is open. Render it once above the app navigator. position picks the initial edge and half (bottom-right by default), offset the distance from the top or bottom safe area, and draggable={false} locks it. Supply children to replace the idle record mark.
While recording, the tab shows a pulsing dot, elapsed time and live microphone levels. Tap it for the options panel: Draw on screen and Stop & send. The panel hides itself after a few seconds so it stays out of the video as much as possible; the tab itself is part of the screen recording. Drag the panel by its top row (the grip, timer and levels) to uncover whatever it was hiding; it reopens where you left it. Draw opens a pen layer over the app: testers circle the problem while narrating, then use Undo, Clear or Done. Drawings appear in the video, and each stroke is recorded as an annotation event with its bounds in screen points. After stopping, a sheet asks the tester what they expected and what happened. It is optional and can be skipped; the recording has already ended, so the note is not in the video. The upload runs while they type, and the report waits up to 3 minutes for the answer before sending without it. Pass askForNote={false} to skip the sheet. Then a toast at the top shows sending progress, then "Report sent" or "Not sent" with the reason; it also reflects BugSession.start()/stop() called directly. Recording stops automatically after maxDurationSeconds (default 150) so uploads stay within the recorder limit. Pass onError to also receive permission, recorder, and upload failures. With react-native-screens installed (included with Expo Router), the tab renders above native modals. Live levels and exact safe-area placement need @bugsession/capture-native 0.1.0-beta.4 or later in a rebuilt native app; older builds show static bars.
Android uses AndroidCapture from @bugsession/capture-native plus an audio adapter implementing prepare, start, stop (returns a local URI), and upload. prepare must request microphone permission. expo-audio can provide this adapter. Android shows a system screen-capture prompt each session and a persistent capture notification; keep the app foregrounded through upload.
Fetch instrumentation omits request/response bodies, headers, URL credentials and query strings. Free-text redaction is best effort. Video, audio, screen labels, URL paths and arbitrary logs can contain private information. Record only test data and stop before entering credentials. Native crashes and process termination can lose in-memory telemetry. A maximum of 5,000 events is retained. Project SDK keys are extractable from an app build, so share them only with invited testers. Each key scopes uploads to one project; it cannot read recordings. Revoke unused keys. Keep recorder operator and Clerk secrets server-side.
Project-scoped beta uploads
Generate an SDK key from your dashboard project. Copy it into recorderToken; the backend derives project scope from the key. No SDK projectId option is needed. A project ID alone never authorizes uploads. Never distribute recorder operator or Clerk secret keys.
Keys allow recording creation, media/telemetry submission and processing status only for their project. They cannot list or download recordings. Revoking a key rejects subsequent requests, including an unfinished upload sequence; an already accepted upload or processing job can finish. Replace the app configuration before revoking a key still used by testers.
Hosted beta accepts native iOS ReplayKit and Android MediaProjection uploads. Limits are 3 active keys per project, 20 accepted recording starts per project per recorder hour, 600 requests per project per minute, 128 MiB per video, 32 MiB per audio upload, and 4 MiB telemetry bodies. The recorder still runs one recording or processing job at a time. Rate counters reset on restart. Mobile keys are extractable; treat them as limited ingestion capabilities, not account credentials.
After stopping, open the same project in the dashboard and refresh its recordings list to see status. Status polling using an SDK key returns a warning count, not raw processing warnings; inspect the dashboard/operator tools for processing details.
