Instrument your mobile app

​

What the React Native SDK captures

• Errors and console: errors that reach React Native’s global error handler, errors thrown while React renders inside <SazabiRoot>, and unhandled promise rejections on Hermes, plus console.error and console.warn output mirrored as log events. app.error.kind carries React Native’s own isFatal flag as fatal or uncaught, and each error is one row: the console.error line React Native prints for it is not mirrored again. With a storage adapter, a fatal error’s events are written to an outbox and replayed on the next launch after retryable failures. Permanent 4xx failures are dropped with a warning; see Delivery.
• Network: fetch and XMLHttpRequest requests other than intake uploads, Metro dev-server traffic, and /symbolicate calls in development, with a request-id response header attached as a join key against platform logs when present.
• Touches: one episode per touch, with taps and rapid repeat taps derived from them. The SDK records developer-authored names (accessibilityLabel, testID), never child text.
• Screens: route changes from your React Navigation or expo-router container, with param keys but not param values.
• Session identity: a session id that outlives launches when a storage adapter is set, a per-launch id, and a client-asserted distinct id you set with identify().

​

Set up the SDK

npm install @sazabi/react-native @react-native-async-storage/async-storage
# Expo: npx expo install @sazabi/react-native @react-native-async-storage/async-storage

import "@sazabi/react-native/register";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { init } from "@sazabi/react-native";
import { AppRegistry } from "react-native";
import App from "./App";
import { name as appName } from "./app.json";

// Or `Config.SAZABI_INTAKE_URL` with react-native-config.
const SAZABI_INTAKE_URL = "https://<your-intake-host>.intake.sazabi.com";

init({
  intakeUrl: SAZABI_INTAKE_URL,
  serviceName: "mobile-app",
  storage: AsyncStorage,
});

AppRegistry.registerComponent(appName, () => App);

import "@sazabi/react-native/register";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { init } from "@sazabi/react-native";
import "expo-router/entry";

init({
  intakeUrl: process.env.EXPO_PUBLIC_SAZABI_INTAKE_URL,
  serviceName: "mobile-app",
  storage: AsyncStorage,
});

import { useEffect } from "react";
import { Stack, useNavigationContainerRef } from "expo-router";
import { SazabiRoot, trackNavigation } from "@sazabi/react-native";

export default function RootLayout() {
  const navigationRef = useNavigationContainerRef();
  useEffect(() => trackNavigation(navigationRef), [navigationRef]);
  return (
    <SazabiRoot>
      <Stack />
    </SazabiRoot>
  );
}

​

Correlate with backend logs

​

Delivery and storage limits

​

Verify

1. Build or run the app with init() active, then launch it on a device or simulator.
2. Trigger an event the SDK captures: tap a button, navigate to another screen, then force a console.error("sazabi react native sdk test") from your app.
3. Filter to service.name equal to the serviceName you configured (mobile-app in the examples above). In a thread, ask the Sazabi agent for logs from that service, or run sazabi logs ask "logs from mobile-app" --since 1h.
4. You should see records with app.event_type values such as click, pointer, navigation, error, or network, with os.name on the resource naming ios or android. Events flush every 5 seconds by default (and when the app goes to the background), so they usually appear within about 10 seconds of the interaction.

​

Troubleshooting

• No events at all. Confirm init() runs in your entry file, that both required options are set, that the app is not running under react-native-web (where this SDK steps aside for the browser SDK), and that no consent gate is holding capture dormant.
• Requests rejected. Confirm intakeUrl is the complete intake URL copied from the source’s setup screen; a partial or hand-built URL is rejected.
• No touches or screens. Wrap the root in <SazabiRoot> and call trackNavigation() with your container ref.
• A fatal error’s events never arrived. Without a storage adapter there is no crash outbox. With AsyncStorage or another promise-returning adapter, the write may not finish before the process dies and the immediate send may fail. Events that were written are replayed on the next launch. A render error is recorded only when it is thrown inside <SazabiRoot>.
• Unhandled rejections are missing. Rejection tracking needs the Hermes engine; an app on JavaScriptCore gets no rejection events. On Hermes, a crash reporter initialized after init() took the engine’s single rejection-tracker slot. Initialize the SDK last, or hand the other reporter’s capture call to the SDK with errors.previousRejectionTracker; see Other crash reporters.
• Another crash reporter stopped seeing rejections. init() took the slot. Pass the reporter’s capture call as errors.previousRejectionTracker, or set errors: { unhandledRejections: false } to leave the slot to it. A development build prints one [@sazabi/react-native] note when the slot is taken with neither option set.
• Jest fails on an ES module. Include the SDK in your transformIgnorePatterns exception; see Jest. Metro resolves the register entry through the package’s react-native field even when package exports are disabled.
• Two copies of the SDK in one bundle. Deduplicate the dependency and import init and SazabiRoot from the same copy. Initialization is shared, but capture components from the other copy can miss events.
• Backend correlation missing. Ensure your backend forwards logs with the incoming trace context.

​

Further reading