React Native

The @rybbit/react-native SDK lets you track screens, events, errors, and users in React Native apps. Mobile sites get an App Analytics dashboard mode with mobile-specific labels (e.g. screen views instead of pageviews).

Creating a Mobile App Site

Before installing the SDK, create a site for your app in the Rybbit dashboard:

1. Click Add Site and select the React Native app option instead of Website.
2. Enter an app identifier (e.g. com.example.app). Letters, numbers, dots, hyphens, and underscores are allowed.
3. Copy the Site ID — you'll pass it to init().

Installation

npm install @rybbit/react-native @react-native-async-storage/async-storage

Initialization

Syntax

async rybbit.init(config: RybbitConfig): Promise<void>;

Example

import AsyncStorage from "@react-native-async-storage/async-storage";
import rybbit from "@rybbit/react-native";

await rybbit.init({
  analyticsHost: "https://app.rybbit.io/api",
  siteId: "1",
  appIdentifier: "com.example.app",
  appVersion: "1.4.2",
  storage: AsyncStorage,
  initialScreenName: "Home",
});

Configuration Options

Required Options

Optional Options

Remote Configuration

During init(), the SDK fetches your site's tracking settings from the dashboard. Two of them affect the React Native SDK:

Web-only settings (session replay, Web Vitals, outbound links, autocapture) do not apply to mobile apps.

Tracking Screens

Screens are the mobile equivalent of pageviews. Each screen view is tracked with the screen name as both the path and title.

Syntax

rybbit.screen(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;

Parameters

• name (string, Required): The screen name (e.g., "Home", "Checkout"). Used as the pathname (/Home) and page title.
• properties (object, Optional): Additional key-value pairs attached to the screen view.
• context (object, Optional): Overrides for the tracked payload. See Track Context.

Example

await rybbit.screen("Checkout");

// With properties and an explicit path
await rybbit.screen("Product", { productId: "sku-123" }, { pathname: "/products/sku-123" });

You can also track a raw path directly, mirroring the web SDK:

rybbit.pageview(path?: string, context?: TrackContext): Promise<void>;

React Navigation

The SDK ships a navigation tracker that hooks into React Navigation's NavigationContainer and automatically tracks a screen view whenever the active route changes. Consecutive events for the same route name are deduplicated.

import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
import rybbit from "@rybbit/react-native";

const navigationTracker = rybbit.createNavigationTracker();

function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => navigationTracker.onReady(navigationRef)}
      onStateChange={() => navigationTracker.onStateChange(navigationRef)}
    >
      {/* screens */}
    </NavigationContainer>
  );
}

Options

rybbit.createNavigationTracker(options?: NavigationTrackerOptions): NavigationTracker;

The returned tracker exposes onReady, onStateChange, and trackCurrentRoute — all take the navigation ref and track the current route if it changed. It works with any navigation library whose ref exposes a getCurrentRoute() method.

Tracking Custom Events

Syntax

rybbit.event(name: string, properties?: TrackProperties, context?: TrackContext): Promise<void>;

Parameters

• name (string, Required): The name of the event you want to track.
• properties (object, Optional): Additional key-value pairs related to the event.

Example

await rybbit.event("signup_started", { plan: "pro" });

await rybbit.event("purchase_completed", {
  orderId: "order-123",
  total: 49.99,
  currency: "USD",
});

Error Tracking

Capture handled errors with additional context. Error tracking must be enabled in your Rybbit dashboard (Capture Errors) — when disabled, error() calls are ignored.

Syntax

rybbit.error(error: Error | unknown, properties?: TrackProperties, context?: TrackContext): Promise<void>;

Non-Error values are converted to an Error. The message is truncated to 500 characters and the stack trace to 2,000.

Example

try {
  await processPayment(order);
} catch (error) {
  await rybbit.error(error, { component: "checkout", orderId: order.id });
  showErrorMessage();
}

User Identification

Associate events with a user ID and optional traits. The ID is persisted through the configured storage adapter and attached to all subsequent events.

rybbit.identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
rybbit.setTraits(traits: Record<string, unknown>): Promise<void>;
rybbit.clearUserId(): Promise<void>;
rybbit.getUserId(): string | null;

// After login
await rybbit.identify("user_123", { plan: "pro", signupDate: "2026-01-15" });

// Update traits later without changing the ID
await rybbit.setTraits({ plan: "enterprise" });

// After logout
await rybbit.clearUserId();

App Lifecycle Events

With autoTrackAppLifecycle enabled (the default), the SDK listens to React Native's AppState and tracks:

• app_open — when the app launches in the foreground or returns to the foreground from the background.
• app_background — when the app leaves the foreground, with a state property ("background" or "inactive").

Set autoTrackAppLifecycle: false in init() to disable these events.

Offline Handling and Retries

Events that fail to send (e.g., no network) are kept in an in-memory queue, capped at maxQueueSize (default 100, oldest dropped first). Queued events are retried when init() completes and whenever you call:

rybbit.flush(): Promise<void>;

Track Context

All tracking methods accept an optional context object to override what's sent with that event:

Device locale, screen dimensions, and a platform-appropriate user agent (including your appVersion) are detected automatically.

Cleanup

Removes the AppState lifecycle listener. Call it if you tear down the SDK, e.g. in tests or when unmounting your app root.

rybbit.cleanup(): void;

Differences from the Web SDK

• Session replay and Web Vitals are web-only and not available for React Native apps.
• No automatic outbound link, button click, form, or copy tracking (there is no DOM).
• Uncaught errors are not captured automatically — use rybbit.error() in your own error boundaries and catch blocks.
• The anonymous visitor ID is generated by the SDK and persisted via your storage adapter, rather than derived from browser fingerprinting.