native-update 1.3.6 → 1.4.0

package/docs/guides/channel-management.md

@@ -0,0 +1,343 @@
+# Channel Management Guide
+
+This guide explains how to use update channels (production, staging, development) to manage different environments for your app updates.
+
+## Overview
+
+Native Update supports three built-in channels that allow you to:
+- Test updates in development before releasing
+- QA updates in staging with beta testers
+- Deploy stable updates to production users
+
+## Channel Types
+
+### 1. Development Channel
+**Purpose**: Local testing and rapid iteration
+
+```typescript
+// Configure for development
+await NativeUpdate.configure({
+  updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+  channel: 'development',
+  autoCheck: true,
+  checkInterval: 60, // Check every minute for rapid testing
+});
+```
+
+**Characteristics**:
+- Fastest update delivery
+- Auto-update enabled by default
+- No user consent required (immediate updates)
+- Ideal for internal testing
+
+### 2. Staging Channel
+**Purpose**: QA testing and beta releases
+
+```typescript
+// Configure for staging
+await NativeUpdate.configure({
+  updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+  channel: 'staging',
+  autoCheck: true,
+  checkInterval: 3600, // Check every hour
+});
+```
+
+**Characteristics**:
+- Beta testing environment
+- User consent typically required
+- Tests update flow before production
+- Ideal for TestFlight/Internal Testing releases
+
+### 3. Production Channel
+**Purpose**: Live user releases
+
+```typescript
+// Configure for production
+await NativeUpdate.configure({
+  updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+  channel: 'production',
+  autoCheck: true,
+  checkInterval: 86400, // Check daily
+});
+```
+
+**Characteristics**:
+- Most stable updates only
+- User consent required
+- Gradual rollout support
+- Automatic rollback on errors
+
+## Dashboard Channel Configuration
+
+### Setting Up Channels in Dashboard
+
+1. **Navigate to your app** in the dashboard (`/dashboard/apps`)
+2. **Click on your app** to open app details
+3. **View Channels section** - shows all three channels with their settings
+
+### Channel Settings
+
+Each channel has these configurable options:
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Enabled | Whether this channel is active | true |
+| Auto Update | Automatically install updates | varies |
+| Update Strategy | immediate/background/manual | background |
+| Require User Consent | Ask before installing | varies |
+| Min Version | Minimum app version required | null |
+
+### Configuring Channel via Dashboard
+
+1. Go to **Dashboard > Apps > [Your App]**
+2. In the **Channels** section, click **Configure**
+3. Adjust settings for each channel:
+   - **Production**: Enable consent, use background strategy
+   - **Staging**: Enable auto-update, use background strategy
+   - **Development**: Enable auto-update, use immediate strategy
+
+## Uploading Builds to Channels
+
+### Via Dashboard Upload Page
+
+1. Go to **Dashboard > Upload**
+2. Select your app
+3. **Choose Channel**: Select production, staging, or development
+4. Upload your build file (zip, apk, or ipa)
+5. Fill in version details:
+   - Version (e.g., 1.2.3)
+   - Build Number
+   - Release Notes
+   - Release Type (major/minor/patch/hotfix)
+6. Click **Upload**
+
+### Via CLI
+
+```bash
+# Upload to development
+npx native-update bundle upload ./www --channel development --version 1.0.0
+
+# Upload to staging
+npx native-update bundle upload ./www --channel staging --version 1.0.0
+
+# Upload to production
+npx native-update bundle upload ./www --channel production --version 1.0.0
+```
+
+## Update Flow by Channel
+
+### Development Flow
+
+```
+Developer changes code
+    ↓
+Build locally: yarn build
+    ↓
+Upload to development channel
+    ↓
+App auto-downloads and applies immediately
+    ↓
+Developer tests changes
+```
+
+### Staging Flow
+
+```
+Code passes development testing
+    ↓
+Upload to staging channel
+    ↓
+QA team / Beta testers receive update
+    ↓
+Users approve and install update
+    ↓
+QA validates functionality
+```
+
+### Production Flow
+
+```
+Code passes staging testing
+    ↓
+Upload to production channel
+    ↓
+Gradual rollout begins (10% → 50% → 100%)
+    ↓
+Users receive update notification
+    ↓
+Users approve and install
+    ↓
+Monitor for errors, rollback if needed
+```
+
+## Environment-Based Configuration
+
+### React/Vite Example
+
+```typescript
+// src/config/update-config.ts
+const getUpdateConfig = () => {
+  const baseConfig = {
+    updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+    autoCheck: true,
+  };
+
+  if (import.meta.env.MODE === 'development') {
+    return {
+      ...baseConfig,
+      channel: 'development',
+      checkInterval: 60,
+    };
+  }
+
+  if (import.meta.env.MODE === 'staging') {
+    return {
+      ...baseConfig,
+      channel: 'staging',
+      checkInterval: 3600,
+    };
+  }
+
+  // Production
+  return {
+    ...baseConfig,
+    channel: 'production',
+    checkInterval: 86400,
+  };
+};
+
+export const updateConfig = getUpdateConfig();
+```
+
+### Capacitor Config Example
+
+```typescript
+// capacitor.config.ts
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp',
+  appName: 'My App',
+  webDir: 'dist',
+  plugins: {
+    NativeUpdate: {
+      updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+      channel: process.env.UPDATE_CHANNEL || 'production',
+      autoCheck: true,
+      checkInterval: 3600,
+    },
+  },
+};
+
+export default config;
+```
+
+## Gradual Rollouts (Production)
+
+### Setting Up Gradual Rollout
+
+1. Go to **Dashboard > Rollouts**
+2. Select your app and channel
+3. Configure rollout percentage:
+   - Start at 10% to catch issues early
+   - Increase to 50% if metrics are good
+   - Complete at 100% for full release
+
+### Rollout Best Practices
+
+1. **Start Small**: Begin with 5-10% of users
+2. **Monitor Errors**: Check error rates in Analytics
+3. **Watch Rollbacks**: High rollback rates indicate issues
+4. **Gradual Increase**: 10% → 25% → 50% → 100%
+5. **Pause if Needed**: Stop rollout if issues arise
+
+## Channel Switching at Runtime
+
+```typescript
+// Switch channel dynamically (advanced use case)
+async function switchToChannel(channel: 'production' | 'staging' | 'development') {
+  await NativeUpdate.configure({
+    channel,
+  });
+
+  // Force check for updates on new channel
+  await NativeUpdate.sync();
+}
+```
+
+## Monitoring Channels
+
+### Dashboard Analytics
+
+View per-channel metrics at **Dashboard > Analytics**:
+
+- **Downloads**: Total downloads per channel
+- **Installs**: Successful installations
+- **Rollbacks**: Failed updates that rolled back
+- **Errors**: Update errors
+
+### Per-Channel Health
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Install Rate | >95% | 90-95% | <90% |
+| Rollback Rate | <1% | 1-5% | >5% |
+| Error Rate | <0.1% | 0.1-1% | >1% |
+
+## Best Practices
+
+### 1. Always Test in Development First
+Never upload directly to production. Flow should be:
+`Development → Staging → Production`
+
+### 2. Use Semantic Versioning
+- **Major** (1.0.0 → 2.0.0): Breaking changes
+- **Minor** (1.0.0 → 1.1.0): New features
+- **Patch** (1.0.0 → 1.0.1): Bug fixes
+- **Hotfix**: Emergency production fixes
+
+### 3. Write Clear Release Notes
+Users see release notes before updating. Make them:
+- Clear and concise
+- Highlight important changes
+- List bug fixes
+- Note any required actions
+
+### 4. Monitor After Release
+- Watch dashboard analytics for 24-48 hours
+- Check error rates and rollbacks
+- Be ready to pause rollout if needed
+
+### 5. Keep Channels in Sync
+- Same code should flow through all channels
+- Don't skip staging for production releases
+- Document channel-specific configurations
+
+## Troubleshooting
+
+### Update Not Appearing on Device
+
+1. **Check channel configuration**: Ensure device is on correct channel
+2. **Verify upload**: Confirm build is uploaded to expected channel
+3. **Check version**: Device version must be compatible
+4. **Force sync**: Call `NativeUpdate.sync()` manually
+
+### Wrong Channel Receiving Updates
+
+1. **Check capacitor.config.ts**: Verify channel setting
+2. **Check environment variables**: Ensure correct env is loaded
+3. **Rebuild app**: Changes to config require rebuild
+
+### Rollout Stuck
+
+1. **Check rollout status**: View in Dashboard > Rollouts
+2. **Verify percentage**: Ensure rollout isn't paused
+3. **Check user count**: Small user bases may not hit percentage thresholds
+
+## Related Documentation
+
+- [Quick Start Guide](../getting-started/quick-start.md)
+- [Configuration Guide](../getting-started/configuration.md)
+- [Deployment Guide](./deployment-guide.md)
+- [Production Readiness](../production-readiness.md)

package/docs/guides/dashboard-guide.md

@@ -0,0 +1,365 @@
+# Dashboard User Guide
+
+Complete guide to using the Native Update Dashboard at [nativeupdate.aoneahsan.com](https://nativeupdate.aoneahsan.com).
+
+## Getting Started
+
+### 1. Create an Account
+
+1. Visit [nativeupdate.aoneahsan.com](https://nativeupdate.aoneahsan.com)
+2. Click **Get Started** or **Sign Up**
+3. Sign in with your Google account
+4. You'll be redirected to the dashboard
+
+### 2. Connect Google Drive
+
+Before uploading builds, connect your Google Drive for storage:
+
+1. Go to **Dashboard > Google Drive**
+2. Click **Connect Google Drive**
+3. Authorize the application
+4. Your builds will be stored in a dedicated folder
+
+## Dashboard Overview
+
+### Navigation
+
+The dashboard sidebar contains:
+
+| Section | Description |
+|---------|-------------|
+| **Overview** | Dashboard home with stats |
+| **Apps** | Manage your applications |
+| **Builds** | View and manage all builds |
+| **Upload** | Upload new builds |
+| **Rollouts** | Manage gradual rollouts |
+| **Analytics** | View update metrics |
+| **Google Drive** | Manage storage connection |
+| **Configuration** | Get integration code snippets |
+| **Settings** | Account settings |
+
+## Managing Apps
+
+### Creating an App
+
+1. Go to **Dashboard > Apps**
+2. Click **Create App**
+3. Fill in the details:
+   - **App Name**: Display name (e.g., "My Awesome App")
+   - **Package ID**: Unique identifier (e.g., `com.example.myapp`)
+   - **Description**: Brief description
+   - **Platforms**: Select iOS, Android, and/or Web
+4. Click **Create App**
+
+### App Details Page
+
+Click on any app to view:
+
+- **Overview Cards**: Total builds, active users, platforms, last build date
+- **Channels**: Production, staging, development settings
+- **Active Rollouts**: Current rollout status
+- **Recent Builds**: Latest builds for this app
+
+### Configuring Channels
+
+Each app has three channels with configurable settings:
+
+1. In the app details page, find the **Channels** section
+2. Click **Configure** on any channel
+3. Adjust settings:
+   - **Enabled**: Turn channel on/off
+   - **Auto Update**: Automatically install updates
+   - **Update Strategy**: immediate/background/manual
+   - **Require User Consent**: Ask before installing
+   - **Min Version**: Minimum required app version
+
+## Uploading Builds
+
+### Upload Process
+
+1. Go to **Dashboard > Upload**
+2. **Select App**: Choose from your registered apps
+3. **Select Channel**: production, staging, or development
+4. **Select Platform**: iOS, Android, or Web
+5. **Upload File**: Drag and drop or click to select
+   - Supported formats: `.zip`, `.apk`, `.ipa`
+6. **Enter Version Info**:
+   - **Version**: Semantic version (e.g., 1.2.3)
+   - **Build Number**: Incremental build number
+   - **Release Notes**: What's new in this version
+   - **Release Type**: major/minor/patch/hotfix
+   - **Pre-release**: Check if this is a beta/alpha
+
+7. Click **Upload Build**
+
+### Build Requirements
+
+| Platform | File Type | Contents |
+|----------|-----------|----------|
+| Web | `.zip` | Built web assets (dist/www folder) |
+| Android | `.apk` or `.zip` | APK or web assets |
+| iOS | `.ipa` or `.zip` | IPA or web assets |
+
+### Upload Progress
+
+The upload page shows:
+- Upload progress percentage
+- File validation status
+- Checksum generation
+- Google Drive upload status
+
+## Managing Builds
+
+### Builds List
+
+Go to **Dashboard > Builds** to see all builds:
+
+- **Version**: Build version (clickable for details)
+- **App**: Associated application
+- **Channel**: Deployment channel
+- **Platform**: Target platform
+- **Status**: active/processing/failed/archived
+- **Size**: File size
+- **Uploaded**: Upload date/time
+
+### Build Detail Page
+
+Click on a version to view complete build information:
+
+**Stats Cards**:
+- Downloads: Total download count
+- Installs: Successful installations
+- Rollbacks: Reverted updates
+- Errors: Failed installations
+
+**Build Information**:
+- Version, build number, version code
+- Channel, platform, release type
+- Pre-release status
+
+**File Details**:
+- File name, size, type, MIME type
+- Checksum (SHA-256)
+- Signature (if signed)
+
+**Release Notes**:
+- Full release notes text
+
+**Upload Information**:
+- Upload timestamp
+- Uploader email
+- Upload duration
+
+### Build Actions
+
+- **Download**: Download the build file from Google Drive
+- **Delete**: Remove the build (with confirmation)
+
+## Rollouts
+
+### Creating a Rollout
+
+1. Go to **Dashboard > Rollouts**
+2. Click **Create Rollout**
+3. Select app and channel
+4. Set initial percentage (e.g., 10%)
+5. Click **Start Rollout**
+
+### Managing Rollouts
+
+For active rollouts, you can:
+
+- **Increase Percentage**: Gradually roll out to more users
+- **Pause**: Stop the rollout temporarily
+- **Resume**: Continue a paused rollout
+- **Complete**: Set to 100% to finish rollout
+
+### Rollout Status
+
+| Status | Description |
+|--------|-------------|
+| Active | Rollout is in progress |
+| Paused | Rollout is temporarily stopped |
+| Completed | Rollout reached 100% |
+
+## Analytics
+
+### Overview Metrics
+
+The Analytics page shows:
+
+- **Total Downloads**: All-time download count
+- **Total Installs**: Successful installations
+- **Success Rate**: Install/download ratio
+- **Active Users**: Currently active users
+
+### Per-App Analytics
+
+Select an app to view:
+
+- Download trends over time
+- Install success rates
+- Error rates
+- Rollback statistics
+- Channel-specific metrics
+
+## Configuration
+
+### Getting Integration Code
+
+1. Go to **Dashboard > Configuration**
+2. Select your app from the dropdown
+3. Copy the configuration for your platform:
+
+**iOS (Info.plist)**:
+```xml
+<key>NativeUpdateConfig</key>
+<dict>
+    <key>appId</key>
+    <string>com.example.myapp</string>
+    <key>updateUrl</key>
+    <string>https://nativeupdate.aoneahsan.com/api/updates</string>
+    <key>channel</key>
+    <string>production</string>
+</dict>
+```
+
+**Android (AndroidManifest.xml)**:
+```xml
+<meta-data
+    android:name="com.aoneahsan.nativeupdate.appId"
+    android:value="com.example.myapp" />
+<meta-data
+    android:name="com.aoneahsan.nativeupdate.updateUrl"
+    android:value="https://nativeupdate.aoneahsan.com/api/updates" />
+```
+
+**Capacitor (capacitor.config.ts)**:
+```typescript
+plugins: {
+  NativeUpdate: {
+    appId: 'com.example.myapp',
+    updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+    channel: 'production',
+  }
+}
+```
+
+**JavaScript/TypeScript**:
+```typescript
+import { NativeUpdate } from 'native-update';
+
+await NativeUpdate.configure({
+  updateUrl: 'https://nativeupdate.aoneahsan.com/api/updates',
+});
+```
+
+## Settings
+
+### Account Settings
+
+Go to **Dashboard > Settings** to manage:
+
+- **Profile**: Display name, email, photo
+- **Preferences**:
+  - Email notifications
+  - Update notifications
+  - Theme (light/dark/auto)
+  - Language
+
+### Plan Information
+
+View your current plan:
+
+- **Beta**: Free tier with full features
+- **Pro**: Enhanced limits and support
+- **Enterprise**: Custom solutions
+
+## Common Workflows
+
+### First-Time Setup
+
+1. Sign up and connect Google Drive
+2. Create your first app
+3. Configure channel settings
+4. Copy integration code to your app
+5. Build and upload your first version
+6. Test on development channel
+7. Promote to staging, then production
+
+### Deploying an Update
+
+1. Make changes to your app code
+2. Build: `yarn build` or `npm run build`
+3. Go to Dashboard > Upload
+4. Select app, channel, and platform
+5. Upload the build file
+6. Add version and release notes
+7. Monitor in Analytics
+
+### Emergency Hotfix
+
+1. Fix the critical issue in code
+2. Build immediately
+3. Upload to production channel
+4. Set release type to "hotfix"
+5. Create immediate rollout (100%)
+6. Monitor for issues
+
+### Rolling Back
+
+1. Go to Dashboard > Builds
+2. Find the previous stable version
+3. Create a new rollout for that version
+4. Or: The plugin automatically rolls back on crash
+
+## Troubleshooting
+
+### Upload Failed
+
+- **Check file size**: Max 500MB per upload
+- **Check file format**: Must be .zip, .apk, or .ipa
+- **Check Google Drive**: Ensure connected and has space
+- **Check network**: Stable connection required
+
+### Build Not Appearing on Device
+
+1. Verify build is uploaded to correct channel
+2. Check device is configured for same channel
+3. Force sync: Call `NativeUpdate.sync()`
+4. Check app version compatibility
+
+### Google Drive Disconnected
+
+1. Go to Dashboard > Google Drive
+2. Click **Reconnect**
+3. Re-authorize the application
+
+### Analytics Not Updating
+
+- Allow 15-30 minutes for data processing
+- Ensure devices have network connectivity
+- Check that events are being sent from app
+
+## API Endpoint
+
+The dashboard uses this API endpoint for updates:
+
+```
+https://nativeupdate.aoneahsan.com/api/updates
+```
+
+Use this URL in your app configuration.
+
+## Support
+
+- **Email**: aoneahsan@gmail.com
+- **Documentation**: [docs folder](../README.md)
+- **Website**: [nativeupdate.aoneahsan.com](https://nativeupdate.aoneahsan.com)
+
+## Related Documentation
+
+- [Channel Management](./channel-management.md)
+- [Quick Start Guide](../getting-started/quick-start.md)
+- [Configuration Guide](../getting-started/configuration.md)
+- [End-to-End Workflow](./end-to-end-workflow.md)