@capawesome/capacitor-live-update 8.6.0 → 8.7.0

package/CapawesomeCapacitorLiveUpdate.podspec

@@ -17,4 +17,19 @@ Pod::Spec.new do |s|
   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", .upToNextMajor(from: "5.10.2")),
-        .package(url: "https://github.com/weichsel/ZIPFoundation.git", .upToNextMinor(from: "0.9.0"))
+        .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,8 +28,17 @@ 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"]))
+            ])
+    ],
+    swiftLanguageModes: [.v5]
 )

package/README.md

@@ -3,8 +3,8 @@
 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.
 
 <div class="capawesome-z29o10a">
-  <a href="https://cloud.capawesome.io/" target="_blank">
-    <img alt="Deliver Live Updates to your Capacitor app with Capawesome Cloud" src="https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1" />
+  <a href="https://capawesome.io/" target="_blank">
+    <img alt="Ship a fix in one command with Capawesome Cloud Live Updates, no store review" src="https://capawesome.io/assets/banners/cloud-ship-a-fix-in-one-command.png" />
   </a>
 </div>
 
@@ -25,6 +25,8 @@ The Capacitor Live Update plugin is one of the most feature-rich Over-the-Air (O
 - 📡 **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.
@@ -114,6 +116,8 @@ 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`)
+- `$kotlinxCoroutinesVersion` version of `org.jetbrains.kotlinx:kotlinx-coroutines-android` (default: `1.11.0`)
 - `$okhttp3Version` version of `com.squareup.okhttp3:okhttp` and `com.squareup.okhttp3:okhttp-brotli` (default: `5.3.2`)
 - `$zip4jVersion` version of `net.lingala.zip4j:zip4j` (default: `2.11.5`)
 
@@ -160,6 +164,31 @@ 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.
 
+#### Swift Package Manager
+
+##### Package traits
+
+The Ionic Live Update Provider SDK is optional and is not included by default. If you use this plugin as a live update provider for Ionic Portals or Federated Capacitor, enable the `IonicProvider` package trait so that the SDK is linked into your app:
+
+```json
+{
+  "experimental": {
+    "ios": {
+      "spm": {
+        "swiftToolsVersion": "6.1",
+        "packageTraits": {
+          "@capawesome/capacitor-live-update": ["IonicProvider"]
+        }
+      }
+    }
+  }
+}
+```
+
+This trait is the Swift Package Manager equivalent of the `CapawesomeCapacitorLiveUpdate/IonicProvider` CocoaPods subspec. See [Ionic Live Update Provider SDK Integration](#ionic-live-update-provider-sdk-integration) for details.
+
+**Attention**: SPM trait support requires Capacitor CLI **8.3.0+** and Xcode **16.3+** (Swift 6.1+).
+
 ### Electron
 
 This plugin supports the [Capacitor Electron platform](https://github.com/capawesome-team/capacitor-electron) (`@capawesome/capacitor-electron` version `0.2.0` or later). No additional configuration is required.
@@ -190,6 +219,10 @@ export default defineConfig({
 });
 ```
 
+## 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`. The manager configuration accepts the keys `appId`, `channel`, `publicKey`, `serverDomain` and `httpTimeout`; we recommend enabling code signing via `publicKey` in production. 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>

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,24 @@ 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'
+    kotlinxCoroutinesVersion = project.hasProperty('kotlinxCoroutinesVersion') ? rootProject.ext.kotlinxCoroutinesVersion : '1.11.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 +35,7 @@ android {
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        consumerProguardFiles 'consumer-rules.pro'
     }
     buildTypes {
         release {
@@ -44,6 +52,12 @@ android {
     }
 }
 
+kotlin {
+    compilerOptions {
+        jvmTarget = JvmTarget.JVM_21
+    }
+}
+
 repositories {
     google()
     mavenCentral()
@@ -57,6 +71,11 @@ dependencies {
     implementation "net.lingala.zip4j:zip4j:$zip4jVersion"
     implementation "com.squareup.okhttp3:okhttp:$okhttp3Version"
     implementation "com.squareup.okhttp3:okhttp-brotli:$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"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:$kotlinxCoroutinesVersion"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"

package/android/consumer-rules.pro

@@ -0,0 +1,5 @@
+# The Ionic Live Update Provider SDK is a compileOnly dependency: it is only
+# present at runtime when the app also uses Federated Capacitor or Ionic
+# Portals (which bring it transitively). Suppress R8 missing-class errors for
+# apps that don't.
+-dontwarn io.ionic.liveupdateprovider.**

package/android/src/main/java/io/capawesome/capacitorjs/plugins/liveupdate/LiveUpdate.java

@@ -1,6 +1,7 @@
 package io.capawesome.capacitorjs.plugins.liveupdate;
 
 import android.app.Activity;
+import android.content.Context;
 import android.content.SharedPreferences;
 import android.content.pm.PackageInfo;
 import android.content.pm.PackageManager;
@@ -85,17 +86,22 @@ import org.json.JSONObject;
 
 public class LiveUpdate {
 
+    private static final AtomicBoolean downloadsDirectoryDeleted = new AtomicBoolean(false);
+
     private final long autoUpdateIntervalMs = 15 * 60 * 1000; // 15 minutes
 
     @NonNull
     private final LiveUpdateConfig config;
 
+    @NonNull
+    private final Context context;
+
     private final String defaultWebAssetDir = Bridge.DEFAULT_WEB_ASSET_DIR;
 
     @NonNull
     private final LiveUpdateHttpClient httpClient;
 
-    @NonNull
+    @Nullable
     private final LiveUpdatePlugin plugin;
 
     @NonNull
@@ -115,11 +121,26 @@ public class LiveUpdate {
     private boolean syncInProgress = false;
 
     public LiveUpdate(@NonNull LiveUpdateConfig config, @NonNull LiveUpdatePlugin plugin) throws PackageManager.NameNotFoundException {
+        this(config, plugin.getContext(), plugin);
+    }
+
+    /**
+     * Creates a headless instance without a Capacitor plugin, e.g. for Ionic Portals hosts
+     * that construct a provider manager directly. WebView-related operations (server path
+     * changes, reload) and plugin events are skipped in this mode.
+     */
+    public LiveUpdate(@NonNull LiveUpdateConfig config, @NonNull Context context) throws PackageManager.NameNotFoundException {
+        this(config, context, null);
+    }
+
+    private LiveUpdate(@NonNull LiveUpdateConfig config, @NonNull Context context, @Nullable LiveUpdatePlugin plugin)
+        throws PackageManager.NameNotFoundException {
         this.config = config;
+        this.context = context;
         this.httpClient = new LiveUpdateHttpClient(config);
         this.plugin = plugin;
-        this.preferences = new LiveUpdatePreferences(plugin.getContext());
-        this.webViewSettingsEditor = plugin.getContext().getSharedPreferences(WebView.WEBVIEW_PREFS_NAME, Activity.MODE_PRIVATE).edit();
+        this.preferences = new LiveUpdatePreferences(context);
+        this.webViewSettingsEditor = context.getSharedPreferences(WebView.WEBVIEW_PREFS_NAME, Activity.MODE_PRIVATE).edit();
 
         // Check version and reset config if version changed
         checkAndResetConfigIfVersionChanged();
@@ -127,8 +148,11 @@ public class LiveUpdate {
         // Set the device ID on the HTTP client (after any potential config reset)
         this.httpClient.setDeviceId(getDeviceId());
 
-        // Delete the leftovers of downloads that were interrupted by a process kill
-        tryDeleteDownloadsDirectory();
+        // Delete the leftovers of downloads that were interrupted by a process kill.
+        // Only once per process, because other instances may be downloading at this moment.
+        if (downloadsDirectoryDeleted.compareAndSet(false, true)) {
+            tryDeleteDownloadsDirectory();
+        }
 
         // Start the rollback timer to rollback to the default bundle
         // if the app is not ready after a certain time
@@ -264,6 +288,15 @@ public class LiveUpdate {
         );
     }
 
+    @Nullable
+    public String getAppId() {
+        String appId = preferences.getAppId();
+        if (appId != null) {
+            return appId;
+        }
+        return config.getAppId();
+    }
+
     public void getBlockedBundles(@NonNull NonEmptyCallback<GetBlockedBundlesResult> callback) {
         String blockedIds = preferences.getBlockedBundleIds();
         String[] bundleIds;
@@ -294,6 +327,22 @@ public class LiveUpdate {
         callback.success(result);
     }
 
+    @Nullable
+    public String getChannel() {
+        String channel = null;
+        if (config.getDefaultChannel() != null) {
+            channel = config.getDefaultChannel();
+        }
+        String nativeChannel = getNativeChannel();
+        if (nativeChannel != null) {
+            channel = nativeChannel;
+        }
+        if (preferences.getChannel() != null) {
+            channel = preferences.getChannel();
+        }
+        return channel;
+    }
+
     public void getConfig(@NonNull NonEmptyCallback<GetConfigResult> callback) {
         String appId = getAppId();
         String autoUpdateStrategy = config.getAutoUpdateStrategy();
@@ -307,6 +356,17 @@ public class LiveUpdate {
         callback.success(result);
     }
 
+    /**
+     * @return The on-disk directory of a downloaded bundle, or `null` if the bundle does not exist.
+     */
+    @Nullable
+    public File getBundleDirectory(@NonNull String bundleId) {
+        if (!hasBundleById(bundleId)) {
+            return null;
+        }
+        return buildBundleDirectoryFor(bundleId);
+    }
+
     public void getCustomId(@NonNull NonEmptyCallback callback) {
         String customId = preferences.getCustomId();
         GetCustomIdResult result = new GetCustomIdResult(customId);
@@ -331,6 +391,10 @@ public class LiveUpdate {
         callback.success(result);
     }
 
+    public String getVersionCodeAsString() throws PackageManager.NameNotFoundException {
+        return String.valueOf(getVersionCodeAsInt());
+    }
+
     public void getVersionName(@NonNull NonEmptyCallback callback) throws PackageManager.NameNotFoundException {
         String versionName = getVersionName();
         GetVersionNameResult result = new GetVersionNameResult(versionName);
@@ -529,6 +593,20 @@ public class LiveUpdate {
         );
     }
 
+    /**
+     * @return `true` if the bundle does not exist or was deleted, `false` if it is the current or next bundle.
+     */
+    public boolean tryDeleteUnusedBundle(@NonNull String bundleId) {
+        if (!hasBundleById(bundleId)) {
+            return true;
+        }
+        if (isBundleInUse(bundleId)) {
+            return false;
+        }
+        deleteBundleById(bundleId);
+        return true;
+    }
+
     private void addBundle(@NonNull String bundleId, @NonNull File sourceDirectory) throws Exception {
         // Search folder with index.html file
         File indexHtmlFile = searchIndexHtmlFile(sourceDirectory);
@@ -542,7 +620,8 @@ public class LiveUpdate {
         // Move the bundle directory to the bundles directory
         File bundleDirectory = buildBundleDirectoryFor(bundleId);
         boolean moved = indexHtmlFile.getParentFile().renameTo(bundleDirectory);
-        if (!moved) {
+        // A concurrent download of the same bundle may have finished first
+        if (!moved && !hasBundleById(bundleId)) {
             throw new Exception(LiveUpdatePlugin.ERROR_BUNDLE_MOVE_FAILED);
         }
     }
@@ -559,15 +638,15 @@ public class LiveUpdate {
     }
 
     private File buildBundlesDirectory() {
-        return new File(plugin.getContext().getFilesDir(), bundlesDirectory);
+        return new File(context.getFilesDir(), bundlesDirectory);
     }
 
     private File buildBundleDirectoryFor(@NonNull String bundleId) {
-        return new File(plugin.getContext().getFilesDir(), bundlesDirectory + "/" + bundleId);
+        return new File(context.getFilesDir(), bundlesDirectory + "/" + bundleId);
     }
 
     private File buildDownloadsDirectory() {
-        return new File(plugin.getContext().getCacheDir(), downloadsDirectory);
+        return new File(context.getCacheDir(), downloadsDirectory);
     }
 
     private void copyCurrentBundleFile(@NonNull ManifestItem fileToCopy, @NonNull File destinationDirectory) throws IOException {
@@ -575,7 +654,7 @@ public class LiveUpdate {
         String currentBundleId = getCurrentBundleId();
         if (currentBundleId == null) {
             // Create the source input stream
-            AssetManager assets = plugin.getContext().getAssets();
+            AssetManager assets = context.getAssets();
             InputStream inputStream = assets.open(defaultWebAssetDir + "/" + href);
             // Create the destination file
             File destination = new File(destinationDirectory, href);
@@ -1003,18 +1082,20 @@ public class LiveUpdate {
         @NonNull NonEmptyCallback<GetLatestBundleResponse> callback
     ) {
         try {
+            String appId = requireAppId(options.getAppId());
+            String bundleId = options.getBundleId() == null ? getCurrentBundleId() : options.getBundleId();
             String channel = options.getChannel() == null ? getChannel() : options.getChannel();
             String url = new HttpUrl.Builder()
                 .scheme("https")
                 .host(config.getServerDomain())
                 .addPathSegment("v1")
                 .addPathSegment("apps")
-                .addPathSegment(requireAppId())
+                .addPathSegment(appId)
                 .addPathSegment("bundles")
                 .addPathSegment("latest")
                 .addQueryParameter("appVersionCode", getVersionCodeAsString())
                 .addQueryParameter("appVersionName", getVersionName())
-                .addQueryParameter("bundleId", getCurrentBundleId())
+                .addQueryParameter("bundleId", bundleId)
                 .addQueryParameter("channelName", channel)
                 .addQueryParameter("customId", preferences.getCustomId())
                 .addQueryParameter("deviceId", getDeviceId())
@@ -1096,41 +1177,13 @@ public class LiveUpdate {
         return checksum.toString();
     }
 
-    @Nullable
-    private String getAppId() {
-        String appId = preferences.getAppId();
-        if (appId != null) {
-            return appId;
-        }
-        return config.getAppId();
-    }
-
-    @Nullable
-    private String getChannel() {
-        String channel = null;
-        if (config.getDefaultChannel() != null) {
-            channel = config.getDefaultChannel();
-        }
-        String nativeChannel = getNativeChannel();
-        if (nativeChannel != null) {
-            channel = nativeChannel;
-        }
-        if (preferences.getChannel() != null) {
-            channel = preferences.getChannel();
-        }
-        return channel;
-    }
-
     @Nullable
     private String getNativeChannel() {
-        int resId = plugin
-            .getContext()
-            .getResources()
-            .getIdentifier("capawesome_live_update_default_channel", "string", plugin.getContext().getPackageName());
+        int resId = context.getResources().getIdentifier("capawesome_live_update_default_channel", "string", context.getPackageName());
         if (resId == 0) {
             return null;
         }
-        return plugin.getContext().getResources().getString(resId);
+        return context.getResources().getString(resId);
     }
 
     /**
@@ -1149,6 +1202,10 @@ public class LiveUpdate {
      * @return The absolute path to the current bundle directory (`public` for the built-in bundle).
      */
     private String getCurrentCapacitorServerPath() {
+        if (plugin == null) {
+            // Headless mode: there is no WebView, so the default bundle is always current.
+            return defaultWebAssetDir;
+        }
         return plugin.getBridge().getServerBasePath();
     }
 
@@ -1183,8 +1240,7 @@ public class LiveUpdate {
      */
     @NonNull
     private String getNextCapacitorServerPath() {
-        String path = plugin
-            .getContext()
+        String path = context
             .getSharedPreferences(WebView.WEBVIEW_PREFS_NAME, Activity.MODE_PRIVATE)
             .getString(WebView.CAP_SERVER_PATH, defaultWebAssetDir);
         // Empty path means default path
@@ -1206,10 +1262,6 @@ public class LiveUpdate {
         return (int) PackageInfoCompat.getLongVersionCode(getPackageInfo());
     }
 
-    private String getVersionCodeAsString() throws PackageManager.NameNotFoundException {
-        return String.valueOf(getVersionCodeAsInt());
-    }
-
     private String getVersionName() throws PackageManager.NameNotFoundException {
         return getPackageInfo().versionName;
     }
@@ -1238,7 +1290,7 @@ public class LiveUpdate {
     private Manifest loadCurrentManifest() throws Exception {
         String currentBundleId = getCurrentBundleId();
         if (currentBundleId == null) {
-            AssetManager assets = plugin.getContext().getAssets();
+            AssetManager assets = context.getAssets();
             boolean manifestFileExists = Arrays.asList(assets.list(defaultWebAssetDir)).contains(manifestFileName);
             if (manifestFileExists) {
                 InputStream inputStream = assets.open(defaultWebAssetDir + "/" + manifestFileName);
@@ -1270,6 +1322,9 @@ public class LiveUpdate {
     }
 
     private void notifyDownloadBundleProgressListeners(@NonNull final DownloadBundleProgressEvent event) {
+        if (plugin == null) {
+            return;
+        }
         plugin.notifyDownloadBundleProgressListeners(event);
     }
 
@@ -1303,7 +1358,12 @@ public class LiveUpdate {
 
     @NonNull
     private String requireAppId() throws Exception {
-        String appId = getAppId();
+        return requireAppId(null);
+    }
+
+    @NonNull
+    private String requireAppId(@Nullable String appIdOverride) throws Exception {
+        String appId = appIdOverride == null ? getAppId() : appIdOverride;
         if (appId == null || appId.isEmpty()) {
             throw new Exception(LiveUpdatePlugin.ERROR_APP_ID_MISSING);
         }
@@ -1365,6 +1425,10 @@ public class LiveUpdate {
     }
 
     private void setCurrentCapacitorServerPath(@NonNull String path) {
+        if (plugin == null) {
+            // Headless mode: there is no WebView to point at the new path.
+            return;
+        }
         if (path.equals(defaultWebAssetDir)) {
             this.plugin.getBridge().setServerAssetPath(path);
         } else {
@@ -1391,11 +1455,17 @@ public class LiveUpdate {
     }
 
     private void notifyNextBundleSetListeners(@Nullable String bundleId) {
+        if (plugin == null) {
+            return;
+        }
         NextBundleSetEvent event = new NextBundleSetEvent(bundleId);
         plugin.notifyNextBundleSetListeners(event);
     }
 
     private void notifyReloadedListeners() {
+        if (plugin == null) {
+            return;
+        }
         plugin.notifyReloadedListeners();
     }
 
@@ -1552,11 +1622,11 @@ public class LiveUpdate {
     }
 
     private PackageInfo getPackageInfo() throws PackageManager.NameNotFoundException {
-        String packageName = this.plugin.getContext().getPackageName();
+        String packageName = this.context.getPackageName();
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-            return this.plugin.getContext().getPackageManager().getPackageInfo(packageName, PackageManager.PackageInfoFlags.of(0));
+            return this.context.getPackageManager().getPackageInfo(packageName, PackageManager.PackageInfoFlags.of(0));
         } else {
-            return this.plugin.getContext().getPackageManager().getPackageInfo(packageName, 0);
+            return this.context.getPackageManager().getPackageInfo(packageName, 0);
         }
     }
 }

package/android/src/main/java/io/capawesome/capacitorjs/plugins/liveupdate/LiveUpdatePlugin.java

@@ -1,5 +1,6 @@
 package io.capawesome.capacitorjs.plugins.liveupdate;
 
+import android.content.Context;
 import android.webkit.WebView;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
@@ -32,14 +33,18 @@ import io.capawesome.capacitorjs.plugins.liveupdate.classes.results.IsSyncingRes
 import io.capawesome.capacitorjs.plugins.liveupdate.interfaces.EmptyCallback;
 import io.capawesome.capacitorjs.plugins.liveupdate.interfaces.NonEmptyCallback;
 import io.capawesome.capacitorjs.plugins.liveupdate.interfaces.Result;
+import io.capawesome.capacitorjs.plugins.liveupdate.providers.ionic.LiveUpdateIonicManager;
+import io.ionic.liveupdateprovider.ProviderError;
+import java.util.Map;
 
 @CapacitorPlugin(name = "LiveUpdate")
 public class LiveUpdatePlugin extends Plugin {
 
     public static final String TAG = "LiveUpdate";
-    public static final String VERSION = "8.6.0";
+    public static final String VERSION = "8.7.0";
     public static final String SHARED_PREFERENCES_NAME = "CapawesomeLiveUpdate"; // DO NOT CHANGE
     public static final String ERROR_APP_ID_MISSING = "appId must be configured.";
+    public static final String ERROR_BUNDLE_DIRECTORY_NOT_FOUND = "Bundle directory could not be resolved.";
     public static final String ERROR_BUNDLE_EXISTS = "bundle already exists.";
     public static final String ERROR_BUNDLE_ID_MISSING = "bundleId must be provided.";
     public static final String ERROR_BUNDLE_INDEX_HTML_MISSING = "The bundle does not contain an index.html file.";
@@ -49,7 +54,9 @@ public class LiveUpdatePlugin extends Plugin {
     public static final String ERROR_CHECKSUM_MISMATCH = "Checksum mismatch.";
     public static final String ERROR_CUSTOM_ID_MISSING = "customId must be provided.";
     public static final String ERROR_DOWNLOAD_FAILED = "Bundle could not be downloaded.";
+    public static final String ERROR_DOWNLOAD_URL_MISSING = "Bundle does not have a valid download URL.";
     public static final String ERROR_HTTP_TIMEOUT = "Request timed out.";
+    public static final String ERROR_PLUGIN_NOT_INITIALIZED = "Plugin is not initialized.";
     public static final String ERROR_URL_MISSING = "url must be provided.";
     public static final String ERROR_SIGNATURE_VERIFICATION_FAILED = "Signature verification failed.";
     public static final String ERROR_PUBLIC_KEY_INVALID = "Invalid public key.";
@@ -73,6 +80,29 @@ public class LiveUpdatePlugin extends Plugin {
         }
     }
 
+    /**
+     * Creates a manager for the Ionic Live Update Provider SDK. Invoked natively by
+     * Federated Capacitor after resolving this plugin by its Capacitor plugin name.
+     *
+     * The SDK is a compileOnly dependency, so this class must load without it:
+     * - It does NOT implement the SDK's `LiveUpdateProvider` interface, because superinterfaces
+     *   are resolved when the class is loaded.
+     * - The return type is `Object` instead of `ProviderManager`, because Capacitor calls
+     *   `Class.getDeclaredMethods()` on every plugin class at load, which resolves the return
+     *   and parameter types of all declared methods.
+     *
+     * Federated Capacitor falls back to resolving `createManager(Context, Map)` reflectively by
+     * name and parameter types and casts the result, so neither must change. SDK types are only
+     * referenced inside the method body, which is resolved lazily.
+     */
+    @NonNull
+    public Object createManager(@NonNull Context context, @NonNull Map<String, ?> configuration) throws ProviderError.InvalidConfiguration {
+        if (implementation == null) {
+            throw new ProviderError.InvalidConfiguration(ERROR_PLUGIN_NOT_INITIALIZED, null);
+        }
+        return new LiveUpdateIonicManager(context, configuration, implementation);
+    }
+
     @Override
     protected void handleOnResume() {
         super.handleOnResume();

package/android/src/main/java/io/capawesome/capacitorjs/plugins/liveupdate/classes/options/DownloadBundleOptions.java

@@ -28,11 +28,17 @@ public class DownloadBundleOptions {
         @Nullable String signature,
         @NonNull String url
     ) {
-        if (artifactType.equals("manifest")) {
-            this.artifactType = ArtifactType.MANIFEST;
-        } else {
-            this.artifactType = ArtifactType.ZIP;
-        }
+        this(artifactType.equals("manifest") ? ArtifactType.MANIFEST : ArtifactType.ZIP, bundleId, checksum, signature, url);
+    }
+
+    public DownloadBundleOptions(
+        @NonNull ArtifactType artifactType,
+        @NonNull String bundleId,
+        @Nullable String checksum,
+        @Nullable String signature,
+        @NonNull String url
+    ) {
+        this.artifactType = artifactType;
         this.bundleId = bundleId;
         this.checksum = checksum;
         this.signature = signature;