@repliqo/sdk-react-native 0.1.0

package/INTEGRATION_GUIDE.md

@@ -0,0 +1,1312 @@
+# Repliqo SDK for React Native - Integration Guide
+
+> **Version:** 0.1.0
+> **Package:** `@repliqo/sdk-react-native`
+> **Last updated:** March 2026
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Prerequisites](#2-prerequisites)
+3. [Installation](#3-installation)
+4. [Quick Start (5-Minute Setup)](#4-quick-start-5-minute-setup)
+5. [Configuration Reference](#5-configuration-reference)
+6. [Navigation Tracking (Automatic)](#6-navigation-tracking-automatic)
+7. [Custom Events](#7-custom-events)
+8. [Error/Crash Tracking](#8-errorcrash-tracking)
+9. [Manual Screen Tracking](#9-manual-screen-tracking)
+10. [Session Management](#10-session-management)
+11. [Device Info](#11-device-info)
+12. [Advanced: Flush Control](#12-advanced-flush-control)
+13. [Advanced: Debug Mode](#13-advanced-debug-mode)
+14. [Dashboard Guide](#14-dashboard-guide)
+15. [API Reference](#15-api-reference)
+16. [Screen Capture Architecture](#16-screen-capture-architecture)
+17. [Troubleshooting](#17-troubleshooting)
+17. [TypeScript Types](#17-typescript-types)
+
+---
+
+## 1. Overview
+
+Repliqo is a lightweight analytics SDK designed specifically for React Native applications. It provides developers with deep visibility into how users interact with their mobile apps by capturing navigation patterns, screen visits, touch events, crashes, and custom events -- all with minimal performance overhead and zero impact on your app's startup time.
+
+The SDK works on a buffer-and-batch architecture: events are collected in memory as users interact with your app, then sent to the Repliqo backend in efficient batches. The backend stores and processes this data, which you can then explore through the Repliqo dashboard. The dashboard provides session replays, heatmaps, funnel analysis, crash reports, and data export capabilities. Because events are batched rather than sent one-by-one, the SDK keeps network usage low and never blocks the main thread.
+
+---
+
+## 2. Prerequisites
+
+Before integrating the Repliqo SDK, make sure your project meets the following requirements:
+
+- **React Native** >= 0.68.0
+- **React** >= 17.0.0
+- **@react-navigation/native** >= 6.0.0 (required only if you want automatic navigation tracking)
+- **A Repliqo account with an API key**
+
+### Getting Your API Key
+
+1. Go to the Repliqo dashboard at **[https://repliqo.odmservice.site](https://repliqo.odmservice.site)**.
+2. Sign in or create a new account.
+3. Navigate to **Settings > Applications** and click **Create Application**.
+4. Give your app a name (this becomes your `appId`) and note the **API key** that is generated.
+5. Copy both the `appId` and the `apiKey` -- you will need them during SDK initialization.
+
+---
+
+## 3. Installation
+
+### From a Local Path (Development)
+
+If you have the SDK source code locally (e.g., in a monorepo or cloned repository), install it by referencing the local path:
+
+```bash
+npm install file:../path/to/sdk-react-native
+```
+
+For example, if your project structure looks like this:
+
+```
+my-workspace/
+  app-analytics-api/
+    packages/
+      sdk-react-native/     # <-- The SDK
+  my-react-native-app/      # <-- Your app
+```
+
+Run this from your React Native app directory:
+
+```bash
+npm install file:../app-analytics-api/packages/sdk-react-native
+```
+
+### From npm (Future)
+
+Once the SDK is published to npm, you will be able to install it with:
+
+```bash
+npm install @repliqo/sdk-react-native
+```
+
+### Post-Installation
+
+After installing, if Metro bundler has trouble resolving the module, clear the cache:
+
+```bash
+npx react-native start --reset-cache
+```
+
+The SDK includes a native Android module for **multi-window screen capture** (captures modals, alerts, and dialogs). It autolinks automatically via React Native CLI — no manual linking, no `settings.gradle` edits, no `MainApplication` changes needed.
+
+On Android, the native module uses `View.draw()` on all app windows to composite a full screenshot including overlays. **No permissions are required** — it does not use MediaProjection or screen recording APIs.
+
+On iOS, the native module is not yet implemented. The SDK falls back to `react-native-view-shot` which captures the main view only.
+
+> **Note:** After installing, you must rebuild the native app (`npx react-native run-android`) for the native module to be linked. A Metro-only restart is not sufficient.
+
+---
+
+## 4. Quick Start (5-Minute Setup)
+
+This section gets you up and running with the absolute minimum configuration. After completing these two steps, navigation tracking and screen visit analytics will work automatically.
+
+### Step 1: Create the Analytics Service File
+
+Create a file at `src/services/repliqo.ts` in your project:
+
+```typescript
+// src/services/repliqo.ts
+
+/**
+ * Repliqo Analytics SDK - Initialization and session management.
+ *
+ * This file initializes the SDK and starts a session with device info.
+ * Import and call initRepliqo() from your App.tsx on startup.
+ */
+import { AppAnalytics } from '@repliqo/sdk-react-native';
+import { Platform, Dimensions } from 'react-native';
+
+// Replace these with your actual values from the Repliqo dashboard
+const REPLIQO_API_KEY = 'your-api-key-here';
+const REPLIQO_APP_ID = 'your-app-id';
+
+// Use localhost for development, production URL for release builds
+const REPLIQO_API_URL = __DEV__
+  ? 'http://10.0.2.2:3050'    // Android emulator localhost
+  : 'https://api-repliqo.odmservice.site';
+
+// Guard against double-initialization
+let initialized = false;
+
+export async function initRepliqo(): Promise<void> {
+  if (initialized) return;
+
+  try {
+    // 1. Initialize the SDK with your configuration
+    AppAnalytics.init({
+      apiKey: REPLIQO_API_KEY,
+      appId: REPLIQO_APP_ID,
+      baseUrl: REPLIQO_API_URL,
+      enableTouchTracking: false,       // Disable if you don't need heatmaps
+      enableNavigationTracking: true,    // Automatic navigation events
+      enableCrashTracking: true,         // Capture JS errors and unhandled rejections
+      enableSnapshots: false,            // Disable for lower overhead
+      batchSize: 20,                     // Send events in groups of 20
+      flushInterval: 30000,              // Flush every 30 seconds
+      debug: __DEV__,                    // Log SDK activity in development
+    });
+
+    // 2. Gather device information
+    const { width, height } = Dimensions.get('window');
+    const deviceId = `${Platform.OS}-${Math.random().toString(36).slice(2, 10)}`;
+
+    // 3. Start a session -- this registers the device with the backend
+    await AppAnalytics.getInstance().startSession(deviceId, {
+      os: Platform.OS,
+      osVersion: String(Platform.Version),
+      model: 'Unknown',                 // Use react-native-device-info for real values
+      brand: 'Unknown',
+      screenWidth: width,
+      screenHeight: height,
+      appVersion: '1.0.0',              // Replace with your app version
+    });
+
+    initialized = true;
+    if (__DEV__) console.log('[Repliqo] Session started');
+  } catch (error) {
+    // Never let analytics break the host app
+    if (__DEV__) console.warn('[Repliqo] Init failed:', error);
+  }
+}
+```
+
+### Step 2: Call It from App.tsx
+
+In your root `App.tsx`, import and call `initRepliqo()` inside a `useEffect`. Use a `setTimeout` to ensure analytics initialization never blocks your app's startup:
+
+```typescript
+// App.tsx
+
+import React, { useEffect } from 'react';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { AppNavigator } from './src/navigation/AppNavigator';
+import { initRepliqo } from './src/services/repliqo';
+
+function App() {
+  useEffect(() => {
+    // Initialize analytics after a short delay so it never blocks app startup
+    setTimeout(initRepliqo, 3000);
+  }, []);
+
+  return (
+    <SafeAreaProvider>
+      <AppNavigator />
+    </SafeAreaProvider>
+  );
+}
+
+export default App;
+```
+
+That is it. With these two files in place, the SDK will:
+
+- Start a session with device metadata.
+- Automatically flush events when the app goes to the background.
+- Track navigation events and screen visits once you wire up the navigation tracker (see [Section 6](#6-navigation-tracking-automatic)).
+
+---
+
+## 5. Configuration Reference
+
+All configuration is passed to `AppAnalytics.init()` via an `SDKConfig` object. The three required fields have no defaults and must always be provided. All other fields are optional and have sensible defaults.
+
+| Property | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `apiKey` | `string` | -- | Yes | Your Repliqo API key. Obtained from the dashboard under Settings > Applications. |
+| `appId` | `string` | -- | Yes | Your application identifier. Must match the app ID registered in the dashboard. |
+| `baseUrl` | `string` | -- | Yes | The Repliqo API base URL. Use `https://api-repliqo.odmservice.site` for production, or a local URL like `http://10.0.2.2:3050` for Android emulator development. |
+| `batchSize` | `number` | `20` | No | Number of events to accumulate before sending a batch to the server. Lower values mean more frequent network requests; higher values reduce request count but increase the risk of data loss if the app is killed. |
+| `flushInterval` | `number` | `30000` | No | Time in milliseconds between automatic batch flushes. Events are sent at least this often, even if `batchSize` has not been reached. Default is 30 seconds. |
+| `enableTouchTracking` | `boolean` | `true` | No | When `true`, touch events (taps) are captured and sent to the backend for heatmap generation. Set to `false` if you only need navigation analytics. |
+| `enableNavigationTracking` | `boolean` | `true` | No | When `true`, navigation events (screen transitions) are tracked. Works with `useNavigationTracker()` or `trackScreenChange()`. |
+| `enableSnapshots` | `boolean` | `true` | No | When `true`, the SDK periodically captures a serialized snapshot of the component tree. Useful for session replay. Increases memory and bandwidth usage. |
+| `enableCrashTracking` | `boolean` | `true` | No | When `true`, the SDK installs a global error handler and captures unhandled JavaScript errors and Promise rejections. Crash reports are sent immediately, not batched. |
+| `snapshotInterval` | `number` | `1000` | No | Time in milliseconds between automatic snapshot captures. Only relevant when `enableSnapshots` is `true`. Default is 1 second. |
+| `maxSnapshotsPerSession` | `number` | `3600` | No | Maximum number of snapshots the SDK will capture per session. Prevents runaway memory usage in long-lived sessions. At the default of 1 snapshot/second, this allows 1 hour of capture. |
+| `debug` | `boolean` | `false` | No | When `true`, the SDK logs detailed information to the console (initialization, event tracking, flushes, errors). Recommended to set `debug: __DEV__` so logs only appear during development. |
+
+---
+
+## 6. Navigation Tracking (Automatic)
+
+The SDK provides two approaches for automatic navigation tracking with `@react-navigation/native`. Choose the one that best fits your app's architecture.
+
+### Approach A: Using the `useNavigationTracker()` Hook
+
+The `useNavigationTracker()` hook is the cleanest integration method. It returns a `navigationRef`, an `onReady` callback, and an `onStateChange` callback that you pass directly to `NavigationContainer`.
+
+```typescript
+// src/navigation/AppNavigator.tsx
+
+import React from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { createStackNavigator } from '@react-navigation/stack';
+import { useNavigationTracker } from '@repliqo/sdk-react-native';
+import { HomeScreen } from '../screens/HomeScreen';
+import { ProfileScreen } from '../screens/ProfileScreen';
+import { SettingsScreen } from '../screens/SettingsScreen';
+
+const Stack = createStackNavigator();
+
+export function AppNavigator() {
+  // The hook manages all navigation tracking state internally
+  const { navigationRef, onReady, onStateChange } = useNavigationTracker();
+
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      onReady={onReady}
+      onStateChange={onStateChange}
+    >
+      <Stack.Navigator screenOptions={{ headerShown: false }}>
+        <Stack.Screen name="Home" component={HomeScreen} />
+        <Stack.Screen name="Profile" component={ProfileScreen} />
+        <Stack.Screen name="Settings" component={SettingsScreen} />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+When the navigator is ready, the hook records the initial screen. On every subsequent state change, it automatically:
+
+1. Detects the currently active route (including nested navigators).
+2. Calls `trackNavigation(fromScreen, toScreen)` to log the transition event.
+3. Calls `onScreenExit(fromScreen)` to record how long the user spent on the previous screen.
+4. Calls `onScreenEnter(toScreen)` to start the timer for the new screen.
+
+### Approach B: Using `trackScreenChange()` Manually
+
+If you need more control over how navigation state is read (for example, with complex nested navigators or non-standard setups), use the `trackScreenChange()` function directly:
+
+```typescript
+// src/navigation/AppNavigator.tsx
+
+import React, { useRef, useCallback } from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+import { createStackNavigator } from '@react-navigation/stack';
+import { trackScreenChange } from '@repliqo/sdk-react-native';
+import { HomeScreen } from '../screens/HomeScreen';
+import { ProfileScreen } from '../screens/ProfileScreen';
+
+const Tab = createBottomTabNavigator();
+const Stack = createStackNavigator();
+
+// Helper to dig through nested navigators and find the active route name
+function getActiveRouteName(state: any): string {
+  const route = state.routes[state.index];
+  if (route.state) return getActiveRouteName(route.state);
+  return route.name;
+}
+
+export function AppNavigator() {
+  // Keep track of the current route name between renders
+  const currentRoute = useRef<string>('');
+
+  const onReady = useCallback(() => {
+    currentRoute.current = 'Home';
+    // Track the initial screen (fromScreen is empty on first load)
+    trackScreenChange('', 'Home');
+  }, []);
+
+  return (
+    <NavigationContainer
+      onReady={onReady}
+      onStateChange={(state) => {
+        if (!state) return;
+
+        const newRoute = getActiveRouteName(state);
+        if (newRoute !== currentRoute.current) {
+          // This single call handles navigation event + screen enter/exit
+          trackScreenChange(currentRoute.current, newRoute);
+          currentRoute.current = newRoute;
+        }
+      }}
+    >
+      <Tab.Navigator screenOptions={{ headerShown: false }}>
+        <Tab.Screen name="Home" component={HomeScreen} />
+        <Tab.Screen name="Profile" component={ProfileScreen} />
+      </Tab.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+### What Data Gets Captured
+
+Each navigation event produces an `AnalyticsEvent` with this structure:
+
+```typescript
+{
+  type: 'navigation',
+  screenName: 'ProfileScreen',           // The destination screen
+  data: {
+    fromScreen: 'HomeScreen',            // Where the user came from
+    toScreen: 'ProfileScreen',           // Where the user went
+  },
+  timestamp: '2026-03-25T14:30:00.000Z', // ISO 8601 timestamp
+}
+```
+
+Additionally, screen visits are tracked automatically with enter/exit timestamps and duration:
+
+```typescript
+{
+  sessionId: 'abc123',
+  screenName: 'HomeScreen',
+  enteredAt: '2026-03-25T14:28:00.000Z',
+  exitedAt: '2026-03-25T14:30:00.000Z',
+  duration: 120000,                       // Duration in milliseconds
+}
+```
+
+---
+
+## 7. Custom Events
+
+Custom events let you track specific user actions that are meaningful to your business logic -- button clicks, form submissions, feature usage, purchase completions, and anything else you want to measure.
+
+### Basic Usage
+
+```typescript
+import { AppAnalytics } from '@repliqo/sdk-react-native';
+
+// Track a simple event (name only)
+AppAnalytics.getInstance().trackCustomEvent('sign_up_completed');
+
+// Track an event with additional data
+AppAnalytics.getInstance().trackCustomEvent('item_purchased', {
+  itemId: 'premium-plan',
+  price: 9.99,
+  currency: 'USD',
+});
+
+// Track feature usage
+AppAnalytics.getInstance().trackCustomEvent('dark_mode_toggled', {
+  enabled: true,
+});
+```
+
+### Real-World Example: Tracking Button Clicks
+
+```typescript
+// src/screens/HomeScreen.tsx
+
+import React from 'react';
+import { View, TouchableOpacity, Text } from 'react-native';
+import { AppAnalytics } from '@repliqo/sdk-react-native';
+
+export function HomeScreen() {
+  const handleCreateHabit = () => {
+    // Track the button click before performing the action
+    AppAnalytics.getInstance().trackCustomEvent('create_habit_tapped', {
+      source: 'home_screen',
+    });
+
+    // ... your actual logic to create a habit
+  };
+
+  const handleShareApp = () => {
+    AppAnalytics.getInstance().trackCustomEvent('share_app_tapped', {
+      source: 'home_screen',
+      method: 'native_share',
+    });
+
+    // ... your share logic
+  };
+
+  return (
+    <View>
+      <TouchableOpacity onPress={handleCreateHabit}>
+        <Text>Create Habit</Text>
+      </TouchableOpacity>
+      <TouchableOpacity onPress={handleShareApp}>
+        <Text>Share App</Text>
+      </TouchableOpacity>
+    </View>
+  );
+}
+```
+
+### Best Practices for Event Naming
+
+- Use **snake_case** for event names: `purchase_completed`, not `PurchaseCompleted` or `purchase-completed`.
+- Start with a **noun** followed by a **verb in past tense**: `habit_created`, `profile_updated`, `session_started`.
+- Keep names **short but descriptive**: `checkout_started` is better than `user_clicked_checkout_button`.
+- Use the `data` parameter for **variable information**: pass `itemId`, `price`, `category` as data, not as part of the event name.
+- Avoid **high-cardinality event names**: do not include IDs or dynamic values in the event name itself. Use `item_viewed` with `{ itemId: '123' }`, not `item_123_viewed`.
+
+---
+
+## 8. Error/Crash Tracking
+
+The SDK can automatically capture JavaScript errors, fatal native crashes, and unhandled Promise rejections, and send them to the Repliqo backend for analysis.
+
+### Automatic Crash Capture
+
+When `enableCrashTracking` is set to `true` (the default), the SDK installs:
+
+1. **A global error handler** via React Native's `ErrorUtils`. This captures all uncaught JavaScript errors, including fatal errors that would crash the app.
+2. **An unhandled rejection handler** that captures Promise rejections that are not caught by a `.catch()` block.
+
+Crash reports are sent **immediately** when they occur (not batched), because the app may be about to terminate. The original React Native error handler is preserved and still called, so the standard red screen / crash behavior is unaffected.
+
+No additional setup is needed beyond enabling the flag:
+
+```typescript
+AppAnalytics.init({
+  apiKey: 'your-api-key',
+  appId: 'your-app-id',
+  baseUrl: 'https://api-repliqo.odmservice.site',
+  enableCrashTracking: true,  // This is the default
+});
+```
+
+### Manual Error Reporting
+
+For errors that you catch yourself (e.g., in try/catch blocks, error boundaries, or API call failures), use `reportError()`:
+
+```typescript
+import { AppAnalytics } from '@repliqo/sdk-react-native';
+
+// Report a caught error with context metadata
+async function fetchUserProfile(userId: string) {
+  try {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: Failed to fetch profile`);
+    }
+    return await response.json();
+  } catch (error) {
+    // Report to Repliqo with extra context
+    AppAnalytics.getInstance().reportError(error as Error, {
+      userId,
+      action: 'fetch_user_profile',
+      httpStatus: (error as any).status,
+    });
+
+    // Handle the error in the UI as normal
+    throw error;
+  }
+}
+```
+
+### React Error Boundary Example
+
+```typescript
+// src/components/AnalyticsErrorBoundary.tsx
+
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+import { View, Text } from 'react-native';
+import { AppAnalytics } from '@repliqo/sdk-react-native';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+}
+
+export class AnalyticsErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // Report the error to Repliqo with component stack information
+    try {
+      AppAnalytics.getInstance().reportError(error, {
+        componentStack: errorInfo.componentStack,
+        source: 'error_boundary',
+      });
+    } catch {
+      // SDK may not be initialized yet
+    }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || (
+        <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+          <Text>Something went wrong.</Text>
+        </View>
+      );
+    }
+    return this.props.children;
+  }
+}
+```
+
+### What Data Is Captured in a Crash Report
+
+Each crash report contains the following fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `sessionId` | `string` or `undefined` | The active session ID, if a session is running. |
+| `type` | `'js_error'` \| `'native_crash'` \| `'unhandled_rejection'` | The category of error. Fatal errors from `ErrorUtils` are reported as `native_crash`. |
+| `message` | `string` | The error message (e.g., `"Cannot read property 'name' of undefined"`). |
+| `stackTrace` | `string` or `undefined` | The JavaScript stack trace, if available. |
+| `screenName` | `string` or `undefined` | The screen the user was on when the crash occurred. |
+| `deviceInfo` | `Record<string, any>` or `undefined` | Optional device context. |
+| `metadata` | `Record<string, any>` or `undefined` | Any additional metadata you pass to `reportError()`. For automatic captures, this includes `{ isFatal: boolean }`. |
+| `timestamp` | `string` | ISO 8601 timestamp of when the error occurred. |
+
+---
+
+## 9. Manual Screen Tracking
+
+In most cases, the automatic navigation tracker (Section 6) handles screen tracking for you. However, there are scenarios where you need manual control:
+
+- Screens not managed by React Navigation (e.g., modals, bottom sheets, onboarding flows).
+- Custom navigation systems that do not use `@react-navigation/native`.
+- Conditional screens that appear within a single navigator route.
+
+### Using `trackScreenEnter()` and `trackScreenExit()`
+
+```typescript
+import { trackScreenEnter, trackScreenExit } from '@repliqo/sdk-react-native';
+
+// Call when the screen becomes visible
+trackScreenEnter('OnboardingStep1');
+
+// Call when the screen is no longer visible
+trackScreenExit('OnboardingStep1');
+```
+
+### Example: Tracking a Modal Screen
+
+```typescript
+// src/components/PremiumModal.tsx
+
+import React, { useEffect } from 'react';
+import { Modal, View, Text } from 'react-native';
+import { trackScreenEnter, trackScreenExit } from '@repliqo/sdk-react-native';
+
+interface PremiumModalProps {
+  visible: boolean;
+  onClose: () => void;
+}
+
+export function PremiumModal({ visible, onClose }: PremiumModalProps) {
+  useEffect(() => {
+    if (visible) {
+      // Register this modal as a screen visit when it opens
+      trackScreenEnter('PremiumUpgradeModal');
+    } else {
+      // Record the exit (and duration) when it closes
+      trackScreenExit('PremiumUpgradeModal');
+    }
+  }, [visible]);
+
+  return (
+    <Modal visible={visible} onRequestClose={onClose}>
+      <View>
+        <Text>Upgrade to Premium</Text>
+        {/* ... modal content ... */}
+      </View>
+    </Modal>
+  );
+}
+```
+
+### When to Use Manual vs. Automatic
+
+| Scenario | Recommended Approach |
+|---|---|
+| Standard React Navigation stack/tab screens | Automatic (`useNavigationTracker` or `trackScreenChange`) |
+| Modals and bottom sheets | Manual (`trackScreenEnter` / `trackScreenExit`) |
+| Onboarding wizard steps within a single route | Manual |
+| Custom navigation (no React Navigation) | Manual |
+| WebView content within a native screen | Manual (track the WebView "page" as a screen) |
+
+---
+
+## 10. Session Management
+
+A session represents a single continuous usage period of your app by a user. Sessions tie all events, screen visits, and crash reports together.
+
+### How Sessions Work
+
+1. **Start**: You call `startSession()` with a device identifier and optional device info. The backend creates a session record and returns a session ID.
+2. **Track**: While the session is active, all events (navigation, touch, custom, screen visits) are associated with this session ID.
+3. **Flush**: Events are periodically flushed to the backend in batches. An automatic flush also happens when the app goes to the background.
+4. **End**: You call `endSession()` (or let the SDK handle it on destroy). This flushes remaining events and tells the backend the session is complete.
+
+### Starting a Session
+
+```typescript
+import { AppAnalytics } from '@repliqo/sdk-react-native';
+import { Platform, Dimensions } from 'react-native';
+
+const analytics = AppAnalytics.getInstance();
+
+// Generate or retrieve a persistent device ID
+const deviceId = 'unique-device-identifier';
+
+// Gather device info (see Section 11 for a complete example)
+const { width, height } = Dimensions.get('window');
+const deviceInfo = {
+  os: Platform.OS,
+  osVersion: String(Platform.Version),
+  model: 'Pixel 7',
+  brand: 'Google',
+  screenWidth: width,
+  screenHeight: height,
+  appVersion: '2.1.0',
+};
+
+// startSession returns the session ID assigned by the backend
+const sessionId = await analytics.startSession(deviceId, deviceInfo);
+console.log('Session ID:', sessionId);
+```
+
+### Ending a Session
+
+```typescript
+// End the session -- this flushes all pending events first
+await AppAnalytics.getInstance().endSession();
+```
+
+Ending a session:
+
+1. Stops snapshot capture (if enabled).
+2. Records the exit for the current screen (if the user is on one).
+3. Flushes all queued events, screen visits, and snapshots.
+4. Notifies the backend that the session has ended.
+5. Clears the session ID and current screen state.
+
+### Checking Session State
+
+```typescript
+const analytics = AppAnalytics.getInstance();
+
+// Get the current session ID (null if no session is active)
+const sessionId = analytics.getSessionId();
+
+// Get the name of the screen the user is currently on
+const currentScreen = analytics.getCurrentScreen();
+```
+
+### Session Lifecycle Diagram
+
+```
+App Launch
+    |
+    v
+AppAnalytics.init(config)    --> SDK initialized, queues created
+    |
+    v
+analytics.startSession()     --> Backend creates session, returns ID
+    |
+    v
+[User interacts with app]    --> Events buffered in memory
+    |
+    v
+[Batch threshold reached]    --> Events sent to backend
+    |                             (automatic, every flushInterval or batchSize)
+    v
+[App goes to background]     --> Automatic flush triggered
+    |
+    v
+[App returns to foreground]  --> Tracking resumes (same session)
+    |
+    v
+analytics.endSession()       --> Final flush, session closed on backend
+    |
+    v
+AppAnalytics.destroy()       --> Cleanup, listeners removed
+```
+
+---
+
+## 11. Device Info
+
+The `DeviceInfo` object provides context about the user's device with each session. This data appears in the dashboard alongside session details and crash reports.
+
+### Basic Device Info (No Extra Dependencies)
+
+Using only React Native's built-in APIs:
+
+```typescript
+import { Platform, Dimensions } from 'react-native';
+import type { DeviceInfo } from '@repliqo/sdk-react-native';
+
+function getBasicDeviceInfo(): DeviceInfo {
+  const { width, height } = Dimensions.get('window');
+
+  return {
+    os: Platform.OS,                         // 'ios' or 'android'
+    osVersion: String(Platform.Version),     // e.g., '33' (Android) or '17.2' (iOS)
+    model: 'Unknown',                        // Not available without a library
+    brand: 'Unknown',                        // Not available without a library
+    screenWidth: width,                      // e.g., 393
+    screenHeight: height,                    // e.g., 852
+    appVersion: '1.0.0',                     // Hardcode or read from your config
+  };
+}
+```
+
+### Enhanced Device Info with `react-native-device-info`
+
+For richer device data, install [react-native-device-info](https://github.com/react-native-device-info/react-native-device-info):
+
+```bash
+npm install react-native-device-info
+```
+
+Then use it to populate the fields:
+
+```typescript
+import { Platform, Dimensions } from 'react-native';
+import DeviceInfoLib from 'react-native-device-info';
+import type { DeviceInfo } from '@repliqo/sdk-react-native';
+
+async function getEnhancedDeviceInfo(): Promise<DeviceInfo> {
+  const { width, height } = Dimensions.get('window');
+
+  return {
+    os: Platform.OS,
+    osVersion: String(Platform.Version),
+    model: DeviceInfoLib.getModel(),                 // e.g., 'Pixel 7'
+    brand: DeviceInfoLib.getBrand(),                  // e.g., 'Google'
+    screenWidth: width,
+    screenHeight: height,
+    appVersion: DeviceInfoLib.getVersion(),           // e.g., '2.1.0'
+  };
+}
+```
+
+### Generating a Persistent Device ID
+
+For the `deviceId` parameter in `startSession()`, you need a value that is unique per device and persists across app launches. Here are some approaches:
+
+```typescript
+import DeviceInfoLib from 'react-native-device-info';
+
+// Option 1: Use react-native-device-info's unique ID (recommended)
+const deviceId = await DeviceInfoLib.getUniqueId();
+
+// Option 2: Generate a random ID and store it with AsyncStorage
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+async function getOrCreateDeviceId(): Promise<string> {
+  let deviceId = await AsyncStorage.getItem('repliqo_device_id');
+  if (!deviceId) {
+    deviceId = `${Platform.OS}-${Math.random().toString(36).slice(2, 10)}`;
+    await AsyncStorage.setItem('repliqo_device_id', deviceId);
+  }
+  return deviceId;
+}
+```
+
+---
+
+## 12. Advanced: Flush Control
+
+The SDK batches events in memory and sends them to the backend periodically. You can control when flushes happen.
+
+### Automatic Flushing
+
+By default, the SDK flushes automatically in two situations:
+
+1. **Timer-based**: Every `flushInterval` milliseconds (default: 30,000ms), all queued events are sent.
+2. **App background**: When the app transitions to the `background` or `inactive` state, a flush is triggered immediately. This is handled internally by the SDK via an `AppState` listener and requires no action from you.
+
+### Manual Flushing
+
+You can trigger a flush at any time:
+
+```typescript
+import { AppAnalytics } from '@repliqo/sdk-react-native';
+
+// Flush all pending events, screen visits, and snapshots immediately
+await AppAnalytics.getInstance().flush();
+```
+
+This is useful in scenarios like:
+
+- Before navigating to a payment screen (ensure all events are sent).
+- After a critical user action that you want to see in the dashboard right away.
+- In a "log out" flow before ending the session.
+
+### Tuning `batchSize` and `flushInterval`
+
+| Use Case | Recommended `batchSize` | Recommended `flushInterval` |
+|---|---|---|
+| **Low-traffic app** (few screens, few events) | `10` | `60000` (60s) |
+| **Standard app** | `20` (default) | `30000` (30s, default) |
+| **High-traffic app** (many touch events, frequent navigation) | `50` | `15000` (15s) |
+| **Real-time monitoring** (debugging, demo) | `5` | `5000` (5s) |
+
+Lower `batchSize` and `flushInterval` values mean more frequent network requests but lower risk of data loss. Higher values reduce network usage but events take longer to appear in the dashboard.
+
+---
+
+## 13. Advanced: Debug Mode
+
+Debug mode enables verbose console logging from the SDK, which is essential during development and integration testing.
+
+### Enabling Debug Mode
+
+```typescript
+AppAnalytics.init({
+  apiKey: 'your-api-key',
+  appId: 'your-app-id',
+  baseUrl: 'https://api-repliqo.odmservice.site',
+  debug: true,   // Enable verbose logging
+});
+```
+
+A common pattern is to tie debug mode to the development build:
+
+```typescript
+debug: __DEV__,  // true in development, false in production
+```
+
+### What Logs to Expect
+
+With debug mode enabled, you will see console output for every SDK operation:
+
+```
+[Repliqo] SDK initialized with config: { baseUrl: "...", appId: "myapp", batchSize: 20, ... }
+[Repliqo] Session started with ID: sess_abc123def456
+[Repliqo] Screen entered: HomeScreen
+[Repliqo] Navigation tracked: HomeScreen -> ProfileScreen
+[Repliqo] Screen exited: HomeScreen duration: 4523
+[Repliqo] Screen entered: ProfileScreen
+[Repliqo] Custom event tracked: settings_opened
+[Repliqo] Touch tracked: { type: "touch", screenName: "ProfileScreen", data: { x: 195, y: 420 } }
+[Repliqo] Flushing queues...
+[Repliqo] Flush complete
+[Repliqo] App going to background/inactive, flushing queues
+```
+
+### How to Verify Events Are Being Sent
+
+1. **Enable debug mode** and watch the console for "Flushing queues..." followed by "Flush complete" without errors.
+2. **Check the dashboard**: Go to [https://repliqo.odmservice.site](https://repliqo.odmservice.site) and look for your session in the Sessions list. Events should appear within a few seconds of a flush.
+3. **Monitor network requests**: Use React Native Debugger or Flipper to inspect outgoing HTTP requests to your `baseUrl`. You should see POST requests to endpoints like `/sessions`, `/events/batch`, and `/screen-visits/batch`.
+4. **Force a flush**: Call `AppAnalytics.getInstance().flush()` from a debug button in your app to send all queued events immediately.
+
+---
+
+## 14. Dashboard Guide
+
+The Repliqo dashboard at [https://repliqo.odmservice.site](https://repliqo.odmservice.site) provides a visual interface for all the data your SDK collects. Here is a brief overview of the main sections.
+
+### Sessions
+
+The sessions view lists all recorded user sessions with:
+
+- **Device info**: OS, OS version, device model, brand, screen dimensions.
+- **Duration**: How long the session lasted.
+- **Screen count**: Number of screens visited during the session.
+- **Event count**: Total events tracked (navigation, touch, custom).
+- **Timestamps**: Start and end times.
+
+Click on a session to see its full timeline of events.
+
+### Screen Visit Analytics
+
+View aggregate data about which screens users visit most often:
+
+- **Screen popularity**: Ranked list of screens by visit count.
+- **Average duration**: How long users spend on each screen.
+- **Entry/exit points**: Which screens users land on first and leave from.
+
+### Heatmaps
+
+When touch tracking is enabled, the dashboard generates visual heatmaps showing where users tap on each screen:
+
+- **Tap density**: Color-coded overlay showing hotspots of user interaction.
+- **Per-screen breakdown**: View heatmaps for individual screens.
+- **Session-level replay**: See the exact touch sequence for a specific session.
+
+### Crash Reports
+
+The crash reports section aggregates all errors reported by the SDK:
+
+- **Error grouping**: Similar errors are grouped together by message and stack trace.
+- **Occurrence count**: How many times each error has occurred.
+- **Affected sessions**: Which sessions experienced the error.
+- **Stack traces**: Full JavaScript stack traces for debugging.
+- **Context**: The screen the user was on, device info, and any metadata you attached.
+
+### Funnels
+
+Define multi-step funnels to track conversion through specific user flows:
+
+- Configure a sequence of screens or events.
+- See drop-off rates at each step.
+- Compare funnel performance across time periods.
+
+### Data Export
+
+Export your analytics data for use in external tools:
+
+- Export sessions, events, or crash reports as CSV or JSON.
+- Filter by date range, app version, or device type before exporting.
+
+---
+
+## 15. API Reference
+
+Quick reference for all public methods on the `AppAnalytics` class.
+
+### Static Methods
+
+| Method | Signature | Returns | Description |
+|---|---|---|---|
+| `init` | `init(config: SDKConfig)` | `AppAnalytics` | Initializes the SDK with the given configuration. Returns the singleton instance. Safe to call multiple times (subsequent calls return the existing instance). |
+| `getInstance` | `getInstance()` | `AppAnalytics` | Returns the singleton instance. Throws an error if `init()` has not been called. |
+| `destroy` | `destroy()` | `void` | Tears down the SDK: stops error tracking and snapshot capture, stops auto-flush timers, performs a final flush (fire-and-forget), removes the AppState listener, and nullifies the singleton. |
+
+### Instance Methods
+
+| Method | Signature | Returns | Description |
+|---|---|---|---|
+| `startSession` | `startSession(deviceId: string, deviceInfo?: DeviceInfo)` | `Promise<string>` | Starts a new session with the backend. Returns the session ID. Sets up error tracker and snapshot capture for this session. |
+| `endSession` | `endSession()` | `Promise<void>` | Ends the current session. Flushes all pending data, records the final screen exit, and notifies the backend. |
+| `trackTouch` | `trackTouch(x: number, y: number, screenName?: string, extra?: Record<string, any>)` | `void` | Records a touch event at the given coordinates. If `screenName` is omitted, uses the current screen. Only works when `enableTouchTracking` is `true`. |
+| `trackNavigation` | `trackNavigation(fromScreen: string, toScreen: string)` | `void` | Records a navigation event between two screens. Only works when `enableNavigationTracking` is `true`. |
+| `trackCustomEvent` | `trackCustomEvent(eventName: string, data?: Record<string, any>)` | `void` | Records a custom event with an arbitrary name and optional data payload. |
+| `reportError` | `reportError(error: Error, metadata?: Record<string, any>)` | `void` | Manually reports a caught error. Only works when `enableCrashTracking` is `true`. The error is sent immediately, not batched. |
+| `onScreenEnter` | `onScreenEnter(screenName: string)` | `void` | Marks the user as having entered a screen. Starts the visit timer. Updates the error tracker's current screen context. |
+| `onScreenExit` | `onScreenExit(screenName: string)` | `void` | Marks the user as having exited a screen. Records a `ScreenVisit` with the duration in the screen visit queue. |
+| `captureSnapshot` | `captureSnapshot(tree: ComponentNode, screenName?: string)` | `void` | Manually captures a component tree snapshot. Only works when `enableSnapshots` is `true` and a session is active. |
+| `flush` | `flush()` | `Promise<void>` | Immediately sends all queued events, screen visits, and snapshots to the backend. |
+| `getSessionId` | `getSessionId()` | `string \| null` | Returns the current session ID, or `null` if no session is active. |
+| `getCurrentScreen` | `getCurrentScreen()` | `string \| null` | Returns the name of the screen the user is currently on, or `null`. |
+| `isInitialized` | `isInitialized()` | `boolean` | Returns `true` if the SDK instance exists and is ready. |
+
+### Standalone Functions
+
+| Function | Signature | Description |
+|---|---|---|
+| `useNavigationTracker` | `useNavigationTracker()` | React hook that returns `{ navigationRef, onReady, onStateChange }` for automatic navigation tracking with `NavigationContainer`. |
+| `trackScreenChange` | `trackScreenChange(fromScreen: string, toScreen: string)` | Convenience function that calls `trackNavigation`, `onScreenExit`, and `onScreenEnter` in sequence. |
+| `trackScreenEnter` | `trackScreenEnter(screenName: string)` | Standalone function to mark screen entry. Silently no-ops if SDK is not initialized. |
+| `trackScreenExit` | `trackScreenExit(screenName: string)` | Standalone function to mark screen exit. Silently no-ops if SDK is not initialized. |
+
+---
+
+## 16. Screen Capture Architecture
+
+The SDK uses a **two-tier capture strategy** for session replay screenshots:
+
+### Tier 1: Native Multi-Window Capture (Android)
+
+The SDK includes a native Android module (`ScreenCaptureModule`) that captures **all visible app windows** — including modals, alerts, system dialogs, keyboard overlays, and toasts.
+
+**How it works:**
+- Uses `WindowManagerGlobal` (via reflection) to enumerate all root views in the process
+- Draws each visible view to a shared `Canvas` using `View.draw()`, composited in z-order
+- Scales to 390px width, compresses to JPEG at 40% quality
+- Returns base64-encoded JPEG to JavaScript
+
+**No permissions required.** No `MediaProjection`, no foreground service, no system dialogs.
+
+### Tier 2: react-native-view-shot (Fallback)
+
+If the native module is unavailable (iOS, or if the module fails to load), the SDK falls back to `react-native-view-shot`'s `captureScreen()`. This captures only the main React Native view — **modals and native dialogs are NOT included** in the fallback.
+
+### Capture Priority
+
+```
+captureScreenshot()
+  ├─ Try: Native multi-window capture (Android)
+  │   └─ Returns: full screenshot including modals/alerts
+  ├─ Fallback: react-native-view-shot
+  │   └─ Returns: main view only (no modals)
+  └─ Last resort: null (frame dropped)
+```
+
+Each frame includes a `source` field (`'native'` or `'viewshot'`) so the replay player knows which method produced it.
+
+### iOS Support
+
+Native multi-window capture is not yet implemented for iOS. iOS sessions use `react-native-view-shot` exclusively. This is a known limitation documented for future development.
+
+---
+
+## 17. Troubleshooting
+
+### "Failed to start session"
+
+**Symptom**: `startSession()` throws an error or the console shows `[Repliqo] Init failed`.
+
+**Possible causes and fixes**:
+
+- **Wrong `baseUrl`**: Verify the URL is correct. For Android emulator, use `http://10.0.2.2:<port>` (not `localhost`). For iOS simulator, use `http://localhost:<port>`.
+- **Invalid API key**: Double-check your `apiKey` matches the one in the Repliqo dashboard.
+- **Network issue**: Ensure the device/emulator has network access. Try opening the `baseUrl` in a browser.
+- **Backend not running**: If developing locally, confirm the Repliqo API server is running.
+
+### Events Not Appearing in the Dashboard
+
+**Symptom**: You see "Session started" in the logs, but events do not show up in the dashboard.
+
+**Possible causes and fixes**:
+
+- **Events are still queued**: The SDK buffers events and sends them in batches. Wait for the `flushInterval` (default 30s) or call `flush()` manually.
+- **`batchSize` too large**: If your `batchSize` is set very high and users don't generate that many events, the batch may never fill up before the flush interval. Reduce `batchSize` or `flushInterval`.
+- **Session not started**: Events are silently dropped if no session is active. Check that `startSession()` completed successfully.
+- **Feature disabled**: If `enableNavigationTracking` is `false`, navigation events are silently ignored. Same for `enableTouchTracking` and touch events.
+
+### Metro Can't Resolve the Module
+
+**Symptom**: Error like `Unable to resolve module @repliqo/sdk-react-native`.
+
+**Fix**: Clear the Metro bundler cache:
+
+```bash
+npx react-native start --reset-cache
+```
+
+If installing from a local path, make sure the path in `package.json` is correct and that the SDK has been built:
+
+```bash
+cd /path/to/sdk-react-native
+npm run build
+```
+
+### Touch Events Not Working
+
+**Symptom**: Touch tracking is enabled but no touch events appear.
+
+**Possible causes and fixes**:
+
+- **`enableTouchTracking: false`**: Verify this is set to `true` in your config.
+- **TouchTracker wrapper missing**: The `TouchTracker` component must wrap your app's component tree to intercept touch events. If you are not using it, touches will not be captured. Consider using manual `trackTouch()` calls as an alternative.
+- **Known limitation**: The `TouchTracker` component can sometimes interfere with gesture handlers (e.g., `react-native-gesture-handler`). If you experience issues, disable `enableTouchTracking` and use manual `trackTouch()` calls for specific interactions instead.
+
+### High Memory Usage
+
+**Symptom**: The app consumes more memory than expected after integrating the SDK.
+
+**Possible causes and fixes**:
+
+- **Snapshots enabled**: Snapshot capture serializes the component tree at regular intervals. This can be memory-intensive. Disable snapshots (`enableSnapshots: false`) if you do not need session replay.
+- **Large `batchSize`**: A very large batch size means more events are held in memory before being sent. Reduce `batchSize` to flush more frequently.
+- **Long sessions**: The `maxSnapshotsPerSession` limit (default 3600) prevents unbounded snapshot growth, but screen visits and events still accumulate. Consider calling `flush()` periodically for very long sessions.
+
+### Crashes Not Being Reported
+
+**Symptom**: `enableCrashTracking` is `true`, but no crash reports appear in the dashboard.
+
+**Possible causes and fixes**:
+
+- **Session not started**: Crash reports include the session ID for context, but they are sent even without a session. Check that the SDK is initialized (not just the session).
+- **Network failure on crash**: If the app crashes before the crash report HTTP request completes, the report may be lost. This is inherent to crash reporting in JavaScript -- native crash reporting libraries handle this better.
+- **Error caught elsewhere**: If another error handler (e.g., Sentry, Bugsnag) catches the error first and does not rethrow it, Repliqo may not see it. The SDK preserves the original error handler chain, so this should not normally be an issue.
+
+---
+
+## 17. TypeScript Types
+
+All types are exported from the main package entry point. You can import them with:
+
+```typescript
+import type {
+  EventType,
+  AnalyticsEvent,
+  TouchEventData,
+  NavigationEventData,
+  ScreenVisit,
+  DeviceInfo,
+  SDKConfig,
+  ComponentNode,
+  SnapshotData,
+  SnapshotDiff,
+  DiffPatch,
+  SnapshotPayload,
+  CrashReport,
+  ResolvedConfig,
+  SnapshotCaptureConfig,
+} from '@repliqo/sdk-react-native';
+```
+
+### `EventType`
+
+```typescript
+type EventType = 'touch' | 'scroll' | 'gesture' | 'navigation' | 'custom';
+```
+
+### `AnalyticsEvent`
+
+```typescript
+interface AnalyticsEvent {
+  type: EventType;
+  screenName?: string;
+  data: Record<string, any>;
+  timestamp: string;  // ISO 8601
+}
+```
+
+### `TouchEventData`
+
+```typescript
+interface TouchEventData {
+  x: number;
+  y: number;
+  elementTag?: string;
+  elementText?: string;
+}
+```
+
+### `NavigationEventData`
+
+```typescript
+interface NavigationEventData {
+  fromScreen: string;
+  toScreen: string;
+}
+```
+
+### `ScreenVisit`
+
+```typescript
+interface ScreenVisit {
+  sessionId: string;
+  screenName: string;
+  enteredAt: string;       // ISO 8601
+  exitedAt?: string;       // ISO 8601
+  duration?: number;       // Milliseconds
+}
+```
+
+### `DeviceInfo`
+
+```typescript
+interface DeviceInfo {
+  os: string;
+  osVersion: string;
+  model: string;
+  brand: string;
+  screenWidth: number;
+  screenHeight: number;
+  appVersion?: string;
+}
+```
+
+### `SDKConfig`
+
+```typescript
+interface SDKConfig {
+  apiKey: string;
+  appId: string;
+  baseUrl: string;
+  batchSize?: number;
+  flushInterval?: number;
+  enableTouchTracking?: boolean;
+  enableNavigationTracking?: boolean;
+  enableSnapshots?: boolean;
+  snapshotInterval?: number;
+  maxSnapshotsPerSession?: number;
+  enableCrashTracking?: boolean;
+  debug?: boolean;
+}
+```
+
+### `CrashReport`
+
+```typescript
+interface CrashReport {
+  sessionId?: string;
+  type: 'js_error' | 'native_crash' | 'unhandled_rejection';
+  message: string;
+  stackTrace?: string;
+  screenName?: string;
+  deviceInfo?: Record<string, any>;
+  metadata?: Record<string, any>;
+  timestamp: string;  // ISO 8601
+}
+```
+
+### `ComponentNode`
+
+```typescript
+interface ComponentNode {
+  type: string;
+  props: Record<string, any>;
+  text?: string;
+  children?: ComponentNode[];
+  bounds?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+}
+```
+
+### `SnapshotData`
+
+```typescript
+interface SnapshotData {
+  screenName: string;
+  timestamp: string;
+  sequence: number;
+  isDiff: boolean;
+  tree: ComponentNode | SnapshotDiff;
+  screenDimensions: {
+    width: number;
+    height: number;
+  };
+}
+```
+
+### `SnapshotDiff`
+
+```typescript
+interface SnapshotDiff {
+  type: 'diff';
+  patches: DiffPatch[];
+}
+```
+
+### `DiffPatch`
+
+```typescript
+interface DiffPatch {
+  path: string;
+  op: 'add' | 'remove' | 'replace';
+  value?: any;
+  oldValue?: any;
+}
+```
+
+### `SnapshotPayload`
+
+```typescript
+interface SnapshotPayload {
+  sessionId: string;
+  screenName: string;
+  timestamp: string;
+  sequence: number;
+  isDiff: boolean;
+  data: Record<string, any>;
+}
+```
+
+---
+
+**Need help?** Open an issue on the Repliqo repository or reach out through the dashboard at [https://repliqo.odmservice.site](https://repliqo.odmservice.site).