@capgo/capacitor-updater 7.50.2 → 7.51.16

package/android/src/main/java/ee/forgr/capacitor_updater/DownloadWorkerManager.java

@@ -1,6 +1,7 @@
 package ee.forgr.capacitor_updater;
 
 import android.content.Context;
+import android.os.Build;
 import androidx.work.BackoffPolicy;
 import androidx.work.Configuration;
 import androidx.work.Constraints;
@@ -8,9 +9,18 @@ import androidx.work.Data;
 import androidx.work.ExistingWorkPolicy;
 import androidx.work.NetworkType;
 import androidx.work.OneTimeWorkRequest;
+import androidx.work.OutOfQuotaPolicy;
+import androidx.work.WorkInfo;
 import androidx.work.WorkManager;
 import androidx.work.WorkRequest;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 
 public class DownloadWorkerManager {
 
@@ -21,6 +31,7 @@ public class DownloadWorkerManager {
     }
 
     private static volatile boolean isInitialized = false;
+    private static final ExecutorService cancelExecutor = Executors.newSingleThreadExecutor();
 
     private static synchronized void initializeIfNeeded(Context context) {
         if (!isInitialized) {
@@ -120,6 +131,11 @@ public class DownloadWorkerManager {
             .addTag(id)
             .addTag(version)
             .addTag("capacitor_updater_download");
+        // Android 12+ expedited jobs skip the WorkManager delay without a
+        // foreground service. Older APIs require getForegroundInfo().
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            workRequestBuilder.setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST);
+        }
 
         // More aggressive retry policy for emulators
         if (isEmulator) {
@@ -142,17 +158,101 @@ public class DownloadWorkerManager {
 
     public static void cancelVersionDownload(Context context, String version) {
         initializeIfNeeded(context.getApplicationContext());
-        WorkManager.getInstance(context).cancelAllWorkByTag(version);
+        cancelExecutor.execute(() -> cancelVersionDownloadInternal(context, version, false));
+    }
+
+    public static boolean cancelVersionDownloadAndAwait(Context context, String version) {
+        initializeIfNeeded(context.getApplicationContext());
+        Future<?> future = cancelExecutor.submit(() -> cancelVersionDownloadInternal(context, version, true));
+        try {
+            future.get(10, TimeUnit.SECONDS);
+            return true;
+        } catch (TimeoutException e) {
+            future.cancel(true);
+            logger.error("Timed out awaiting version download cancel");
+            return false;
+        } catch (Exception e) {
+            logger.error("Error awaiting version download cancel: " + e.getMessage());
+            return false;
+        }
+    }
+
+    private static Set<String> collectManifestIdsForVersion(WorkManager workManager, String version) {
+        Set<String> downloadIds = new HashSet<>();
+        try {
+            List<WorkInfo> workInfos = workManager.getWorkInfosByTag(version).get();
+            for (WorkInfo workInfo : workInfos) {
+                for (String tag : workInfo.getTags()) {
+                    if (!"capacitor_updater_download".equals(tag) && !version.equals(tag)) {
+                        downloadIds.add(tag);
+                    }
+                }
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException("Interrupted while collecting manifest ids before version cancel", e);
+        } catch (Exception e) {
+            logger.error("Error collecting manifest ids before version cancel: " + e.getMessage());
+        }
+        return downloadIds;
+    }
+
+    private static void clearManifestIds(Set<String> downloadIds) {
+        for (String downloadId : downloadIds) {
+            DataManager.getInstance().clearManifest(downloadId);
+        }
+    }
+
+    private static void cancelVersionDownloadInternal(Context context, String version, boolean awaitFinished) {
+        if (Thread.currentThread().isInterrupted()) {
+            return;
+        }
+        WorkManager workManager = WorkManager.getInstance(context);
+        Set<String> downloadIds = collectManifestIdsForVersion(workManager, version);
+        workManager.cancelAllWorkByTag(version);
+        clearManifestIds(downloadIds);
+        if (awaitFinished) {
+            awaitVersionWorkFinished(workManager, version);
+        }
+    }
+
+    private static void awaitVersionWorkFinished(WorkManager workManager, String version) {
+        for (int i = 0; i < 100; i++) {
+            if (Thread.currentThread().isInterrupted()) {
+                throw new IllegalStateException("Interrupted while waiting for version download cancel");
+            }
+            try {
+                boolean anyActive = workManager
+                    .getWorkInfosByTag(version)
+                    .get()
+                    .stream()
+                    .anyMatch((workInfo) -> !workInfo.getState().isFinished());
+                if (!anyActive) {
+                    return;
+                }
+                Thread.sleep(100);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                throw new IllegalStateException("Interrupted while waiting for download cancel", e);
+            } catch (Exception e) {
+                throw new IllegalStateException("Error waiting for download cancel: " + e.getMessage(), e);
+            }
+        }
+        throw new IllegalStateException("Timed out waiting for version download cancel: " + version);
     }
 
     public static void cancelBundleDownload(Context context, String id, String version) {
         String uniqueWorkName = "bundle_" + id + "_" + version;
         initializeIfNeeded(context.getApplicationContext());
-        WorkManager.getInstance(context).cancelUniqueWork(uniqueWorkName);
+        WorkManager workManager = WorkManager.getInstance(context);
+        workManager.cancelUniqueWork(uniqueWorkName);
+        DataManager.getInstance().clearManifest(id);
     }
 
     public static void cancelAllDownloads(Context context) {
         initializeIfNeeded(context.getApplicationContext());
-        WorkManager.getInstance(context).cancelAllWorkByTag("capacitor_updater_download");
+        WorkManager workManager = WorkManager.getInstance(context);
+        workManager.cancelAllWorkByTag("capacitor_updater_download");
+        DataManager.getInstance().clearAllManifests();
     }
 }

package/android/src/main/java/ee/forgr/capacitor_updater/InternalUtils.java

@@ -22,7 +22,7 @@ public class InternalUtils {
     public static String getPackageName(PackageManager pm, String packageName) {
         try {
             PackageInfo pInfo = getPackageInfoInternal(pm, packageName);
-            return (pInfo != null) ? pInfo.packageName : null;
+            return pInfo != null ? pInfo.packageName : null;
         } catch (PackageManager.NameNotFoundException e) {
             // Exception is handled internally, and null is returned to indicate the package name could not be retrieved
             return null;

package/android/src/main/java/ee/forgr/capacitor_updater/ShakeMenu.java

@@ -13,6 +13,7 @@ import android.hardware.SensorManager;
 import android.text.Editable;
 import android.text.TextWatcher;
 import android.widget.ArrayAdapter;
+import android.widget.Button;
 import android.widget.EditText;
 import android.widget.LinearLayout;
 import android.widget.ListView;
@@ -117,65 +118,8 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
                     isShowing = false;
                     return;
                 }
-                if (Boolean.TRUE.equals(plugin.shakeChannelSelectorEnabled)) {
-                    showCombinedPreviewMenu();
-                    return;
-                }
-                String appName = activity.getPackageManager().getApplicationLabel(activity.getApplicationInfo()).toString();
-                String title = "Preview " + appName + " Menu";
-                String message = "Reload, switch, or leave the current preview.";
-                List<String> actions = new ArrayList<>();
-                actions.add("Reload preview");
-                if (plugin.previewMenuPreviews().length() > 0) {
-                    actions.add("Switch preview");
-                }
-                actions.add("Leave test app");
-                final boolean[] openingNestedSelector = { false };
-                final boolean[] previewActionRunning = { false };
 
-                AlertDialog.Builder builder = new AlertDialog.Builder(activity);
-                builder.setTitle(title);
-                builder.setMessage(message);
-                builder.setItems(actions.toArray(new String[0]), (dialogInterface, which) -> {
-                    AlertDialog dialog = (AlertDialog) dialogInterface;
-                    String action = actions.get(which);
-                    if ("Reload preview".equals(action)) {
-                        previewActionRunning[0] = true;
-                        logger.info("Reloading webview");
-                        runPreviewMenuAction(dialog, "Could not reload the test app.", "Error reloading test app: ", () ->
-                            plugin.reloadPreviewSessionFromShakeMenu()
-                        );
-                    } else if ("Switch preview".equals(action)) {
-                        openingNestedSelector[0] = true;
-                        dialog.dismiss();
-                        showPreviewSelector();
-                    } else {
-                        previewActionRunning[0] = true;
-                        runPreviewMenuAction(dialog, "Could not leave the test app.", "Error leaving test app: ", () ->
-                            plugin.leavePreviewSessionFromShakeMenu()
-                        );
-                    }
-                });
-
-                // Cancel button
-                builder.setNegativeButton(
-                    "Close menu",
-                    new DialogInterface.OnClickListener() {
-                        public void onClick(DialogInterface dialog, int id) {
-                            logger.info("Shake menu cancelled");
-                            dialog.dismiss();
-                            isShowing = false;
-                        }
-                    }
-                );
-
-                AlertDialog dialog = builder.create();
-                dialog.setOnDismissListener((dialogInterface) -> {
-                    if (!openingNestedSelector[0] && !previewActionRunning[0]) {
-                        isShowing = false;
-                    }
-                });
-                dialog.show();
+                showPreviewActionsMenu(Boolean.TRUE.equals(plugin.shakeChannelSelectorEnabled));
             } catch (Exception e) {
                 logger.error("Error showing shake menu: " + e.getMessage());
                 isShowing = false;
@@ -183,65 +127,95 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
         });
     }
 
-    private void showCombinedPreviewMenu() {
-        try {
-            String appName = activity.getPackageManager().getApplicationLabel(activity.getApplicationInfo()).toString();
-            String title = "Preview " + appName + " Menu";
-            String message = "Reload, switch, or leave the current preview.";
-            List<String> actions = new ArrayList<>();
-            actions.add("Reload preview");
-            if (plugin.previewMenuPreviews().length() > 0) {
-                actions.add("Switch preview");
-            }
-            actions.add("Leave test app");
-            actions.add("Switch channel");
-            final boolean[] openingNestedSelector = { false };
-            final boolean[] previewActionRunning = { false };
+    private void showPreviewActionsMenu(boolean includeChannelSelector) {
+        String appName = activity.getPackageManager().getApplicationLabel(activity.getApplicationInfo()).toString();
+        String title = "Preview " + appName + " Menu";
+        String message = "Reload, switch, or leave the current preview.";
+        final boolean[] openingNestedSelector = { false };
+        final boolean[] previewActionRunning = { false };
+        final AlertDialog[] dialogRef = { null };
+        List<Button> buttons = new ArrayList<>();
+
+        LinearLayout layout = new LinearLayout(activity);
+        layout.setOrientation(LinearLayout.VERTICAL);
+        int horizontalPadding = dpToPx(16);
+        int verticalPadding = dpToPx(8);
+        layout.setPadding(horizontalPadding, verticalPadding, horizontalPadding, verticalPadding);
+
+        addPreviewMenuButton(layout, buttons, "Reload preview", () -> {
+            AlertDialog dialog = dialogRef[0];
+            previewActionRunning[0] = true;
+            setPreviewMenuButtonsEnabled(buttons, false);
+            logger.info("Reloading webview");
+            runPreviewMenuAction(dialog, "Could not reload the test app.", "Error reloading test app: ", () ->
+                plugin.reloadPreviewSessionFromShakeMenu()
+            );
+        });
 
-            AlertDialog.Builder builder = new AlertDialog.Builder(activity);
-            builder.setTitle(title);
-            builder.setMessage(message);
-            builder.setItems(actions.toArray(new String[0]), (dialogInterface, which) -> {
-                AlertDialog dialog = (AlertDialog) dialogInterface;
-                String action = actions.get(which);
-                if ("Reload preview".equals(action)) {
-                    previewActionRunning[0] = true;
-                    logger.info("Reloading webview");
-                    runPreviewMenuAction(dialog, "Could not reload the test app.", "Error reloading test app: ", () ->
-                        plugin.reloadPreviewSessionFromShakeMenu()
-                    );
-                } else if ("Leave test app".equals(action)) {
-                    previewActionRunning[0] = true;
-                    runPreviewMenuAction(dialog, "Could not leave the test app.", "Error leaving test app: ", () ->
-                        plugin.leavePreviewSessionFromShakeMenu()
-                    );
-                } else if ("Switch preview".equals(action)) {
-                    openingNestedSelector[0] = true;
-                    dialog.dismiss();
-                    showPreviewSelector();
-                } else {
-                    openingNestedSelector[0] = true;
-                    dialog.dismiss();
-                    showChannelSelector();
-                }
-            });
-            builder.setNegativeButton("Close menu", (dialog, id) -> {
-                logger.info("Shake menu cancelled");
+        if (plugin.previewMenuPreviews().length() > 0) {
+            addPreviewMenuButton(layout, buttons, "Switch preview", () -> {
+                AlertDialog dialog = dialogRef[0];
+                openingNestedSelector[0] = true;
                 dialog.dismiss();
-                isShowing = false;
+                showPreviewSelector();
             });
+        }
 
-            AlertDialog dialog = builder.create();
-            dialog.setOnDismissListener((dialogInterface) -> {
-                if (!openingNestedSelector[0] && !previewActionRunning[0]) {
-                    isShowing = false;
-                }
+        if (includeChannelSelector) {
+            addPreviewMenuButton(layout, buttons, "Switch channel", () -> {
+                AlertDialog dialog = dialogRef[0];
+                openingNestedSelector[0] = true;
+                dialog.dismiss();
+                showChannelSelector();
             });
-            dialog.show();
-        } catch (Exception e) {
-            logger.error("Error showing combined shake menu: " + e.getMessage());
-            isShowing = false;
         }
+
+        addPreviewMenuButton(layout, buttons, "Leave test app", () -> {
+            AlertDialog dialog = dialogRef[0];
+            previewActionRunning[0] = true;
+            setPreviewMenuButtonsEnabled(buttons, false);
+            runPreviewMenuAction(dialog, "Could not leave the test app.", "Error leaving test app: ", () ->
+                plugin.leavePreviewSessionFromShakeMenu()
+            );
+        });
+
+        addPreviewMenuButton(layout, buttons, "Close menu", () -> {
+            AlertDialog dialog = dialogRef[0];
+            if (dialog != null) {
+                logger.info("Shake menu cancelled");
+                dialog.dismiss();
+                isShowing = false;
+            }
+        });
+
+        AlertDialog.Builder builder = new AlertDialog.Builder(activity);
+        builder.setTitle(title);
+        builder.setMessage(message);
+        builder.setView(layout);
+
+        AlertDialog dialog = builder.create();
+        dialogRef[0] = dialog;
+        dialog.setOnDismissListener((dialogInterface) -> {
+            if (!openingNestedSelector[0] && !previewActionRunning[0]) {
+                isShowing = false;
+            }
+        });
+        dialog.show();
+    }
+
+    private void addPreviewMenuButton(LinearLayout layout, List<Button> buttons, String title, Runnable action) {
+        Button button = new Button(activity);
+        button.setAllCaps(false);
+        button.setText(title);
+        LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(
+            LinearLayout.LayoutParams.MATCH_PARENT,
+            LinearLayout.LayoutParams.WRAP_CONTENT
+        );
+        params.setMargins(0, 0, 0, dpToPx(8));
+        button.setLayoutParams(params);
+        button.setOnClickListener((view) -> action.run());
+        buttons.add(button);
+        layout.addView(button);
     }
 
     private void runPreviewMenuAction(AlertDialog dialog, String failureMessage, String errorPrefix, PreviewMenuAction action) {
@@ -262,10 +236,13 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
         }).start();
     }
 
-    private void setPreviewMenuButtonsEnabled(AlertDialog dialog, boolean enabled) {
-        dialog.getButton(AlertDialog.BUTTON_POSITIVE).setEnabled(enabled);
-        dialog.getButton(AlertDialog.BUTTON_NEUTRAL).setEnabled(enabled);
-        dialog.getButton(AlertDialog.BUTTON_NEGATIVE).setEnabled(enabled);
+    private void setPreviewMenuButtonsEnabled(List<Button> buttons, boolean enabled) {
+        for (Button button : buttons) {
+            if (!enabled && "Close menu".equals(button.getText().toString())) {
+                continue;
+            }
+            button.setEnabled(enabled);
+        }
     }
 
     private void showPreviewSelector() {
@@ -299,7 +276,7 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
         String name = preview.optString("name", "");
         JSObject bundle = preview.getJSObject("bundle");
         String version = bundle == null ? "" : bundle.optString("version", "");
-        String label = !name.isEmpty() ? name : (!version.isEmpty() ? version : preview.optString("id", "Preview"));
+        String label = !name.isEmpty() ? name : !version.isEmpty() ? version : preview.optString("id", "Preview");
         if (preview.optBoolean("isActive", false)) {
             label += " (current)";
         }
@@ -819,8 +796,20 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
 
                                 String latestUrl = getString(latestRes, "url");
 
-                                // Check if there's an actual update available
-                                if ("up_to_date".equals(latestKind) || latestUrl == null || latestUrl.isEmpty()) {
+                                Object manifestObj = latestRes.get("manifest");
+                                JSONArray manifestArray = null;
+                                if (manifestObj instanceof JSONArray) {
+                                    manifestArray = (JSONArray) manifestObj;
+                                } else if (manifestObj instanceof List) {
+                                    manifestArray = new JSONArray((List<?>) manifestObj);
+                                }
+                                final boolean hasManifest = manifestArray != null && manifestArray.length() > 0;
+
+                                // Check if there's an actual update available. A manifest-only
+                                // response legitimately has no URL (the files come from the
+                                // manifest, not a zip), so only report "already on latest" when
+                                // the URL is empty AND there is no manifest to download from.
+                                if ("up_to_date".equals(latestKind) || ((latestUrl == null || latestUrl.isEmpty()) && !hasManifest)) {
                                     activity.runOnUiThread(() -> {
                                         progressDialog.dismiss();
                                         showSuccess("Channel set to " + channelName + ". Already on latest version.");
@@ -843,25 +832,18 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
 
                                 String sessionKey = getString(latestRes, "sessionKey");
                                 String checksum = getString(latestRes, "checksum");
-                                Object manifestObj = latestRes.get("manifest");
+
+                                // A manifest-only response has no zip URL; downloadManifest
+                                // tolerates the placeholder URL the plugin already uses.
+                                final String downloadUrl =
+                                    latestUrl == null || latestUrl.isEmpty() ? "https://404.capgo.app/no.zip" : latestUrl;
 
                                 // Download the update
                                 try {
                                     BundleInfo bundle;
-                                    if (manifestObj != null) {
-                                        JSONArray manifestArray = null;
-                                        if (manifestObj instanceof JSONArray) {
-                                            manifestArray = (JSONArray) manifestObj;
-                                        } else if (manifestObj instanceof List) {
-                                            manifestArray = new JSONArray((List<?>) manifestObj);
-                                        }
-
-                                        if (manifestArray == null) {
-                                            throw new IllegalArgumentException("Invalid manifest format");
-                                        }
-
+                                    if (hasManifest) {
                                         bundle = updater.downloadManifest(
-                                            latestUrl,
+                                            downloadUrl,
                                             versionForUi,
                                             sessionKey != null ? sessionKey : "",
                                             checksum != null ? checksum : "",
@@ -869,7 +851,7 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
                                         );
                                     } else {
                                         bundle = updater.download(
-                                            latestUrl,
+                                            downloadUrl,
                                             versionForUi,
                                             sessionKey != null ? sessionKey : "",
                                             checksum != null ? checksum : ""

package/dist/docs.json

@@ -156,7 +156,7 @@
             "text": "{Error} If the download fails or the bundle is invalid."
           }
         ],
-        "docs": "Download a new bundle from the provided URL for later installation.\n\nThe downloaded bundle is stored locally but not activated. To use it:\n- Call {@link next} to set it for installation on next app backgrounding/restart\n- Call {@link set} to activate it immediately (destroys current JavaScript context)\n\nThe URL should point to a zip file containing either:\n- Your app files directly in the zip root, or\n- A single folder containing all your app files\n\nThe bundle must include an `index.html` file at the root level.\n\nFor encrypted bundles, provide the `sessionKey` and `checksum` parameters.\nFor multi-file delta updates, provide the `manifest` array.\n\n**Android Background Runner note:** `@capacitor/background-runner` loads its\nconfigured runner script from native APK assets. Live updates cannot replace\nthat runner script. Keep it stable across OTA updates and ship a native app\nupdate when the runner code changes.",
+        "docs": "Download a new bundle from the provided URL for later installation.\n\nThe downloaded bundle is stored locally but not activated. To use it:\n- Call {@link next} to set it for installation on next app backgrounding/restart\n- Call {@link set} to activate it immediately (destroys current JavaScript context)\n\nThe URL should point to a zip file containing either:\n- Your app files directly in the zip root, or\n- A single folder containing all your app files\n\nThe bundle must include an `index.html` file at the root level.\n\nFor encrypted bundles, provide the `sessionKey` and `checksum` parameters.\nFor multi-file delta updates, provide the `manifest` array.\n\n**Android Background Runner note:** `@capacitor/background-runner` loads its\nconfigured runner script from native APK assets. Live updates cannot replace\nthat runner script. Keep it stable across OTA updates and ship a native app\nupdate when the runner code changes. When a bundle switch happens, Capacitor\nUpdater cancels and reschedules configured Background Runner WorkManager jobs\nand syncs the bundled runner script into native `public/` storage when present.",
         "complexTypes": [
           "BundleInfo",
           "DownloadOptions"
@@ -846,7 +846,7 @@
             "text": "4.7.0"
           }
         ],
-        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the\nselected channel locally on the device. It does not create or update a backend Device Override,\nso the device will not appear as overridden in the Capgo dashboard. Only assignments created\nfrom the dashboard or the Public API are shown in the Device Override UI.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend to validate the specified channel, then stores the\nchannel locally on the device.",
+        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the\nselected channel locally on the device for future app restarts. It does not create or update\na backend Device Override, so the device will not appear as overridden in the Capgo dashboard.\nOnly assignments created from the dashboard or the Public API are shown in the Device Override UI.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend to validate the specified channel, then stores the\nchannel locally on the device for future app restarts.",
         "complexTypes": [
           "ChannelRes",
           "SetChannelOptions"
@@ -911,7 +911,7 @@
             "text": "4.8.0"
           }
         ],
-        "docs": "Get the current channel assigned to this device.\n\nReturns information about:\n- `channel`: The currently assigned channel name (if any)\n- `allowSet`: Whether the channel allows self-assignment\n- `status`: Operation status\n- `error`/`message`: Additional information (if applicable)\n\nUse this to:\n- Display current channel to users (e.g., \"You're on the Beta channel\")\n- Check if a device is on a specific channel before showing features\n- Verify channel assignment after calling {@link setChannel}\n\nOn native platforms, a successful response also refreshes the locally persisted\ndefault channel used by update checks.",
+        "docs": "Get the current channel assigned to this device.\n\nReturns information about:\n- `channel`: The currently assigned channel name (if any)\n- `allowSet`: Whether the channel allows self-assignment\n- `status`: Operation status\n- `error`/`message`: Additional information (if applicable)\n\nUse this to:\n- Display current channel to users (e.g., \"You're on the Beta channel\")\n- Check if a device is on a specific channel before showing features\n- Verify channel assignment after calling {@link setChannel}\n\nOn native platforms, a successful response also refreshes the default channel used by update checks.\nThis refresh is persisted across app restarts.",
         "complexTypes": [
           "GetChannelRes"
         ],
@@ -4468,6 +4468,14 @@
         {
           "text": "'downloading'",
           "complexTypes": []
+        },
+        {
+          "text": "'deleted'",
+          "complexTypes": []
+        },
+        {
+          "text": "'deleting'",
+          "complexTypes": []
         }
       ]
     },
@@ -4575,7 +4583,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the number of seconds the native plugin should wait before considering API timeout.\n\nOnly available for Android and iOS.",
+          "docs": "Configure the number of seconds the native plugin should wait before considering an HTTP timeout.\nApplies to update checks and file downloads. On Android these are idle connect/read/write\ntimeouts and do not cap total download time; on iOS the request timeout also bounds the\ntotal download duration.\n\nOnly available for Android and iOS.",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -4623,7 +4631,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure how the plugin checks for, downloads, and applies live updates.\n\nThe plugin checks for updates when the app moves to the foreground and, if\n{@link periodCheckDelay} is set, on a repeating timer while the app stays open.\n\nBoolean values keep their existing behavior:\n- `true`: Same as `\"atBackground\"`.\n- `false`: Same as `\"off\"`.\n\nString values merge the previous Auto Update and Direct Update configuration:\n- `\"off\"`: Disable automatic update checks.\n- `\"atBackground\"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background.\n- `\"atInstall\"`: Apply immediately only after a fresh install or native app store update; otherwise use `\"atBackground\"` behavior.\n- `\"onLaunch\"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `\"atBackground\"` behavior.\n- `\"always\"`: Check on every foreground transition and apply immediately whenever an update is available.\n- `\"onlyDownload\"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically.\n\nOnly available for Android and iOS.",
+          "docs": "Configure how the plugin checks for, downloads, and applies live updates.\n\nThe plugin checks for updates when the app moves to the foreground. When\n{@link periodCheckDelay} is greater than 0, it also checks on a repeating timer\nwhile the app stays open.\n\nBoolean values keep their existing behavior:\n- `true`: Same as `\"atBackground\"`.\n- `false`: Same as `\"off\"`.\n\nString values merge the previous Auto Update and Direct Update configuration:\n- `\"off\"`: Disable automatic update checks.\n- `\"atBackground\"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background.\n- `\"atInstall\"`: Apply immediately only after a fresh install or native app store update; otherwise use `\"atBackground\"` behavior.\n- `\"onLaunch\"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `\"atBackground\"` behavior.\n- `\"always\"`: Check on every foreground transition and apply immediately whenever an update is available.\n- `\"onlyDownload\"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically.\n\nOnly available for Android and iOS.",
           "complexTypes": [],
           "type": "boolean | 'always' | 'off' | 'atBackground' | 'atInstall' | 'onLaunch' | 'onlyDownload' | undefined"
         },
@@ -4687,7 +4695,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.\nNative stats include update lifecycle events, app health signals such as crashes,\nAndroid ANRs, low-memory exits, iOS memory warnings, and WebView health signals\nsuch as JavaScript errors, unhandled promise rejections, resource load failures,\nWebView renderer exits, and unclean WebView restarts when available.",
+          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.\nNative stats include update lifecycle events, app health signals such as crashes,\nAndroid ANRs, low-memory exits, iOS memory warnings, and WebView health signals\nsuch as JavaScript errors, unhandled promise rejections, resource load failures,\nWebView renderer exits, unclean WebView restarts, app launch readiness timing,\nand WebView load milestones when available.",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -4727,7 +4735,7 @@
           "name": "directUpdate",
           "tags": [
             {
-              "text": "Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.\nWorks well for apps less than 10MB and with uploads done using --delta flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates (use default behavior: download on foreground check, apply when backgrounded)\n- atInstall: Direct update only after app install or native app store update, otherwise act as directUpdate = false\n- onLaunch: Direct update only when the app is brought to the foreground from a killed state, otherwise act as directUpdate = false\n- always: Direct update on every foreground check whenever an update is available, never act as directUpdate = false\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nActivate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.\nOnly available for Android and iOS.",
+              "text": "Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.\nWorks well for apps less than 10MB and with uploads done using --delta flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates\n- atInstall: Same as `\"atInstall\"` for {@link autoUpdate}\n- onLaunch: Same as `\"onLaunch\"` for {@link autoUpdate}\n- always: Same as `\"always\"` for {@link autoUpdate}\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nActivate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.\nOnly available for Android and iOS.",
               "name": "deprecated"
             },
             {
@@ -4807,7 +4815,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the delay period for period update check. the unit is in seconds.\n\nOnly available for Android and iOS.\nCannot be less than 600 seconds (10 minutes).",
+          "docs": "Configure the interval in seconds for repeating update checks while the app stays open.\nForeground checks still run when this is 0. Values below 600 are normalized to 600.\n\nOnly available for Android and iOS.\nCannot be less than 600 seconds (10 minutes).",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -5035,6 +5043,22 @@
           "complexTypes": [],
           "type": "boolean | undefined"
         },
+        {
+          "name": "persistDefaultChannelOnReinstall",
+          "tags": [
+            {
+              "text": "true",
+              "name": "default"
+            },
+            {
+              "text": "8.51.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Keep the default channel stored by {@link CapacitorUpdaterPlugin.setChannel} or refreshed by\n{@link CapacitorUpdaterPlugin.getChannel} when app data is restored into a new app install.\n\n`setChannel()` and a successful `getChannel()` still persist the selected channel across app\nrestarts. When this option is `false`, native startup clears that persisted channel when it\ndetects app data restored into a new installation. Native build cleanup clears the persisted\nchannel only when `persistDefaultChannelOnReinstall` is `false`, `resetWhenUpdate` is `true`,\nand the native build version has changed.\n\nOnly available for Android and iOS.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
         {
           "name": "defaultChannel",
           "tags": [