Cordova Live Update Plugin

Cordova plugin that allows you to update your app remotely in real-time without requiring users to download a new version from the app store, also known as Over-the-Air (OTA) updates.

Features

• 🔋 Supports Android and iOS
• ⚡️ Works with stock Cordova WebView — does not require cordova-plugin-ionic-webview
• 📦 Bundle Management — download, set, and delete bundles
• ☁️ Cloud Support — manage updates via Capawesome Cloud
• 📺 Channel Support — set a channel for the app to manage different versions
• 🔄 Auto Update — background update strategy with 15-minute throttle
• 🛟 Rollback — automatic revert to the default bundle on failed updates
• 🔁 Delta Updates — manifest mode downloads only changed files
• ⚙️ Runtime Configuration — update plugin configuration at runtime
• 📡 Update Lifecycle Events — track download progress, react to bundle changes, detect reloads
• 🏷️ Custom Properties — associate custom key-value metadata with bundles via Capawesome Cloud
• 🔒 Security — verify authenticity and integrity of bundles via RSA signature
• 🌐 Open Source — MIT licensed

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Compatibility

WebView Compatibility

This plugin swaps the files served to the WebView by hooking into Cordova's official plugin extension points (CordovaPluginPathHandler on Android, CDVPluginSchemeHandler on iOS). These hooks only fire when the WebView loads content via a custom scheme, which is the default for modern Cordova:

• Android (cordova-android ≥10): loads from https://localhost/ via WebViewAssetLoader.
• iOS (cordova-ios ≥7): loads from app://localhost/ via WKURLSchemeHandler.

The plugin does NOT work if your app forces the WebView back to the legacy file:// scheme, for example:

• <preference name="AndroidInsecureFileModeEnabled" value="true" />
• <preference name="Scheme" value="file" />

cordova-plugin-ionic-webview

cordova-plugin-ionic-webview is not compatible with this plugin. It replaces the WebView with its own local server that serves content directly and never calls the extension points above, so downloaded bundles are silently ignored — sync() and reload() appear to succeed, but the WebView keeps showing the content shipped in the app binary. This affects both Android and iOS.

If your app uses cordova-plugin-ionic-webview, remove it:

cordova plugin remove cordova-plugin-ionic-webview

It is no longer maintained and is no longer needed: modern Cordova serves the WebView through WKWebView on iOS and the system WebView on Android out of the box, with the same custom-scheme behavior this plugin relies on.

Guides

• Getting Started with Capawesome Cloud Live Updates
• Migrating from Ionic Appflow to Capawesome Cloud

Installation

Install the plugin by running the following command and follow the platform-specific instructions below:

cordova plugin add @capawesome/cordova-live-update --variable APP_ID=<your-app-id>

Android

Channel

For a static default channel, use the DEFAULT_CHANNEL plugin variable — no native config required.

If you are using Versioned Channels, the channel value needs to be interpolated from the build's versionCode, which can't be expressed via a plugin variable. Use Cordova's build-extras.gradle mechanism instead. In your app's config.xml, add:

<platform name="android">
    <resource-file src="build-extras.gradle" target="app/build-extras.gradle"/>
</platform>

Then create build-extras.gradle next to config.xml:

android {
    applicationVariants.all { variant ->
        variant.resValue "string", "capawesome_live_update_default_channel", "production-${variant.versionCode}"
    }
}

iOS

Channel

For a static default channel, use the DEFAULT_CHANNEL plugin variable — no native config required.

If you are using Versioned Channels, use Cordova's <config-file> mechanism in your app's config.xml:

<platform name="ios">
    <config-file target="*-Info.plist" parent="CapawesomeLiveUpdateDefaultChannel">
        <string>production-$(CURRENT_PROJECT_VERSION)</string>
    </config-file>
</platform>

Xcode resolves $(CURRENT_PROJECT_VERSION) at build time.

Privacy manifest

Starting with cordova-ios 7.1.0, the iOS Privacy Manifest is configured via a <privacy-manifest> element inside the <platform name="ios"> section of your app's config.xml. Add an NSPrivacyAccessedAPICategoryUserDefaults entry for this plugin:

<platform name="ios">
    <privacy-manifest>
        <key>NSPrivacyAccessedAPITypes</key>
        <array>
            <!-- Add this dict entry to the array if the key already exists. -->
            <dict>
                <key>NSPrivacyAccessedAPIType</key>
                <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
                <key>NSPrivacyAccessedAPITypeReasons</key>
                <array>
                    <string>CA92.1</string>
                </array>
            </dict>
        </array>
    </privacy-manifest>
</platform>

We recommend to declare CA92.1 as the reason for accessing the UserDefaults API.

Plugin Variables

These map to Cordova <preference> entries in config.xml. Set them at install time with --variable, or edit config.xml directly:

Example

<plugin name="@capawesome/cordova-live-update" spec="0.1.0">
  <variable name="APP_ID" value="6e351b4f-69a7-415e-a057-4567df7ffe94" />
  <variable name="AUTO_UPDATE_STRATEGY" value="background" />
  <variable name="DEFAULT_CHANNEL" value="production" />
  <variable name="READY_TIMEOUT" value="10000" />
  <variable name="PUBLIC_KEY" value="-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDodf1SD0OOn6hIlDuKBza0Ed0OqtwyVJwiyjmE9BJaZ7y8ZUfcF+SKmd0l2cDPM45XIg2tAFux5n29uoKyHwSt+6tCi5CJA5Z1/1eZruRRqABLonV77KS3HUtvOgqRLDnKSV89dYZkM++NwmzOPgIF422mvc+VukcVOBfc8/AHQIDAQAB-----END PUBLIC KEY-----" />
</plugin>

Demo

A working example can be found here: capawesome-team/cordova-live-update-demo

Android	iOS

Usage

The plugin attaches to cordova.plugins.LiveUpdate once deviceready fires.

If you use TypeScript, type definitions are available from the npm package:

import type { LiveUpdatePlugin } from '@capawesome/cordova-live-update';

declare const cordova: { plugins: { LiveUpdate: LiveUpdatePlugin } };

const { LiveUpdate } = cordova.plugins;

const deleteBundle = async () => {
  await LiveUpdate.deleteBundle({ bundleId: 'my-bundle' });
};

const downloadBundle = async () => {
  await LiveUpdate.downloadBundle({ url: 'https://example.com/1.0.0.zip', bundleId: '1.0.0' });
};

const fetchChannels = async () => {
  const result = await LiveUpdate.fetchChannels();
  return result.channels;
};

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

const getBundles = async () => {
  const result = await LiveUpdate.getBundles();
  return result.bundleIds;
};

const getChannel = async () => {
  const result = await LiveUpdate.getChannel();
  return result.channel;
};

const getCurrentBundle = async () => {
  const result = await LiveUpdate.getCurrentBundle();
  return result.bundleId;
};

const getCustomId = async () => {
  const result = await LiveUpdate.getCustomId();
  return result.customId;
};

const getDeviceId = async () => {
  const result = await LiveUpdate.getDeviceId();
  return result.deviceId;
};

const getNextBundle = async () => {
  const result = await LiveUpdate.getNextBundle();
  return result.bundleId;
};

const getVersionCode = async () => {
  const result = await LiveUpdate.getVersionCode();
  return result.versionCode;
};

const getVersionName = async () => {
  const result = await LiveUpdate.getVersionName();
  return result.versionName;
};

const ready = async () => {
  const result = await LiveUpdate.ready();
  if (result.currentBundleId) {
    console.log(`The app is now using the bundle with the identifier ${result.currentBundleId}.`);
  }
  if (result.previousBundleId) {
    console.log(`The app was using the bundle with the identifier ${result.previousBundleId}.`);
  }
  if (result.rollback) {
    console.log('The app was reset to the default bundle.');
  }
};

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

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

const setChannel = async () => {
  await LiveUpdate.setChannel({ channel: 'production-5' });
};

const setCustomId = async () => {
  await LiveUpdate.setCustomId({ customId: 'my-custom-id' });
};

const setNextBundle = async () => {
  await LiveUpdate.setNextBundle({ bundleId: '7f0b9bf2-dff6-4be2-bcac-b068cc5ea756' });
};

const sync = async () => {
  const result = await LiveUpdate.sync({
    channel: 'production-5',
  });
  return result.nextBundleId;
};

const isNewBundleAvailable = async () => {
  const { bundleId: latestBundleId } = await LiveUpdate.fetchLatestBundle({
    channel: 'production-5',
  });
  if (latestBundleId) {
    const { bundleId: currentBundleId } = await LiveUpdate.getCurrentBundle();
    return latestBundleId !== currentBundleId;
  } else {
    return false;
  }
};

API

• clearBlockedBundles()
• deleteBundle(...)
• downloadBundle(...)
• fetchChannels(...)
• fetchLatestBundle(...)
• getBlockedBundles()
• getBundles()
• getChannel()
• getConfig()
• getDownloadedBundles()
• getCurrentBundle()
• getCustomId()
• getDeviceId()
• isSyncing()
• getNextBundle()
• getVersionCode()
• getVersionName()
• ready()
• reload()
• reset()
• resetConfig()
• setChannel(...)
• setConfig(...)
• setCustomId(...)
• setNextBundle(...)
• sync(...)
• addListener('downloadBundleProgress', ...)
• addListener('nextBundleSet', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

clearBlockedBundles()

clearBlockedBundles() => any

Clear all blocked bundles from the blocked list.

This removes all bundle identifiers that were automatically blocked due to rollbacks when autoBlockRolledBackBundles is enabled.

Returns: any

Since: 0.1.0

deleteBundle(...)

deleteBundle(options: DeleteBundleOptions) => any

Delete a bundle from the app.

Returns: any

Since: 0.1.0

downloadBundle(...)

downloadBundle(options: DownloadBundleOptions) => any

Download a bundle.

Returns: any

Since: 0.1.0

fetchChannels(...)

fetchChannels(options?: FetchChannelsOptions | undefined) => any

Fetch channels from Capawesome Cloud.

This is primarily intended for development and QA purposes. It allows you to retrieve a list of available channels so you can dynamically switch between them using setChannel(...).

Attention: Only works for apps with public channels enabled. If channels are private, they can still be set using setChannel(...) but won't be returned by this method.

Returns: any

Since: 0.1.0

fetchLatestBundle(...)

fetchLatestBundle(options?: FetchLatestBundleOptions | undefined) => any

Fetch the latest bundle using the Capawesome Cloud.

Returns: any

Since: 0.1.0

getBlockedBundles()

getBlockedBundles() => any

Get all blocked bundle identifiers.

Returns the list of bundle identifiers that were automatically blocked due to rollbacks when autoBlockRolledBackBundles is enabled.

Returns: any

Since: 0.1.0

getBundles()

getBundles() => any

Get all identifiers of bundles that have been downloaded.

Returns: any

Since: 0.1.0

getChannel()

getChannel() => any

Get the channel that is used for the update.

The channel is resolved in the following order (highest priority first):

1. setChannel() (SharedPreferences on Android / UserDefaults on iOS)
2. Native config (CapawesomeLiveUpdateDefaultChannel in Info.plist on iOS or capawesome_live_update_default_channel in strings.xml on Android)
3. The DEFAULT_CHANNEL preference in config.xml

Note: The channel parameter of sync() takes the highest priority but is not persisted and therefore not returned by this method.

Returns: any

Since: 0.1.0

getConfig()

getConfig() => any

Get the runtime configuration.

Returns the current plugin configuration including any runtime overrides set via setConfig().

Returns: any

Since: 0.1.0

getDownloadedBundles()

getDownloadedBundles() => any

Get all identifiers of bundles that have been downloaded.

Returns: any

Since: 0.1.0

getCurrentBundle()

getCurrentBundle() => any

Get the bundle identifier of the current bundle. The current bundle is the bundle that is currently used by the app.

Returns: any

Since: 0.1.0

getCustomId()

getCustomId() => any

Get the custom identifier of the device.

Returns: any

Since: 0.1.0

getDeviceId()

getDeviceId() => any

Get the unique device identifier.

Returns: any

Since: 0.1.0

isSyncing()

isSyncing() => any

Check whether a sync operation is currently in progress.

Returns: any

Since: 0.1.0

getNextBundle()

getNextBundle() => any

Get the bundle identifier of the next bundle. The next bundle is the bundle that will be used after calling reload() or restarting the app.

Returns: any

Since: 0.1.0

getVersionCode()

getVersionCode() => any

Get the version code of the app.

On Android, this is the versionCode from PackageInfo. On iOS, this is the CFBundleVersion from the Info.plist file.

Returns: any

Since: 0.1.0

getVersionName()

getVersionName() => any

Get the version name of the app.

On Android, this is the versionName from PackageInfo. On iOS, this is the CFBundleShortVersionString from the Info.plist file.

Returns: any

Since: 0.1.0

ready()

ready() => any

Notify the plugin that the app is ready to use and no rollback is needed.

Attention: This method should be called as soon as the app is ready to use to prevent the app from being reset to the default bundle.

Returns: any

Since: 0.1.0

reload()

reload() => any

Reload the app to apply the new bundle.

Returns: any

Since: 0.1.0

reset()

reset() => any

Reset the app to the default bundle.

Call reload() or restart the app to apply the changes.

Returns: any

Since: 0.1.0

resetConfig()

resetConfig() => any

Reset the runtime configuration to the values from config.xml.

This clears any runtime configuration set via setConfig(). The changes take effect immediately.

Returns: any

Since: 0.1.0

setChannel(...)

setChannel(options: SetChannelOptions) => any

Set the channel to use for the update.

Returns: any

Since: 0.1.0

setConfig(...)

setConfig(options: SetConfigOptions) => any

Set the runtime configuration.

This allows updating plugin configuration options at runtime. The changes are persisted across app restarts and take effect immediately.

Important: Runtime configuration is automatically reset to default values whenever the native app is updated to a new version. This ensures that configuration from previous versions doesn't persist after an app update.

Returns: any

Since: 0.1.0

setCustomId(...)

setCustomId(options: SetCustomIdOptions) => any

Set the custom identifier of the device.

Returns: any

Since: 0.1.0

setNextBundle(...)

setNextBundle(options: SetNextBundleOptions) => any

Set the next bundle to use for the app.

Call reload() or restart the app to apply the changes.

Returns: any

Since: 0.1.0

sync(...)

sync(options?: SyncOptions | undefined) => any

Automatically download and set the latest bundle for the app using the Capawesome Cloud.

Call reload() or restart the app to apply the changes.

Returns: any

Since: 0.1.0

addListener('downloadBundleProgress', ...)

addListener(eventName: 'downloadBundleProgress', listenerFunc: DownloadBundleProgressListener) => any

Listen for the download progress of a bundle.

Returns: any

Since: 0.1.0

addListener('nextBundleSet', ...)

addListener(eventName: 'nextBundleSet', listenerFunc: NextBundleSetListener) => any

Listen for when a bundle is set as the next bundle.

This event is triggered whenever a bundle is set to be used on the next app restart, either through automatic updates or manual calls to setNextBundle().

Returns: any

Since: 0.1.0

removeAllListeners()

removeAllListeners() => any

Remove all listeners for this plugin.

Returns: any

Since: 0.1.0

Interfaces

DeleteBundleOptions

DownloadBundleOptions

FetchChannelsOptions

FetchChannelsResult

Channel

FetchLatestBundleOptions

FetchLatestBundleResult

GetBlockedBundlesResult

GetBundlesResult

GetChannelResult

GetConfigResult

GetDownloadedBundlesResult

GetCurrentBundleResult

GetCustomIdResult

GetDeviceIdResult

IsSyncingResult

GetNextBundleResult

GetVersionCodeResult

GetVersionNameResult

ReadyResult

SetChannelOptions

SetConfigOptions

SetCustomIdOptions

SetNextBundleOptions

SyncOptions

SyncResult

DownloadBundleProgressEvent

Event that is triggered when the download progress of a bundle changes.

PluginListenerHandle

Handle returned from addListener(...). Call remove() to detach the listener.

NextBundleSetEvent

Event that is triggered when a bundle is set as the next bundle.

Type Aliases

DownloadBundleProgressListener

Listener for the download progress of a bundle.

(event: DownloadBundleProgressEvent): void

NextBundleSetListener

Listener for when a bundle is set as the next bundle.

(event: NextBundleSetEvent): void

Changelog

See CHANGELOG.md.

License

See LICENSE.