Skip to content

Announcing the Capacitor Live Update Plugin

One of the biggest advantages of Capacitor over other runtimes is the ability to deliver updates in real-time without having to resubmit your app to the app stores, so-called Over-the-Air (OTA) updates. For this reason, we are very excited to introduce you today to our brand new Capacitor Live Update plugin. In this blog post, you will learn everything about the new plugin and how you can implement it in your Capacitor app.

Deprecated

This guide is deprecated. Please refer to the Getting Started guide for the most up-to-date instructions and best practices.

How it works

Live updates are a powerful feature that allows you to deliver small bug fixes and updates to your Capacitor app in real-time. For this, it is important to understand the different layers of a Capacitor app and how they interact with each other.

Layers Layers

Capacitor App Layers

As you can see in the image above, a Capacitor app basically consists of a web layer and a native layer. The web layer consists of the HTML, CSS, and JavaScript files that are loaded into the web view. The native layer consists of the native code that is compiled into the app.

Limitation

Live updates only allow you to update the web layer of your app.

So as long as you only make changes to your web application, you can deploy live updates without having to resubmit your app to the app stores. As soon as you make a change to the native code, such as adding a plugin, you must resubmit your app to the app stores.

Installation

First you need to install the package and sync your Capacitor project:

npm install @capawesome/capacitor-live-update
npx cap sync

Usage

To distribute live updates to your users, we recommend using Capawesome Cloud. Capawesome Cloud provides a complete solution for managing and distributing your bundles with advanced features like Channels, Rollouts, and Analytics.

Getting Started with Capawesome Cloud

Getting Started Guide

For the most up-to-date instructions and best practices, check out our comprehensive Getting Started guide. It includes the latest features like automatic update strategies and streamlined setup steps.

To get started, you need to create an account on the Capawesome Cloud Console.

After you have created an account, we recommend that you install the Capawesome CLI to manage your apps and bundles from the command line.

npm install -g @capawesome/cli

First, you need to log in to Capawesome Cloud:

npx @capawesome/cli login

Then you can create a new app:

npx @capawesome/cli apps:create --name "My App"

After you have created an app, you need to configure the Capacitor Live Update plugin. To do this, simply add the ID of the app you have just created to the Capacitor configuration file:

capacitor.config.json
{
  "plugins": {
    "LiveUpdate": {
      "appId": "00000000-0000-0000-0000-000000000000"
    }
  }
}

Sync your Capacitor project to apply the changes:

npx cap sync

Next, you can upload a new bundle to the Capawesome Cloud. For this, you simply need to specify the path to the bundle (e.g. www or dist) and the ID of the app (see previous step):

npx @capawesome/cli apps:liveupdates:upload --app-id <app-id> --path www
Upload to a channel

We recommend that you also specify a Channel when uploading the bundle:

npx @capawesome/cli apps:liveupdates:upload --app-id <app-id> --path www --channel production-1.0.0

This way you can easily restrict live updates to native versions of your app and prevent incompatible updates.

The Capawesome CLI then automatically creates a zip archive of the bundle and uploads it to the Capawesome Cloud where it becomes immediately available for download.

All that's left to do is to call the sync() method in your app to check for new updates and apply them if necessary.

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

const sync = async () => {
    const result = await LiveUpdate.sync();
    if (result.nextBundleId) {
        await LiveUpdate.reload();
    }
};

The new bundle becomes available only after restarting the app. Therefore, if you want to apply the new bundle immediately, you should call the reload() method to reload the web view.

Again, make sure to call the ready() method as soon as the the app is ready to prevent a rollback:

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

const ready = async () => {
    await LiveUpdate.ready();
};

Testing

When testing the plugin, you must make sure that you do not use the Live Reload option, as in this case a development server is used to load the bundle.

Therefore, simply start your app without the live reload option, for example with the following command:

npx cap run android

As soon as you have installed a live update, the app will use the live update bundle and no longer the default bundle. So if you make local changes to your app and execute npx cap run, for example, these changes will apply to the default bundle, which is not currently in use. You then have three options to get back to the default bundle:

  1. Reset: Call the reset() method to reset the app to the default bundle.
  2. Reinstall: Reinstall the app to use the default bundle.
  3. Update: Increase the versionCode/CFBundleVersion so that the plugin automatically performs a reset.

However, this is only a problem during development. It is not a problem in production, as the versionCode/CFBundleVersion is always incremented during a native update and the plugin automatically resets to the default bundle.

Closing Thoughts

We hope you are as excited as we are about the new Capacitor Live Update plugin. We are already working on new features and improvements, such as automatic update modes and partial updates. Be sure to check out the API Reference to see what else you can do with this plugin. If you have any questions, just create a discussion in the GitHub repository. Make sure you follow us on X so you don't miss any future updates.