@capgo/capacitor-updater 8.45.10 → 8.46.0

package/ios/Sources/CapacitorUpdaterPlugin/CapacitorUpdaterPlugin.swift

@@ -47,8 +47,10 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "setMultiDelay", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "cancelDelay", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getLatest", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "triggerUpdateCheck", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "setChannel", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "unsetChannel", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "reportWebViewError", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getChannel", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "listChannels", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "setCustomId", returnType: CAPPluginReturnPromise),
@@ -64,6 +66,8 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "isShakeMenuEnabled", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "setShakeChannelSelector", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "isShakeChannelSelectorEnabled", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getAppId", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setAppId", returnType: CAPPluginReturnPromise),
         // App Store update methods
         CAPPluginMethod(name: "getAppUpdateInfo", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "openAppStore", returnType: CAPPluginReturnPromise),
@@ -72,7 +76,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "completeFlexibleUpdate", returnType: CAPPluginReturnPromise)
     ]
     public var implementation = CapgoUpdater()
-    private let pluginVersion: String = "8.45.10"
+    private let pluginVersion: String = "8.46.0"
     static let updateUrlDefault = "https://plugin.capgo.app/updates"
     static let statsUrlDefault = "https://plugin.capgo.app/stats"
     static let channelUrlDefault = "https://plugin.capgo.app/channel_self"
@@ -128,6 +132,8 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     private var persistModifyUrl = false
     private var allowManualBundleError = false
     private var keepUrlPathFlagLastValue: Bool?
+    private var appHealthTracker: AppHealthTracker?
+    private var webViewStatsReporter: WebViewStatsReporter?
     public var shakeMenuEnabled = false
     public var shakeChannelSelectorEnabled = false
     let semaphoreReady = DispatchSemaphore(value: 0)
@@ -143,6 +149,9 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         } else {
             logger.error("Failed to get webView for logging")
         }
+        let webViewStatsReporter = WebViewStatsReporter(implementation: implementation)
+        self.webViewStatsReporter = webViewStatsReporter
+        webViewStatsReporter.install(on: self.bridge?.webView)
         #if targetEnvironment(simulator)
         logger.info("::::: SIMULATOR :::::")
         logger.info("Application directory: \(NSHomeDirectory())")
@@ -223,17 +232,21 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         resetWhenUpdate = getConfig().getBoolean("resetWhenUpdate", true)
         shakeMenuEnabled = getConfig().getBoolean("shakeMenu", false)
         shakeChannelSelectorEnabled = getConfig().getBoolean("allowShakeChannelSelector", false)
-        let periodCheckDelayValue = getConfig().getInt("periodCheckDelay", 0)
-        if periodCheckDelayValue >= 0 && periodCheckDelayValue > 600 {
-            periodCheckDelay = 600
-        } else {
-            periodCheckDelay = periodCheckDelayValue
-        }
+        periodCheckDelay = Self.normalizedPeriodCheckDelaySeconds(getConfig().getInt("periodCheckDelay", 0))
 
         implementation.setPublicKey(getConfig().getString("publicKey") ?? "")
         implementation.notifyDownloadRaw = notifyDownload
         implementation.notifyListeners = { [weak self] eventName, data in
-            self?.notifyListeners(eventName, data: data)
+            let emit = {
+                self?.notifyListeners(eventName, data: data)
+            }
+            if Thread.isMainThread {
+                emit()
+            } else {
+                DispatchQueue.main.async {
+                    emit()
+                }
+            }
         }
         implementation.pluginVersion = self.pluginVersion
 
@@ -278,12 +291,17 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             implementation.defaultChannel = getConfig().getString("defaultChannel", "")!
         }
         self.implementation.autoReset()
+        let appHealthTracker = AppHealthTracker(implementation: self.implementation)
+        self.appHealthTracker = appHealthTracker
+        appHealthTracker.reportPreviousUncleanForegroundExit()
+        appHealthTracker.startSession()
 
-        // Check if app was recently installed/updated BEFORE cleanupObsoleteVersions updates LatestVersionNative
+        // Check if app was recently installed/updated BEFORE cleanup updates the stored native build version.
         self.wasRecentlyInstalledOrUpdated = self.checkIfRecentlyInstalledOrUpdated()
 
         if resetWhenUpdate {
-            self.cleanupObsoleteVersions()
+            let didResetCurrentBundle = self.resetCurrentBundleForNativeBuildChangeIfNeeded()
+            self.cleanupObsoleteVersions(didResetCurrentBundle: didResetCurrentBundle)
         }
 
         // Load the server
@@ -300,6 +318,8 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         let nc = NotificationCenter.default
         nc.addObserver(self, selector: #selector(appMovedToBackground), name: UIApplication.didEnterBackgroundNotification, object: nil)
         nc.addObserver(self, selector: #selector(appMovedToForeground), name: UIApplication.willEnterForegroundNotification, object: nil)
+        nc.addObserver(self, selector: #selector(appWillTerminate), name: UIApplication.willTerminateNotification, object: nil)
+        nc.addObserver(self, selector: #selector(appDidReceiveMemoryWarning), name: UIApplication.didReceiveMemoryWarningNotification, object: nil)
 
         // Check for 'kill' delay condition on app launch
         // This handles cases where the app was killed (willTerminateNotification is not reliable for system kills)
@@ -356,6 +376,22 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    @objc private func appWillTerminate() {
+        appHealthTracker?.markForeground(false)
+    }
+
+    @objc private func appDidReceiveMemoryWarning() {
+        appHealthTracker?.reportMemoryWarning()
+    }
+
+    @objc func reportWebViewError(_ call: CAPPluginCall) {
+        guard let webViewStatsReporter = webViewStatsReporter else {
+            call.resolve()
+            return
+        }
+        webViewStatsReporter.reportError(call)
+    }
+
     private func initialLoad() -> Bool {
         guard let bridge = self.bridge else { return false }
         if keepUrlPathAfterReload {
@@ -399,7 +435,29 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         semaphoreReady.signal()
     }
 
-    private func cleanupObsoleteVersions() {
+    func storedNativeBuildVersion() -> String {
+        UserDefaults.standard.string(forKey: "LatestNativeBuildVersion") ?? UserDefaults.standard.string(forKey: "LatestVersionNative") ?? "0"
+    }
+
+    func hasNativeBuildVersionChanged() -> Bool {
+        let previous = self.storedNativeBuildVersion()
+        return previous != "0" && self.currentBuildVersion != previous
+    }
+
+    @discardableResult
+    func resetCurrentBundleForNativeBuildChangeIfNeeded() -> Bool {
+        let previous = self.storedNativeBuildVersion()
+        guard previous != "0" && self.currentBuildVersion != previous else {
+            return false
+        }
+
+        // Reset startup state synchronously so initialLoad() boots from the builtin bundle.
+        self.logger.info("Native build version changed from \(previous) to \(self.currentBuildVersion). Resetting startup bundle to builtin.")
+        self.implementation.reset(isInternal: true)
+        return true
+    }
+
+    private func cleanupObsoleteVersions(didResetCurrentBundle: Bool = false) {
         cleanupThread = Thread {
             self.cleanupLock.lock()
             defer {
@@ -434,9 +492,12 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             // 1. Write "LatestVersionNative" - this fixes the part 1 of this bug
             // 2. Compare both keys. If any is not equal to "currentBuildVersion", then revert to builtin version. This fixes the part 2 of this bug
 
-            let previous = UserDefaults.standard.string(forKey: "LatestNativeBuildVersion") ?? UserDefaults.standard.string(forKey: "LatestVersionNative") ?? "0"
+            let previous = self.storedNativeBuildVersion()
             if previous != "0" && self.currentBuildVersion != previous {
-                _ = self._reset(toLastSuccessful: false, usePendingBundle: false)
+                if !didResetCurrentBundle {
+                    self.logger.info("Native build version changed from \(previous) to \(self.currentBuildVersion). Resetting current bundle to builtin.")
+                    self.implementation.reset(isInternal: true)
+                }
                 let res = self.implementation.list()
                 for version in res {
                     // Check if thread was cancelled
@@ -496,11 +557,88 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         logger.info("Cleanup finished, proceeding with download")
     }
 
+    private func resolveCall(_ call: CAPPluginCall, data: PluginCallResultData? = nil) {
+        let resolve = {
+            let savedCall = self.bridge?.savedCall(withID: call.callbackId)
+            let targetCall = savedCall ?? call
+
+            if let data {
+                targetCall.resolve(data)
+            } else {
+                targetCall.resolve()
+            }
+
+            if savedCall != nil {
+                self.bridge?.releaseCall(withID: call.callbackId)
+            }
+        }
+
+        if Thread.isMainThread {
+            resolve()
+        } else {
+            DispatchQueue.main.async {
+                resolve()
+            }
+        }
+    }
+
+    private func rejectCall(_ call: CAPPluginCall, message: String, code: String? = nil, error: Error? = nil, data: PluginCallResultData? = nil) {
+        let reject = {
+            let savedCall = self.bridge?.savedCall(withID: call.callbackId)
+            let targetCall = savedCall ?? call
+
+            targetCall.reject(message, code, error, data)
+
+            if savedCall != nil {
+                self.bridge?.releaseCall(withID: call.callbackId)
+            }
+        }
+
+        if Thread.isMainThread {
+            reject()
+        } else {
+            DispatchQueue.main.async {
+                reject()
+            }
+        }
+    }
+
+    private func saveCallForAsyncHandling(_ call: CAPPluginCall) {
+        bridge?.saveCall(call)
+    }
+
+    private func notifyListenersOnMain(_ eventName: String, data: JSObject) {
+        let notify = {
+            self.notifyListeners(eventName, data: data)
+        }
+
+        if Thread.isMainThread {
+            notify()
+        } else {
+            DispatchQueue.main.async {
+                notify()
+            }
+        }
+    }
+
+    private func bundlePayload(_ bundleInfo: BundleInfo) -> JSObject {
+        var payload: JSObject = [:]
+        for (key, value) in bundleInfo.toJSON() {
+            payload[key] = value
+        }
+        return payload
+    }
+
     @objc func notifyDownload(id: String, percent: Int, ignoreMultipleOfTen: Bool = false, bundle: BundleInfo? = nil) {
         let bundleInfo = bundle ?? self.implementation.getBundleInfo(id: id)
-        self.notifyListeners("download", data: ["percent": percent, "bundle": bundleInfo.toJSON()])
+        var downloadPayload: JSObject = [:]
+        downloadPayload["percent"] = percent
+        downloadPayload["bundle"] = bundlePayload(bundleInfo)
+        self.notifyListenersOnMain("download", data: downloadPayload)
         if percent == 100 {
-            self.notifyListeners("downloadComplete", data: ["bundle": bundleInfo.toJSON()])
+            var downloadCompletePayload: JSObject = [:]
+            downloadCompletePayload["bundle"] = bundlePayload(bundleInfo)
+            self.notifyListenersOnMain("downloadComplete", data: downloadCompletePayload)
             self.implementation.sendStats(action: "download_complete", versionName: bundleInfo.getVersionName())
         } else if percent.isMultiple(of: 10) || ignoreMultipleOfTen {
             self.implementation.sendStats(action: "download_\(percent)", versionName: bundleInfo.getVersionName())
@@ -597,6 +735,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         let manifestArray = call.getArray("manifest")
         let url = URL(string: urlString)
         logger.info("Downloading \(String(describing: url))")
+        self.saveCallForAsyncHandling(call)
         DispatchQueue.global(qos: .background).async {
             do {
                 let next: BundleInfo
@@ -644,13 +783,17 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                 } else {
                     self.logger.info("Good checksum \(next.getChecksum()) \(checksum)")
                 }
-                self.notifyListeners("updateAvailable", data: ["bundle": next.toJSON()])
-                call.resolve(next.toJSON())
+                var updateAvailablePayload: JSObject = [:]
+                updateAvailablePayload["bundle"] = self.bundlePayload(next)
+                self.notifyListenersOnMain("updateAvailable", data: updateAvailablePayload)
+                self.resolveCall(call, data: next.toJSON())
             } catch {
                 self.logger.error("Failed to download from: \(String(describing: url)) \(error.localizedDescription)")
-                self.notifyListeners("downloadFailed", data: ["version": version])
+                var downloadFailedPayload: JSObject = [:]
+                downloadFailedPayload["version"] = version
+                self.notifyListenersOnMain("downloadFailed", data: downloadFailedPayload)
                 self.implementation.sendStats(action: "download_fail")
-                call.reject("Failed to download from: \(url!) - \(error.localizedDescription)")
+                self.rejectCall(call, message: "Failed to download from: \(url!) - \(error.localizedDescription)")
             }
         }
     }
@@ -876,25 +1019,68 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
 
     @objc func getLatest(_ call: CAPPluginCall) {
         let channel = call.getString("channel")
-        DispatchQueue.global(qos: .background).async {
+        self.saveCallForAsyncHandling(call)
+        runGetLatestWork {
             let res = self.implementation.getLatest(url: URL(string: self.updateUrl)!, channel: channel)
-            if res.error != nil {
-                call.reject( res.error!)
-            } else if res.message != nil {
-                call.reject( res.message!)
+            if let error = res.error, !error.isEmpty {
+                let responseKind = self.updateResponseKind(kind: res.kind)
+                res.kind = responseKind
+                if responseKind == "failed" {
+                    self.rejectCall(call, message: error)
+                } else {
+                    if res.version.isEmpty {
+                        res.version = self.implementation.getCurrentBundle().getVersionName()
+                    }
+                    self.resolveCall(call, data: res.toDict())
+                }
+            } else if let kind = res.kind, !kind.isEmpty {
+                let responseKind = self.updateResponseKind(kind: kind)
+                res.kind = responseKind
+                if responseKind != "failed" {
+                    if res.version.isEmpty {
+                        res.version = self.implementation.getCurrentBundle().getVersionName()
+                    }
+                    self.resolveCall(call, data: res.toDict())
+                } else {
+                    self.rejectCall(call, message: res.message ?? "server did not provide a message")
+                }
+            } else if let message = res.message, !message.isEmpty {
+                self.rejectCall(call, message: message)
             } else {
-                call.resolve(res.toDict())
+                self.resolveCall(call, data: res.toDict())
             }
         }
     }
 
+    public func triggerBackgroundUpdateCheck() -> String {
+        guard !self.updateUrl.isEmpty, URL(string: self.updateUrl) != nil else {
+            logger.error("Error no url or wrong format")
+            return "unavailable"
+        }
+        if self.isDownloadStuckOrTimedOut() {
+            logger.info("Download already in progress, skipping duplicate download request")
+            return "already_running"
+        }
+        self.backgroundDownload()
+        return "queued"
+    }
+
+    @objc func triggerUpdateCheck(_ call: CAPPluginCall) {
+        let status = self.triggerBackgroundUpdateCheck()
+        call.resolve([
+            "status": status,
+            "queued": status == "queued"
+        ])
+    }
+
     @objc func unsetChannel(_ call: CAPPluginCall) {
         let triggerAutoUpdate = call.getBool("triggerAutoUpdate", false)
-        DispatchQueue.global(qos: .background).async {
+        self.saveCallForAsyncHandling(call)
+        DispatchQueue.global(qos: .utility).async {
             let configDefaultChannel = self.getConfig().getString("defaultChannel", "")!
             let res = self.implementation.unsetChannel(defaultChannelKey: self.defaultChannelDefaultsKey, configDefaultChannel: configDefaultChannel)
             if res.error != "" {
-                call.reject(res.error, "UNSETCHANNEL_FAILED", nil, [
+                self.rejectCall(call, message: res.error, code: "UNSETCHANNEL_FAILED", data: [
                     "message": res.error,
                     "error": res.error.contains("Channel URL") ? "missing_config" : "request_failed"
                 ])
@@ -908,7 +1094,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                         self.logger.info("Download already in progress, skipping duplicate download request")
                     }
                 }
-                call.resolve(res.toDict())
+                self.resolveCall(call, data: res.toDict())
             }
         }
     }
@@ -923,17 +1109,18 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             return
         }
         let triggerAutoUpdate = call.getBool("triggerAutoUpdate") ?? false
-        DispatchQueue.global(qos: .background).async {
+        self.saveCallForAsyncHandling(call)
+        DispatchQueue.global(qos: .utility).async {
             let res = self.implementation.setChannel(channel: channel, defaultChannelKey: self.defaultChannelDefaultsKey, allowSetDefaultChannel: self.allowSetDefaultChannel)
             if res.error != "" {
                 // Fire channelPrivate event if channel doesn't allow self-assignment
                 if res.error.contains("cannot_update_via_private_channel") || res.error.contains("channel_self_set_not_allowed") {
-                    self.notifyListeners("channelPrivate", data: [
+                    self.notifyListenersOnMain("channelPrivate", data: [
                         "channel": channel,
                         "message": res.error
                     ])
                 }
-                call.reject(res.error, "SETCHANNEL_FAILED", nil, [
+                self.rejectCall(call, message: res.error, code: "SETCHANNEL_FAILED", data: [
                     "message": res.error,
                     "error": res.error.contains("Channel URL") ? "missing_config" : (res.error.contains("cannot_update_via_private_channel") || res.error.contains("channel_self_set_not_allowed")) ? "channel_private" : "request_failed"
                 ])
@@ -947,35 +1134,39 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                         self.logger.info("Download already in progress, skipping duplicate download request")
                     }
                 }
-                call.resolve(res.toDict())
+                self.resolveCall(call, data: res.toDict())
             }
         }
     }
 
     @objc func getChannel(_ call: CAPPluginCall) {
-        DispatchQueue.global(qos: .background).async {
+        self.saveCallForAsyncHandling(call)
+        DispatchQueue.global(qos: .utility).async {
             let res = self.implementation.getChannel()
             if res.error != "" {
-                call.reject(res.error, "GETCHANNEL_FAILED", nil, [
+                self.rejectCall(call, message: res.error, code: "GETCHANNEL_FAILED", data: [
                     "message": res.error,
                     "error": res.error.contains("Channel URL") ? "missing_config" : "request_failed"
                 ])
             } else {
-                call.resolve(res.toDict())
+                self.resolveCall(call, data: res.toDict())
             }
         }
     }
 
     @objc func listChannels(_ call: CAPPluginCall) {
-        DispatchQueue.global(qos: .background).async {
+        self.saveCallForAsyncHandling(call)
+        DispatchQueue.global(qos: .utility).async {
             let res = self.implementation.listChannels()
             if res.error != "" {
-                call.reject(res.error, "LISTCHANNELS_FAILED", nil, [
+                self.rejectCall(call, message: res.error, code: "LISTCHANNELS_FAILED", data: [
                     "message": res.error,
                     "error": res.error.contains("Channel URL") ? "missing_config" : "request_failed"
                 ])
             } else {
-                call.resolve(res.toDict())
+                var payload: JSObject = [:]
+                payload["channels"] = res.channels
+                self.resolveCall(call, data: payload)
             }
         }
     }
@@ -1102,6 +1293,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         let bundle = self.implementation.getCurrentBundle()
         self.implementation.setSuccess(bundle: bundle, autoDeletePrevious: self.autoDeletePrevious)
         logger.info("Current bundle loaded successfully. [notifyAppReady was called] \(bundle.toString())")
+
         call.resolve(["bundle": bundle.toJSON()])
     }
 
@@ -1191,7 +1383,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
 
         logger.info("Current bundle is: \(current.toString())")
 
-        if BundleStatus.SUCCESS.localizedString != current.getStatus() {
+        if BundleStatus.SUCCESS.storedValue != current.getStatus() {
             logger.error("notifyAppReady was not called, roll back current bundle: \(current.toString())")
             logger.error("Did you forget to call 'notifyAppReady()' in your Capacitor App code?")
             self.notifyListeners("updateFailed", data: [
@@ -1572,6 +1764,13 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         plannedDirectUpdate && directUpdateMode == "onLaunch"
     }
 
+    static func normalizedPeriodCheckDelaySeconds(_ value: Int) -> Int {
+        guard value > 0 else {
+            return 0
+        }
+        return max(600, value)
+    }
+
     private func getOnLaunchDirectUpdateUsed() -> Bool {
         self.onLaunchDirectUpdateStateLock.lock()
         defer { self.onLaunchDirectUpdateStateLock.unlock() }
@@ -1601,6 +1800,10 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         self.updateUrl = updateUrl
     }
 
+    func setCurrentBuildVersionForTesting(_ currentBuildVersion: String) {
+        self.currentBuildVersion = currentBuildVersion
+    }
+
     func shouldUseDirectUpdateForTesting() -> Bool {
         self.shouldUseDirectUpdate()
     }
@@ -1618,6 +1821,56 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         self.notifyListeners("majorAvailable", data: payload)
     }
 
+    static func normalizedUpdateResponseKind(kind: String?) -> String {
+        if let kind, ["up_to_date", "blocked", "failed"].contains(kind) {
+            return kind
+        }
+        return "failed"
+    }
+
+    private func updateResponseKind(kind: String?) -> String {
+        Self.normalizedUpdateResponseKind(kind: kind)
+    }
+
+    private func endBackgroundDownloadAfterLatestError(
+        backendError: String,
+        res: AppVersion,
+        current: BundleInfo,
+        plannedDirectUpdate: Bool
+    ) {
+        let statusCode = res.statusCode
+        let responseKind = self.updateResponseKind(kind: res.kind)
+        let responseMessage = res.message?.isEmpty == false ? res.message : nil
+        let message = responseMessage ?? (backendError.isEmpty ? "server did not provide a message" : backendError)
+        let latestVersionName = res.version.isEmpty ? current.getVersionName() : res.version
+        self.notifyListeners("updateCheckResult", data: [
+            "kind": responseKind,
+            "error": backendError,
+            "message": message,
+            "statusCode": statusCode,
+            "version": latestVersionName,
+            "bundle": current.toJSON()
+        ])
+
+        if responseKind == "up_to_date" {
+            self.logger.info("No new version available")
+        } else if responseKind == "blocked" {
+            self.logger.info("Update check blocked with error: \(backendError)")
+        } else {
+            self.logger.error("getLatest failed with error: \(backendError)")
+        }
+
+        let isFailure = responseKind == "failed"
+        self.endBackGroundTaskWithNotif(
+            msg: message,
+            latestVersionName: latestVersionName,
+            current: current,
+            error: isFailure,
+            plannedDirectUpdate: plannedDirectUpdate,
+            sendStats: isFailure
+        )
+    }
+
     func endBackGroundTaskWithNotif(
         msg: String,
         latestVersionName: String,
@@ -1672,6 +1925,26 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     func runBackgroundDownloadWork(_ work: @escaping () -> Void) {
+        // Live update checks/downloads are user-visible work. Using `.background`
+        // lets the scheduler starve them for minutes while the app is active.
+        DispatchQueue.global(qos: .utility).async(execute: work)
+    }
+
+    private func beginDownloadBackgroundTask() {
+        let registerTask = {
+            self.backgroundTaskID = UIApplication.shared.beginBackgroundTask(withName: "Finish Download Tasks") {
+                self.endBackGroundTask()
+            }
+        }
+
+        if Thread.isMainThread {
+            registerTask()
+        } else {
+            DispatchQueue.main.sync(execute: registerTask)
+        }
+    }
+
+    func runGetLatestWork(_ work: @escaping () -> Void) {
         DispatchQueue.global(qos: .background).async(execute: work)
     }
 
@@ -1697,26 +1970,20 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         self.runBackgroundDownloadWork {
             // Wait for cleanup to complete before starting download
             self.waitForCleanupIfNeeded()
-            self.backgroundTaskID = UIApplication.shared.beginBackgroundTask(withName: "Finish Download Tasks") {
-                // End the task if time expires.
-                self.endBackGroundTask()
-            }
+            self.beginDownloadBackgroundTask()
             self.logger.info("Check for update via \(self.updateUrl)")
             let res = self.implementation.getLatest(url: url, channel: nil)
             let current = self.implementation.getCurrentBundle()
 
             // Handle network errors and other failures first
-            if let backendError = res.error, !backendError.isEmpty {
-                self.logger.error("getLatest failed with error: \(backendError)")
-                let statusCode = res.statusCode
-                let responseIsOk = statusCode >= 200 && statusCode < 300
-                self.endBackGroundTaskWithNotif(
-                    msg: res.message ?? backendError,
-                    latestVersionName: res.version,
+            let backendError = res.error ?? ""
+            let backendKind = res.kind ?? ""
+            if !backendError.isEmpty || !backendKind.isEmpty {
+                self.endBackgroundDownloadAfterLatestError(
+                    backendError: backendError,
+                    res: res,
                     current: current,
-                    error: true,
-                    plannedDirectUpdate: plannedDirectUpdate,
-                    sendStats: !responseIsOk
+                    plannedDirectUpdate: plannedDirectUpdate
                 )
                 return
             }
@@ -1942,6 +2209,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     @objc func appMovedToForeground() {
+        appHealthTracker?.markForeground(true)
         let current: BundleInfo = self.implementation.getCurrentBundle()
         self.implementation.sendStats(action: "app_moved_to_foreground", versionName: current.getVersionName())
         self.delayUpdateUtils.checkCancelDelay(source: .foreground)
@@ -1987,7 +2255,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                 timer.invalidate()
                 return
             }
-            DispatchQueue.global(qos: .background).async {
+            DispatchQueue.global(qos: .utility).async {
                 let res = self.implementation.getLatest(url: url, channel: nil)
                 let current = self.implementation.getCurrentBundle()
 
@@ -2008,6 +2276,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     @objc func appMovedToBackground() {
         // Reset timeout flag at start of each background cycle
         self.autoSplashscreenTimedOut = false
+        appHealthTracker?.markForeground(false)
 
         let current: BundleInfo = self.implementation.getCurrentBundle()
         self.implementation.sendStats(action: "app_moved_to_background", versionName: current.getVersionName())
@@ -2139,29 +2408,30 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
 
         logger.info("Getting App Store update info for \(bundleId) in country \(country)")
 
+        self.saveCallForAsyncHandling(call)
         DispatchQueue.global(qos: .background).async {
             let urlString = "https://itunes.apple.com/lookup?bundleId=\(bundleId)&country=\(country)"
             guard let url = URL(string: urlString) else {
-                call.reject("Invalid URL for App Store lookup")
+                self.rejectCall(call, message: "Invalid URL for App Store lookup")
                 return
             }
 
             let task = URLSession.shared.dataTask(with: url) { data, _, error in
                 if let error = error {
                     self.logger.error("App Store lookup failed: \(error.localizedDescription)")
-                    call.reject("App Store lookup failed: \(error.localizedDescription)")
+                    self.rejectCall(call, message: "App Store lookup failed: \(error.localizedDescription)")
                     return
                 }
 
                 guard let data = data else {
-                    call.reject("No data received from App Store")
+                    self.rejectCall(call, message: "No data received from App Store")
                     return
                 }
 
                 do {
                     guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any],
                           let resultCount = json["resultCount"] as? Int else {
-                        call.reject("Invalid response from App Store")
+                        self.rejectCall(call, message: "Invalid response from App Store")
                         return
                     }
 
@@ -2218,10 +2488,10 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                         self.logger.info("App not found in App Store for bundleId: \(bundleId)")
                     }
 
-                    call.resolve(result)
+                    self.resolveCall(call, data: result)
                 } catch {
                     self.logger.error("Failed to parse App Store response: \(error.localizedDescription)")
-                    call.reject("Failed to parse App Store response: \(error.localizedDescription)")
+                    self.rejectCall(call, message: "Failed to parse App Store response: \(error.localizedDescription)")
                 }
             }
             task.resume()
@@ -2230,37 +2500,48 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
 
     @objc func openAppStore(_ call: CAPPluginCall) {
         let appId = call.getString("appId")
+        let bundleId = implementation.appId
+        self.saveCallForAsyncHandling(call)
 
-        if let appId = appId {
-            // Open App Store with provided app ID
-            let urlString = "https://apps.apple.com/app/id\(appId)"
+        func openAppStorePage(urlString: String, invalidMessage: String = "Invalid App Store URL", failureMessage: String = "Failed to open App Store") {
             guard let url = URL(string: urlString) else {
-                call.reject("Invalid App Store URL")
+                self.rejectCall(call, message: invalidMessage)
                 return
             }
             DispatchQueue.main.async {
                 UIApplication.shared.open(url) { success in
                     if success {
-                        call.resolve()
+                        self.resolveCall(call)
                     } else {
-                        call.reject("Failed to open App Store")
+                        self.rejectCall(call, message: failureMessage)
                     }
                 }
             }
+        }
+
+        func openFallbackAppStorePage() {
+            guard let encodedBundleId = bundleId.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) else {
+                self.rejectCall(call, message: "Failed to build App Store fallback URL")
+                return
+            }
+            openAppStorePage(urlString: "https://apps.apple.com/app/\(encodedBundleId)")
+        }
+
+        if let appId = appId {
+            openAppStorePage(urlString: "https://apps.apple.com/app/id\(appId)")
         } else {
-            // Look up app ID using bundle identifier
-            let bundleId = implementation.appId
             let lookupUrl = "https://itunes.apple.com/lookup?bundleId=\(bundleId)"
 
             DispatchQueue.global(qos: .background).async {
                 guard let url = URL(string: lookupUrl) else {
-                    call.reject("Invalid lookup URL")
+                    openFallbackAppStorePage()
                     return
                 }
 
                 let task = URLSession.shared.dataTask(with: url) { data, _, error in
                     if let error = error {
-                        call.reject("Failed to lookup app: \(error.localizedDescription)")
+                        self.logger.error("App Store lookup failed: \(error.localizedDescription)")
+                        openFallbackAppStorePage()
                         return
                     }
 
@@ -2269,39 +2550,11 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                           let results = json["results"] as? [[String: Any]],
                           let appInfo = results.first,
                           let trackId = appInfo["trackId"] as? Int else {
-                        // If lookup fails, try opening the generic App Store app page using bundle ID
-                        let fallbackUrlString = "https://apps.apple.com/app/\(bundleId)"
-                        guard let fallbackUrl = URL(string: fallbackUrlString) else {
-                            call.reject("Failed to find app in App Store and fallback URL is invalid")
-                            return
-                        }
-                        DispatchQueue.main.async {
-                            UIApplication.shared.open(fallbackUrl) { success in
-                                if success {
-                                    call.resolve()
-                                } else {
-                                    call.reject("Failed to open App Store")
-                                }
-                            }
-                        }
-                        return
-                    }
-
-                    let appStoreUrl = "https://apps.apple.com/app/id\(trackId)"
-                    guard let url = URL(string: appStoreUrl) else {
-                        call.reject("Invalid App Store URL")
+                        openFallbackAppStorePage()
                         return
                     }
 
-                    DispatchQueue.main.async {
-                        UIApplication.shared.open(url) { success in
-                            if success {
-                                call.resolve()
-                            } else {
-                                call.reject("Failed to open App Store")
-                            }
-                        }
-                    }
+                    openAppStorePage(urlString: "https://apps.apple.com/app/id\(trackId)")
                 }
                 task.resume()
             }