sitepong 0.0.16 → 0.0.18

package/README.md

@@ -447,6 +447,272 @@ function CheckoutButton() {
 
 ---
 
+## React Native / Expo
+
+First-class React Native support with automatic error capture, navigation tracking, and performance monitoring.
+
+```bash
+# Core
+npm install sitepong @react-native-async-storage/async-storage
+
+# Optional: persistent device ID (survives reinstalls)
+npm install @sitepong/device-id
+
+# Optional: screen recording
+npm install @sitepong/screen-recorder
+```
+
+Add plugins to your `app.json` (only for native modules you installed):
+
+```json
+{
+  "plugins": [
+    "@sitepong/device-id",
+    "@sitepong/screen-recorder"
+  ]
+}
+```
+
+Then run `npx expo prebuild` to regenerate native projects.
+
+```tsx
+import { SitePongRNProvider } from 'sitepong/react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+
+export default function App() {
+  const navigationRef = useNavigationContainerRef();
+  return (
+    <SitePongRNProvider
+      apiKey="your-api-key"
+      asyncStorage={AsyncStorage}
+      navigationRef={navigationRef}
+    >
+      <NavigationContainer ref={navigationRef}>
+        {/* Your screens */}
+      </NavigationContainer>
+    </SitePongRNProvider>
+  );
+}
+```
+
+### React Native Hooks
+
+```tsx
+import {
+  useScreenTrack,
+  useAppState,
+  useRemoteConfig,
+  useRNPerformance,
+} from 'sitepong/react-native';
+
+function MyScreen() {
+  useScreenTrack('MyScreen');
+  const appState = useAppState();
+  const config = useRemoteConfig();
+  const perf = useRNPerformance('MyScreen');
+
+  // perf.markRenderComplete() when screen is ready
+}
+```
+
+### Screen Recording
+
+Captures H.264 video in a rolling buffer. Requires the `@sitepong/screen-recorder` native module.
+
+```bash
+npm install @sitepong/screen-recorder
+```
+
+**Two modes:**
+
+#### On Error (via Provider)
+
+Recording starts automatically and keeps the **last 10 seconds**. When an error is captured the buffer is **automatically flushed and attached to the error**. No video is sent during normal usage.
+
+```tsx
+<SitePongRNProvider
+  apiKey="your-api-key"
+  asyncStorage={AsyncStorage}
+  screenRecording={{
+    enabled: true,
+    fps: 1,
+    quality: 'standard',
+    // bufferDuration defaults to 10_000 (10s) in on-error mode
+  }}
+>
+  {/* Your app */}
+</SitePongRNProvider>
+```
+
+When `captureError()` is called (or the global error handler fires), the SDK automatically flushes the last 10 seconds of video and attaches it to the error.
+
+#### Manual
+
+Start and stop recording yourself. Keeps the **last 60 seconds** by default. Call `flushScreenRecording()` to upload when you decide.
+
+```tsx
+import {
+  startScreenRecording,
+  stopScreenRecording,
+  flushScreenRecording,
+} from 'sitepong/react-native';
+
+// Start — keeps a 60s rolling buffer
+startScreenRecording('your-api-key', 'https://ingest.sitepong.com', sessionId, {
+  fps: 1,
+  quality: 'standard',
+  // bufferDuration defaults to 60_000 (60s) in manual mode
+});
+
+// Upload the buffer whenever you want
+await flushScreenRecording();
+
+// Stop and discard the buffer
+stopScreenRecording();
+```
+
+**Masking sensitive content:**
+
+```tsx
+import { SensitiveView } from '@sitepong/screen-recorder';
+
+<SensitiveView>
+  <Text>SSN: 123-45-6789</Text>
+  <Text>Card: 4111-1111-1111-1111</Text>
+</SensitiveView>
+```
+
+Content inside `<SensitiveView>` is replaced with a black rectangle in recorded video.
+
+**Configuration:**
+
+| Option | Default (on-error) | Default (manual) | Description |
+|---|---|---|---|
+| `enabled` | `false` | n/a | Enable via provider |
+| `fps` | `1` | `1` | Frames per second (1-10) |
+| `quality` | `'standard'` | `'standard'` | `'low'` / `'standard'` / `'high'` |
+| `sampleRate` | `1.0` | `1.0` | Fraction of sessions to record (0-1) |
+| `bufferDuration` | `10000` (10s) | `60000` (60s) | Rolling buffer size in ms |
+| `maxDuration` | `3600000` | `3600000` | Max recording duration in ms |
+
+### Device Intelligence (React Native)
+
+Persistent device identification that **survives app reinstalls**. Requires the `@sitepong/device-id` native module.
+
+```bash
+npm install @sitepong/device-id
+```
+
+Add the config plugin to your `app.json` / `app.config.js`:
+
+```json
+{
+  "plugins": ["@sitepong/device-id"]
+}
+```
+
+Once installed, the SDK automatically uses the native device ID:
+- **iOS**: UUID stored in Keychain (persists across uninstall/reinstall, cleared on factory reset)
+- **Android**: SHA-256 of `ANDROID_ID` + SharedPreferences UUID (stable per signing key since Android 8)
+
+```tsx
+import { fetchPersistentDeviceId, fetchNativeDeviceSignals } from 'sitepong/react-native';
+
+// Get persistent device ID
+const deviceId = await fetchPersistentDeviceId();
+
+// Get full native signals
+const signals = await fetchNativeDeviceSignals();
+// { deviceId, platform, osVersion, model, manufacturer, isEmulator, screenScale,
+//   identifierForVendor (iOS), androidId (Android) }
+```
+
+Or use the native module directly:
+
+```tsx
+import { getDeviceId, getDeviceSignals } from '@sitepong/device-id';
+
+const deviceId = await getDeviceId();
+const signals = await getDeviceSignals();
+```
+
+**Identity hierarchy** (all platforms):
+
+| Level | Scope | Persistence |
+|-------|-------|-------------|
+| `deviceId` | Hardware-level | Survives reinstalls (RN only) |
+| `anonymousId` | App-level UUID | Persists in storage |
+| `sessionId` | Session-scoped | 30-min timeout |
+| `userId` | Developer-set | Via `identify()` |
+
+### SQLite Query Tracking
+
+Monitor `expo-sqlite` query performance with automatic timing and slow query detection.
+
+```tsx
+import { createTrackedDatabase } from 'sitepong/react-native';
+import * as SQLite from 'expo-sqlite';
+
+const db = SQLite.openDatabaseSync('myapp.db');
+const trackedDb = createTrackedDatabase(db, {
+  slowQueryThreshold: 100, // ms — log queries slower than this
+  trackAll: false,         // if true, track every query
+});
+
+// Use trackedDb exactly like db — same API
+const users = trackedDb.getAllSync('SELECT * FROM users WHERE active = 1');
+```
+
+Tracked queries emit `$sqlite_query` events with `{ sql, durationMs, rowCount }` and add breadcrumbs for debugging.
+
+### What's Included
+
+- **Error Capture**: Automatic `ErrorUtils.setGlobalHandler()` + promise rejection tracking
+- **Screen Recording**: H.264 rolling buffer — on-error (10s, auto-attached) or manual (60s)
+- **Device Intelligence**: Persistent device ID via Keychain (iOS) / ANDROID_ID (Android)
+- **SQLite Tracking**: Query timing and slow query detection for expo-sqlite
+- **Navigation Tracking**: React Navigation integration, tracks `$screen_view` events + breadcrumbs
+- **Network Interception**: XHR monkey-patch for request tracking + breadcrumbs
+- **Performance**: Cold start timing, screen render tracking
+- **App State**: Automatic foreground/background/inactive tracking
+- **AsyncStorage**: Persistent storage for session data and remote config cache
+
+---
+
+## Remote Config
+
+The SDK can fetch behavior configuration from SitePong servers on init, allowing you to change sampling rates, feature toggles, and transport settings without publishing a new SDK version.
+
+```javascript
+sitepong.init({
+  apiKey: 'your-api-key',
+  remoteConfig: { enabled: true },
+});
+
+// Check if a remote config feature is enabled
+const enabled = sitepong.isRemoteConfigFeatureEnabled('session_replay');
+
+// Get full remote config
+const config = sitepong.getRemoteConfig();
+
+// Listen for config changes
+sitepong.onRemoteConfigChange((newConfig) => {
+  console.log('Config updated:', newConfig);
+});
+```
+
+Remote config is managed from the **SDK Config** page in the SitePong dashboard, where you can adjust:
+
+- **Sampling rates** for errors, analytics, replay, and performance
+- **Feature toggles** for any SDK feature
+- **Autocapture settings** (pageviews, clicks, forms, network requests)
+- **Transport settings** (flush interval, batch size, retry attempts)
+
+The SDK caches config locally (with configurable TTL) and refreshes in the background, so your app always starts instantly with the last-known config.
+
+---
+
 ## Framework Integration
 
 ### Next.js
@@ -690,6 +956,14 @@ sitepong.init({
 | `getDbQueryCount()` | Get query count |
 | `getDbNPlusOnePatterns()` | Get N+1 patterns |
 
+### Remote Config
+
+| Method | Description |
+|--------|-------------|
+| `getRemoteConfig()` | Get full remote config |
+| `isRemoteConfigFeatureEnabled(feature)` | Check if remote feature is enabled |
+| `onRemoteConfigChange(callback)` | Listen for config changes (returns unsubscribe fn) |
+
 ### Profiling
 
 | Method | Description |