@capgo/capacitor-updater 8.46.1 → 8.47.0

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

@@ -7,8 +7,7 @@
 package ee.forgr.capacitor_updater;
 
 import android.app.Activity;
-import android.app.ActivityManager;
-import android.app.ApplicationExitInfo;
+import android.app.AlertDialog;
 import android.content.Context;
 import android.content.Intent;
 import android.content.SharedPreferences;
@@ -87,6 +86,12 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private static final String STATS_URL_PREF_KEY = "CapacitorUpdater.statsUrl";
     private static final String CHANNEL_URL_PREF_KEY = "CapacitorUpdater.channelUrl";
     private static final String DEFAULT_CHANNEL_PREF_KEY = "CapacitorUpdater.defaultChannel";
+    private static final String PREVIEW_SESSION_PREF_KEY = "CapacitorUpdater.previewSession";
+    private static final String PREVIEW_PREVIOUS_SHAKE_MENU_PREF_KEY = "CapacitorUpdater.previewPreviousShakeMenu";
+    private static final String PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY = "CapacitorUpdater.previewPreviousShakeChannelSelector";
+    private static final String PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY = "CapacitorUpdater.previewPreviousNextBundle";
+    private static final String PREVIEW_PREVIOUS_APP_ID_PREF_KEY = "CapacitorUpdater.previewPreviousAppId";
+    private static final String PREVIEW_APP_ID_PREF_KEY = "CapacitorUpdater.previewAppId";
     private static final String[] BREAKING_EVENT_NAMES = { "breakingAvailable", "majorAvailable" };
     private static final String LAST_FAILED_BUNDLE_PREF_KEY = "CapacitorUpdater.lastFailedBundle";
     private static final String LAST_REPORTED_APP_EXIT_TIMESTAMP_PREF_KEY = "CapacitorUpdater.lastReportedAppExitTimestamp";
@@ -95,8 +100,20 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private static final int SPLASH_SCREEN_RETRY_DELAY_MS = 100;
     private static final int SPLASH_SCREEN_MAX_RETRIES = 20;
     private static final long PENDING_BUNDLE_APP_READY_MIN_TIMEOUT_MS = 30000L;
-
-    private final String pluginVersion = "8.46.1";
+    static final int APPLICATION_EXIT_REASON_UNKNOWN = 0;
+    static final int APPLICATION_EXIT_REASON_EXIT_SELF = 1;
+    static final int APPLICATION_EXIT_REASON_SIGNALED = 2;
+    static final int APPLICATION_EXIT_REASON_LOW_MEMORY = 3;
+    static final int APPLICATION_EXIT_REASON_CRASH = 4;
+    static final int APPLICATION_EXIT_REASON_CRASH_NATIVE = 5;
+    static final int APPLICATION_EXIT_REASON_ANR = 6;
+    static final int APPLICATION_EXIT_REASON_INITIALIZATION_FAILURE = 7;
+    static final int APPLICATION_EXIT_REASON_PERMISSION_CHANGE = 8;
+    static final int APPLICATION_EXIT_REASON_EXCESSIVE_RESOURCE_USAGE = 9;
+    static final int APPLICATION_EXIT_REASON_USER_REQUESTED = 10;
+    static final int APPLICATION_EXIT_REASON_DEPENDENCY_DIED = 12;
+
+    private final String pluginVersion = "8.47.0";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -126,7 +143,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private volatile boolean onLaunchDirectUpdateUsed = false;
     Boolean shakeMenuEnabled = false;
     Boolean shakeChannelSelectorEnabled = false;
+    Boolean previewSessionEnabled = false;
+    private Boolean previewSessionAlertPending = false;
     private Boolean allowManualBundleError = false;
+    private Boolean allowPreview = false;
     Boolean allowSetDefaultChannel = true;
 
     String getUpdateUrl() {
@@ -411,6 +431,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 "appId is missing in capacitor.config.json or plugin config, and cannot be retrieved from the native app, please add it globally or in the plugin config"
             );
         }
+        this.allowPreview = this.getConfig().getBoolean("allowPreview", false);
         logger.info("appId: " + implementation.appId);
 
         this.persistCustomId = this.getConfig().getBoolean("persistCustomId", false);
@@ -499,12 +520,30 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.implementation.timeout = this.getConfig().getInt("responseTimeout", 20) * 1000;
         this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
         this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
+        this.previewSessionEnabled = Boolean.TRUE.equals(this.allowPreview) && this.prefs.getBoolean(PREVIEW_SESSION_PREF_KEY, false);
+        if (!Boolean.TRUE.equals(this.allowPreview) && this.prefs.getBoolean(PREVIEW_SESSION_PREF_KEY, false)) {
+            this.clearPreviewSessionBecauseDisabled();
+        }
+        this.implementation.previewSession = Boolean.TRUE.equals(this.previewSessionEnabled);
+        if (Boolean.TRUE.equals(this.previewSessionEnabled)) {
+            final String previewAppId = this.prefs.getString(PREVIEW_APP_ID_PREF_KEY, "");
+            if (previewAppId != null && !previewAppId.isEmpty()) {
+                this.setActiveAppId(previewAppId);
+                logger.info("Using preview appId " + previewAppId);
+            }
+            this.shakeMenuEnabled = true;
+            this.shakeChannelSelectorEnabled = false;
+        }
         boolean resetWhenUpdate = this.getConfig().getBoolean("resetWhenUpdate", true);
 
         // Check if app was recently installed/updated BEFORE cleanupObsoleteVersions updates LatestVersionNative
         this.wasRecentlyInstalledOrUpdated = this.checkIfRecentlyInstalledOrUpdated();
+        final boolean nativeBuildVersionChanged = this.hasNativeBuildVersionChanged();
 
         this.implementation.autoReset(this.currentBuildVersion, resetWhenUpdate);
+        if (nativeBuildVersionChanged) {
+            this.clearPreviewSessionForNativeBuildChange();
+        }
         this.reportPreviousAppExitReasons();
         this.reportPreviousWebViewRenderProcessGone();
         this.installWebViewStatsReporter();
@@ -850,66 +889,38 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return false;
     }
 
+    private boolean hasNativeBuildVersionChanged() {
+        final String lastKnownVersion = this.getStoredNativeBuildVersion();
+        return !lastKnownVersion.isEmpty() && !lastKnownVersion.equals(this.currentBuildVersion);
+    }
+
     private void reportPreviousAppExitReasons() {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R || this.implementation == null || this.implementation.statsUrl.isEmpty()) {
             return;
         }
 
-        try {
-            final ActivityManager activityManager = (ActivityManager) this.getContext().getSystemService(Context.ACTIVITY_SERVICE);
-            if (activityManager == null) {
-                return;
-            }
-
-            final List<ApplicationExitInfo> exitReasons = activityManager.getHistoricalProcessExitReasons(
-                this.getContext().getPackageName(),
-                0,
-                8
-            );
-            if (exitReasons == null || exitReasons.isEmpty()) {
-                return;
-            }
-
-            final long lastReportedTimestamp = this.prefs.getLong(LAST_REPORTED_APP_EXIT_TIMESTAMP_PREF_KEY, 0L);
-            long newestReportedTimestamp = lastReportedTimestamp;
-            final BundleInfo current = this.implementation.getCurrentBundle();
-            final String versionName = current == null ? "" : current.getVersionName();
-
-            for (final ApplicationExitInfo exitInfo : exitReasons) {
-                if (exitInfo == null || exitInfo.getTimestamp() <= lastReportedTimestamp) {
-                    continue;
-                }
-
-                final String action = statsActionForApplicationExitReason(exitInfo.getReason());
-                if (action == null) {
-                    continue;
-                }
-
-                this.implementation.sendStats(action, versionName, "", buildApplicationExitMetadata(exitInfo));
-                newestReportedTimestamp = Math.max(newestReportedTimestamp, exitInfo.getTimestamp());
-            }
-
-            if (newestReportedTimestamp > lastReportedTimestamp) {
-                this.prefs.edit().putLong(LAST_REPORTED_APP_EXIT_TIMESTAMP_PREF_KEY, newestReportedTimestamp).apply();
-            }
-        } catch (final Exception e) {
-            logger.warn("Unable to report previous app exit reason: " + e.getMessage());
-        }
+        AndroidAppExitReporter.reportPreviousAppExitReasons(
+            this.getContext(),
+            this.prefs,
+            this.implementation,
+            this.logger,
+            LAST_REPORTED_APP_EXIT_TIMESTAMP_PREF_KEY
+        );
     }
 
     static String statsActionForApplicationExitReason(final int reason) {
         switch (reason) {
-            case ApplicationExitInfo.REASON_CRASH:
+            case APPLICATION_EXIT_REASON_CRASH:
                 return "app_crash";
-            case ApplicationExitInfo.REASON_CRASH_NATIVE:
+            case APPLICATION_EXIT_REASON_CRASH_NATIVE:
                 return "app_crash_native";
-            case ApplicationExitInfo.REASON_ANR:
+            case APPLICATION_EXIT_REASON_ANR:
                 return "app_anr";
-            case ApplicationExitInfo.REASON_LOW_MEMORY:
+            case APPLICATION_EXIT_REASON_LOW_MEMORY:
                 return "app_killed_low_memory";
-            case ApplicationExitInfo.REASON_EXCESSIVE_RESOURCE_USAGE:
+            case APPLICATION_EXIT_REASON_EXCESSIVE_RESOURCE_USAGE:
                 return "app_killed_excessive_resource_usage";
-            case ApplicationExitInfo.REASON_INITIALIZATION_FAILURE:
+            case APPLICATION_EXIT_REASON_INITIALIZATION_FAILURE:
                 return "app_initialization_failure";
             default:
                 return null;
@@ -918,58 +929,34 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
     static String applicationExitReasonName(final int reason) {
         switch (reason) {
-            case ApplicationExitInfo.REASON_EXIT_SELF:
+            case APPLICATION_EXIT_REASON_EXIT_SELF:
                 return "exit_self";
-            case ApplicationExitInfo.REASON_SIGNALED:
+            case APPLICATION_EXIT_REASON_SIGNALED:
                 return "signaled";
-            case ApplicationExitInfo.REASON_LOW_MEMORY:
+            case APPLICATION_EXIT_REASON_LOW_MEMORY:
                 return "low_memory";
-            case ApplicationExitInfo.REASON_CRASH:
+            case APPLICATION_EXIT_REASON_CRASH:
                 return "crash";
-            case ApplicationExitInfo.REASON_CRASH_NATIVE:
+            case APPLICATION_EXIT_REASON_CRASH_NATIVE:
                 return "crash_native";
-            case ApplicationExitInfo.REASON_ANR:
+            case APPLICATION_EXIT_REASON_ANR:
                 return "anr";
-            case ApplicationExitInfo.REASON_INITIALIZATION_FAILURE:
+            case APPLICATION_EXIT_REASON_INITIALIZATION_FAILURE:
                 return "initialization_failure";
-            case ApplicationExitInfo.REASON_PERMISSION_CHANGE:
+            case APPLICATION_EXIT_REASON_PERMISSION_CHANGE:
                 return "permission_change";
-            case ApplicationExitInfo.REASON_EXCESSIVE_RESOURCE_USAGE:
+            case APPLICATION_EXIT_REASON_EXCESSIVE_RESOURCE_USAGE:
                 return "excessive_resource_usage";
-            case ApplicationExitInfo.REASON_USER_REQUESTED:
+            case APPLICATION_EXIT_REASON_USER_REQUESTED:
                 return "user_requested";
-            case ApplicationExitInfo.REASON_DEPENDENCY_DIED:
+            case APPLICATION_EXIT_REASON_DEPENDENCY_DIED:
                 return "dependency_died";
             default:
                 return "unknown";
         }
     }
 
-    private static Map<String, String> buildApplicationExitMetadata(final ApplicationExitInfo exitInfo) {
-        final Map<String, String> metadata = new HashMap<>();
-        metadata.put("exit_reason", applicationExitReasonName(exitInfo.getReason()));
-        metadata.put("exit_reason_code", Integer.toString(exitInfo.getReason()));
-        metadata.put("exit_status", Integer.toString(exitInfo.getStatus()));
-        metadata.put("exit_importance", Integer.toString(exitInfo.getImportance()));
-        metadata.put("exit_timestamp", Long.toString(exitInfo.getTimestamp()));
-        metadata.put("pid", Integer.toString(exitInfo.getPid()));
-        metadata.put("pss_kb", Long.toString(exitInfo.getPss()));
-        metadata.put("rss_kb", Long.toString(exitInfo.getRss()));
-
-        final String processName = exitInfo.getProcessName();
-        if (processName != null && !processName.isEmpty()) {
-            metadata.put("process_name", truncateStatsMetadataValue(processName, 128));
-        }
-
-        final String description = exitInfo.getDescription();
-        if (description != null && !description.isEmpty()) {
-            metadata.put("exit_description", truncateStatsMetadataValue(description, 512));
-        }
-
-        return metadata;
-    }
-
-    private static String truncateStatsMetadataValue(final String value, final int maxLength) {
+    static String truncateStatsMetadataValue(final String value, final int maxLength) {
         return value.length() <= maxLength ? value : value.substring(0, maxLength);
     }
 
@@ -1104,6 +1091,19 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return map;
     }
 
+    private static JSObject jsonObjectToJSObject(final JSONObject json) throws JSONException {
+        final JSObject ret = new JSObject();
+        final JSONArray names = json.names();
+        if (names == null) {
+            return ret;
+        }
+        for (int i = 0; i < names.length(); i++) {
+            final String key = names.getString(i);
+            ret.put(key, json.get(key));
+        }
+        return ret;
+    }
+
     @PluginMethod
     public void reportWebViewError(final PluginCall call) {
         final JSObject data = call.getData();
@@ -2051,6 +2051,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
                         }
                         this.notifyBundleSet(next);
                         this.implementation.setNextBundle(null);
+                        this.showPreviewSessionNoticeIfNeeded();
                         call.resolve();
                         return;
                     }
@@ -2062,6 +2063,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 }
 
                 if (this._reload()) {
+                    this.showPreviewSessionNoticeIfNeeded();
                     call.resolve();
                 } else {
                     logger.error("Reload failed");
@@ -2116,6 +2118,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 } else {
                     logger.info("Bundle successfully set to " + id);
                     this.notifyBundleSet(this.implementation.getBundleInfo(id));
+                    this.showPreviewSessionNoticeIfNeeded();
                     call.resolve();
                 }
             } catch (final Exception e) {
@@ -2125,6 +2128,308 @@ public class CapacitorUpdaterPlugin extends Plugin {
         });
     }
 
+    @PluginMethod
+    public void startPreviewSession(final PluginCall call) {
+        if (!Boolean.TRUE.equals(this.allowPreview)) {
+            logger.error("startPreviewSession not allowed set allowPreview in your config to true to enable it");
+            call.reject("startPreviewSession not allowed");
+            return;
+        }
+        final String previewAppId = this.normalizePreviewAppId(call.getString("appId"));
+        startNewThread(() -> {
+            try {
+                if (!Boolean.TRUE.equals(this.previewSessionEnabled)) {
+                    final BundleInfo current = this.implementation.getCurrentBundle();
+                    if (!this.implementation.setPreviewFallbackBundle(current.getId())) {
+                        logger.error("Could not save current bundle as preview fallback");
+                        call.reject("Could not save current bundle as preview fallback");
+                        return;
+                    }
+
+                    final BundleInfo previousNext = this.implementation.getNextBundle();
+                    if (previousNext == null || previousNext.isDeleted() || previousNext.isErrorStatus()) {
+                        this.editor.remove(PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY);
+                    } else {
+                        this.editor.putString(PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY, previousNext.getId());
+                    }
+
+                    this.editor.putString(PREVIEW_PREVIOUS_APP_ID_PREF_KEY, this.implementation.appId);
+                    this.editor.putBoolean(PREVIEW_PREVIOUS_SHAKE_MENU_PREF_KEY, Boolean.TRUE.equals(this.shakeMenuEnabled));
+                    this.editor.putBoolean(
+                        PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY,
+                        Boolean.TRUE.equals(this.shakeChannelSelectorEnabled)
+                    );
+                    logger.info("Preview session started with fallback bundle: " + current);
+                }
+
+                if (previewAppId != null) {
+                    this.setActiveAppId(previewAppId);
+                    this.editor.putString(PREVIEW_APP_ID_PREF_KEY, previewAppId);
+                    logger.info("Preview session using appId: " + previewAppId);
+                }
+
+                this.previewSessionEnabled = true;
+                this.previewSessionAlertPending = true;
+                this.implementation.previewSession = true;
+                this.shakeMenuEnabled = true;
+                this.shakeChannelSelectorEnabled = false;
+                this.editor.putBoolean(PREVIEW_SESSION_PREF_KEY, true);
+                this.editor.apply();
+                this.ensureShakeMenuStarted();
+                call.resolve();
+            } catch (final Exception e) {
+                logger.error("Could not start preview session " + e.getMessage());
+                call.reject("Could not start preview session", e);
+            }
+        });
+    }
+
+    public boolean leavePreviewSessionFromShakeMenu() {
+        final BundleInfo previewBundle = this.implementation.getCurrentBundle();
+
+        final boolean didReset = this.resetToPreviewFallbackBundle();
+        if (!didReset) {
+            return false;
+        }
+
+        if (!this.clearPreviewChannelOverride()) {
+            return false;
+        }
+        final BundleInfo previewFallbackBundle = this.implementation.getPreviewFallbackBundle();
+        this.endPreviewSession();
+        final BundleInfo restoredNextBundle = this.implementation.getNextBundle();
+        if (
+            !previewBundle.isBuiltin() &&
+            (previewFallbackBundle == null || !previewBundle.getId().equals(previewFallbackBundle.getId())) &&
+            (restoredNextBundle == null || !previewBundle.getId().equals(restoredNextBundle.getId()))
+        ) {
+            try {
+                this.implementation.delete(previewBundle.getId(), false);
+            } catch (final Exception err) {
+                logger.warn("Cannot delete preview bundle " + previewBundle.getId() + ": " + err.getMessage());
+            }
+        }
+        return true;
+    }
+
+    public boolean reloadPreviewSessionFromShakeMenu() {
+        return this._reload();
+    }
+
+    public boolean hasActivePreviewSession() {
+        return Boolean.TRUE.equals(this.previewSessionEnabled);
+    }
+
+    private boolean resetToPreviewFallbackBundle() {
+        final BundleInfo fallback = this.implementation.getPreviewFallbackBundle();
+        if (fallback == null || fallback.isErrorStatus()) {
+            logger.error("No preview fallback bundle available");
+            return false;
+        }
+        if (!this.implementation.canSet(fallback)) {
+            logger.error("Preview fallback bundle is not installable");
+            return false;
+        }
+
+        final CapgoUpdater.ResetState previousState = this.implementation.captureResetState();
+        final String previousBundleName = this.implementation.getCurrentBundle().getVersionName();
+        logger.info("Resetting to preview fallback bundle: " + fallback.getVersionName());
+        if (this.implementation.stagePreviewFallbackReload(fallback) && this._reload()) {
+            this.implementation.finalizeResetTransition(previousBundleName, false);
+            this.notifyBundleSet(fallback);
+            return true;
+        }
+        this.implementation.restoreResetState(previousState);
+        this.restoreLiveBundleStateAfterFailedReload();
+        return false;
+    }
+
+    private void endPreviewSession() {
+        final boolean previousShakeMenuEnabled = this.prefs.getBoolean(
+            PREVIEW_PREVIOUS_SHAKE_MENU_PREF_KEY,
+            this.getConfig().getBoolean("shakeMenu", false)
+        );
+        final boolean previousShakeChannelSelectorEnabled = this.prefs.getBoolean(
+            PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY,
+            this.getConfig().getBoolean("allowShakeChannelSelector", false)
+        );
+        this.restorePreviewPreviousNextBundle();
+        this.restorePreviewPreviousAppId();
+
+        this.previewSessionEnabled = false;
+        this.previewSessionAlertPending = false;
+        this.implementation.previewSession = false;
+        this.shakeMenuEnabled = previousShakeMenuEnabled;
+        this.shakeChannelSelectorEnabled = previousShakeChannelSelectorEnabled;
+        this.implementation.setPreviewFallbackBundle(null);
+        this.clearPreviewSessionPreferences();
+        logger.info("Preview session ended");
+    }
+
+    private void clearPreviewSessionBecauseDisabled() {
+        logger.info("Preview session disabled by config; restoring preview fallback");
+        final BundleInfo fallback = this.implementation.getPreviewFallbackBundle();
+        final BundleInfo bundleToRestore = fallback == null || fallback.isErrorStatus()
+            ? this.implementation.getBundleInfo(BundleInfo.ID_BUILTIN)
+            : fallback;
+
+        if (this.implementation.canSet(bundleToRestore)) {
+            this.implementation.stagePreviewFallbackReload(bundleToRestore);
+        } else {
+            logger.warn("Could not restore preview fallback while disabling preview");
+        }
+
+        this.restorePreviewPreviousNextBundle();
+        this.restorePreviewPreviousAppId();
+        this.previewSessionEnabled = false;
+        this.previewSessionAlertPending = false;
+        this.implementation.previewSession = false;
+        this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
+        this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
+        this.clearPreviewSessionPreferences();
+    }
+
+    private void clearPreviewSessionPreferences() {
+        if (this.implementation != null) {
+            this.implementation.setPreviewFallbackBundle(null);
+        }
+        this.editor.remove(PREVIEW_SESSION_PREF_KEY);
+        this.editor.remove(PREVIEW_PREVIOUS_SHAKE_MENU_PREF_KEY);
+        this.editor.remove(PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY);
+        this.editor.remove(PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY);
+        this.editor.remove(PREVIEW_PREVIOUS_APP_ID_PREF_KEY);
+        this.editor.remove(PREVIEW_APP_ID_PREF_KEY);
+        this.editor.apply();
+    }
+
+    private void setActiveAppId(final String appId) {
+        this.implementation.appId = appId;
+        if (this.implementation.versionOs != null) {
+            DownloadService.updateUserAgent(this.implementation.appId, this.pluginVersion, this.implementation.versionOs);
+        }
+    }
+
+    private void restorePreviewPreviousAppId() {
+        final String previousAppId = this.prefs.getString(PREVIEW_PREVIOUS_APP_ID_PREF_KEY, "");
+        if (previousAppId == null || previousAppId.isEmpty()) {
+            return;
+        }
+        this.setActiveAppId(previousAppId);
+        logger.info("Restored appId after preview: " + previousAppId);
+    }
+
+    private String normalizePreviewAppId(final String rawAppId) {
+        if (rawAppId == null) {
+            return null;
+        }
+
+        final String appId = rawAppId.trim();
+        if (appId.isEmpty()) {
+            return null;
+        }
+
+        final String lowercasedAppId = appId.toLowerCase(java.util.Locale.ROOT);
+        if ("undefined".equals(lowercasedAppId) || "null".equals(lowercasedAppId)) {
+            return null;
+        }
+
+        return appId;
+    }
+
+    private void clearPreviewSessionForNativeBuildChange() {
+        if (!Boolean.TRUE.equals(this.previewSessionEnabled) && this.implementation.getPreviewFallbackBundle() == null) {
+            return;
+        }
+        logger.info("Native build changed; clearing preview session state");
+        this.previewSessionEnabled = false;
+        this.previewSessionAlertPending = false;
+        this.implementation.previewSession = false;
+        this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
+        this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
+        this.restorePreviewPreviousAppId();
+        this.implementation.setPreviewFallbackBundle(null);
+        this.implementation.setNextBundle(null);
+        this.clearPreviewChannelOverride();
+        this.clearPreviewSessionPreferences();
+    }
+
+    private boolean clearPreviewChannelOverride() {
+        final String configDefaultChannel = this.getConfig().getString("defaultChannel", "");
+        final AtomicReference<Map<String, Object>> unsetChannelResult = new AtomicReference<>();
+        try {
+            this.implementation.unsetChannel(this.editor, DEFAULT_CHANNEL_PREF_KEY, configDefaultChannel, unsetChannelResult::set);
+        } catch (final Exception err) {
+            logger.error("Could not clear preview channel override: " + err.getMessage());
+            return false;
+        }
+
+        final Map<String, Object> result = unsetChannelResult.get();
+        if (result == null) {
+            logger.error("Could not clear preview channel override: no result");
+            return false;
+        }
+        if (result.containsKey("error")) {
+            final Object message = result.getOrDefault("message", result.get("error"));
+            logger.error("Could not clear preview channel override: " + message);
+            return false;
+        }
+        return true;
+    }
+
+    private void restorePreviewPreviousNextBundle() {
+        final String previousNextBundleId = this.prefs.getString(PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY, null);
+        if (previousNextBundleId == null || previousNextBundleId.isEmpty()) {
+            this.implementation.setNextBundle(null);
+            return;
+        }
+        if (!this.implementation.setNextBundle(previousNextBundleId)) {
+            logger.warn("Could not restore pre-preview next bundle: " + previousNextBundleId);
+            this.implementation.setNextBundle(null);
+        }
+    }
+
+    private void ensureShakeMenuStarted() {
+        if (getActivity() instanceof com.getcapacitor.BridgeActivity && shakeMenu == null) {
+            try {
+                shakeMenu = new ShakeMenu(this, (com.getcapacitor.BridgeActivity) getActivity(), logger);
+                logger.info("Shake menu initialized");
+            } catch (Exception e) {
+                logger.error("Failed to initialize shake menu: " + e.getMessage());
+            }
+        }
+    }
+
+    private void showPreviewSessionNoticeIfNeeded() {
+        if (!Boolean.TRUE.equals(this.previewSessionEnabled) || !Boolean.TRUE.equals(this.previewSessionAlertPending)) {
+            return;
+        }
+        this.previewSessionAlertPending = false;
+
+        new Handler(Looper.getMainLooper()).postDelayed(
+            () -> {
+                try {
+                    if (!Boolean.TRUE.equals(this.previewSessionEnabled)) {
+                        return;
+                    }
+                    if (getActivity() == null || getActivity().isFinishing()) {
+                        this.previewSessionAlertPending = true;
+                        return;
+                    }
+
+                    new AlertDialog.Builder(getActivity())
+                        .setTitle("Preview started")
+                        .setMessage("Shake your device anytime to reload or leave the test app.")
+                        .setPositiveButton("Got it", (dialog, which) -> dialog.dismiss())
+                        .show();
+                } catch (final Exception e) {
+                    this.previewSessionAlertPending = true;
+                    logger.warn("Could not show preview session notice: " + e.getMessage());
+                }
+            },
+            600
+        );
+    }
+
     @PluginMethod
     public void delete(final PluginCall call) {
         final String id = call.getString("id");
@@ -2206,37 +2511,121 @@ public class CapacitorUpdaterPlugin extends Plugin {
     @PluginMethod
     public void getLatest(final PluginCall call) {
         final String channel = call.getString("channel");
-        startNewThread(() ->
-            CapacitorUpdaterPlugin.this.implementation.getLatest(CapacitorUpdaterPlugin.this.updateUrl, channel, (res) -> {
-                JSObject jsRes = InternalUtils.mapToJSObject(res);
-                if (jsRes.has("error") || jsRes.has("kind")) {
-                    String error = jsRes.has("error") ? jsRes.getString("error") : "";
-                    String errorMessage = jsRes.has("message") ? jsRes.getString("message") : "server did not provide a message";
-                    String kind = CapacitorUpdaterPlugin.this.getUpdateResponseKind(jsRes.has("kind") ? jsRes.getString("kind") : null);
-                    String latestVersion = jsRes.has("version") ? jsRes.getString("version") : "";
-                    jsRes.put("kind", kind);
-                    CapacitorUpdaterPlugin.this.notifyBreakingEventsIfNeeded(jsRes, latestVersion);
-                    if ("failed".equals(kind)) {
-                        logger.error("getLatest failed with error: " + error + ", message: " + errorMessage);
-                        call.reject(error.isEmpty() ? errorMessage : error);
-                    } else {
-                        if (!jsRes.has("version") || jsRes.getString("version").isEmpty()) {
-                            jsRes.put("version", CapacitorUpdaterPlugin.this.implementation.getCurrentBundle().getVersionName());
-                        }
-                        logger.info("getLatest returned " + kind + ": " + errorMessage);
-                        call.resolve(jsRes);
-                    }
-                    return;
-                } else if (jsRes.has("message")) {
-                    String latestVersion = jsRes.has("version") ? jsRes.getString("version") : "";
-                    CapacitorUpdaterPlugin.this.notifyBreakingEventsIfNeeded(jsRes, latestVersion);
-                    call.reject(jsRes.getString("message"));
-                    return;
+        final boolean includeBundleSize = call.getBoolean("includeBundleSize", false);
+        final String previewAppId = this.normalizePreviewAppId(call.getString("appId"));
+        final boolean hasPreviewAppId = previewAppId != null;
+        if (hasPreviewAppId && !Boolean.TRUE.equals(this.allowPreview)) {
+            logger.error("getLatest preview override not allowed set allowPreview in your config to true to enable it");
+            call.reject("getLatest preview override not allowed");
+            return;
+        }
+
+        final Callback latestCallback = (res) -> {
+            JSObject jsRes = InternalUtils.mapToJSObject(res);
+            if (jsRes.has("error") || jsRes.has("kind")) {
+                String error = jsRes.has("error") ? jsRes.getString("error") : "";
+                String errorMessage = jsRes.has("message") ? jsRes.getString("message") : "server did not provide a message";
+                String kind = CapacitorUpdaterPlugin.this.getUpdateResponseKind(jsRes.has("kind") ? jsRes.getString("kind") : null);
+                String latestVersion = jsRes.has("version") ? jsRes.getString("version") : "";
+                jsRes.put("kind", kind);
+                CapacitorUpdaterPlugin.this.notifyBreakingEventsIfNeeded(jsRes, latestVersion);
+                if ("failed".equals(kind)) {
+                    logger.error("getLatest failed with error: " + error + ", message: " + errorMessage);
+                    call.reject(error.isEmpty() ? errorMessage : error);
                 } else {
+                    if (!jsRes.has("version") || jsRes.getString("version").isEmpty()) {
+                        jsRes.put("version", CapacitorUpdaterPlugin.this.implementation.getCurrentBundle().getVersionName());
+                    }
+                    logger.info("getLatest returned " + kind + ": " + errorMessage);
                     call.resolve(jsRes);
                 }
-            })
-        );
+                return;
+            } else if (jsRes.has("message")) {
+                String latestVersion = jsRes.has("version") ? jsRes.getString("version") : "";
+                CapacitorUpdaterPlugin.this.notifyBreakingEventsIfNeeded(jsRes, latestVersion);
+                call.reject(jsRes.getString("message"));
+                return;
+            } else {
+                if (includeBundleSize) {
+                    CapacitorUpdaterPlugin.this.attachBundleSize(jsRes);
+                }
+                call.resolve(jsRes);
+            }
+        };
+
+        startNewThread(() -> {
+            if (hasPreviewAppId) {
+                CapacitorUpdaterPlugin.this.implementation.getLatest(
+                    CapacitorUpdaterPlugin.this.updateUrl,
+                    channel,
+                    previewAppId,
+                    latestCallback
+                );
+                return;
+            }
+            CapacitorUpdaterPlugin.this.implementation.getLatest(CapacitorUpdaterPlugin.this.updateUrl, channel, latestCallback);
+        });
+    }
+
+    private void attachBundleSize(final JSObject latest) {
+        try {
+            final JSONArray manifest = latest.optJSONArray("manifest");
+            if (manifest == null || manifest.length() == 0) {
+                return;
+            }
+            final String sessionKey = latest.optString("sessionKey", "");
+            final JSONObject missing = this.implementation.missingBundleFilesResult(manifest, sessionKey);
+            final JSONArray missingManifest = missing.getJSONArray("missing");
+            final JSONObject size = this.implementation.getBundleDownloadSize(
+                this.updateUrl,
+                latest.optString("version", ""),
+                missingManifest
+            );
+            latest.put("missing", missing);
+            latest.put("downloadSize", size);
+        } catch (Exception e) {
+            logger.error("Failed to attach bundle size to getLatest result");
+            logger.debug("Error: " + e.getMessage());
+        }
+    }
+
+    @PluginMethod
+    public void getMissingBundleFiles(final PluginCall call) {
+        final JSONArray manifest = call.getData().optJSONArray("manifest");
+        if (manifest == null) {
+            call.reject("getMissingBundleFiles called without manifest");
+            return;
+        }
+        String sessionKey = call.getString("sessionKey");
+        if (sessionKey == null) {
+            sessionKey = "";
+        }
+        final String finalSessionKey = sessionKey;
+        startNewThread(() -> {
+            try {
+                call.resolve(jsonObjectToJSObject(this.implementation.missingBundleFilesResult(manifest, finalSessionKey)));
+            } catch (Exception e) {
+                call.reject("Could not get missing bundle files", e);
+            }
+        });
+    }
+
+    @PluginMethod
+    public void getBundleDownloadSize(final PluginCall call) {
+        final JSONArray manifest = call.getData().optJSONArray("manifest");
+        if (manifest == null) {
+            call.reject("getBundleDownloadSize called without manifest");
+            return;
+        }
+        final String version = call.getData().optString("version", "");
+        startNewThread(() -> {
+            try {
+                final JSONObject size = this.implementation.getBundleDownloadSize(this.updateUrl, version, manifest);
+                call.resolve(jsonObjectToJSObject(size));
+            } catch (Exception e) {
+                call.reject("Could not get bundle download size", e);
+            }
+        });
     }
 
     public String triggerBackgroundUpdateCheck() {
@@ -3377,7 +3766,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
             call.reject("setAppId called without appId");
             return;
         }
-        this.implementation.appId = appId;
+        this.setActiveAppId(appId);
         call.resolve();
     }