@capgo/capacitor-updater 8.47.3 → 8.47.5

package/README.md

@@ -2200,9 +2200,10 @@ If you don't use backend, you need to provide the URL and version of the bundle.
 
 ##### StartPreviewSessionOptions
 
-| Prop        | Type                | Description                                                                                                                                                                                     | Default                | Since  |
-| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
-| **`appId`** | <code>string</code> | App id to use while the preview session is active. The previous app id is restored when leaving the preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.47.0 |
+| Prop             | Type                | Description                                                                                                                                                                                                                                                               | Default                | Since  |
+| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
+| **`appId`**      | <code>string</code> | App id to use while the preview session is active. The previous app id is restored when leaving the preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.                                                                           | <code>undefined</code> | 8.47.0 |
+| **`payloadUrl`** | <code>string</code> | HTTP(S) URL returning a preview download payload. When provided, the native shake reload action fetches this payload again before reloading so channel previews can move to the latest bundle. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.48.0 |
 
 
 ##### BundleListResult

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

@@ -49,9 +49,13 @@ import com.google.android.play.core.install.model.AppUpdateType;
 import com.google.android.play.core.install.model.InstallStatus;
 import com.google.android.play.core.install.model.UpdateAvailability;
 import io.github.g00fy2.versioncompare.Version;
+import java.io.ByteArrayOutputStream;
 import java.io.IOException;
+import java.io.InputStream;
+import java.net.HttpURLConnection;
 import java.net.MalformedURLException;
 import java.net.URL;
+import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.HashMap;
@@ -98,7 +102,11 @@ public class CapacitorUpdaterPlugin extends Plugin {
     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_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY = "CapacitorUpdater.previewPreviousDefaultChannel";
+    private static final String PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY = "CapacitorUpdater.previewPreviousDefaultChannelWasSet";
     private static final String PREVIEW_APP_ID_PREF_KEY = "CapacitorUpdater.previewAppId";
+    private static final String PREVIEW_PAYLOAD_URL_PREF_KEY = "CapacitorUpdater.previewPayloadUrl";
+    private static final String PREVIEW_SESSION_ALERT_PENDING_PREF_KEY = "CapacitorUpdater.previewSessionAlertPending";
     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";
@@ -120,7 +128,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     static final int APPLICATION_EXIT_REASON_USER_REQUESTED = 10;
     static final int APPLICATION_EXIT_REASON_DEPENDENCY_DIED = 12;
 
-    private final String pluginVersion = "8.47.3";
+    private final String pluginVersion = "8.47.5";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -153,6 +161,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     Boolean shakeChannelSelectorEnabled = false;
     Boolean previewSessionEnabled = false;
     private Boolean previewSessionAlertPending = false;
+    private Boolean isLeavingPreviewForIncomingLink = false;
     private Boolean allowManualBundleError = false;
     private Boolean allowPreview = false;
     Boolean allowSetDefaultChannel = true;
@@ -495,6 +504,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
         this.implementation.previewSession = Boolean.TRUE.equals(this.previewSessionEnabled);
         if (Boolean.TRUE.equals(this.previewSessionEnabled)) {
+            this.previewSessionAlertPending = this.prefs.contains(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY)
+                ? this.prefs.getBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, false)
+                : true;
             final String previewAppId = this.prefs.getString(PREVIEW_APP_ID_PREF_KEY, "");
             if (previewAppId != null && !previewAppId.isEmpty()) {
                 this.setActiveAppId(previewAppId);
@@ -513,6 +525,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
         if (nativeBuildVersionChanged) {
             this.clearPreviewSessionForNativeBuildChange();
         }
+        this.leavePreviewSessionForLaunchIntentIfNeeded();
         this.reportPreviousAppExitReasons();
         this.reportPreviousWebViewRenderProcessGone();
         this.installWebViewStatsReporter();
@@ -527,6 +540,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.delayUpdateUtils.checkCancelDelay(DelayUpdateUtils.CancelDelaySource.KILLED);
 
         this.checkForUpdateAfterDelay();
+        this.showPreviewSessionNoticeIfNeeded();
 
         // On Android 14+ (API 34+), topActivity in RecentTaskInfo returns null due to
         // security restrictions (StrandHogg task hijacking mitigations). Use ProcessLifecycleOwner
@@ -1930,6 +1944,20 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
     }
 
+    private BundleInfo downloadBundle(
+        final String url,
+        final String version,
+        final String sessionKey,
+        final String checksum,
+        final JSONArray manifest
+    ) throws IOException {
+        if (manifest != null) {
+            return this.implementation.downloadManifest(url, version, sessionKey, checksum, manifest);
+        }
+
+        return this.implementation.download(url, version, sessionKey, checksum);
+    }
+
     @PluginMethod
     public void download(final PluginCall call) {
         final String url = call.getString("url");
@@ -1951,20 +1979,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
             logger.info("Downloading " + url);
             startNewThread(() -> {
                 try {
-                    final BundleInfo downloaded;
-                    if (manifest != null) {
-                        // For manifest downloads, we need to handle this asynchronously
-                        // to avoid automatically scheduling/applying the downloaded bundle.
-                        // Manual download must not schedule/apply the bundle automatically.
-                        CapacitorUpdaterPlugin.this.implementation.downloadBackground(url, version, sessionKey, checksum, manifest, false);
-                        // Return immediately with a pending status - the actual result will come via listeners
-                        final String id = CapacitorUpdaterPlugin.this.implementation.randomString();
-                        downloaded = new BundleInfo(id, version, BundleStatus.DOWNLOADING, new Date(System.currentTimeMillis()), "");
-                        call.resolve(InternalUtils.mapToJSObject(downloaded.toJSONMap()));
-                        return;
-                    } else {
-                        downloaded = CapacitorUpdaterPlugin.this.implementation.download(url, version, sessionKey, checksum);
-                    }
+                    final BundleInfo downloaded = this.downloadBundle(url, version, sessionKey, checksum, manifest);
                     if (downloaded.isErrorStatus()) {
                         throw new RuntimeException("Download failed: " + downloaded.getStatus());
                     } else {
@@ -2231,6 +2246,13 @@ public class CapacitorUpdaterPlugin extends Plugin {
             return;
         }
         final String previewAppId = this.normalizePreviewAppId(call.getString("appId"));
+        final String rawPayloadUrl = call.getString("payloadUrl");
+        final String previewPayloadUrl = this.normalizePreviewPayloadUrl(rawPayloadUrl);
+        if (this.hasPreviewPayloadUrl(rawPayloadUrl) && previewPayloadUrl == null) {
+            logger.error("startPreviewSession called with invalid payloadUrl");
+            call.reject("Invalid preview payloadUrl");
+            return;
+        }
         startNewThread(() -> {
             try {
                 if (!Boolean.TRUE.equals(this.previewSessionEnabled)) {
@@ -2249,6 +2271,16 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     }
 
                     this.editor.putString(PREVIEW_PREVIOUS_APP_ID_PREF_KEY, this.implementation.appId);
+                    if (this.prefs.contains(DEFAULT_CHANNEL_PREF_KEY)) {
+                        this.editor.putString(
+                            PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY,
+                            this.prefs.getString(DEFAULT_CHANNEL_PREF_KEY, "")
+                        );
+                        this.editor.putBoolean(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY, true);
+                    } else {
+                        this.editor.remove(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY);
+                        this.editor.putBoolean(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY, false);
+                    }
                     this.editor.putBoolean(PREVIEW_PREVIOUS_SHAKE_MENU_PREF_KEY, Boolean.TRUE.equals(this.shakeMenuEnabled));
                     this.editor.putBoolean(
                         PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY,
@@ -2263,12 +2295,20 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     logger.info("Preview session using appId: " + previewAppId);
                 }
 
+                if (previewPayloadUrl != null) {
+                    this.editor.putString(PREVIEW_PAYLOAD_URL_PREF_KEY, previewPayloadUrl);
+                    logger.info("Preview session using payload URL");
+                } else {
+                    this.editor.remove(PREVIEW_PAYLOAD_URL_PREF_KEY);
+                }
+
                 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.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, true);
                 this.editor.apply();
                 this.ensureShakeMenuStarted();
                 call.resolve();
@@ -2287,12 +2327,61 @@ public class CapacitorUpdaterPlugin extends Plugin {
             return false;
         }
 
-        if (!this.clearPreviewChannelOverride()) {
-            return false;
+        final BundleInfo previewFallbackBundle = this.implementation.getPreviewFallbackBundle();
+        this.endPreviewSession();
+        final BundleInfo restoredNextBundle = this.implementation.getNextBundle();
+        this.deletePreviewBundleIfUnused(previewBundle, previewFallbackBundle, restoredNextBundle);
+        return true;
+    }
+
+    private void leavePreviewSessionForLaunchIntentIfNeeded() {
+        final Intent intent = getActivity() == null ? null : getActivity().getIntent();
+        if (
+            intent == null ||
+            !Intent.ACTION_VIEW.equals(intent.getAction()) ||
+            intent.getData() == null ||
+            !Boolean.TRUE.equals(this.previewSessionEnabled) ||
+            !isPreviewDeepLink(intent.getData()) ||
+            Boolean.TRUE.equals(this.isLeavingPreviewForIncomingLink)
+        ) {
+            return;
         }
+
+        this.isLeavingPreviewForIncomingLink = true;
+        logger.info("Preview deeplink launch detected while preview session is active; restoring fallback before initial load");
+        if (!this.leavePreviewSessionWithoutReload()) {
+            logger.error("Could not leave preview session before initial preview deeplink routing");
+            this.isLeavingPreviewForIncomingLink = false;
+        }
+    }
+
+    private boolean leavePreviewSessionWithoutReload() {
+        final BundleInfo previewBundle = this.implementation.getCurrentBundle();
         final BundleInfo previewFallbackBundle = this.implementation.getPreviewFallbackBundle();
+        if (previewFallbackBundle == null || previewFallbackBundle.isErrorStatus()) {
+            logger.error("No preview fallback bundle available");
+            return false;
+        }
+        if (!this.implementation.canSet(previewFallbackBundle)) {
+            logger.error("Preview fallback bundle is not installable");
+            return false;
+        }
+        if (!this.implementation.stagePreviewFallbackReload(previewFallbackBundle)) {
+            logger.error("Could not stage preview fallback bundle");
+            return false;
+        }
+
         this.endPreviewSession();
         final BundleInfo restoredNextBundle = this.implementation.getNextBundle();
+        this.deletePreviewBundleIfUnused(previewBundle, previewFallbackBundle, restoredNextBundle);
+        return true;
+    }
+
+    private void deletePreviewBundleIfUnused(
+        final BundleInfo previewBundle,
+        final BundleInfo previewFallbackBundle,
+        final BundleInfo restoredNextBundle
+    ) {
         if (
             !previewBundle.isBuiltin() &&
             (previewFallbackBundle == null || !previewBundle.getId().equals(previewFallbackBundle.getId())) &&
@@ -2304,10 +2393,14 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 logger.warn("Cannot delete preview bundle " + previewBundle.getId() + ": " + err.getMessage());
             }
         }
-        return true;
     }
 
     public boolean reloadPreviewSessionFromShakeMenu() {
+        final String payloadUrl = this.storedPreviewPayloadUrl();
+        if (payloadUrl != null) {
+            return this.refreshPreviewSessionFromPayloadUrl(payloadUrl);
+        }
+
         return this._reload();
     }
 
@@ -2350,9 +2443,11 @@ public class CapacitorUpdaterPlugin extends Plugin {
         );
         this.restorePreviewPreviousNextBundle();
         this.restorePreviewPreviousAppId();
+        this.restorePreviewPreviousDefaultChannel();
 
         this.previewSessionEnabled = false;
         this.previewSessionAlertPending = false;
+        this.isLeavingPreviewForIncomingLink = false;
         this.implementation.previewSession = false;
         this.shakeMenuEnabled = previousShakeMenuEnabled;
         this.shakeChannelSelectorEnabled = previousShakeChannelSelectorEnabled;
@@ -2376,8 +2471,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
         this.restorePreviewPreviousNextBundle();
         this.restorePreviewPreviousAppId();
+        this.restorePreviewPreviousDefaultChannel();
         this.previewSessionEnabled = false;
         this.previewSessionAlertPending = false;
+        this.isLeavingPreviewForIncomingLink = false;
         this.implementation.previewSession = false;
         this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
         this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
@@ -2393,7 +2490,11 @@ public class CapacitorUpdaterPlugin extends Plugin {
         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_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY);
+        this.editor.remove(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY);
         this.editor.remove(PREVIEW_APP_ID_PREF_KEY);
+        this.editor.remove(PREVIEW_PAYLOAD_URL_PREF_KEY);
+        this.editor.remove(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY);
         this.editor.apply();
     }
 
@@ -2413,6 +2514,23 @@ public class CapacitorUpdaterPlugin extends Plugin {
         logger.info("Restored appId after preview: " + previousAppId);
     }
 
+    private void restorePreviewPreviousDefaultChannel() {
+        final String configDefaultChannel = this.getConfig().getString("defaultChannel", "");
+        if (this.prefs.getBoolean(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY, false)) {
+            final String previousDefaultChannel = this.prefs.getString(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY, "");
+            this.editor.putString(DEFAULT_CHANNEL_PREF_KEY, previousDefaultChannel);
+            this.implementation.defaultChannel = previousDefaultChannel;
+            this.editor.apply();
+            logger.info("Restored defaultChannel after preview");
+            return;
+        }
+
+        this.editor.remove(DEFAULT_CHANNEL_PREF_KEY);
+        this.implementation.defaultChannel = configDefaultChannel;
+        this.editor.apply();
+        logger.info("Restored defaultChannel after preview to config value");
+    }
+
     private String normalizePreviewAppId(final String rawAppId) {
         if (rawAppId == null) {
             return null;
@@ -2431,6 +2549,146 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return appId;
     }
 
+    private boolean hasPreviewPayloadUrl(final String rawPayloadUrl) {
+        if (rawPayloadUrl == null) {
+            return false;
+        }
+
+        final String payloadUrl = rawPayloadUrl.trim();
+        if (payloadUrl.isEmpty()) {
+            return false;
+        }
+
+        final String lowercasedPayloadUrl = payloadUrl.toLowerCase(java.util.Locale.ROOT);
+        return !"undefined".equals(lowercasedPayloadUrl) && !"null".equals(lowercasedPayloadUrl);
+    }
+
+    private String normalizePreviewPayloadUrl(final String rawPayloadUrl) {
+        if (!this.hasPreviewPayloadUrl(rawPayloadUrl)) {
+            return null;
+        }
+
+        final String payloadUrl = rawPayloadUrl.trim();
+        try {
+            final URL parsedUrl = new URL(payloadUrl);
+            final String protocol = parsedUrl.getProtocol();
+            if (!"https".equals(protocol) && !"http".equals(protocol)) {
+                return null;
+            }
+            return parsedUrl.toString();
+        } catch (final MalformedURLException ignored) {
+            return null;
+        }
+    }
+
+    private String storedPreviewPayloadUrl() {
+        return this.normalizePreviewPayloadUrl(this.prefs.getString(PREVIEW_PAYLOAD_URL_PREF_KEY, null));
+    }
+
+    private String previewPathFromUri(final Uri uri) {
+        if ("capgo".equals(uri.getScheme())) {
+            final String host = uri.getHost();
+            final String path = uri.getPath();
+            return ("/" + (host == null ? "" : host) + (path == null ? "" : path)).replaceAll("/+", "/");
+        }
+
+        return uri.getPath();
+    }
+
+    private boolean isPreviewDeepLink(final Uri uri) {
+        final String path = this.previewPathFromUri(uri);
+        return "/preview/channel".equals(path) || "/preview/bundle".equals(path);
+    }
+
+    private String readResponseBody(final InputStream stream) throws IOException {
+        if (stream == null) {
+            return "";
+        }
+
+        try (InputStream input = stream; ByteArrayOutputStream output = new ByteArrayOutputStream()) {
+            final byte[] buffer = new byte[8192];
+            int read;
+            while ((read = input.read(buffer)) != -1) {
+                output.write(buffer, 0, read);
+            }
+            return output.toString(StandardCharsets.UTF_8.name());
+        }
+    }
+
+    private JSONObject fetchPreviewPayload(final String payloadUrl) throws IOException, JSONException {
+        final HttpURLConnection connection = (HttpURLConnection) new URL(payloadUrl).openConnection();
+        connection.setRequestMethod("GET");
+        connection.setRequestProperty("Accept", "application/json");
+        connection.setConnectTimeout(30000);
+        connection.setReadTimeout(60000);
+
+        try {
+            final int statusCode = connection.getResponseCode();
+            final String body = this.readResponseBody(
+                statusCode >= 200 && statusCode < 300 ? connection.getInputStream() : connection.getErrorStream()
+            );
+            final JSONObject payload = new JSONObject(body);
+            if (statusCode < 200 || statusCode >= 300) {
+                throw new IOException(
+                    payload.optString("message", payload.optString("error", "Preview payload request failed with HTTP " + statusCode))
+                );
+            }
+            return payload;
+        } finally {
+            connection.disconnect();
+        }
+    }
+
+    private BundleInfo downloadPreviewPayloadBundle(final JSONObject payload) throws IOException, JSONException {
+        final String version = payload.optString("version", "").trim();
+        if (version.isEmpty()) {
+            throw new IOException("Preview payload is missing a version");
+        }
+
+        final JSONArray manifest = payload.optJSONArray("manifest");
+        final String url = payload.optString("url", "");
+        if ((url == null || url.isEmpty()) && (manifest == null || manifest.length() == 0)) {
+            throw new IOException("Preview payload is missing download information");
+        }
+
+        return this.downloadBundle(
+            url == null || url.isEmpty() ? "https://404.capgo.app/no.zip" : url,
+            version,
+            payload.optString("sessionKey", ""),
+            payload.optString("checksum", ""),
+            manifest
+        );
+    }
+
+    private boolean refreshPreviewSessionFromPayloadUrl(final String payloadUrl) {
+        try {
+            final JSONObject payload = this.fetchPreviewPayload(payloadUrl);
+            final String version = payload.optString("version", "").trim();
+            if (version.isEmpty()) {
+                throw new IOException("Preview payload is missing a version");
+            }
+
+            if (version.equals(this.implementation.getCurrentBundle().getVersionName())) {
+                logger.info("Preview payload unchanged, reloading current bundle");
+                return this._reload();
+            }
+
+            final BundleInfo next = this.downloadPreviewPayloadBundle(payload);
+            if (next.isErrorStatus()) {
+                throw new IOException("Download failed: " + next.getStatus());
+            }
+            if (!this.implementation.set(next.getId())) {
+                throw new IOException("Downloaded preview bundle cannot be applied");
+            }
+
+            this.notifyBundleSet(next);
+            return this._reload();
+        } catch (final Exception err) {
+            logger.error("Could not refresh preview session: " + err.getMessage());
+            return false;
+        }
+    }
+
     private void clearPreviewSessionForNativeBuildChange() {
         if (!Boolean.TRUE.equals(this.previewSessionEnabled) && this.implementation.getPreviewFallbackBundle() == null) {
             return;
@@ -2438,39 +2696,17 @@ public class CapacitorUpdaterPlugin extends Plugin {
         logger.info("Native build changed; clearing preview session state");
         this.previewSessionEnabled = false;
         this.previewSessionAlertPending = false;
+        this.isLeavingPreviewForIncomingLink = false;
         this.implementation.previewSession = false;
         this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
         this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
         this.restorePreviewPreviousAppId();
+        this.restorePreviewPreviousDefaultChannel();
         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()) {
@@ -2499,6 +2735,8 @@ public class CapacitorUpdaterPlugin extends Plugin {
             return;
         }
         this.previewSessionAlertPending = false;
+        this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, false);
+        this.editor.apply();
 
         new Handler(Looper.getMainLooper()).postDelayed(
             () -> {
@@ -2508,6 +2746,8 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     }
                     if (getActivity() == null || getActivity().isFinishing()) {
                         this.previewSessionAlertPending = true;
+                        this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, true);
+                        this.editor.apply();
                         return;
                     }
 
@@ -2518,6 +2758,8 @@ public class CapacitorUpdaterPlugin extends Plugin {
                         .show();
                 } catch (final Exception e) {
                     this.previewSessionAlertPending = true;
+                    this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, true);
+                    this.editor.apply();
                     logger.warn("Could not show preview session notice: " + e.getMessage());
                 }
             },
@@ -3762,6 +4004,34 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
     }
 
+    @Override
+    protected void handleOnNewIntent(Intent intent) {
+        super.handleOnNewIntent(intent);
+        if (
+            intent == null ||
+            !Intent.ACTION_VIEW.equals(intent.getAction()) ||
+            intent.getData() == null ||
+            !Boolean.TRUE.equals(this.previewSessionEnabled) ||
+            !isPreviewDeepLink(intent.getData()) ||
+            Boolean.TRUE.equals(this.isLeavingPreviewForIncomingLink)
+        ) {
+            return;
+        }
+
+        this.isLeavingPreviewForIncomingLink = true;
+        if (getActivity() != null) {
+            getActivity().setIntent(intent);
+        }
+        logger.info("Preview deeplink received while preview session is active; restoring fallback before routing");
+        startNewThread(() -> {
+            final boolean didLeave = this.leavePreviewSessionFromShakeMenu();
+            if (!didLeave) {
+                logger.error("Could not leave preview session before routing incoming preview deeplink");
+                this.isLeavingPreviewForIncomingLink = false;
+            }
+        });
+    }
+
     @Override
     public void handleOnStart() {
         try {

package/dist/docs.json

@@ -1991,6 +1991,22 @@
           "docs": "App id to use while the preview session is active.\nThe previous app id is restored when leaving the preview session.\nRequires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.",
           "complexTypes": [],
           "type": "string | undefined"
+        },
+        {
+          "name": "payloadUrl",
+          "tags": [
+            {
+              "text": "8.48.0",
+              "name": "since"
+            },
+            {
+              "text": "undefined",
+              "name": "default"
+            }
+          ],
+          "docs": "HTTP(S) URL returning a preview download payload.\nWhen provided, the native shake reload action fetches this payload again\nbefore reloading so channel previews can move to the latest bundle.\nRequires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.",
+          "complexTypes": [],
+          "type": "string | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -1973,6 +1973,15 @@ export interface StartPreviewSessionOptions {
      * @default undefined
      */
     appId?: string;
+    /**
+     * HTTP(S) URL returning a preview download payload.
+     * When provided, the native shake reload action fetches this payload again
+     * before reloading so channel previews can move to the latest bundle.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
+     * @since 8.48.0
+     * @default undefined
+     */
+    payloadUrl?: string;
 }
 export interface AppReadyResult {
     bundle: BundleInfo;