@teardown/react-native 2.0.0 → 2.0.2

package/docs/04-force-updates.mdx

@@ -0,0 +1,339 @@
+# Force Updates
+
+Manage app version requirements and force updates with the ForceUpdateClient.
+
+## Overview
+
+The ForceUpdateClient automatically:
+- Checks app version against your backend
+- Monitors app state changes (background/foreground)
+- Throttles version checks to prevent excessive API calls
+- Emits version status changes for UI updates
+
+## Version Status Types
+
+```typescript
+type VersionStatus = 
+  | { type: "initializing" }      // Initial state
+  | { type: "checking" }           // Currently checking version
+  | { type: "up_to_date" }        // Version is current
+  | { type: "update_available" }  // New version available (optional)
+  | { type: "update_recommended" } // Update is recommended
+  | { type: "update_required" }   // Update is required
+  | { type: "disabled" }          // Version/build is disabled
+```
+
+## Using Force Updates
+
+### Access via Hook
+
+```typescript
+import { useForceUpdate } from '@teardown/react-native';
+
+function MyComponent() {
+  const { versionStatus, isUpdateRequired, isUpdateAvailable } = useForceUpdate();
+  
+  if (isUpdateRequired) {
+    return <UpdateRequiredScreen />;
+  }
+  
+  if (isUpdateAvailable) {
+    return <UpdateAvailableBanner />;
+  }
+  
+  return <App />;
+}
+```
+
+### Hook Return Value
+
+```typescript
+type UseForceUpdateResult = {
+  versionStatus: VersionStatus;
+  isUpdateAvailable: boolean;    // true if any update exists
+  isUpdateRequired: boolean;     // true if update is required
+}
+```
+
+## Configuration
+
+Configure force update behavior when initializing TeardownCore:
+
+```typescript
+const teardown = new TeardownCore({
+  // ... other options
+  forceUpdate: {
+    // Minimum time between foreground checks (default: 30000ms = 30s)
+    throttleMs: 30_000,
+    
+    // Minimum time since last successful check (default: 300000ms = 5min)
+    checkCooldownMs: 300_000,
+  },
+});
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `throttleMs` | 30000 | Min milliseconds between foreground transitions before checking |
+| `checkCooldownMs` | 300000 | Min milliseconds since last successful check before re-checking |
+
+## How It Works
+
+### Automatic Checks
+
+The SDK automatically checks version in these scenarios:
+
+1. **Initial Identification**
+   - When the SDK initializes
+   - When `identify()` is called
+   
+2. **App Foreground**
+   - When app returns from background
+   - Subject to throttle and cooldown timers
+
+### Check Flow
+
+```
+App goes to foreground
+  ↓
+Check throttle timer (last foreground < throttleMs ago?)
+  ↓ No
+Check cooldown timer (last check < checkCooldownMs ago?)
+  ↓ No
+Call identify() to refresh version status
+  ↓
+Update version status
+  ↓
+Emit VERSION_STATUS_CHANGED event
+```
+
+### Throttle vs Cooldown
+
+- **Throttle**: Prevents checks when rapidly switching apps
+- **Cooldown**: Prevents excessive API calls even with long background periods
+
+Example:
+```typescript
+// User switches between apps rapidly:
+// 10:00:00 - Foreground (check)
+// 10:00:05 - Foreground (throttled - too soon)
+// 10:00:45 - Foreground (check - passed throttle)
+// 10:00:50 - Foreground (cooldown - last check < 5min ago)
+```
+
+## Building Update UI
+
+### Required Update Screen
+
+```typescript
+function UpdateRequiredScreen() {
+  const { isUpdateRequired, versionStatus } = useForceUpdate();
+  
+  if (!isUpdateRequired) return null;
+  
+  return (
+    <View style={styles.container}>
+      <Text>Update Required</Text>
+      <Text>Please update to continue using the app</Text>
+      <Button 
+        title="Update Now" 
+        onPress={() => Linking.openURL('market://details?id=com.yourapp')}
+      />
+    </View>
+  );
+}
+```
+
+### Optional Update Banner
+
+```typescript
+function UpdateBanner() {
+  const { isUpdateAvailable, isUpdateRequired } = useForceUpdate();
+  const [dismissed, setDismissed] = useState(false);
+  
+  // Don't show if required (use dedicated screen)
+  if (isUpdateRequired || !isUpdateAvailable || dismissed) {
+    return null;
+  }
+  
+  return (
+    <View style={styles.banner}>
+      <Text>A new version is available</Text>
+      <Button title="Update" onPress={handleUpdate} />
+      <Button title="Later" onPress={() => setDismissed(true)} />
+    </View>
+  );
+}
+```
+
+### Full-Screen Takeover
+
+Example from the SDK:
+
+```typescript
+function FullscreenTakeover() {
+  const { isUpdateRequired } = useForceUpdate();
+  
+  if (!isUpdateRequired) return null;
+  
+  return (
+    <Modal visible={true} animationType="fade">
+      <UpdateRequiredScreen />
+    </Modal>
+  );
+}
+
+// In your layout
+<TeardownProvider core={teardown}>
+  <App />
+  <FullscreenTakeover />
+</TeardownProvider>
+```
+
+## Listening to Status Changes
+
+### Via Hook (Recommended)
+
+```typescript
+const { versionStatus } = useForceUpdate();
+
+useEffect(() => {
+  console.log('Version status:', versionStatus.type);
+}, [versionStatus]);
+```
+
+### Via Event Listener
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function MyComponent() {
+  const { core } = useTeardown();
+  
+  useEffect(() => {
+    const unsubscribe = core.forceUpdate.onVersionStatusChange((status) => {
+      console.log('Status changed:', status.type);
+      
+      if (status.type === 'update_required') {
+        // Show update UI
+      }
+    });
+    
+    return unsubscribe;
+  }, []);
+}
+```
+
+## Getting Current Status
+
+```typescript
+// Via hook (reactive)
+const { versionStatus } = useForceUpdate();
+
+// Via client (direct)
+const status = core.forceUpdate.getVersionStatus();
+```
+
+## Platform-Specific Store Links
+
+### iOS
+
+```typescript
+const APP_STORE_ID = 'your-app-id';
+const APP_STORE_URL = `https://apps.apple.com/app/id${APP_STORE_ID}`;
+
+<Button 
+  title="Update" 
+  onPress={() => Linking.openURL(APP_STORE_URL)} 
+/>
+```
+
+### Android
+
+```typescript
+const PACKAGE_NAME = 'com.yourcompany.yourapp';
+const PLAY_STORE_URL = `market://details?id=${PACKAGE_NAME}`;
+const PLAY_STORE_WEB = `https://play.google.com/store/apps/details?id=${PACKAGE_NAME}`;
+
+const handleUpdate = async () => {
+  const supported = await Linking.canOpenURL(PLAY_STORE_URL);
+  const url = supported ? PLAY_STORE_URL : PLAY_STORE_WEB;
+  Linking.openURL(url);
+};
+```
+
+### Cross-Platform
+
+```typescript
+import { Platform, Linking } from 'react-native';
+
+const STORE_URL = Platform.select({
+  ios: 'https://apps.apple.com/app/id123456789',
+  android: 'market://details?id=com.yourapp',
+  default: 'https://yourapp.com/download',
+});
+
+<Button 
+  title="Update Now" 
+  onPress={() => Linking.openURL(STORE_URL)} 
+/>
+```
+
+## Version Status in Backend
+
+Version status is determined by your backend configuration:
+
+- `UP_TO_DATE`: Current version matches or is newer than minimum
+- `UPDATE_AVAILABLE`: New version exists, but not required
+- `UPDATE_RECOMMENDED`: New version exists, recommended to update
+- `UPDATE_REQUIRED`: Current version is below minimum required
+- `DISABLED`: This specific version/build is disabled
+
+Configure these in your Teardown dashboard under project settings.
+
+## Best Practices
+
+### 1. Use Full-Screen Takeover for Required Updates
+
+```typescript
+// ✅ Good - blocks app usage
+{isUpdateRequired && <UpdateRequiredModal />}
+
+// ❌ Bad - user can dismiss and continue with outdated version
+{isUpdateRequired && <UpdateBanner dismissible />}
+```
+
+### 2. Make Optional Updates Dismissible
+
+```typescript
+// ✅ Good - user can choose when to update
+{isUpdateAvailable && !isUpdateRequired && <DismissibleBanner />}
+```
+
+### 3. Respect User Decisions
+
+```typescript
+// ✅ Good - remember dismissal for session
+const [dismissed, setDismissed] = useState(false);
+
+// ❌ Bad - annoying the user every render
+{isUpdateAvailable && <Banner />}
+```
+
+### 4. Provide Clear CTAs
+
+```typescript
+// ✅ Good - clear action
+<Button title="Update Now" onPress={openStore} />
+
+// ❌ Bad - vague
+<Button title="OK" onPress={openStore} />
+```
+
+## Next Steps
+
+- [Device Information](./05-device-info.mdx)
+- [Hooks Reference](./08-hooks-reference.mdx)
+- [Advanced Usage](./09-advanced.mdx)

package/docs/05-device-info.mdx

@@ -0,0 +1,324 @@
+# Device Information
+
+Collect comprehensive device, OS, and app information with the DeviceClient.
+
+## Overview
+
+The DeviceClient provides:
+- Unique device identification
+- Comprehensive device information
+- Platform-specific adapters
+- Automatic device fingerprinting
+
+## Device Adapters
+
+The SDK uses adapters to collect device information across different platforms.
+
+### Expo Adapter
+
+For Expo applications:
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { ExpoDeviceAdapter } from '@teardown/react-native/expo';
+
+const teardown = new TeardownCore({
+  // ... other options
+  deviceAdapter: new ExpoDeviceAdapter(),
+});
+```
+
+Required dependencies:
+```bash
+bun add expo-application expo-device expo-updates
+```
+
+### React Native Adapter
+
+For React Native CLI applications:
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { ReactNativeDeviceAdapter } from '@teardown/react-native/device-info';
+
+const teardown = new TeardownCore({
+  // ... other options
+  deviceAdapter: new ReactNativeDeviceAdapter(),
+});
+```
+
+Required dependencies:
+```bash
+bun add react-native-device-info
+```
+
+## Device ID
+
+Every device gets a unique, persistent identifier.
+
+### Getting Device ID
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function MyComponent() {
+  const { core } = useTeardown();
+  
+  const getDeviceId = async () => {
+    const deviceId = await core.device.getDeviceId();
+    console.log('Device ID:', deviceId);
+  };
+}
+```
+
+### How It Works
+
+1. On first launch, a random UUID is generated
+2. ID is persisted in namespaced storage
+3. Same ID is used for all subsequent sessions
+4. Survives app updates and reinstalls (depending on storage)
+
+## Device Information
+
+### Getting Device Info
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+```
+
+### DeviceInfo Object
+
+```typescript
+type DeviceInfo = {
+  // App Information
+  app_version: string;          // e.g., "1.0.0"
+  app_build: string;           // e.g., "100"
+  app_bundle_id: string;       // e.g., "com.company.app"
+  
+  // Device Information
+  device_platform: DevicePlatformEnum;  // IOS, ANDROID, WEB, etc.
+  device_os_version: string;            // e.g., "17.0"
+  device_model: string;                 // e.g., "iPhone 14 Pro"
+  device_manufacturer: string;          // e.g., "Apple"
+  
+  // Update Information (Expo only)
+  update?: {
+    update_id: string;
+    channel: string;
+    created_at: string;
+    runtime_version: string;
+  } | null;
+}
+```
+
+## Platform Enums
+
+### DevicePlatformEnum
+
+```typescript
+enum DevicePlatformEnum {
+  IOS = "IOS",
+  ANDROID = "ANDROID",
+  WEB = "WEB",
+  WINDOWS = "WINDOWS",
+  MACOS = "MACOS",
+  LINUX = "LINUX",
+  PHONE = "PHONE",
+  TABLET = "TABLET",
+  DESKTOP = "DESKTOP",
+  CONSOLE = "CONSOLE",
+  TV = "TV",
+  WEARABLE = "WEARABLE",
+  GAME_CONSOLE = "GAME_CONSOLE",
+  VR = "VR",
+  UNKNOWN = "UNKNOWN",
+  OTHER = "OTHER",
+}
+```
+
+## Creating Custom Adapters
+
+You can create custom device adapters for specific platforms or needs.
+
+### Adapter Interface
+
+```typescript
+interface DeviceInfoAdapter {
+  getDeviceInfo(): Promise<DeviceInfo>;
+}
+```
+
+### Example: Custom Web Adapter
+
+```typescript
+class WebDeviceAdapter implements DeviceInfoAdapter {
+  async getDeviceInfo(): Promise<DeviceInfo> {
+    return {
+      app_version: '1.0.0',
+      app_build: '1',
+      app_bundle_id: 'com.yourapp.web',
+      device_platform: DevicePlatformEnum.WEB,
+      device_os_version: navigator.userAgent,
+      device_model: 'Web Browser',
+      device_manufacturer: this.getBrowserName(),
+      update: null,
+    };
+  }
+  
+  private getBrowserName(): string {
+    const ua = navigator.userAgent;
+    if (ua.includes('Chrome')) return 'Chrome';
+    if (ua.includes('Firefox')) return 'Firefox';
+    if (ua.includes('Safari')) return 'Safari';
+    return 'Unknown';
+  }
+}
+
+// Use it
+const teardown = new TeardownCore({
+  deviceAdapter: new WebDeviceAdapter(),
+  // ...
+});
+```
+
+## Expo Update Information
+
+When using Expo with OTA updates, the SDK automatically includes update information:
+
+```typescript
+{
+  update: {
+    update_id: "abc123",
+    channel: "production",
+    created_at: "2024-01-01T00:00:00Z",
+    runtime_version: "1.0.0",
+  }
+}
+```
+
+This helps track which OTA update version users are running.
+
+## Usage in Identification
+
+Device information is automatically sent during identification:
+
+```typescript
+await core.identity.identify({
+  user_id: 'user-123',
+});
+
+// Automatically includes:
+// - Device ID
+// - Device platform
+// - OS version
+// - App version
+// - Device model
+// - Manufacturer
+// - Update info (if Expo)
+```
+
+This data is visible in your Teardown dashboard for analytics and debugging.
+
+## Platform Detection Examples
+
+### Check if iOS
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+const isIOS = deviceInfo.device_platform === DevicePlatformEnum.IOS;
+
+if (isIOS) {
+  // iOS-specific logic
+}
+```
+
+### Check Version
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+const version = deviceInfo.app_version;
+
+if (compareVersions(version, '2.0.0') < 0) {
+  // Running version older than 2.0.0
+}
+```
+
+### Check if Tablet
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+const isTablet = deviceInfo.device_platform === DevicePlatformEnum.TABLET;
+
+if (isTablet) {
+  // Show tablet-optimized UI
+}
+```
+
+## Storage
+
+Device ID is stored in namespaced storage:
+
+```
+Key: teardown:v1:device:deviceId
+Value: "uuid-generated-on-first-launch"
+```
+
+## Best Practices
+
+### 1. Cache Device Info If Needed Frequently
+
+```typescript
+// ❌ Bad - fetches every render
+function MyComponent() {
+  const deviceInfo = await core.device.getDeviceInfo();
+}
+
+// ✅ Good - fetch once and cache
+function MyComponent() {
+  const [deviceInfo, setDeviceInfo] = useState(null);
+  
+  useEffect(() => {
+    core.device.getDeviceInfo().then(setDeviceInfo);
+  }, []);
+}
+```
+
+### 2. Use Platform-Specific Code When Needed
+
+```typescript
+const deviceInfo = await core.device.getDeviceInfo();
+
+if (deviceInfo.device_platform === DevicePlatformEnum.IOS) {
+  // iOS-specific behavior
+} else if (deviceInfo.device_platform === DevicePlatformEnum.ANDROID) {
+  // Android-specific behavior
+}
+```
+
+### 3. Don't Manually Generate Device IDs
+
+```typescript
+// ❌ Bad - inconsistent with SDK
+const myDeviceId = uuid.v4();
+
+// ✅ Good - use SDK's device ID
+const deviceId = await core.device.getDeviceId();
+```
+
+## Privacy Considerations
+
+The SDK collects:
+- ✅ Device model and OS (for compatibility)
+- ✅ App version (for update management)
+- ✅ Generated device ID (for analytics)
+- ❌ No personal information
+- ❌ No advertising IDs
+- ❌ No contacts or photos
+
+Device ID is randomly generated and not tied to hardware identifiers.
+
+## Next Steps
+
+- [Storage](./06-storage.mdx)
+- [Logging](./06-logging.mdx)
+- [API Reference](./07-api-reference.mdx)