@capawesome/capacitor-live-update 8.2.2 → 8.3.0-dev.f9cc1d15.1783929784

package/CapawesomeCapacitorLiveUpdate.podspec

@@ -13,8 +13,23 @@ Pod::Spec.new do |s|
   s.source_files = 'ios/Plugin/**/*.{swift,h,m,c,cc,mm,cpp}'
   s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
-  s.dependency 'Alamofire', '~> 5.10.2'
+  s.dependency 'Alamofire', '>= 5.10.2', '< 6.0.0'
   s.dependency 'ZIPFoundation', '~> 0.9.0'
   s.swift_version = '5.1'
   s.static_framework = true
+  s.default_subspec = 'Default'
+
+  s.subspec 'Default' do |ss|
+    # Default subspec
+  end
+
+  # Opt-in subspec that pulls in the Ionic Live Update Provider SDK and
+  # compiles in the provider/manager classes guarded by
+  # `#if CAPAWESOME_INCLUDE_IONIC_PROVIDER`.
+  s.subspec 'IonicProvider' do |ss|
+    ss.dependency 'LiveUpdateProvider', '~> 1.0.0'
+    ss.pod_target_xcconfig = {
+      'OTHER_SWIFT_FLAGS' => '$(inherited) -DCAPAWESOME_INCLUDE_IONIC_PROVIDER'
+    }
+  end
 end

package/Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version: 5.9
+// swift-tools-version: 6.1
 import PackageDescription
 
 let package = Package(
@@ -9,10 +9,17 @@ let package = Package(
             name: "CapawesomeCapacitorLiveUpdate",
             targets: ["LiveUpdatePlugin"])
     ],
+    traits: [
+        .trait(
+            name: "IonicProvider",
+            description: "Enables the Ionic Live Update Provider SDK integration."
+        )
+    ],
     dependencies: [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
-        .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMinor(from: "5.10.2")),
-        .package(url: "https://github.com/weichsel/ZIPFoundation.git", .upToNextMinor(from: "0.9.0"))
+        .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.10.2")),
+        .package(url: "https://github.com/weichsel/ZIPFoundation.git", .upToNextMinor(from: "0.9.0")),
+        .package(url: "https://github.com/ionic-team/live-update-provider-sdk.git", from: "1.0.0")
     ],
     targets: [
         .target(
@@ -21,12 +28,21 @@ let package = Package(
                 .product(name: "Capacitor", package: "capacitor-swift-pm"),
                 .product(name: "Cordova", package: "capacitor-swift-pm"),
                 .product(name: "Alamofire", package: "Alamofire"),
-                .product(name: "ZIPFoundation", package: "ZIPFoundation")
+                .product(name: "ZIPFoundation", package: "ZIPFoundation"),
+                .product(
+                    name: "LiveUpdateProvider",
+                    package: "live-update-provider-sdk",
+                    condition: .when(traits: ["IonicProvider"])
+                )
             ],
-            path: "ios/Plugin"),
+            path: "ios/Plugin",
+            swiftSettings: [
+                .define("CAPAWESOME_INCLUDE_IONIC_PROVIDER", .when(traits: ["IonicProvider"]))
+            ]),
         .testTarget(
             name: "LiveUpdatePluginTests",
             dependencies: ["LiveUpdatePlugin"],
             path: "ios/PluginTests")
-    ]
+    ],
+    swiftLanguageModes: [.v5]
 )

package/README.md

@@ -1,4 +1,4 @@
-# @capawesome/capacitor-live-update
+# Capacitor Live Update Plugin
 
 Capacitor plugin that allows you to update your app remotely in real-time without requiring users to download a new version from the app store, known as Over-the-Air (OTA) updates.
 
@@ -10,7 +10,7 @@ Capacitor plugin that allows you to update your app remotely in real-time withou
 
 ## Features
 
-We are proud to offer one of the most complete and feature-rich Capacitor plugins for Over-the-Air (OTA) updates. Here are some of the key features:
+The Capacitor Live Update plugin is one of the most feature-rich Over-the-Air (OTA) update solutions for Capacitor apps. Here are some of the key features:
 
 - 🔋 Supports **Android and iOS**
 - ⚡️ **Capacitor 6/7/8** support
@@ -25,28 +25,36 @@ We are proud to offer one of the most complete and feature-rich Capacitor plugin
 - 📡 **Update Lifecycle Events**: Track download progress, react to bundle changes, and detect reloads with auto-blocking of rolled back bundles.
 - 🏠 **Self-Hosted Bundles**: Download bundles from any URL, no Capawesome Cloud dependency required.
 - 🏷️ **Custom Properties**: Associate custom key-value metadata with bundles via Capawesome Cloud.
+- 🌀 **Ionic Portals Support**: Power live updates for [Ionic Portals](https://ionic.io/docs/portals) via the [Ionic Live Update Provider SDK](https://github.com/ionic-team/live-update-provider-sdk).
+- 🧩 **Federated Capacitor Support**: Power live updates for [Federated Capacitor](https://ionic.io/docs/portals/for-capacitor/overview) shells via the [Ionic Live Update Provider SDK](https://github.com/ionic-team/live-update-provider-sdk).
 - 🔒 **Security**: Verify the authenticity and integrity of the bundle using a public key.
 - ⚔️ **Battle-Tested**: Used in more than 1,000 projects to update apps on more than 20,000,000 devices.
 - 🌐 **Open Source**: Licensed under the MIT License.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The Live Update plugin is typically used to ship changes to users without going through the app stores, for example:
+
+- **Instant bug fixes**: Deliver critical fixes to your users in real-time without waiting for app store reviews.
+- **Fast feature delivery**: Ship new web-based features as soon as they are ready by publishing a new bundle.
+- **Staged rollouts**: Gradually roll out new bundles to a subset of devices to gather feedback before a full release.
+- **Testing and QA channels**: Distribute preview versions to testers via dedicated channels before promoting them to production.
+- **Safe releases**: Automatically roll back to the default bundle if a faulty update prevents the app from becoming ready.
 
 ## Compatibility
 
 | Plugin Version | Capacitor Version | Status         |
 | -------------- | ----------------- | -------------- |
 | 8.x.x          | >=8.x.x           | Active support |
-| 7.x.x          | 7.x.x             | Deprecated     |
-| 6.x.x          | 6.x.x             | Deprecated     |
+| 7.x.x          | 7.x.x             | Maintenance    |
+| 6.x.x          | 6.x.x             | Maintenance    |
 | 5.x.x          | 5.x.x             | Deprecated     |
 
 ## Guides
 
-- [Getting Started with Capawesome Cloud Live Updates](https://capawesome.io/cloud/live-updates/setup/)
+- [Getting Started with Capawesome Cloud Live Updates](https://capawesome.io/docs/cloud/live-updates/setup/)
 - [Migrating from Ionic Appflow to Capawesome Cloud](https://capawesome.io/blog/migrating-from-ionic-appflow-to-capawesome-cloud/)
 - [Migrating from App Center to Capawesome Cloud](https://capawesome.io/blog/migrating-from-app-center-to-capawesome-cloud/)
 
@@ -76,7 +84,7 @@ npx cap sync
 
 #### Channel
 
-If you are using [Versioned Channels](https://capawesome.io/cloud/live-updates/guides/best-practices/#versioned-channels), you can set a default channel directly in your native project by adding a string resource.
+If you are using [Versioned Channels](https://capawesome.io/docs/cloud/live-updates/guides/best-practices/#versioned-channels), you can set a default channel directly in your native project by adding a string resource.
 This allows you to tie the channel to the version code at build time.
 
 Add the following to your app's `build.gradle` file:
@@ -93,6 +101,7 @@ android {
 
 If needed, you can define the following project variable in your app’s `variables.gradle` file to change the default version of the dependency:
 
+- `$ionicLiveUpdateProviderVersion` version of `io.ionic:liveupdateprovider` (default: `1.0.0`)
 - `$okhttp3Version` version of `com.squareup.okhttp3:okhttp` (default: `5.3.2`)
 - `$zip4jVersion` version of `net.lingala.zip4j:zip4j` (default: `2.11.5`)
 
@@ -102,7 +111,7 @@ This can be useful if you encounter dependency conflicts with other plugins in y
 
 #### Channel
 
-If you are using [Versioned Channels](https://capawesome.io/cloud/live-updates/guides/best-practices/#versioned-channels), you can set a default channel directly in your native project by adding a key to your `Info.plist` file.
+If you are using [Versioned Channels](https://capawesome.io/docs/cloud/live-updates/guides/best-practices/#versioned-channels), you can set a default channel directly in your native project by adding a key to your `Info.plist` file.
 This allows you to tie the channel to the build version at build time.
 
 Add the following to your `Info.plist` file:
@@ -139,6 +148,10 @@ Add the `NSPrivacyAccessedAPICategoryUserDefaults` dictionary key to your [Priva
 
 We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api#4278401) as the reason for accessing the [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults) API.
 
+## Ionic Live Update Provider SDK Integration
+
+This plugin implements the [Ionic Live Update Provider SDK](https://github.com/ionic-team/live-update-provider-sdk) contract, so that **Ionic Portals** and **Federated Capacitor** apps can use Capawesome Cloud to deliver live updates. Federated Capacitor resolves the provider by the plugin name `LiveUpdate`. See [the full setup guide](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/live-update/docs/ionic-live-update-provider-sdk-integration.md) for details.
+
 ## Configuration
 
 <docgen-config>
@@ -206,57 +219,191 @@ export default config;
 
 </docgen-config>
 
+## Demo
+
+A working example can be found here: [capawesome-team/capacitor-live-update-demo](https://github.com/capawesome-team/capacitor-live-update-demo)
+
+| Android                                                                                                                                              | iOS                                                                                                                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| <img src="https://raw.githubusercontent.com/capawesome-team/capacitor-plugins/main/packages/live-update/.github/assets/demo-android.png" width="324" alt="Android Demo" /> | <img src="https://raw.githubusercontent.com/capawesome-team/capacitor-plugins/main/packages/live-update/.github/assets/demo-ios.png" width="324" alt="iOS Demo" /> |
+
 ## Usage
 
+All methods are only available on Android and iOS. The following examples show how to sync with Capawesome Cloud, mark the app as ready, check for and download new bundles, switch between and manage bundles, work with channels, inspect the current and next bundle, identify devices, read the app version, and reset to the default bundle.
+
+### Sync with Capawesome Cloud
+
+Automatically download and set the latest bundle for the app using [Capawesome Cloud](https://cloud.capawesome.io/). Call `reload()` or restart the app to apply the changes. The `channel` option overrides the channel for this single sync call without persisting it:
+
 ```typescript
 import { LiveUpdate } from '@capawesome/capacitor-live-update';
 
-const deleteBundle = async () => {
-  await LiveUpdate.deleteBundle({ bundleId: 'my-bundle' });
+const sync = async () => {
+  const result = await LiveUpdate.sync({
+    channel: 'production-5',
+  });
+  return result.nextBundleId;
 };
+```
+
+### Notify the plugin that the app is ready
+
+Call `ready()` as soon as the app is ready to use so that the plugin knows no rollback is needed. If the `readyTimeout` configuration option is set and this method is not called in time, the plugin resets the app to the default bundle:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
+
+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.');
+  }
+};
+```
+
+### Check if a new bundle is available
+
+Fetch the latest bundle from Capawesome Cloud and compare it with the bundle that is currently in use:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
+
+const fetchLatestBundle = async () => {
+  await LiveUpdate.fetchLatestBundle();
+};
+
+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;
+  }
+};
+```
+
+### Download a bundle from your own server
+
+Download a self-hosted bundle from any URL, without any Capawesome Cloud dependency:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
 
 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;
+### Switch to a downloaded bundle
+
+Set the next bundle to use for the app. Call `reload()` or restart the app to apply the changes:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
+
+const setNextBundle = async () => {
+  await LiveUpdate.setNextBundle({ bundleId: '7f0b9bf2-dff6-4be2-bcac-b068cc5ea756' });
 };
 
-const fetchLatestBundle = async () => {
-  await LiveUpdate.fetchLatestBundle();
+const reload = async () => {
+  await LiveUpdate.reload();
 };
+```
+
+### Manage downloaded bundles
+
+Get the identifiers of all bundles that have been downloaded and delete bundles that are no longer needed:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
 
 const getBundles = async () => {
   const result = await LiveUpdate.getBundles();
   return result.bundleIds;
 };
 
+const deleteBundle = async () => {
+  await LiveUpdate.deleteBundle({ bundleId: 'my-bundle' });
+};
+```
+
+### Work with channels
+
+Set the channel to use for updates, read the currently resolved channel, and fetch the available channels from Capawesome Cloud. The channel set via `setChannel(...)` is persisted across app restarts. Note that `fetchChannels(...)` only works for apps with public channels enabled:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
+
+const setChannel = async () => {
+  await LiveUpdate.setChannel({ channel: 'production-5' });
+};
+
 const getChannel = async () => {
   const result = await LiveUpdate.getChannel();
   return result.channel;
 };
 
+const fetchChannels = async () => {
+  const result = await LiveUpdate.fetchChannels();
+  return result.channels;
+};
+```
+
+### Inspect the current and next bundle
+
+Get the identifier of the bundle that is currently used by the app and of the bundle that will be used after the next reload or app restart:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
+
 const getCurrentBundle = async () => {
   const result = await LiveUpdate.getCurrentBundle();
   return result.bundleId;
 };
 
-const getCustomId = async () => {
-  const result = await LiveUpdate.getCustomId();
-  return result.customId;
+const getNextBundle = async () => {
+  const result = await LiveUpdate.getNextBundle();
+  return result.bundleId;
 };
+```
+
+### Identify devices
+
+Read the unique device identifier and manage a custom identifier for the device:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
 
 const getDeviceId = async () => {
   const result = await LiveUpdate.getDeviceId();
   return result.deviceId;
 };
 
-const getNextBundle = async () => {
-  const result = await LiveUpdate.getNextBundle();
-  return result.bundleId;
+const setCustomId = async () => {
+  await LiveUpdate.setCustomId({ customId: 'my-custom-id' });
+};
+
+const getCustomId = async () => {
+  const result = await LiveUpdate.getCustomId();
+  return result.customId;
 };
+```
+
+### Read the app version
+
+Get the native version code and version name of the app, for example to restrict live updates to compatible native versions:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
 
 const getVersionCode = async () => {
   const result = await LiveUpdate.getVersionCode();
@@ -267,58 +414,18 @@ 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.');
-  }
-};
+### Reset to the default bundle
 
-const reload = async () => {
-  await LiveUpdate.reload();
-};
+Reset the app to the bundle that shipped with the native app binary. Call `reload()` or restart the app to apply the changes:
+
+```typescript
+import { LiveUpdate } from '@capawesome/capacitor-live-update';
 
 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
@@ -1011,21 +1118,22 @@ Remove all listeners for this plugin.
 
 #### FetchLatestBundleResult
 
-| Prop                   | Type                                    | Description                                                                                                                                                                                  | Since |
-| ---------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| **`artifactType`**     | <code>'manifest' \| 'zip'</code>        | The artifact type of the bundle.                                                                                                                                                             | 6.7.0 |
-| **`bundleId`**         | <code>string \| null</code>             | The unique identifier of the latest bundle. On Capawesome Cloud, this is the ID of the app build artifact. If `null`, no bundle is available.                                                | 6.6.0 |
-| **`checksum`**         | <code>string</code>                     | The checksum of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the checksum will be returned as response header when downloading the bundle.   | 7.1.0 |
-| **`customProperties`** | <code>{ [key: string]: string; }</code> | Custom properties that are associated with the latest bundle.                                                                                                                                | 7.0.0 |
-| **`downloadUrl`**      | <code>string</code>                     | The URL of the latest bundle to download. Pass this URL to the `downloadBundle(...)` method to download the bundle.                                                                          | 6.7.0 |
-| **`signature`**        | <code>string</code>                     | The signature of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the signature will be returned as response header when downloading the bundle. | 7.1.0 |
+| Prop                   | Type                                    | Description                                                                                                                                                                                     | Since |
+| ---------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`artifactType`**     | <code>'manifest' \| 'zip'</code>        | The artifact type of the bundle.                                                                                                                                                                | 6.7.0 |
+| **`bundleId`**         | <code>string \| null</code>             | The unique identifier of the latest bundle. On Capawesome Cloud, this is the ID of the app build artifact. If `null`, no bundle is available.                                                   | 6.6.0 |
+| **`channel`**          | <code>string</code>                     | The name of the channel that the bundle is actually from. This is the resolved channel after applying any forced channel assignment and may differ from the channel set by the Live Update SDK. | 8.3.0 |
+| **`checksum`**         | <code>string</code>                     | The checksum of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the checksum will be returned as response header when downloading the bundle.      | 7.1.0 |
+| **`customProperties`** | <code>{ [key: string]: string; }</code> | Custom properties that are associated with the latest bundle.                                                                                                                                   | 7.0.0 |
+| **`downloadUrl`**      | <code>string</code>                     | The URL of the latest bundle to download. Pass this URL to the `downloadBundle(...)` method to download the bundle.                                                                             | 6.7.0 |
+| **`signature`**        | <code>string</code>                     | The signature of the latest bundle if the bundle is self-hosted. If the bundle is hosted on Capawesome Cloud, the signature will be returned as response header when downloading the bundle.    | 7.1.0 |
 
 
 #### FetchLatestBundleOptions
 
-| Prop          | Type                | Description                                                      | Since |
-| ------------- | ------------------- | ---------------------------------------------------------------- | ----- |
-| **`channel`** | <code>string</code> | The name of the channel where the latest bundle is fetched from. | 6.7.0 |
+| Prop          | Type                | Description                                                                                                                                                                                            | Since |
+| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`channel`** | <code>string</code> | The preferred channel name from which the latest bundle should be fetched. This is the SDK preference and may be overridden by a forced channel assignment configured in the Capawesome Cloud Console. | 6.7.0 |
 
 
 #### GetBlockedBundlesResult
@@ -1159,9 +1267,9 @@ Remove all listeners for this plugin.
 
 #### SyncOptions
 
-| Prop          | Type                | Description                                                      | Since |
-| ------------- | ------------------- | ---------------------------------------------------------------- | ----- |
-| **`channel`** | <code>string</code> | The name of the channel where the latest bundle is fetched from. | 6.7.0 |
+| Prop          | Type                | Description                                                                                                                                                                                            | Since |
+| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`channel`** | <code>string</code> | The preferred channel name from which the latest bundle should be fetched. This is the SDK preference and may be overridden by a forced channel assignment configured in the Capawesome Cloud Console. | 6.7.0 |
 
 
 #### PluginListenerHandle
@@ -1241,7 +1349,7 @@ This way, the app will check for updates, but no updates will be found.
 
 ## Limitations
 
-Live updates are only supported for [binary-compatible changes](https://capawesome.io/cloud/live-updates/faq/#what-are-binary-compatible-changes) (e.g. HTML, CSS, JavaScript).
+Live updates are only supported for [binary-compatible changes](https://capawesome.io/docs/cloud/live-updates/faq/#what-are-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 [restrict live updates to compatible native versions](https://capawesome.io/blog/how-to-restrict-capacitor-live-updates-to-native-versions/) of your app.
 
@@ -1259,7 +1367,7 @@ On Capawesome Cloud, the bundle ID corresponds to the ID of the app build artifa
 There are four ways to set a channel, listed from lowest to highest priority:
 
 1. **Capacitor config**: Set the `defaultChannel` property in the [plugin configuration](#configuration). This is the simplest way to set a static default channel.
-2. **Native config**: Set `CapawesomeLiveUpdateDefaultChannel` in `Info.plist` (iOS) or `capawesome_live_update_default_channel` in `strings.xml` (Android). This is useful for [Versioned Channels](https://capawesome.io/cloud/live-updates/guides/best-practices/#versioned-channels) where the channel is tied to the build version.
+2. **Native config**: Set `CapawesomeLiveUpdateDefaultChannel` in `Info.plist` (iOS) or `capawesome_live_update_default_channel` in `strings.xml` (Android). This is useful for [Versioned Channels](https://capawesome.io/docs/cloud/live-updates/guides/best-practices/#versioned-channels) where the channel is tied to the build version.
 3. **[`setChannel(...)`](#setchannel)**: Set the channel at runtime. The value is persisted across app restarts.
 4. **[`sync(...)`](#sync)**: Pass a `channel` option to override the channel for a single sync call. This does **not** persist the channel.
 
@@ -1279,6 +1387,27 @@ You then have three options to get back to the default bundle:
 
 However, this is only a problem during development. It is not a problem in production, as Capacitor automatically resets to the default bundle after a native update.
 
+### Do I have to use Capawesome Cloud?
+
+No, the plugin also supports self-hosted bundles. You can download a bundle from any URL using the [`downloadBundle(...)`](#downloadbundle) method and apply it with [`setNextBundle(...)`](#setnextbundle), without any Capawesome Cloud dependency. Capawesome Cloud is only required for the convenience features such as [`sync(...)`](#sync), channels, and rollouts.
+
+### What changes can I ship with a live update?
+
+Live updates are only supported for [binary-compatible changes](https://capawesome.io/docs/cloud/live-updates/faq/#what-are-binary-compatible-changes) such as HTML, CSS, and JavaScript. If you change native code, for example by adding a new plugin, you need to resubmit your app to the app stores. You should therefore [restrict live updates to compatible native versions](https://capawesome.io/blog/how-to-restrict-capacitor-live-updates-to-native-versions/) of your app, as described in the [Limitations](#limitations) section.
+
+### How does the rollback mechanism work?
+
+If the `readyTimeout` configuration option is set, the plugin waits for the app to call the [`ready()`](#ready) method after a new bundle has been applied. If the method is not called within the configured timeout, the plugin assumes the bundle is faulty and resets the app to the default bundle. It is strongly recommended to configure `readyTimeout` (e.g. `10000` ms). Additionally, with the `autoBlockRolledBackBundles` option enabled, bundles that caused a rollback are automatically blocked and skipped in future sync operations.
+
+## Related Plugins
+
+- [App Update](https://capawesome.io/docs/sdks/capacitor/app-update/): Assist users with native app updates, which are required for changes that are not binary-compatible.
+- [Firebase Remote Config](https://capawesome.io/docs/sdks/capacitor/firebase/remote-config/): Change the behavior and appearance of your app remotely without publishing an update.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/live-update/CHANGELOG.md).

package/android/build.gradle

@@ -1,3 +1,5 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
 ext {
     junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
     androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
@@ -5,19 +7,23 @@ ext {
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
     okhttp3Version = project.hasProperty('okhttp3Version') ? rootProject.ext.okhttp3Version : '5.3.2'
     zip4jVersion = project.hasProperty('zip4jVersion') ? rootProject.ext.zip4jVersion : '2.11.5'
+    ionicLiveUpdateProviderVersion = project.hasProperty('ionicLiveUpdateProviderVersion') ? rootProject.ext.ionicLiveUpdateProviderVersion : '1.0.0'
 }
 
 buildscript {
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
     repositories {
         google()
         mavenCentral()
     }
     dependencies {
         classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
 
 apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
 
 android {
     namespace = "io.capawesome.capacitorjs.plugins.liveupdate"
@@ -28,6 +34,7 @@ android {
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        consumerProguardFiles 'consumer-rules.pro'
     }
     buildTypes {
         release {
@@ -44,6 +51,12 @@ android {
     }
 }
 
+kotlin {
+    compilerOptions {
+        jvmTarget = JvmTarget.JVM_21
+    }
+}
+
 repositories {
     google()
     mavenCentral()
@@ -56,6 +69,10 @@ dependencies {
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation "net.lingala.zip4j:zip4j:$zip4jVersion"
     implementation "com.squareup.okhttp3:okhttp:$okhttp3Version"
+    // The Ionic Live Update Provider SDK is compile-time only: Federated Capacitor
+    // and Ionic Portals bring it transitively at runtime, and the provider classes
+    // are only loaded when a host actually calls `createManager`.
+    compileOnly "io.ionic:liveupdateprovider:$ionicLiveUpdateProviderVersion"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"