--- title: Getting Started with Live Updates description: Set up Capawesome Cloud Live Updates in your Capacitor or Cordova app. Install the SDK, configure updates, and ship over-the-air updates in minutes. --- # Getting Started In this guide, you will set up Capawesome Cloud Live Updates in your app and ship your first over-the-air update. The Live Update SDK is available for both **Capacitor** and **Cordova** with full API parity — use the runtime tabs throughout this guide to follow along with your framework. !!! tip "Prefer to learn from a working example?" Clone a ready-to-run demo app with Live Updates already wired up: - [Capacitor Live Update demo](https://github.com/capawesome-team/capacitor-live-update-demo){:target="_blank"} - [Cordova Live Update demo](https://github.com/capawesome-team/cordova-live-update-demo){:target="_blank"} ## Prerequisites Before you begin, ensure you have: - A [Capawesome Cloud](https://console.cloud.capawesome.io){:target="_blank"} account and organization. - A Capacitor or Cordova app project on your local machine. - The latest version of the [Capawesome CLI](../cli/index.md) installed and [authenticated](../cli/authentication.md). ## AI-Assisted Setup (Recommended) The fastest way to get started is with an AI coding assistant. First, add the [Capawesome skills](https://github.com/capawesome-team/skills){:target="_blank"} to your project: ```bash npx skills add capawesome-team/skills --skill capawesome-cloud ``` Then use the following prompt in your preferred AI tool (e.g. [Claude Code](https://www.anthropic.com/claude-code){:target="_blank"}, [Cursor](https://www.cursor.com/){:target="_blank"}, or [GitHub Copilot](https://github.com/features/copilot){:target="_blank"}): ``` Use the `capawesome-cloud` skill from `capawesome-team/skills` to help me set up Live Updates in my project. ``` The assistant will create an app in Capawesome Cloud, install and configure the SDK, publish your first update, and verify that everything works. Once complete, continue with [Next Steps](#next-steps). ## Manual Setup If you prefer to set things up manually, follow the steps below. ### Step 1: Create an App To identify your app to Capawesome Cloud, first create an app. If you already have one, **skip to Step 2**. === "CLI" Use the [`apps:create`](../cli/commands.md#appscreate) command: ```bash npx @capawesome/cli apps:create ``` You will be prompted to select an organization and provide a name. The CLI then creates the app and prints the app ID. === "Console" Open the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/apps){:target="_blank"}, select your organization, and click **Create app**. Provide a name and click **Create**. Copy the app ID — you will need it in the next step. ### Step 2: Install the SDK Install the Live Update SDK in your project. === "Capacitor" ```bash npm install @capawesome/capacitor-live-update npx cap sync ``` !!! note "Older Capacitor versions" For **Capacitor 7**, use `@capawesome/capacitor-live-update@v7-lts`. For **Capacitor 6**, use `@capawesome/capacitor-live-update@v6-lts`. === "Cordova" ```bash cordova plugin add @capawesome/cordova-live-update --variable APP_ID=00000000-0000-0000-0000-000000000000 ``` Replace the `APP_ID` value with the app ID from Step 1. !!! warning "WebView scheme" The plugin requires the default custom WebView scheme. It does not work if your app sets `Scheme=file` or `AndroidInsecureFileModeEnabled=true`. ### Step 3: Configure the SDK Configure the SDK with your app ID and the recommended settings. The `autoUpdateStrategy: background` option checks for updates on app start and resume, downloads them in the background, and applies them on the next launch — no extra code required. The `readyTimeout` and `autoBlockRolledBackBundles` options enable [automatic rollback](rollbacks.md) of a broken update. === "Capacitor" ```typescript title="capacitor.config.ts" import { CapacitorConfig } from "@capacitor/cli"; const config: CapacitorConfig = { plugins: { LiveUpdate: { appId: "00000000-0000-0000-0000-000000000000", autoUpdateStrategy: "background", autoBlockRolledBackBundles: true, readyTimeout: 10000 } } }; export default config; ``` Apply the configuration: ```bash npx cap sync ``` === "Cordova" Configure the plugin via preferences in your `config.xml`: ```xml title="config.xml" ``` Cordova only reads these preferences when a platform is added, so changes to them don't take effect until you remove and re-add the affected platforms: ```bash cordova platform rm android ios cordova platform add android ios ``` For automatic rollback to work, call `ready()` as early as possible at app start to signal that the new bundle started successfully: === "Capacitor" ```typescript import { LiveUpdate } from "@capawesome/capacitor-live-update"; await LiveUpdate.ready(); ``` === "Cordova" ```javascript document.addEventListener("deviceready", async () => { await cordova.plugins.LiveUpdate.ready(); }); ``` ### Step 4: Publish Your First Update Build your web assets, then upload them as a Live Update bundle with the CLI (the same command for both runtimes): ```bash npm run build npx @capawesome/cli apps:liveupdates:upload ``` You will be prompted for the path to your web assets directory (e.g. `www` or `dist`) and the target app. After the upload completes, the bundle is available to your users. Open the [Deployments](https://console.cloud.capawesome.io/apps/_/deployments){:target="_blank"} page in the Console to see the details. ### Step 5: Test Your Setup Make a small visible change to your web assets, rebuild, and upload a new bundle with the same command. Then force-close and restart your app. !!! note "Force an update check" With an `autoUpdateStrategy`, updates are only checked on resume if the last check was more than 15 minutes ago. During development, **force-close and restart the app** to trigger a check immediately. Wait around 15–30 seconds, then restart again to see the change take effect. 🎉 Not seeing the update? Head over to [Troubleshooting](troubleshooting.md) — it walks through the most common reasons an update doesn't reach the device and how to fix them. ## Make Updates Version-Compatible !!! danger "Do this before shipping to production" A Live Update can only change your **web layer** — it must stay compatible with the **native binary** already installed on the device. Shipping a bundle that relies on a native feature an older app version doesn't have will **crash the app on launch**. See [Binary-Compatible Changes](binary-compatible-changes.md) for the full rules. The safest way to prevent this is **versioned channels**: pin each native release to its own channel so a bundle only ever reaches compatible devices. Configure the channel natively at build time, derived from your version code. === "Capacitor" On Android, add a resource value in `android/app/build.gradle`: ```groovy title="android/app/build.gradle" android { defaultConfig { resValue "string", "capawesome_live_update_default_channel", "production-" + defaultConfig.versionCode } } ``` On iOS, add a key to `ios/App/App/Info.plist`: ```xml title="ios/App/App/Info.plist" CapawesomeLiveUpdateDefaultChannel production-$(CURRENT_PROJECT_VERSION) ``` === "Cordova" On Android, set the channel via a `build-extras.gradle` file included through your `config.xml`: ```groovy title="build-extras.gradle" android { applicationVariants.all { variant -> variant.resValue "string", "capawesome_live_update_default_channel", "production-" + variant.versionCode } } ``` On iOS, add the channel key to your `Info.plist` via `config.xml`: ```xml title="config.xml" production-$(CURRENT_PROJECT_VERSION) ``` Every native release now ships pinned to its own channel, and uploads to `production-` only reach matching devices. See [Manage Channels](channels.md) for alternatives, such as selecting the channel at runtime. ## Next Steps
- :material-rocket-launch:{ .lg .middle } **Publish an Update** --- The recurring workflow for shipping updates to your users. [:octicons-arrow-right-24: Publish an update](publish.md) - :material-shield-key:{ .lg .middle } **Sign Your Bundles** --- Add code signing so only you can publish updates to your app. [:octicons-arrow-right-24: Sign your bundles](code-signing.md)
## Bonus: Video Walkthrough Prefer to watch the setup end-to-end? This walkthrough covers the first deployment, channel setup, and runtime behavior in a real project: