@capawesome/capacitor-live-update¶

Capacitor plugin to update your app remotely in real-time.

Features¶

🔋 Supports Android and iOS
⚡️ Capacitor 6 support
📦 Bundle Management: Download, set, and delete bundles.
☁️ Cloud Support: Use the Capawesome Cloud to manage your app updates.
📺 Channel Support: Set a channel for the app to manage different versions.
🔄 Auto Update: Automatically download and set the latest bundle for the app.
🛟 Rollback: Reset the app to the default bundle if an incompatible bundle has been set.

Installation¶

npm install @capawesome/capacitor-live-update
npx cap sync

Android¶

Variables¶

This plugin will use the following project variables (defined in your app’s variables.gradle file):

$okhttp3Version version of com.squareup.okhttp3:okhttp (default: 22.3.1)
$zip4jVersion version of net.lingala.zip4j:zip4j (default: 2.11.5)

iOS¶

Privacy manifest¶

Add the NSPrivacyAccessedAPICategoryUserDefaults dictionary key to your Privacy Manifest (usually ios/App/PrivacyInfo.xcprivacy):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      <!-- Add this dict entry to the array if the file already exists. -->
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

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

Configuration¶

Prop	Type	Description	Default	Since
`appId`	`string`	The app ID is used to identify the app when using Capawesome Cloud.		5.0.0
`autoDeleteBundles`	`boolean`	Whether or not to automatically delete unused bundles. When enabled, the plugin will automatically delete unused bundles after calling `ready()`.	`false`	5.0.0
`enabled`	`boolean`	Whether or not the plugin is enabled.	`true`	5.0.0
`readyTimeout`	`number`	The timeout in milliseconds to wait for the app to be ready before resetting to the default bundle.	`10000`	5.0.0
`resetOnUpdate`	`boolean`	Whether or not the app should be reset to the default bundle during an update.	`true`	5.0.0

Examples¶

In capacitor.config.json:

{
  "plugins": {
    "LiveUpdate": {
      "appId": '4100e356-e851-47fe-9d3c-b411eb325a99',
      "autoDeleteBundles": undefined,
      "enabled": undefined,
      "readyTimeout": undefined,
      "resetOnUpdate": undefined
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor/live-update" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: '4100e356-e851-47fe-9d3c-b411eb325a99',
      autoDeleteBundles: undefined,
      enabled: undefined,
      readyTimeout: undefined,
      resetOnUpdate: undefined,
    },
  },
};

export default config;

Demo¶

A working example can be found here: robingenz/capacitor-plugin-demo

Guides¶

Announcing the Capacitor Live Update Plugin

Usage¶

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

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 getBundle = async () => {
  const result = await LiveUpdate.getBundle();
  return result.bundleId;
};

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

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

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

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

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 () => {
  await LiveUpdate.ready();
};

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

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

const setBundle = async () => {
  await LiveUpdate.setBundle({ bundleId: '1.0.0' });
};

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

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

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

API¶

deleteBundle(...)
downloadBundle(...)
getBundle()
getBundles()
getChannel()
getCustomId()
getDeviceId()
getVersionCode()
getVersionName()
ready()
reload()
reset()
setBundle(...)
setChannel(...)
setCustomId(...)
sync()
Interfaces

deleteBundle(...)¶

deleteBundle(options: DeleteBundleOptions) => Promise<void>

Delete a bundle from the app.

Only available on Android and iOS.

Param	Type
`options`	`DeleteBundleOptions`

Since: 5.0.0

downloadBundle(...)¶

downloadBundle(options: DownloadBundleOptions) => Promise<void>

Download a bundle.

Only available on Android and iOS.

Param	Type
`options`	`DownloadBundleOptions`

Since: 5.0.0

getBundle()¶

getBundle() => Promise<GetBundleResult>

Get the active bundle identifier.

Only available on Android and iOS.

Returns: Promise<GetBundleResult>

Since: 5.0.0

getBundles()¶

getBundles() => Promise<GetBundlesResult>

Get all available bundle identifiers.

Only available on Android and iOS.

Returns: Promise<GetBundlesResult>

Since: 5.0.0

getChannel()¶

getChannel() => Promise<GetChannelResult>

Get the channel of the app.

Only available on Android and iOS.

Returns: Promise<GetChannelResult>

Since: 5.0.0

getCustomId()¶

getCustomId() => Promise<GetCustomIdResult>

Get the custom identifier of the app.

Only available on Android and iOS.

Returns: Promise<GetCustomIdResult>

Since: 5.0.0

getDeviceId()¶

getDeviceId() => Promise<GetDeviceIdResult>

Get the device identifier of the app.

Only available on Android and iOS.

Returns: Promise<GetDeviceIdResult>

Since: 5.0.0

getVersionCode()¶

getVersionCode() => Promise<GetVersionCodeResult>

Get the version code of the app.

Only available on Android and iOS.

Returns: Promise<GetVersionCodeResult>

Since: 5.0.0

getVersionName()¶

getVersionName() => Promise<GetVersionNameResult>

Get the version name of the app.

Only available on Android and iOS.

Returns: Promise<GetVersionNameResult>

Since: 5.0.0

ready()¶

ready() => Promise<void>

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

Only available on Android and iOS.

Since: 5.0.0

reload()¶

reload() => Promise<void>

Reload the app to apply the new bundle.

Only available on Android and iOS.

Since: 5.0.0

reset()¶

reset() => Promise<void>

Reset the app to the default bundle.

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

Only available on Android and iOS.

Since: 5.0.0

setBundle(...)¶

setBundle(options: SetBundleOptions) => Promise<void>

Set the next bundle to use for the app.

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

Only available on Android and iOS.

Param	Type
`options`	`SetBundleOptions`

Since: 5.0.0

setChannel(...)¶

setChannel(options: SetChannelOptions) => Promise<void>

Set the channel of the app.

Only available on Android and iOS.

Param	Type
`options`	`SetChannelOptions`

Since: 5.0.0

setCustomId(...)¶

setCustomId(options: SetCustomIdOptions) => Promise<void>

Set the custom identifier of the app.

Only available on Android and iOS.

Param	Type
`options`	`SetCustomIdOptions`

Since: 5.0.0

sync()¶

sync() => Promise<SyncResult>

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

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

Only available on Android and iOS.

Returns: Promise<SyncResult>

Since: 5.0.0

Interfaces¶

DeleteBundleOptions¶

Prop	Type	Description	Since
`bundleId`	`string`	The unique identifier of the bundle to delete.	5.0.0

DownloadBundleOptions¶

Prop	Type	Description	Since
`url`	`string`	The URL of the bundle to download. The bundle must be a ZIP file containing at least a `index.html` file.	5.0.0
`bundleId`	`string`	The unique identifier of the bundle.	5.0.0

GetBundleResult¶

Prop	Type	Description	Since
`bundleId`	`string \| null`	The unique identifier of the active bundle. If `null`, the default bundle is being used.	5.0.0

GetBundlesResult¶

Prop	Type	Description	Since
`bundleIds`	`string[]`	An array of unique identifiers of all available bundles.	5.0.0

GetChannelResult¶

Prop	Type	Description	Since
`channel`	`string \| null`	The channel of the app. If `null`, the app is using the default channel.	5.0.0

GetCustomIdResult¶

Prop	Type	Description	Since
`customId`	`string \| null`	The custom identifier of the app. If `null`, no custom identifier is set.	5.0.0

GetDeviceIdResult¶

Prop	Type	Description	Since
`deviceId`	`string`	The unique identifier of the device. On iOS, `identifierForVendor` is used. The value of this property is the same for apps that come from the same vendor running on the same device.	5.0.0

GetVersionCodeResult¶

Prop	Type	Description	Since
`versionCode`	`string`	The version code of the app. On Android, this is the `versionCode` from the `android/app/build.gradle` file. On iOS, this is the `CFBundleVersion` from the `Info.plist` file.	5.0.0

GetVersionNameResult¶

Prop	Type	Description	Since
`versionName`	`string`	The version name of the app. On Android, this is the `versionName` from the `android/app/build.gradle` file. On iOS, this is the `CFBundleShortVersionString` from the `Info.plist` file.	5.0.0

SetBundleOptions¶

Prop	Type	Description	Since
`bundleId`	`string`	The unique identifier of the bundle to use.	5.0.0

SetChannelOptions¶

Prop	Type	Description	Since
`channel`	`string \| null`	The channel of the app. Set `null` to remove the channel.	5.0.0

SetCustomIdOptions¶

Prop	Type	Description	Since
`customId`	`string \| null`	The custom identifier of the app. Set `null` to remove the custom identifier.	5.0.0

SyncResult¶

Prop	Type	Description	Since
`nextBundleId`	`string \| null`	The identifier of the next bundle to use. If `null`, the app is up-to-date and no new bundle is available.	5.0.0

Testing¶

When testing the plugin, you must make sure that you do not use the Live Reload option, as in this case a development server is used to load the bundle.

Therefore, simply start your app without the live reload option, for example with the following command:

npx ionic cap run android --open

If you want to disable the plugin to test other parts of your app, you can set the enabled configuration option to false.

Limitations¶

Live updates are only supported for binary-compatible changes (e.g. HTML, CSS, JavaScript). If you change native code, such as adding a new plugin, you need to resubmit your app to the app stores. For this reason, you must be careful to limit live updates to compatible native versions of your app.

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.