Update Strategies

There are several ways to implement over-the-air (OTA) updates in your Capacitor app using Capawesome Cloud Live Updates. Each strategy serves different use cases and user experience requirements.

Background

The most basic implementation automatically checks for updates in the background. Simply set the autoUpdateStrategy configuration option to background in your Capacitor configuration file:

capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      autoUpdateStrategy: 'background',
      defaultChannel: 'production-5' // Optional
    }
  }
};

export default config;

This automatically checks for the latest bundle at app startup and when the app resumes (if the last check was more than 15 minutes ago), downloads it in the background, and applies it on the next app launch. You can optionally use the defaultChannel option to specify which channel to pull updates from. This is equivalent to calling the sync() method manually on app start and resume, but without needing to write any code. It's the easiest way to ensure your users receive updates without any interruptions.

Info

The autoUpdateStrategy configuration option was introduced in version 7.3.0 of the Capacitor Live Update plugin. Make sure to update to the latest version to take advantage of this feature.

Always Latest

If you want to ensure that your users always have the latest version immediately, you can combine the background update strategy with the nextBundleSet event listener to prompt users to apply updates as soon as they're downloaded.

First, enable the background update strategy by setting autoUpdateStrategy to background in your Capacitor configuration file (see Background section). Then, add the nextBundleSet listener:

import { LiveUpdate } from "@capawesome/capacitor-live-update";

const initializeApp = async () => {
  LiveUpdate.addListener('nextBundleSet', async () => {
    const shouldReload = confirm('A new update is available. Would you like to install it now?');
    if (shouldReload) {
      // Reload the webview to apply the update immediately
      await LiveUpdate.reload();
    }
  });
};

The nextBundleSet event fires whenever a new bundle is downloaded and set as the next bundle, allowing you to provide users with the option to apply updates without restarting the app.

Info

The autoUpdateStrategy configuration option was introduced in version 7.3.0 of the Capacitor Live Update plugin. Make sure to update to the latest version to take advantage of this feature.

Force Update

If you need to ensure that users are always on the latest version when they open the app, you can implement a strategy that forces an update check and reloads the app if a new version is available before the splash screen is hidden.

For this approach, you first need to configure the splash screen to not auto-hide using the Capacitor Configuration file:

TypeScriptJSON

capacitor.config.ts

import { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  plugins: {
    SplashScreen: {
      launchAutoHide: false
    }
  }
};

export default config;

capacitor.config.json

{
  "plugins": {
    "SplashScreen": {
      "launchAutoHide": false
    }
  }
}

Then you can implement the force update strategy as follows:

import { SplashScreen } from '@capacitor/splash-screen';
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const initializeApp = async () => {
  const { nextBundleId } = await LiveUpdate.sync();
  if (nextBundleId) {
    // Reload the webview to apply the update immediately
    await LiveUpdate.reload();
  } else {
    // No update available, hide the splash screen
    await SplashScreen.hide();
  }
};

This initializeApp function should be called once at app startup. It checks for updates and applies them immediately if available. If no updates are found, it hides the splash screen. This ensures that users always have the latest version of the app before they start using it.

However, keep in mind that forcing updates in this way may lead to a poor user experience since users will have to wait for the update to download and apply before they can interact with the app. This can be a real problem if the update is large or the user's internet connection is slow. It's essential to balance the need for updates with the overall user experience.

Instant

For critical updates that need to be delivered immediately, you can use silent push notifications to trigger updates while users are actively using the app. Silent push notifications deliver data directly to the app without displaying a notification, so no permissions are required.

Here's an example implementation using the Capacitor Firebase Cloud Messaging plugin:

import { FirebaseMessaging } from '@capacitor-firebase/messaging';
import { LiveUpdate } from '@capawesome/capacitor-live-update';

const initializeApp = async () => {
  FirebaseMessaging.addListener('notificationReceived', async (notification) => {
    if (notification.data?.type === 'live-update') {
      const { nextBundleId } = await LiveUpdate.sync();
      if (nextBundleId) {
        const shouldReload = confirm('A critical update is available. Would you like to install it now?');
        if (shouldReload) {
          // Reload the webview to apply the update immediately
          await LiveUpdate.reload();
        }
      } else {
        // Update already installed or no update available
      }
    }
  });
};

This strategy requires a push notification service and backend infrastructure to send notifications when new bundles are deployed. This approach is also beneficial if you want to minimize connections to Capawesome Cloud, which can save battery and bandwidth.