Skip to content

Best Practices

Here are some best practices to follow when using the Live Update SDK to ensure a smooth user experience:

Automatic Rollbacks

We strongly recommend enabling automatic rollbacks to ensure that your users can always revert to a previous version of your app if an update fails or does not work as expected. For more information, check out the Rollbacks guide.

Binary Compatible Changes

It is important to make sure that only Binary Compatible Changes are delivered to your users to prevent incompatible updates.

Capawesome Cloud offers two different ways to restrict live updates to specific native versions:

Versioned Bundles

Versioned bundles allow you to restrict live updates to specific native versions by defining a range of version codes for each platform.

Version Code

The version code (named versionCode on Android and CFBundleVersion on iOS) is the internal version number of your app. It is used to determine whether one version is more recent than another and must be incremented each time you release a new version of your app.

To create a versioned bundle, you only need to specify the minimum and maximum version codes for each platform:

  • Minimum Version: The native binary must have at least this version code to be compatible with the bundle.
  • Maximum Version: The native binary must have at most this version code to be compatible with the bundle.
  • Equivalent: If the native binary has this exact version code, do NOT download the bundle, because they are equal.

To set the version code restrictions when uploading a live update using the Capawesome CLI, use the --android-min, --android-max, --android-eq, --ios-min, --ios-max, and --ios-eq options:

npx @capawesome/cli apps:liveupdates:upload --android-min 10 --android-max 12 --android-eq 11 --ios-min 10 --ios-max 12 --ios-eq 11

In this example, we restrict the bundle to Android version codes 10 to 12 (excluding 11) and iOS version codes 10 to 12 (excluding 11).

To set the version code restrictions using the Capawesome Cloud Console, navigate to the app you want to restrict the bundle for, and click on the Builds menu item in the sidebar. Next, create a new build or select an existing build. On the build details page, click on the "Settings" tab and set the version code restrictions in the "Versioning" section.

Versioned Bundle

Versioned Channels

Versioned channels allow you to restrict live updates to specific native versions by creating a channel for each version code. This is the recommended approach, as it leaves less room for mistakes and makes bundles easier to manage. Channels also offer advanced features such as bundle limits.

To create a versioned channel, you can use the following Capawesome CLI command:

npx @capawesome/cli apps:channels:create --name production-10

In this example, we created a channel named production-10 for the version code 10.

To upload a bundle to a specific channel, you can use the following Capawesome CLI command:

npx @capawesome/cli apps:liveupdates:upload --channel production-10

Finally, we just need to set the correct channel in the app to ensure that only compatible bundles are downloaded:

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

const sync = async () => {
  // Get the version code of the native app
  const { versionCode } = await LiveUpdate.getVersionCode();
  // Automatically download and set the latest compatible bundle
  await LiveUpdate.sync({ channel: `production-${versionCode}` });
};

Code Signing

We strongly recommend signing your app bundles to ensure their integrity and authenticity. This way, you can be sure that the bundles have not been tampered with and are coming from a trusted source. For more information, check out the Code Signing guide.

Reasonable Update Checks

While it's important to keep your app up-to-date, checking for updates too frequently can lead to a poor user experience. Not only does the device get rate-limited after a certain number of requests, but these requests also use up a lot of the device's resources like battery and data.

The simplest and most effective way to handle update checks is to use the autoUpdateStrategy configuration option. This automatically checks for updates at app startup and when the app resumes (with a minimum 15-minute interval between checks), which provides a perfect balance between keeping your app up-to-date and preserving device resources.

If you choose to implement manual update checks, you should definitely NOT (!!!) check for updates in fixed intervals:

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

// Do NOT do this!!!
setTimeout(() => {
  LiveUpdate.checkForUpdate();
}, 60000);

This approach can quickly lead to organizational rate-limiting and drains the device's battery and data.

For manual implementation examples, check out the Update Strategies guide.