capacitor-simtocare-updater

Barebones Capacitor plugin for live updates on iOS. Download bundled www zips from your server and deploy them with reload and rollback functionality.

Install

npm install capacitor-simtocare-updater
npx cap sync

Usage

1. Download a Bundle

Download a zip file containing your web assets from your server:

import { Updater } from 'capacitor-simtocare-updater';

await Updater.downloadBundle({
  url: 'https://your-server.com/bundles/v1.2.3.zip',
  bundleId: 'v1.2.3',
  checksum: 'abc123def456...' // Optional MD5 checksum for verification
});

2. Set Next Bundle and Reload

Set which bundle should be loaded on the next reload:

await Updater.setNextBundle({ bundleId: 'v1.2.3' });
await Updater.reload(); // Recreates view controller and loads new bundle

Note: reload() recreates the app's view controller with a smooth transition. The new bundle loads automatically. Works seamlessly in Single App Mode / Kiosk Mode.

3. Confirm the Update Works

IMPORTANT: After reloading with a new bundle, you MUST call notifyReady() within 30 seconds to confirm the app is working correctly. If you don't call this, the app will automatically rollback to the previous bundle.

// Call this after your app has loaded and verified everything works
await Updater.notifyReady();

4. Manual Rollback

If something goes wrong, you can manually rollback:

await Updater.rollback();

5. Get Current Bundle

Check which bundle is currently active:

const { bundleId } = await Updater.getCurrentBundle();
console.log('Current bundle:', bundleId); // null means native bundle

Complete Example

import { Updater } from 'capacitor-simtocare-updater';

async function updateApp() {
  try {
    // 1. Download the new bundle
    console.log('Downloading update...');
    await Updater.downloadBundle({
      url: 'https://your-server.com/bundles/v1.2.3.zip',
      bundleId: 'v1.2.3',
      checksum: 'abc123def456...' // Optional MD5 checksum for verification
    });
    
    // 2. Set it as the next bundle to load
    await Updater.setNextBundle({ bundleId: 'v1.2.3' });
    
    // 3. Reload the app
    console.log('Reloading with new bundle...');
    await Updater.reload();
    
  } catch (error) {
    console.error('Update failed:', error);
  }
}

// After app loads with new bundle:
async function confirmUpdate() {
  try {
    const { bundleId } = await Updater.getCurrentBundle();
    
    if (bundleId) {
      // We're running a downloaded bundle
      console.log('Running bundle:', bundleId);
      
      // Verify app is working (check critical features)
      const isWorking = await verifyAppFeatures();
      
      if (isWorking) {
        // Confirm the update is good
        await Updater.notifyReady();
        console.log('Update confirmed!');
      } else {
        // Something's wrong, rollback
        console.log('App not working correctly, rolling back...');
        await Updater.rollback();
      }
    }
  } catch (error) {
    console.error('Error confirming update:', error);
  }
}

async function verifyAppFeatures(): Promise<boolean> {
  // Add your app-specific checks here
  // Return true if everything works, false otherwise
  return true;
}

Bundle Structure

Your zip file should contain the built web assets (typically from www or dist folder):

bundle.zip
├── index.html
├── css/
│   └── app.css
├── js/
│   └── app.js
└── assets/
    └── ...

How It Works

1. Download: Bundles are downloaded to Library/NoCloud/ionic_built_snapshots/{bundleId}/
2. Next Bundle: When you set a next bundle and reload, it becomes the current bundle
3. Rollback Timer: After loading a new bundle, you have 30 seconds to call notifyReady()
4. Auto Rollback: If notifyReady() isn't called within 30 seconds, the app automatically rolls back
5. Manual Rollback: You can also manually rollback if you detect issues

API

downloadBundle(options: { url: string; bundleId: string; checksum?: string })

Download a bundle zip file from a URL.

• url: Full URL to the zip file
• bundleId: Unique identifier for this bundle (e.g., version number)
• checksum (optional): MD5 checksum for verification. If provided, the downloaded file will be verified against this checksum

setNextBundle(options: { bundleId: string })

Set which bundle should be loaded on next reload.

• bundleId: The bundle ID to load next

getCurrentBundle()

Get the currently active bundle ID.

Returns: { bundleId: string | null } - null means using native bundle

reload()

Reload the app with the next bundle (if set).

How it works: Recreates the root view controller to force Capacitor re-initialization. The app stays running and automatically loads from the new bundle path. Works seamlessly in Single App Mode / Kiosk Mode.

Note: There's a brief 0.3s cross-dissolve transition as the new bundle loads.

rollback()

Rollback to the previous bundle (or native bundle if no previous).

notifyReady()

Confirm the current bundle is working correctly. This stops the auto-rollback timer.

IMPORTANT: Must be called within 30 seconds of loading a new bundle.

Notes

• Only works on iOS (web version throws "not implemented" errors)
• Bundles are stored in Library/NoCloud to exclude them from iCloud backup
• The native bundle is used when no downloaded bundles are active
• Always call notifyReady() after loading a new bundle to prevent auto-rollback

License

MIT