@galacha/react-native

React Native SDK for Galacha Logs - Session recording and analytics for mobile apps.

Installation

npm install @galacha/react-native

# Required peer dependencies
npm install @react-native-async-storage/async-storage

# Optional - for navigation tracking
npm install @react-navigation/native

# Optional - for advanced gesture tracking
npm install react-native-gesture-handler

Quick Start

import Galacha from '@galacha/react-native';

// Initialize the SDK
await Galacha.init({
  projectKey: 'pk_your_project_key',
});

// Identify a user (optional)
Galacha.identify('user123', {
  email: '[email protected]',
  plan: 'pro',
});

// Track custom events
Galacha.track('purchase', {
  amount: 99.99,
  currency: 'USD',
});

Configuration Options

Galacha.init({
  // Required
  projectKey: 'pk_xxx',

  // Optional - API endpoint (default: https://api.galacha.me)
  apiUrl: 'https://api.galacha.me',

  // Optional - Initial user identification
  identifier: '[email protected]',
  traits: { plan: 'pro' },

  // Optional - Feature flags (all default to true)
  captureTouches: true,    // Track touch events
  captureNetwork: true,     // Track network requests
  captureErrors: true,      // Track JS errors
  maskTextInputs: true,     // Mask text inputs for privacy

  // Optional - Batching settings
  flushIntervalMs: 5000,    // Flush every 5 seconds
  flushMaxEvents: 50,       // Flush when 50 events buffered
  sessionTimeoutMs: 1800000, // 30 minute session timeout
});

API Reference

Galacha.init(config)

Initialize the SDK. Must be called before any other methods.

await Galacha.init({
  projectKey: 'pk_xxx',
});

Galacha.identify(userId, traits?)

Associate the current session with a user identity.

Galacha.identify('user123', {
  email: '[email protected]',
  company: 'Acme Inc',
  plan: 'enterprise',
});

Galacha.track(eventName, properties?)

Track a custom event.

Galacha.track('button_clicked', {
  button: 'checkout',
  screen: 'cart',
});

Galacha.track('purchase_completed', {
  orderId: '12345',
  amount: 149.99,
  items: 3,
});

Galacha.screen(screenName, params?)

Manually track a screen view. Use this if you're not using React Navigation.

Galacha.screen('ProductDetail', {
  productId: 'abc123',
  category: 'electronics',
});

Galacha.flush()

Manually flush buffered events to the server.

await Galacha.flush();

Galacha.stop()

Stop the SDK and cleanup resources.

await Galacha.stop();

React Navigation Integration

For automatic screen tracking with React Navigation:

import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import Galacha, { createNavigationRecorder } from '@galacha/react-native';

function App() {
  const navigationRef = useNavigationContainerRef();
  const navigationRecorder = createNavigationRecorder(Galacha.getBuffer()!);

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => navigationRecorder.onNavigationReady(navigationRef)}
      onStateChange={(state) => navigationRecorder.onStateChange(state)}
    >
      {/* Your app screens */}
    </NavigationContainer>
  );
}

Touch Tracking

For detailed touch tracking, wrap your app with TouchCaptureView:

import Galacha, { TouchCaptureView } from '@galacha/react-native';

function App() {
  const buffer = Galacha.getBuffer();

  if (!buffer) return null;

  return (
    <TouchCaptureView buffer={buffer}>
      {/* Your app content */}
    </TouchCaptureView>
  );
}

Or use the touch handlers directly:

import { createTouchHandlers } from '@galacha/react-native';

function MyComponent() {
  const buffer = Galacha.getBuffer();
  const handlers = buffer ? createTouchHandlers(buffer) : {};

  return (
    <View
      onTouchStart={handlers.onTouchStart}
      onTouchMove={handlers.onTouchMove}
      onTouchEnd={handlers.onTouchEnd}
    >
      {/* Content */}
    </View>
  );
}

Event Types

The SDK automatically captures these events:

App Lifecycle

• app_state_change - Foreground/background transitions
• app_launch - App launch events

Navigation

• screen_view - Screen views (with React Navigation or manual)
• navigation_state - Full navigation state changes

Interactions

• touch - Touch press, move, release, long press
• gesture - Swipes and other gestures

Network

• network_request - HTTP requests with method, URL, status, duration

Errors

• js_error - Unhandled JavaScript errors and promise rejections

Device

• device_info - Platform, OS version, screen dimensions
• session_meta - Session metadata on start

Privacy

The SDK is designed with privacy in mind:

• No screen recording - Unlike web SDKs, we don't capture screenshots by default
• Text input masking - Enabled by default to protect sensitive input
• Network body not captured - Only metadata (URL, status, timing)
• Local processing - Events are batched locally before sending

Debugging

In development mode (__DEV__), the SDK logs debug information to the console:

[Galacha] Initializing with config: {...}
[Galacha] Session initialized: abc123
[Galacha] Screen view: HomeScreen
[Galacha] Sent 10 events successfully

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import Galacha, {
  GalachaConfig,
  MobileEventType,
  TouchEvent,
  ScreenViewEvent,
} from '@galacha/react-native';

Requirements

• React Native >= 0.70.0
• React >= 17.0.0
• @react-native-async-storage/async-storage >= 1.17.0

License

MIT