Capacitor Updater

Capacitor Updater is a plugin that allows you to update your Capacitor application remotely in real-time. It serves as an open-source alternative to services like Appflow or CodePush, enabling you to push JavaScript, HTML, and CSS updates directly to users without waiting for App Store or Play Store review processes.

Key capabilities include:

• Instant Updates: Push web assets immediately.
• Delta Updates: Download only changed files to minimize data usage.
• Rollback Protection: Automatically revert to a stable bundle if an update fails.
• Channel Management: Use different channels (e.g., staging, production) to manage environments or target specific devices for QA.
• Security: Updates are encrypted and signed.
• Deployment Modes: You can use the managed capgo.app cloud, host your own backend, or use manual methods (zipping/uploading files via JS).

To automate the splashscreen lifecycle during updates, use the autoSplashscreen and autoSplashscreenLoader options. This is specifically for Android and iOS.

Requirements

1. @capacitor/splash-screen plugin: Must be installed.
2. Configuration: The splashscreen plugin must be configured with launchAutoHide: false.
3. Update Mode: autoUpdate must be set to atInstall, always, or onLaunch (or the deprecated directUpdate must be set to atInstall, always, onLaunch, or true).

Options

• autoSplashscreen: When true, the plugin automatically calls SplashScreen.hide() after updates are applied or if no update is needed. This removes the need to manually listen for appReady events.
• autoSplashscreenLoader: When true (and autoSplashscreen is enabled), a native loading indicator is displayed on top of the splashscreen while automatic direct updates are running.

The plugin provides a suite of methods to manage local preview bundles, enabling an Expo Go-style development flow. You can start a session, list available previews, switch between them, and manage their lifecycle.

Key Workflow:

1. Use notifyAppReady to prepare the session state before calling set.
2. Use listPreviews to see what is available.
3. Use setPreview to switch to a specific bundle (this saves the current live bundle as a fallback).
4. Use resetPreview to return to the original live bundle.
5. Use deletePreview to remove a specific preview bundle from local storage.

// Example workflow for managing previews
await CapacitorUpdater.notifyAppReady({ /* options */ });
const previews = await CapacitorUpdater.listPreviews();

// Switch to a specific preview
await CapacitorUpdater.setPreview({ id: 'some-preview-id' });

// Return to the live app
await CapacitorUpdater.resetPreview();

Flexible updates follow a specific lifecycle on Android to ensure a smooth user experience without interrupting tasks:

1. Initiation: Call startFlexibleUpdate() to begin the background download.
2. Monitoring: Listen to the onFlexibleUpdateStateChange event to track progress.
3. Completion of Download: When the event status is DOWNLOADED, the update is ready but not yet installed.
4. User Prompt: Notify the user that the update is ready and ask for permission to restart.
5. Installation: Call completeFlexibleUpdate() to finalize the installation and trigger the app restart.

This pattern is ideal for non-critical updates where you want to minimize user disruption.

// Conceptual flow for flexible updates

// 1. Start
await CapacitorUpdater.startFlexibleUpdate();

// 2. Listen (pseudo-code for the listener pattern)
CapacitorUpdater.addListener('onFlexibleUpdateStateChange', (state) => {
  if (state.status === 'DOWNLOADED') {
    // 3. Prompt user
    showRestartPrompt().then(async () => {
      // 4. Complete
      await CapacitorUpdater.completeFlexibleUpdate();
    });
  }
});

Capacitor Updater is designed to be compliant with Google Play and Apple App Store guidelines regarding Over-the-Air (OTA) updates.

Google Play

Updating JavaScript bundles is permitted under the Device and Network Abuse policy because JavaScript runs in a virtual machine (WebView) and does not update native code or bypass Android API restrictions.

App Store

Apple allows OTA updates of JavaScript and assets per Section 3.3.2 of the License Agreement, provided the update:

• Does not change the primary purpose of the application.
• Does not create a storefront for other code/apps.
• Does not bypass OS security features.

Recommendation: To remain fully compliant with App Store Review Guidelines, avoid implementing a 'Force Update' scenario that prevents users from accessing functionality, as this can be interpreted as forcing users to perform specific actions to use the app.