Getting Started¶

In this guide, you will learn how to set up Capawesome Cloud Live Updates in your Capacitor app.

Preparation¶

First, create an account on the Capawesome Cloud Console and set up your organization.

Installation¶

Within your Capacitor app project, install the Capacitor Live Update plugin:

npm install @capawesome/capacitor-live-update

Sync your Capacitor project to register the plugin:

npx cap sync

Configuration¶

Next, you need to configure the plugin to work with Capawesome Cloud.

App ID¶

In order for your app to identify itself to Capawesome Cloud, you must configure an app ID. For this, you need to create an app on the Capawesome Cloud Console:

The app ID can then be copied via the item menu. Paste the app ID into the Capacitor configuration file of your project:

TypeScriptJSON

capacitor.config.ts

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

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: "00000000-0000-0000-0000-000000000000"
    }
  }
};

export default config;

capacitor.config.json

{
  "plugins": {
    "LiveUpdate": {
      "appId": "00000000-0000-0000-0000-000000000000"
    }
  }
}

After configuring the app ID, sync your Capacitor project to apply the changes:

npx cap sync

Usage¶

The most basic usage of the Live Update plugin is to just call the sync() method. This method checks for updates, downloads them if available, and applies them on the next app start. If you want to apply the update immediately, you can also call the reload() method. Here is an example using the Always Latest update strategy:

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

App.addListener("resume", async () => {
  const { nextBundleId } = await LiveUpdate.sync();
  if (nextBundleId) {
    // Ask the user if they want to apply the update immediately
    const shouldReload = confirm("A new update is available. Would you like to install it?");
    if (shouldReload) {
      await LiveUpdate.reload();
    }
  }
});

This approach will check for updates every time the app is resumed using the App plugin. If an update is available, the user will be prompted to install it.

Feel free to also check out the other Update Strategies and make sure to take a look at the Best Practices guide.

Congratulations! You have successfully set up Capawesome Cloud Live Updates in your Capacitor app. 🎉

Publishing an update¶

To publish your first update, you need to create a bundle on Capawesome Cloud. For this, you need a bundle artifact. A bundle artifact is the build output of your web app. In most projects, you can create a web build with the following command:

npm run build

This should create a dist or www folder with the updated files that you want to replace in your native app. You can then upload those files using the Capawesome CLI. First, install the CLI:

npm install -g @capawesome/cli@latest

Then, create a new bundle with the following command:

npx @capawesome/cli apps:bundles:create

This will create a new bundle on Capawesome Cloud which is now available as a live update for your app. The next time your app calls the sync() method, it will download and apply the new bundle.

Congratulations! You have successfully set up Capawesome Cloud Live Updates in your Capacitor app. 🎉