cordova-plugin-hot-updates 2.1.1 → 2.2.0

package/README.md

@@ -1,31 +1,23 @@
-# Cordova Hot Updates Plugin
+# Cordova Hot Updates Plugin v2.2.0
 
-🔥 **Frontend-controlled over-the-air (OTA) hot updates for Cordova iOS applications**
+Frontend-controlled manual hot updates for Cordova iOS applications using WebView Reload approach.
 
 [![npm version](https://badge.fury.io/js/cordova-plugin-hot-updates.svg)](https://badge.fury.io/js/cordova-plugin-hot-updates)
 [![License](https://img.shields.io/badge/License-Custom%20Non--Commercial-blue.svg)](#license)
 
 This plugin enables **manual, JavaScript-controlled** web content updates for your Cordova iOS applications without requiring App Store approval. Your frontend code decides when to check, download, and install updates.
 
-## ✨ What's New in v2.1.0
+## Features
 
-- ✅ **Smart Download**: `getUpdate()` won't re-download already installed versions
-- ✅ **Cleaner Native Code**: Removed debug logs and emojis for production
-- ✅ **Better Documentation**: Complete API docs in `docs/` folder
-- ✅ **Bug Fixes**: Fixed duplicate download issues and code cleanup
+- **Frontend Control**: JavaScript decides when to update (no automatic background checking)
+- **Two-Step Updates**: Separate download (`getUpdate`) and install (`forceUpdate`) for better UX
+- **Auto-Install on Launch**: If user ignores update prompt, it installs on next app launch
+- **Canary System**: Automatic rollback if update fails to load (20-second timeout)
+- **IgnoreList**: Tracks problematic versions (information only, does NOT block installation)
+- **Instant Effect**: WebView Reload approach - no app restart needed
+- **Cache Management**: Clears WKWebView cache (disk, memory, Service Worker) before reload
 
-[See full changelog](CHANGELOG.md)
-
-## 🎯 Key Features
-
-- **🎮 Frontend Control**: Your JavaScript decides when to update (no automatic background checks)
-- **⚡ Two-Step Updates**: Separate download and install for better UX
-- **🔄 Auto-Install**: If user ignores popup, update installs on next app launch
-- **🐦 Canary System**: Automatic rollback if update fails to load (20-second timeout)
-- **📋 IgnoreList**: Tracks problematic versions (informational only)
-- **🚀 Instant Effect**: WebView Reload approach - no app restart needed
-
-## 📦 Installation
+## Installation
 
 ```bash
 # Install from npm
@@ -36,166 +28,358 @@ cd platforms/ios
 pod install
 ```
 
+Or install from local directory:
+
+```bash
+cordova plugin add /path/to/cordova-plugin-hot-updates
+```
+
+Or install from GitHub:
+
+```bash
+cordova plugin add https://github.com/vladimirDarksy/Cordova_hot_update.git
+```
+
 **Requirements:**
 - Cordova >= 7.0.0
 - cordova-ios >= 4.4.0
-- iOS >= 11.0
+- iOS >= 11.2
 - CocoaPods (for SSZipArchive dependency)
 
-## 🚀 Quick Start
+## Quick Start
 
 ### 1. Minimal Integration
 
 ```javascript
 document.addEventListener('deviceready', function() {
-    // STEP 1: Confirm app loaded successfully (REQUIRED on every start!)
-    cordova.exec(
-        function(info) {
-            const currentVersion = info.installedVersion || info.appBundleVersion;
-
-            // This MUST be called within 20 seconds or automatic rollback occurs
-            window.HotUpdates.canary(currentVersion, function() {
-                console.log('✅ Canary confirmed');
-            });
-
-            // STEP 2: Check for updates on YOUR server
-            fetch('https://your-api.com/updates/check?version=' + currentVersion)
-                .then(r => r.json())
-                .then(data => {
-                    if (data.hasUpdate) {
-                        // STEP 3: Download update
-                        window.HotUpdates.getUpdate({
-                            url: data.downloadURL,
-                            version: data.newVersion
-                        }, function(error) {
-                            if (error) {
-                                console.error('Download failed:', error.error.message);
-                                return;
-                            }
+    // CRITICAL: Confirm successful bundle load within 20 seconds
+    var currentVersion = localStorage.getItem('app_version') || '1.0.0';
+    window.hotUpdate.canary(currentVersion);
+
+    // Check for updates
+    checkForUpdates();
+}, false);
+
+function checkForUpdates() {
+    fetch('https://your-server.com/api/check-update?version=1.0.0')
+        .then(response => response.json())
+        .then(data => {
+            if (data.hasUpdate) {
+                downloadAndInstall(data.downloadUrl, data.version);
+            }
+        });
+}
 
-                            // STEP 4: Show popup
-                            if (confirm('Update to ' + data.newVersion + '?')) {
-                                // STEP 5: Install immediately
-                                window.HotUpdates.forceUpdate(function(error) {
-                                    if (error) {
-                                        console.error('Install failed:', error.error.message);
-                                    }
-                                    // WebView reloads automatically
-                                });
-                            }
-                            // If user cancels: update installs automatically on next launch
-                        });
-                    }
+function downloadAndInstall(url, version) {
+    window.hotUpdate.getUpdate({url: url, version: version}, function(error) {
+        if (!error) {
+            if (confirm('Update available. Install now?')) {
+                localStorage.setItem('app_version', version);
+                window.hotUpdate.forceUpdate(function(error) {
+                    // WebView will reload, canary() will be called in deviceready
                 });
-        },
-        function(error) {
-            console.error('Failed to get version:', error);
-        },
-        'HotUpdates',
-        'getVersionInfo',
-        []
-    );
+            }
+            // If user declines, update auto-installs on next launch
+        }
+    });
+}
+```
+
+## Error Handling
+
+All errors are returned in a unified format for programmatic handling:
+
+```javascript
+// Error format
+callback({
+  error: {
+    code: "ERROR_CODE",        // Code for programmatic handling
+    message: "Detailed message" // Detailed message for logs
+  }
+})
+
+// Success result
+callback(null)
+```
+
+### Error Codes
+
+#### getUpdate() errors:
+- `UPDATE_DATA_REQUIRED` - Missing updateData parameter
+- `URL_REQUIRED` - Missing url parameter
+- `DOWNLOAD_IN_PROGRESS` - Download already in progress
+- `DOWNLOAD_FAILED` - Network download error (message contains details)
+- `HTTP_ERROR` - HTTP status != 200 (message contains status code)
+- `TEMP_DIR_ERROR` - Error creating temporary directory
+- `EXTRACTION_FAILED` - Error extracting ZIP archive
+- `WWW_NOT_FOUND` - www folder not found in archive
+
+#### forceUpdate() errors:
+- `NO_UPDATE_READY` - getUpdate() not called first
+- `UPDATE_FILES_NOT_FOUND` - Downloaded update files not found
+- `INSTALL_FAILED` - Error copying files (message contains details)
+
+#### canary() errors:
+- `VERSION_REQUIRED` - Missing version parameter
+
+### Error Handling Example
+
+```javascript
+window.hotUpdate.getUpdate({url: 'http://...'}, function(error) {
+  if (error) {
+    console.error('[HotUpdates]', error.code, ':', error.message);
+
+    switch(error.code) {
+      case 'HTTP_ERROR':
+        // Handle HTTP errors
+        break;
+      case 'DOWNLOAD_FAILED':
+        // Handle network errors
+        break;
+      default:
+        console.error('Unknown error:', error);
+    }
+  } else {
+    console.log('Update downloaded successfully');
+  }
 });
 ```
 
-## 📚 API Reference
+## API Reference
+
+All API methods are available via `window.hotUpdate` after the `deviceready` event.
+
+### window.hotUpdate.getUpdate(options, callback)
 
-### Core Methods (v2.1.0)
+Downloads update from server.
 
-#### 1. `getUpdate({url, version?}, callback)`
+Downloads ZIP from provided URL and saves to two locations:
+- `temp_downloaded_update` (for immediate installation via `forceUpdate()`)
+- `pending_update` (for auto-installation on next app launch)
 
-Downloads update in background. **Does NOT install!**
+If version already downloaded, returns success without re-downloading.
 
+**Does NOT check ignoreList** - JavaScript controls all installation decisions.
+
+**Parameters:**
+- `options` (Object):
+  - `url` (string, required) - URL to download ZIP archive
+  - `version` (string, optional) - Version string
+- `callback` (Function) - `callback(error)`
+  - `null` on success
+  - `{error: {message?: string}}` on error
+
+**Example:**
 ```javascript
-window.HotUpdates.getUpdate({
-    url: 'https://server.com/updates/2.7.8.zip',
-    version: '2.7.8'  // Optional
+window.hotUpdate.getUpdate({
+    url: 'https://your-server.com/updates/2.0.0.zip',
+    version: '2.0.0'
 }, function(error) {
     if (error) {
-        console.error('Download failed:', error.error.message);
+        console.error('Download failed:', error);
     } else {
-        console.log('✅ Download complete');
+        console.log('Update downloaded successfully');
     }
 });
 ```
 
-**Features:**
-- Returns success if version already installed (won't re-download)
-- Saves to two locations: immediate install + auto-install on next launch
-- Callback format: `null` on success, `{error: {message}}` on error
+---
+
+### window.hotUpdate.forceUpdate(callback)
+
+Installs downloaded update immediately and reloads WebView.
+
+**Process:**
+1. Backup current version to `www_previous`
+2. Copy downloaded update to `Documents/www`
+3. Clear WebView cache (disk, memory, Service Worker)
+4. Reload WebView
+5. Start 20-second canary timer
+
+**IMPORTANT:** JavaScript MUST call `canary(version)` within 20 seconds after reload to confirm successful bundle load. Otherwise automatic rollback occurs.
 
-#### 2. `forceUpdate(callback)`
+**Does NOT check ignoreList** - JavaScript decides what to install.
 
-Installs downloaded update and reloads WebView. **No parameters needed!**
+**Parameters:**
+- `callback` (Function) - `callback(error)`
+  - `null` on success (before WebView reload)
+  - `{error: {message?: string}}` on error
 
+**Example:**
 ```javascript
-window.HotUpdates.forceUpdate(function(error) {
+window.hotUpdate.forceUpdate(function(error) {
     if (error) {
-        console.error('Install failed:', error.error.message);
+        console.error('Install failed:', error);
     } else {
-        console.log('✅ Installed, reloading...');
+        console.log('Update installing, WebView will reload...');
     }
 });
 ```
 
-**Important:**
-- Must call `getUpdate()` first
-- WebView reloads automatically after ~1 second
-- Call `canary()` after reload to confirm success
+---
+
+### window.hotUpdate.canary(version, callback)
+
+Confirms successful bundle load after update.
 
-#### 3. `canary(version, callback)`
+**MUST be called within 20 seconds** after `forceUpdate()` to stop canary timer and prevent automatic rollback.
 
-Confirms bundle loaded successfully. **REQUIRED on every app start!**
+**If not called within 20 seconds:**
+- Automatic rollback to previous version
+- Failed version added to ignoreList
+- WebView reloaded with previous version
 
+**Parameters:**
+- `version` (string) - Version that loaded successfully
+- `callback` (Function, optional) - Not used, method is synchronous
+
+**Example:**
 ```javascript
-window.HotUpdates.canary('2.7.8', function() {
-    console.log('✅ Canary confirmed');
-});
+document.addEventListener('deviceready', function() {
+    var version = localStorage.getItem('app_version') || '1.0.0';
+    window.hotUpdate.canary(version);
+}, false);
 ```
 
-**Critical:**
-- Must be called within 20 seconds after app start
-- If not called: automatic rollback to previous version
-- Failed version is added to ignore list
+---
+
+### window.hotUpdate.getIgnoreList(callback)
+
+Returns list of problematic versions (information only).
+
+**This is an INFORMATION-ONLY system** - native does NOT block installation. JavaScript should read this list and decide whether to skip these versions.
 
-#### 4. `getIgnoreList(callback)`
+Native automatically adds versions to this list when rollback occurs.
 
-Returns list of versions that caused problems.
+**Parameters:**
+- `callback` (Function) - `callback(result)`
+  - `result`: `{versions: string[]}` - Array of problematic version strings
 
+**Example:**
 ```javascript
-window.HotUpdates.getIgnoreList(function(result) {
-    const badVersions = result.versions; // ["2.7.5", "2.7.6"]
+window.hotUpdate.getIgnoreList(function(result) {
+    console.log('Problematic versions:', result.versions);
 
-    // Check before downloading
-    if (!badVersions.includes(newVersion)) {
-        // Safe to download
+    if (result.versions.includes(newVersion)) {
+        console.log('Skipping known problematic version');
     }
 });
 ```
 
-**Note:** IgnoreList is informational only - you decide whether to skip versions.
+---
 
-## 🖥️ Server Requirements
+## Complete Update Flow
 
-Your server should provide:
+```javascript
+// Step 1: Check for updates on your server
+function checkForUpdates() {
+    var currentVersion = localStorage.getItem('app_version') || '1.0.0';
+
+    fetch('https://your-server.com/api/check-update?version=' + currentVersion)
+        .then(response => response.json())
+        .then(data => {
+            if (data.hasUpdate) {
+                // Step 2: Check ignoreList
+                window.hotUpdate.getIgnoreList(function(ignoreList) {
+                    if (ignoreList.versions.includes(data.version)) {
+                        console.log('Skipping problematic version');
+                        return;
+                    }
+
+                    // Step 3: Download
+                    window.hotUpdate.getUpdate({
+                        url: data.downloadUrl,
+                        version: data.version
+                    }, function(error) {
+                        if (!error) {
+                            // Step 4: Prompt user
+                            if (confirm('Update available. Install now?')) {
+                                // Save version for canary check
+                                localStorage.setItem('app_version', data.version);
+
+                                // Step 5: Install
+                                window.hotUpdate.forceUpdate(function(error) {
+                                    // WebView will reload
+                                });
+                            }
+                            // If declined, auto-installs on next launch
+                        }
+                    });
+                });
+            }
+        });
+}
+
+// Step 6: After reload, confirm success
+document.addEventListener('deviceready', function() {
+    var version = localStorage.getItem('app_version') || '1.0.0';
+    window.hotUpdate.canary(version); // Must call within 20 seconds!
+
+    initApp();
+}, false);
+```
+
+## How It Works
+
+### Update Flow
 
-### Check Endpoint
+1. **Download** (`getUpdate()`):
+   - Downloads ZIP from URL
+   - Validates `www` folder structure
+   - Saves to TWO locations:
+     - `temp_downloaded_update` (for immediate install)
+     - `pending_update` (for auto-install on next launch)
 
-**GET** `/api/updates/check?version={current}&platform=ios`
+2. **Installation Options**:
+   - **Immediate**: User clicks "Update" → `forceUpdate()` installs now
+   - **Deferred**: User ignores → Auto-installs on next app launch
+
+3. **Rollback Protection**:
+   - Previous version backed up before installation
+   - 20-second canary timer starts after reload
+   - If `canary()` not called → automatic rollback
+   - Failed version added to ignoreList
+
+4. **IgnoreList System**:
+   - Native tracks failed versions
+   - JavaScript reads via `getIgnoreList()`
+   - **Does NOT block** - JS decides what to install
+
+### Storage Structure
+
+```
+Documents/
+├── www/                    // Active version
+├── www_previous/           // Previous version (rollback)
+├── pending_update/         // Next launch auto-install
+└── temp_downloaded_update/ // Immediate install
+```
 
-```json
+### Version Management
+
+- **appBundleVersion** - Native app version from Info.plist
+- **installedVersion** - Current hot update version
+- **previousVersion** - Last working version (rollback)
+
+## Update Server API
+
+Your server should provide:
+
+**Check API:**
+```
+GET https://your-server.com/api/check-update?version=1.0.0&platform=ios
+
+Response:
 {
   "hasUpdate": true,
-  "newVersion": "2.7.8",
-  "downloadURL": "https://server.com/updates/2.7.8.zip",
-  "minAppVersion": "2.7.0"
+  "version": "2.0.0",
+  "downloadUrl": "https://your-server.com/updates/2.0.0.zip",
+  "minAppVersion": "2.7.0",
+  "releaseNotes": "Bug fixes"
 }
 ```
 
-### Update Package
-
-ZIP file containing `www` folder:
-
+**Update ZIP Structure:**
 ```
 update.zip
 └── www/
@@ -205,105 +389,90 @@ update.zip
     └── ...
 ```
 
-## 🔧 How It Works
+## Best Practices
 
-### Two-Step Update Flow
+### 1. Always Call Canary
 
+```javascript
+document.addEventListener('deviceready', function() {
+    var version = localStorage.getItem('app_version');
+    window.hotUpdate.canary(version); // Within 20 seconds!
+}, false);
 ```
-1. JS checks YOUR server for updates
-2. getUpdate() downloads ZIP in background
-3. Show popup to user
-4. User clicks "Update": forceUpdate() installs immediately
-5. User ignores: update auto-installs on next app launch
-6. WebView reloads with new content
-7. JS calls canary() to confirm success
-```
-
-### Rollback Protection
-
-- 20-second canary timer starts after update
-- If `canary()` not called → automatic rollback
-- Failed version added to ignore list
-- App continues working on previous version
 
-### File Structure
+### 2. Check IgnoreList
 
+```javascript
+window.hotUpdate.getIgnoreList(function(result) {
+    if (result.versions.includes(newVersion)) {
+        console.log('Known problematic version');
+    }
+});
 ```
-Documents/
-├── www/                     # Active version
-├── www_previous/            # Backup (for rollback)
-├── pending_update/          # Next launch auto-install
-└── temp_downloaded_update/  # Immediate install
-```
-
-## 📖 Full Documentation
-
-- **[docs/README.md](docs/README.md)** - Quick start guide
-- **[docs/API.md](docs/API.md)** - Complete API reference
-- **[docs/hot-updates-admin.html](docs/hot-updates-admin.html)** - Testing interface
-- **[CHANGELOG.md](CHANGELOG.md)** - Version history
 
-## 🐛 Troubleshooting
+### 3. Handle Errors
 
-### Common Issues
-
-**Updates not working**
-- Check `canary()` is called on every app start
-- Verify server URL returns correct JSON
-- Check iOS device logs for errors
+```javascript
+window.hotUpdate.getUpdate(options, function(error) {
+    if (error) {
+        analytics.track('update_failed', {error: error.message});
+        showUserMessage('Update failed');
+    }
+});
+```
 
-**Duplicate downloads**
-- ✅ Fixed in v2.1.0! `getUpdate()` now checks installed version
+### 4. Store Version
 
-**WebView shows old content**
-- ✅ Fixed in v2.1.0! Cache is cleared before reload
+```javascript
+// Before forceUpdate
+localStorage.setItem('app_version', newVersion);
 
-**CocoaPods errors**
-```bash
-cd platforms/ios
-pod install
-cordova clean ios && cordova build ios
+// After reload
+var version = localStorage.getItem('app_version');
+window.hotUpdate.canary(version);
 ```
 
-### Debug Logs
-
-All plugin actions are logged with `[HotUpdates]` prefix:
+## Troubleshooting
 
-```bash
-# iOS Simulator
-cordova run ios --debug
-
-# iOS Device
-# Use Xcode console or Safari Web Inspector
-```
+### Update doesn't install
 
-## ⚠️ Important Notes
+- Check ZIP structure (must have `www/` folder)
+- Check URL accessibility
+- Check Xcode console: `[HotUpdates] ...`
 
-- **iOS Only**: Currently supports iOS platform only
-- **Manual Updates Only**: No automatic background checking (you control everything)
-- **App Store Compliance**: Only update web content, not native code
-- **HTTPS Required**: Update server should use HTTPS in production
-- **Testing**: Test rollback mechanism thoroughly
+### Automatic rollback
 
-## 🤝 Contributing
+**Cause:** `canary()` not called within 20 seconds
 
-Contributions are welcome! Please submit a Pull Request.
+**Solution:** Call immediately in `deviceready`:
+```javascript
+document.addEventListener('deviceready', function() {
+    window.hotUpdate.canary(version); // First thing!
+}, false);
+```
 
-## 📝 License
+### window.hotUpdate is undefined
 
-This project is licensed under the Custom Non-Commercial License - see the [LICENSE](LICENSE) file for details.
+**Cause:** Called before `deviceready`
 
-**⚠️ Commercial use is strictly prohibited without explicit written permission from the copyright holder.**
+**Solution:**
+```javascript
+document.addEventListener('deviceready', function() {
+    console.log(window.hotUpdate); // Now available
+}, false);
+```
 
-For commercial licensing inquiries, please contact: **Mustafin Vladimir** <outvova.gor@gmail.com>
+## License
 
-## 🙋‍♂️ Support
+Custom Non-Commercial License - See [LICENSE](LICENSE) file
 
-- **Issues**: [GitHub Issues](https://github.com/vladimirDarksy/Cordova_hot_update/issues)
-- **npm**: [cordova-plugin-hot-updates](https://www.npmjs.com/package/cordova-plugin-hot-updates)
+## Author
 
----
+**Mustafin Vladimir**
+- GitHub: [@vladimirDarksy](https://github.com/vladimirDarksy)
+- Email: outvova.gor@gmail.com
 
-**Made with ❤️ by [Mustafin Vladimir](https://github.com/vladimirDarksy)**
+## Support
 
-**Version:** 2.1.0 | **Last Updated:** 2025-11-04
+- Issues: https://github.com/vladimirDarksy/Cordova_hot_update/issues
+- Repository: https://github.com/vladimirDarksy/Cordova_hot_update