Skip to content

Getting Started

In this guide, you will learn how to set up Capawesome Cloud Live Updates in your Capacitor 6 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@^6.0.0

Next, configure the plugin by pasting the app ID from Step 1 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",
    },
  },
};

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

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

npx cap sync

Since Capacitor 6 does not support automatic update strategies, you need to manually implement the update logic using the sync(...) method. Here's 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 code checks for updates every time the app resumes from the background. If an update is available, it prompts the user to install it immediately.

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.

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, restart your app on a device or emulator. When the app resumes, it should check for updates, prompt you to install the new update, and apply it if you confirm.

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