@zetalyx/react-native

React Native SDK for Zetalyx — crash reporting, screen tracking, network logging, and analytics for mobile apps.

Installation

npm install @zetalyx/react-native

Quick Start

1. Wrap your app with the provider

import { ZetalyxRNProvider } from '@zetalyx/react-native';

export default function App() {
  return (
    <ZetalyxRNProvider apiKey="pk_live_your_api_key" userId={currentUser?.id}>
      <Navigation />
    </ZetalyxRNProvider>
  );
}

2. Use hooks in any component

import { useTrack, useTrackBehavior } from '@zetalyx/react-native';

function HomeScreen() {
  const track = useTrack();
  const trackBehavior = useTrackBehavior();

  useEffect(() => {
    track('screen_loaded', { screen: 'home' });
  }, []);

  return (
    <Button
      title="Get Started"
      onPress={() => trackBehavior('cta_pressed', { screen: 'home' })}
    />
  );
}

Features

• Crash reporting — auto-captures JS crashes via React Native's ErrorUtils
• Screen tracking — automatic screen view tracking with React Navigation
• Network logging — intercepts fetch to track HTTP errors and requests
• App lifecycle — tracks app foreground/background transitions
• Session management — automatic session ID and user identity
• Batched transport — events queued and sent in batches with retry/backoff

Provider

<ZetalyxRNProvider
  apiKey="pk_live_..."        // Required
  userId="user_123"           // Optional — auto-calls identify()
  endpoint="https://..."      // Default: 'https://api.zetalyx.com'
  batchSize={10}              // Flush after N events
  flushInterval={5000}        // Flush every N ms
  debug={false}               // Console debug logging
  autoCaptureErrors={true}    // Auto-capture JS crashes (default: true)
>
  {children}
</ZetalyxRNProvider>

The provider automatically:

• Creates and manages the RNClient lifecycle
• Sets up crash handler via ErrorUtils (when autoCaptureErrors is true)
• Cleans up on unmount

Hooks

useZetalyxRN()

Access the underlying RNClient instance directly.

const client = useZetalyxRN();
await client.flush();

useTrack()

const track = useTrack();
track('item_viewed', { item_id: '123', category: 'electronics' });

useTrackError()

const trackError = useTrackError();

try {
  await apiCall();
} catch (err) {
  trackError(err, { context: 'api_call' });
}

useTrackBehavior()

const trackBehavior = useTrackBehavior();
trackBehavior('add_to_cart', { product_id: 'sku_456', quantity: 2 });

Screen Tracking with React Navigation

Automatically track screen views when navigating between screens:

import { NavigationContainer } from '@react-navigation/native';
import { useZetalyxNavigation } from '@zetalyx/react-native';

function App() {
  const client = useZetalyxRN();
  const { navigationRef, onStateChange } = useZetalyxNavigation(client);

  return (
    <NavigationContainer ref={navigationRef} onStateChange={onStateChange}>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Profile" component={ProfileScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

This tracks:

• screen_view events with the screen name
• Time spent on each screen (duration_ms)
• Previous screen name and navigation params

Network Logging

Intercept fetch calls to automatically track HTTP errors and optionally all requests:

import { enableNetworkLogging, useZetalyxRN } from '@zetalyx/react-native';

function App() {
  const client = useZetalyxRN();

  useEffect(() => {
    const cleanup = enableNetworkLogging(client, {
      captureErrors: true,     // Track 4xx/5xx responses (default: true)
      captureRequests: false,  // Track all requests (default: false)
      ignoreUrls: [/zetalyx/], // Ignore SDK's own requests (default)
    });

    return cleanup;
  }, [client]);

  return <YourApp />;
}

Tracked data includes: URL, HTTP method, status code, and duration.

App Lifecycle Tracking

Track when the app moves between foreground and background:

import { setupLifecycleTracking } from '@zetalyx/react-native';

// Inside a component or effect
useEffect(() => {
  const cleanup = setupLifecycleTracking(client);
  return cleanup;
}, [client]);

This tracks app_foreground and app_background behavior events.

Direct Client Usage

For cases outside of React components:

import { RNClient } from '@zetalyx/react-native';

const zetalyx = new RNClient({
  apiKey: 'pk_live_your_api_key',
});

zetalyx.track('app_launched');
zetalyx.identify('user_123');
zetalyx.trackError(new Error('Something failed'));

// Flush before the app closes
await zetalyx.flush();

Full Example

import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import {
  ZetalyxRNProvider,
  useZetalyxRN,
  useZetalyxNavigation,
  useTrack,
  enableNetworkLogging,
  setupLifecycleTracking,
} from '@zetalyx/react-native';

const Stack = createNativeStackNavigator();

function AppContent() {
  const client = useZetalyxRN();
  const { navigationRef, onStateChange } = useZetalyxNavigation(client);

  useEffect(() => {
    const cleanupNetwork = enableNetworkLogging(client, { captureErrors: true });
    const cleanupLifecycle = setupLifecycleTracking(client);

    return () => {
      cleanupNetwork();
      cleanupLifecycle();
    };
  }, [client]);

  return (
    <NavigationContainer ref={navigationRef} onStateChange={onStateChange}>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Profile" component={ProfileScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

export default function App() {
  return (
    <ZetalyxRNProvider
      apiKey="pk_live_your_api_key"
      userId={currentUser?.id}
      debug={__DEV__}
    >
      <AppContent />
    </ZetalyxRNProvider>
  );
}

License

MIT