Skip to content

Getting Started

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

Prerequisites

Before you begin, ensure you have:

Step 1: Create an App

In order for your app to identify itself to Capawesome Cloud, you must first create an app in Capawesome Cloud. If you have already created an app, you can skip this step and proceed to Step 2.

To create an app using the Capawesome CLI, use the apps:create command:

npx @capawesome/cli apps:create

You will be prompted to select the organization you want to create the app in and to provide a name for the app. The CLI will then create the app and display the app ID.

To create an app using the Capawesome Cloud Console, select the organization you want to create the app in and click on the "Create App" button.

Provide a name for the app and click on the "Create" button.

Make sure to copy the app ID, as you will need it in the next step.

Step 2: Install SDK

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

npm install @capawesome/capacitor-live-update@^7.3.0

Next, configure the plugin by pasting the app ID from Step 1 and setting the autoUpdateStrategy option to background in the Capacitor configuration file of your project:

capacitor.config.ts
import { CapacitorConfig } from "@capacitor/cli";

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

export default config;
capacitor.config.json
{
  "plugins": {
    "LiveUpdate": {
      "appId": "00000000-0000-0000-0000-000000000000",
      "autoUpdateStrategy": "background"
    }
  }
}

The autoUpdateStrategy option set to background is the simplest and most effective way to keep your users up to date. It automatically checks for updates at app startup and when the app resumes, downloads them in the background, and applies them on the next app launch—all without requiring any additional code or user interaction. This makes it the perfect default choice for most applications. See Update Strategies for more information on alternative strategies.

Finally, sync your Capacitor project using the Capacitor CLI to register the plugin and apply the configuration:

npx cap sync

Step 3: Publish First Update

To publish your first live update, you need to deploy a build to a live update channel in Capawesome Cloud. This can be done easily using the Capawesome CLI.

First, build the web assets of your Capacitor app:

npm run build

Then, upload those web assets as a live update bundle to Capawesome Cloud using the following command:

npx @capawesome/cli apps:liveupdates:upload

This command will ask you to enter the path to your web assets directory (e.g., www or dist) and the app you want to upload the bundle to. After the upload is complete, the bundle will be instantly available to your users. Navigate to the Deployments page in the Capawesome Cloud Console to see the details of your deployment.

Force Update Check

When using an autoUpdateStrategy, updates are only checked on app resume if the last check was more than 15 minutes ago. To force a live update check during development, force-close your app and restart it.

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

Step 4: Test Your Setup

To verify that everything is working correctly, you can make a small change to your web assets (e.g., change some text in your HTML or CSS files), build the web assets again, and upload a new live update bundle using the same command as before:

npx @capawesome/cli apps:liveupdates:upload

After uploading the new bundle, force-close your app and restart it. Since you have set the autoUpdateStrategy to background, the app should automatically download and apply the new bundle in the background. Wait around 15-30 seconds, then restart the app again to see the changes take effect.

If you prefer to get a notification when an update is ready, you can extend your setup by implementing the Always Latest update strategy.

Debugging

The Live Update SDK provides useful debugging information in Android's Logcat and iOS's Xcode console. If you encounter any issues during testing, check the logs for more details.

Next Steps

Now that you have Live Updates set up, explore the following guides to make the most out of it.

  • Best Practices

    Learn about best practices for using Capawesome Cloud Live Updates in your Capacitor app.

    Learn More

  • Advanced Usage

    Learn about advanced features and how to customize the Live Update plugin to your needs.

    Learn More