npm package: @galacha/react-native
Description: React Native SDK for Galacha Logs - Session recording and analytics
Author: Galacha
Latest version: 0.8.0

# @galacha/react-native

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

## Installation

```bash
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

```typescript
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: 'user@example.com',
  plan: 'pro',
});

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

## Configuration Options

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

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

  // Optional - Initial user identification
  identifier: 'user@email.com',
  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.

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

### `Galacha.identify(userId, traits?)`

Associate the current session with a user identity.

```typescript
Galacha.identify('user123', {
  email: 'user@example.com',
  company: 'Acme Inc',
  plan: 'enterprise',
});
```

### `Galacha.track(eventName, properties?)`

Track a custom event.

```typescript
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.

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

### `Galacha.flush()`

Manually flush buffered events to the server.

```typescript
await Galacha.flush();
```

### `Galacha.stop()`

Stop the SDK and cleanup resources.

```typescript
await Galacha.stop();
```

## React Navigation Integration

For automatic screen tracking with React Navigation:

```typescript
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`:

```typescript
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:

```typescript
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:

```typescript
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