native-update 1.3.6 → 1.4.0

package/docs/guides/end-to-end-workflow.md

@@ -0,0 +1,491 @@
+# End-to-End Workflow Guide
+
+This guide walks you through the complete workflow from setting up Native Update to deploying your first OTA update to production users.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Native Update Workflow                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  1. SETUP           2. INTEGRATE         3. BUILD & UPLOAD          │
+│  ┌─────────┐        ┌─────────────┐      ┌──────────────────┐       │
+│  │Dashboard│   →    │ App Code    │  →   │ Dashboard Upload │       │
+│  │ Account │        │ Integration │      │ or CLI           │       │
+│  └─────────┘        └─────────────┘      └──────────────────┘       │
+│                                                                     │
+│  4. TEST            5. ROLLOUT           6. MONITOR                 │
+│  ┌─────────┐        ┌─────────────┐      ┌──────────────────┐       │
+│  │Dev/Stage│   →    │ Production  │  →   │ Analytics &      │       │
+│  │ Testing │        │ Deployment  │      │ Rollback         │       │
+│  └─────────┘        └─────────────┘      └──────────────────┘       │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- [ ] A Capacitor app (React, Vue, Angular, or vanilla JS)
+- [ ] Node.js 18+ installed
+- [ ] yarn package manager
+- [ ] Google account (for dashboard login)
+
+## Phase 1: Dashboard Setup (10 minutes)
+
+### Step 1.1: Create Dashboard Account
+
+1. Visit [nativeupdate.aoneahsan.com](https://nativeupdate.aoneahsan.com)
+2. Click **Get Started**
+3. Sign in with Google
+4. Complete onboarding
+
+### Step 1.2: Connect Google Drive
+
+1. Go to **Dashboard > Google Drive**
+2. Click **Connect Google Drive**
+3. Grant permissions
+4. Verify connection is active (green status)
+
+### Step 1.3: Create Your App
+
+1. Go to **Dashboard > Apps**
+2. Click **Create App**
+3. Enter details:
+   ```
+   App Name: My Awesome App
+   Package ID: com.example.myawesomeapp
+   Description: A sample app with OTA updates
+   Platforms: [x] iOS [x] Android [x] Web
+   ```
+4. Click **Create App**
+
+### Step 1.4: Note Your Configuration
+
+1. Go to **Dashboard > Configuration**
+2. Select your app
+3. Copy the Capacitor configuration (you'll need this later)
+
+## Phase 2: App Integration (15 minutes)
+
+### Step 2.1: Install the Plugin
+
+```bash
+# Navigate to your Capacitor project
+cd my-capacitor-app
+
+# Install the plugin
+yarn add native-update
+
+# Sync with native platforms
+npx cap sync
+```
+
+### Step 2.2: Configure Capacitor
+
+Update `capacitor.config.ts`:
+
+```typescript
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myawesomeapp',
+  appName: 'My Awesome App',
+  webDir: 'dist',
+  plugins: {
+    NativeUpdate: {
+      appId: 'com.example.myawesomeapp',
+      updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+      channel: 'production',
+      autoCheck: true,
+      checkInterval: 3600,
+      updateStrategy: 'background'
+    }
+  }
+};
+
+export default config;
+```
+
+### Step 2.3: Initialize in Your App
+
+Create `src/services/update-service.ts`:
+
+```typescript
+import { NativeUpdate } from 'native-update';
+
+export const updateService = {
+  async initialize() {
+    // Configure the plugin
+    await NativeUpdate.configure({
+      updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+      autoCheck: true,
+    });
+
+    // Set up event listeners
+    NativeUpdate.addListener('updateAvailable', (info) => {
+      console.log('Update available:', info.version);
+      this.promptUpdate(info);
+    });
+
+    NativeUpdate.addListener('downloadProgress', (progress) => {
+      console.log(`Download: ${progress.percent}%`);
+    });
+
+    NativeUpdate.addListener('updateReady', () => {
+      console.log('Update ready to install');
+    });
+
+    // Check for updates on startup
+    await this.checkForUpdates();
+  },
+
+  async checkForUpdates() {
+    try {
+      const result = await NativeUpdate.sync();
+
+      if (result.status === 'UPDATE_AVAILABLE') {
+        return result;
+      }
+
+      return null;
+    } catch (error) {
+      console.error('Update check failed:', error);
+      return null;
+    }
+  },
+
+  async promptUpdate(updateInfo: any) {
+    // Show your custom UI or use native dialog
+    const shouldUpdate = confirm(
+      `Version ${updateInfo.version} is available. Update now?`
+    );
+
+    if (shouldUpdate) {
+      await this.downloadAndInstall();
+    }
+  },
+
+  async downloadAndInstall() {
+    try {
+      // Download is handled by sync, just reload
+      await NativeUpdate.reload();
+    } catch (error) {
+      console.error('Update failed:', error);
+    }
+  },
+};
+```
+
+### Step 2.4: Initialize on App Start
+
+In your main app file (e.g., `App.tsx` or `main.ts`):
+
+```typescript
+import { updateService } from './services/update-service';
+
+// Initialize updates when app starts
+async function initApp() {
+  await updateService.initialize();
+}
+
+initApp();
+```
+
+### Step 2.5: Build Your App
+
+```bash
+# Build web assets
+yarn build
+
+# Sync to native platforms
+npx cap sync
+
+# Run on device/simulator to test
+npx cap run ios
+# or
+npx cap run android
+```
+
+## Phase 3: First Upload (5 minutes)
+
+### Step 3.1: Build for Upload
+
+```bash
+# Create production build
+yarn build
+```
+
+### Step 3.2: Upload via Dashboard
+
+1. Go to **Dashboard > Upload**
+2. Select your app
+3. Select **development** channel (for initial testing)
+4. Select your platform
+5. Upload your `dist` folder as a ZIP:
+   ```bash
+   # Create ZIP of your build
+   cd dist && zip -r ../build-v1.0.0.zip . && cd ..
+   ```
+6. Enter version details:
+   ```
+   Version: 1.0.0
+   Build Number: 1
+   Release Notes: Initial release with OTA support
+   Release Type: major
+   ```
+7. Click **Upload Build**
+
+### Step 3.3: Verify Upload
+
+1. Go to **Dashboard > Builds**
+2. Confirm your build appears with status "active"
+
+## Phase 4: Testing (10 minutes)
+
+### Step 4.1: Test on Development Channel
+
+1. Ensure your app is configured for `channel: 'development'`
+2. Run the app on a device/simulator
+3. The app should detect no updates (you're on latest)
+
+### Step 4.2: Make a Change
+
+1. Edit something visible in your app (e.g., change a title)
+2. Rebuild: `yarn build`
+3. Upload as version 1.0.1 to development channel
+
+### Step 4.3: Verify Update Works
+
+1. Reopen your app (or wait for auto-check)
+2. App should detect update available
+3. Accept the update
+4. App reloads with new changes
+5. Verify your change is visible
+
+### Step 4.4: Test Rollback (Optional)
+
+1. Make a breaking change that crashes the app
+2. Upload as version 1.0.2
+3. The plugin should automatically rollback to 1.0.1
+
+## Phase 5: Staging Deployment
+
+### Step 5.1: Upload to Staging
+
+1. Once development testing passes
+2. Go to **Dashboard > Upload**
+3. Upload the same build to **staging** channel
+4. Version: Keep same version (1.0.1)
+
+### Step 5.2: Configure Staging Testers
+
+1. Build app with `channel: 'staging'`
+2. Distribute to QA team via TestFlight/Firebase Distribution
+3. They will receive staging updates
+
+### Step 5.3: QA Validation
+
+Have testers verify:
+- [ ] Update is detected
+- [ ] Download completes successfully
+- [ ] App reloads correctly
+- [ ] All features work as expected
+- [ ] No crashes or errors
+
+## Phase 6: Production Deployment
+
+### Step 6.1: Upload to Production
+
+1. Go to **Dashboard > Upload**
+2. Upload to **production** channel
+3. Double-check version and release notes
+
+### Step 6.2: Create Gradual Rollout
+
+1. Go to **Dashboard > Rollouts**
+2. Click **Create Rollout**
+3. Select your app and production channel
+4. Set initial percentage: **10%**
+5. Click **Start Rollout**
+
+### Step 6.3: Monitor Initial Rollout
+
+Wait 24-48 hours and check:
+- **Analytics**: View download and install rates
+- **Errors**: Check for any reported errors
+- **Rollbacks**: Monitor rollback rate (should be <1%)
+
+### Step 6.4: Expand Rollout
+
+If metrics are healthy:
+1. Go to **Dashboard > Rollouts**
+2. Increase to **50%**
+3. Monitor for another 24 hours
+4. Increase to **100%** to complete
+
+## Phase 7: Ongoing Maintenance
+
+### Regular Update Cycle
+
+```
+1. Develop features/fixes
+       ↓
+2. Build and test locally
+       ↓
+3. Upload to development
+       ↓
+4. Internal testing
+       ↓
+5. Upload to staging
+       ↓
+6. QA testing
+       ↓
+7. Upload to production
+       ↓
+8. Gradual rollout (10% → 50% → 100%)
+       ↓
+9. Monitor analytics
+```
+
+### Monitoring Checklist
+
+Daily:
+- [ ] Check error rates in Analytics
+- [ ] Review any reported issues
+- [ ] Monitor rollback rates
+
+Weekly:
+- [ ] Review overall success rates
+- [ ] Plan upcoming updates
+- [ ] Archive old builds
+
+Monthly:
+- [ ] Audit channel configurations
+- [ ] Review security settings
+- [ ] Check storage usage
+
+## Complete Code Example
+
+Here's a complete React example:
+
+```typescript
+// src/App.tsx
+import { useEffect, useState } from 'react';
+import { NativeUpdate } from 'native-update';
+
+function App() {
+  const [updateStatus, setUpdateStatus] = useState<string>('Checking...');
+  const [version, setVersion] = useState<string>('1.0.0');
+
+  useEffect(() => {
+    initializeUpdates();
+  }, []);
+
+  async function initializeUpdates() {
+    try {
+      // Configure
+      await NativeUpdate.configure({
+        updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+        autoCheck: true,
+      });
+
+      // Get current version
+      const info = await NativeUpdate.getCurrentBundle();
+      setVersion(info.version || '1.0.0');
+
+      // Set up listeners
+      NativeUpdate.addListener('updateAvailable', (info) => {
+        setUpdateStatus(`Update ${info.version} available!`);
+      });
+
+      NativeUpdate.addListener('downloadProgress', (progress) => {
+        setUpdateStatus(`Downloading: ${progress.percent}%`);
+      });
+
+      // Check for updates
+      const result = await NativeUpdate.sync();
+
+      if (result.status === 'UPDATE_AVAILABLE') {
+        setUpdateStatus('Update available');
+      } else if (result.status === 'UP_TO_DATE') {
+        setUpdateStatus('Up to date');
+      }
+    } catch (error) {
+      setUpdateStatus('Error checking updates');
+      console.error(error);
+    }
+  }
+
+  async function handleUpdate() {
+    try {
+      setUpdateStatus('Installing...');
+      await NativeUpdate.reload();
+    } catch (error) {
+      setUpdateStatus('Update failed');
+    }
+  }
+
+  return (
+    <div className="app">
+      <h1>My App v{version}</h1>
+      <p>Status: {updateStatus}</p>
+
+      {updateStatus.includes('available') && (
+        <button onClick={handleUpdate}>
+          Install Update
+        </button>
+      )}
+
+      {/* Change this text to test OTA updates! */}
+      <p>Welcome to my awesome app!</p>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## Troubleshooting
+
+### Update Not Detected
+
+1. Check network connectivity
+2. Verify channel configuration matches
+3. Check build is uploaded to correct channel
+4. Try manual sync: `await NativeUpdate.sync()`
+
+### Download Fails
+
+1. Check internet connection
+2. Verify Google Drive is connected
+3. Check file isn't corrupted
+4. Try re-uploading the build
+
+### App Crashes After Update
+
+1. Plugin should auto-rollback
+2. Check error logs
+3. Verify build was tested properly
+4. Upload a fixed version
+
+### Rollout Not Progressing
+
+1. Check rollout status in dashboard
+2. Verify percentage is set correctly
+3. Ensure enough users to hit percentage
+
+## Next Steps
+
+- [Channel Management](./channel-management.md) - Advanced channel configuration
+- [Dashboard Guide](./dashboard-guide.md) - Full dashboard documentation
+- [Security Best Practices](./security-best-practices.md) - Secure your updates
+- [API Reference](../api/API.md) - Complete API documentation
+
+## Support
+
+Need help? Contact us:
+- Email: aoneahsan@gmail.com
+- Website: [nativeupdate.aoneahsan.com](https://nativeupdate.aoneahsan.com)