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 to manage your live updates.

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:

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

Let's take a look at how to use the Live Update plugin in your app. The plugin provides several methods to check for updates, download them, and apply them to your app. The most common use case is to check for updates when the app starts, download them, and ask the user if they want to apply the update immediately or on the next app start.

Basic usage

The most basic usage of the Live Update plugin is to call the sync() method when the app starts. This method checks for updates, downloads them if available, and sets them as the next bundle to be applied. You can then call the reload() method to apply the update immediately. If the reload(...) method is not called, the new bundle will be used on the next app start.

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

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

Advanced usage

If you want more control over the update process, you can use the following methods:

1. fetchLatestBundle(): Check for updates without downloading them.
2. downloadBundle(): Download updates without applying them.
3. setNextBundle(): Set a new bundle as the next bundle to be applied.
4. reload(): Apply the new bundle immediately.

Check for updates

You can check for new bundles without downloading them by using the fetchLatestBundle() method:

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

const checkForUpdates = async () => {
  const result = await LiveUpdate.fetchLatestBundle();
  if (result.bundleId) {
    console.log("New update available: " + result.downloadUrl);
  } else {
    console.log("No update available");
  }
};

This method returns all important information about the latest bundle, including the bundle ID and the download URL.

Download updates

You can then download bundles by using the downloadBundle() method:

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

const downloadUpdate = async (bundleId: string, url: string) => {
  await LiveUpdate.downloadBundle({
    bundleId,
  });
};

This method downloads the bundle, extracts the files, and moves them to the correct location in your app.

Apply updates

You can set a new bundle as the next bundle to be applied by using the setNextBundle() method:

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

const setNextBundle = async (bundleId: string) => {
  await LiveUpdate.setNextBundle({
    bundleId,
  });
};

If the bundle should be applied immediately, you can also call the reload() method:

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

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

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. 🎉