feat: beta background sync (#21243)

* feat: ios background sync

# Conflicts:
#	mobile/ios/Runner/Info.plist

* feat: Android sync

* add local sync worker and rename stuff

* group upload notifications

* uncomment onresume beta handling

* rename methods

---------

Co-authored-by: shenlong-tanwen <139912620+shalong-tanwen@users.noreply.github.com>
Co-authored-by: Alex <alex.tran1502@gmail.com>

mobile/ios/Runner/Background/BackgroundWorker.g.swift

@@ -0,0 +1,245 @@
+// Autogenerated from Pigeon (v26.0.0), do not edit directly.
+// See also: https://pub.dev/packages/pigeon
+
+import Foundation
+
+#if os(iOS)
+  import Flutter
+#elseif os(macOS)
+  import FlutterMacOS
+#else
+  #error("Unsupported platform.")
+#endif
+
+private func wrapResult(_ result: Any?) -> [Any?] {
+  return [result]
+}
+
+private func wrapError(_ error: Any) -> [Any?] {
+  if let pigeonError = error as? PigeonError {
+    return [
+      pigeonError.code,
+      pigeonError.message,
+      pigeonError.details,
+    ]
+  }
+  if let flutterError = error as? FlutterError {
+    return [
+      flutterError.code,
+      flutterError.message,
+      flutterError.details,
+    ]
+  }
+  return [
+    "\(error)",
+    "\(type(of: error))",
+    "Stacktrace: \(Thread.callStackSymbols)",
+  ]
+}
+
+private func createConnectionError(withChannelName channelName: String) -> PigeonError {
+  return PigeonError(code: "channel-error", message: "Unable to establish connection on channel: '\(channelName)'.", details: "")
+}
+
+private func isNullish(_ value: Any?) -> Bool {
+  return value is NSNull || value == nil
+}
+
+private func nilOrValue<T>(_ value: Any?) -> T? {
+  if value is NSNull { return nil }
+  return value as! T?
+}
+
+
+private class BackgroundWorkerPigeonCodecReader: FlutterStandardReader {
+}
+
+private class BackgroundWorkerPigeonCodecWriter: FlutterStandardWriter {
+}
+
+private class BackgroundWorkerPigeonCodecReaderWriter: FlutterStandardReaderWriter {
+  override func reader(with data: Data) -> FlutterStandardReader {
+    return BackgroundWorkerPigeonCodecReader(data: data)
+  }
+
+  override func writer(with data: NSMutableData) -> FlutterStandardWriter {
+    return BackgroundWorkerPigeonCodecWriter(data: data)
+  }
+}
+
+class BackgroundWorkerPigeonCodec: FlutterStandardMessageCodec, @unchecked Sendable {
+  static let shared = BackgroundWorkerPigeonCodec(readerWriter: BackgroundWorkerPigeonCodecReaderWriter())
+}
+
+/// Generated protocol from Pigeon that represents a handler of messages from Flutter.
+protocol BackgroundWorkerFgHostApi {
+  func enableSyncWorker() throws
+  func enableUploadWorker(callbackHandle: Int64) throws
+  func disableUploadWorker() throws
+}
+
+/// Generated setup class from Pigeon to handle messages through the `binaryMessenger`.
+class BackgroundWorkerFgHostApiSetup {
+  static var codec: FlutterStandardMessageCodec { BackgroundWorkerPigeonCodec.shared }
+  /// Sets up an instance of `BackgroundWorkerFgHostApi` to handle messages through the `binaryMessenger`.
+  static func setUp(binaryMessenger: FlutterBinaryMessenger, api: BackgroundWorkerFgHostApi?, messageChannelSuffix: String = "") {
+    let channelSuffix = messageChannelSuffix.count > 0 ? ".\(messageChannelSuffix)" : ""
+    let enableSyncWorkerChannel = FlutterBasicMessageChannel(name: "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFgHostApi.enableSyncWorker\(channelSuffix)", binaryMessenger: binaryMessenger, codec: codec)
+    if let api = api {
+      enableSyncWorkerChannel.setMessageHandler { _, reply in
+        do {
+          try api.enableSyncWorker()
+          reply(wrapResult(nil))
+        } catch {
+          reply(wrapError(error))
+        }
+      }
+    } else {
+      enableSyncWorkerChannel.setMessageHandler(nil)
+    }
+    let enableUploadWorkerChannel = FlutterBasicMessageChannel(name: "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFgHostApi.enableUploadWorker\(channelSuffix)", binaryMessenger: binaryMessenger, codec: codec)
+    if let api = api {
+      enableUploadWorkerChannel.setMessageHandler { message, reply in
+        let args = message as! [Any?]
+        let callbackHandleArg = args[0] as! Int64
+        do {
+          try api.enableUploadWorker(callbackHandle: callbackHandleArg)
+          reply(wrapResult(nil))
+        } catch {
+          reply(wrapError(error))
+        }
+      }
+    } else {
+      enableUploadWorkerChannel.setMessageHandler(nil)
+    }
+    let disableUploadWorkerChannel = FlutterBasicMessageChannel(name: "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFgHostApi.disableUploadWorker\(channelSuffix)", binaryMessenger: binaryMessenger, codec: codec)
+    if let api = api {
+      disableUploadWorkerChannel.setMessageHandler { _, reply in
+        do {
+          try api.disableUploadWorker()
+          reply(wrapResult(nil))
+        } catch {
+          reply(wrapError(error))
+        }
+      }
+    } else {
+      disableUploadWorkerChannel.setMessageHandler(nil)
+    }
+  }
+}
+/// Generated protocol from Pigeon that represents a handler of messages from Flutter.
+protocol BackgroundWorkerBgHostApi {
+  func onInitialized() throws
+}
+
+/// Generated setup class from Pigeon to handle messages through the `binaryMessenger`.
+class BackgroundWorkerBgHostApiSetup {
+  static var codec: FlutterStandardMessageCodec { BackgroundWorkerPigeonCodec.shared }
+  /// Sets up an instance of `BackgroundWorkerBgHostApi` to handle messages through the `binaryMessenger`.
+  static func setUp(binaryMessenger: FlutterBinaryMessenger, api: BackgroundWorkerBgHostApi?, messageChannelSuffix: String = "") {
+    let channelSuffix = messageChannelSuffix.count > 0 ? ".\(messageChannelSuffix)" : ""
+    let onInitializedChannel = FlutterBasicMessageChannel(name: "dev.flutter.pigeon.immich_mobile.BackgroundWorkerBgHostApi.onInitialized\(channelSuffix)", binaryMessenger: binaryMessenger, codec: codec)
+    if let api = api {
+      onInitializedChannel.setMessageHandler { _, reply in
+        do {
+          try api.onInitialized()
+          reply(wrapResult(nil))
+        } catch {
+          reply(wrapError(error))
+        }
+      }
+    } else {
+      onInitializedChannel.setMessageHandler(nil)
+    }
+  }
+}
+/// Generated protocol from Pigeon that represents Flutter messages that can be called from Swift.
+protocol BackgroundWorkerFlutterApiProtocol {
+  func onLocalSync(maxSeconds maxSecondsArg: Int64?, completion: @escaping (Result<Void, PigeonError>) -> Void)
+  func onIosUpload(isRefresh isRefreshArg: Bool, maxSeconds maxSecondsArg: Int64?, completion: @escaping (Result<Void, PigeonError>) -> Void)
+  func onAndroidUpload(completion: @escaping (Result<Void, PigeonError>) -> Void)
+  func cancel(completion: @escaping (Result<Void, PigeonError>) -> Void)
+}
+class BackgroundWorkerFlutterApi: BackgroundWorkerFlutterApiProtocol {
+  private let binaryMessenger: FlutterBinaryMessenger
+  private let messageChannelSuffix: String
+  init(binaryMessenger: FlutterBinaryMessenger, messageChannelSuffix: String = "") {
+    self.binaryMessenger = binaryMessenger
+    self.messageChannelSuffix = messageChannelSuffix.count > 0 ? ".\(messageChannelSuffix)" : ""
+  }
+  var codec: BackgroundWorkerPigeonCodec {
+    return BackgroundWorkerPigeonCodec.shared
+  }
+  func onLocalSync(maxSeconds maxSecondsArg: Int64?, completion: @escaping (Result<Void, PigeonError>) -> Void) {
+    let channelName: String = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.onLocalSync\(messageChannelSuffix)"
+    let channel = FlutterBasicMessageChannel(name: channelName, binaryMessenger: binaryMessenger, codec: codec)
+    channel.sendMessage([maxSecondsArg] as [Any?]) { response in
+      guard let listResponse = response as? [Any?] else {
+        completion(.failure(createConnectionError(withChannelName: channelName)))
+        return
+      }
+      if listResponse.count > 1 {
+        let code: String = listResponse[0] as! String
+        let message: String? = nilOrValue(listResponse[1])
+        let details: String? = nilOrValue(listResponse[2])
+        completion(.failure(PigeonError(code: code, message: message, details: details)))
+      } else {
+        completion(.success(()))
+      }
+    }
+  }
+  func onIosUpload(isRefresh isRefreshArg: Bool, maxSeconds maxSecondsArg: Int64?, completion: @escaping (Result<Void, PigeonError>) -> Void) {
+    let channelName: String = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.onIosUpload\(messageChannelSuffix)"
+    let channel = FlutterBasicMessageChannel(name: channelName, binaryMessenger: binaryMessenger, codec: codec)
+    channel.sendMessage([isRefreshArg, maxSecondsArg] as [Any?]) { response in
+      guard let listResponse = response as? [Any?] else {
+        completion(.failure(createConnectionError(withChannelName: channelName)))
+        return
+      }
+      if listResponse.count > 1 {
+        let code: String = listResponse[0] as! String
+        let message: String? = nilOrValue(listResponse[1])
+        let details: String? = nilOrValue(listResponse[2])
+        completion(.failure(PigeonError(code: code, message: message, details: details)))
+      } else {
+        completion(.success(()))
+      }
+    }
+  }
+  func onAndroidUpload(completion: @escaping (Result<Void, PigeonError>) -> Void) {
+    let channelName: String = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.onAndroidUpload\(messageChannelSuffix)"
+    let channel = FlutterBasicMessageChannel(name: channelName, binaryMessenger: binaryMessenger, codec: codec)
+    channel.sendMessage(nil) { response in
+      guard let listResponse = response as? [Any?] else {
+        completion(.failure(createConnectionError(withChannelName: channelName)))
+        return
+      }
+      if listResponse.count > 1 {
+        let code: String = listResponse[0] as! String
+        let message: String? = nilOrValue(listResponse[1])
+        let details: String? = nilOrValue(listResponse[2])
+        completion(.failure(PigeonError(code: code, message: message, details: details)))
+      } else {
+        completion(.success(()))
+      }
+    }
+  }
+  func cancel(completion: @escaping (Result<Void, PigeonError>) -> Void) {
+    let channelName: String = "dev.flutter.pigeon.immich_mobile.BackgroundWorkerFlutterApi.cancel\(messageChannelSuffix)"
+    let channel = FlutterBasicMessageChannel(name: channelName, binaryMessenger: binaryMessenger, codec: codec)
+    channel.sendMessage(nil) { response in
+      guard let listResponse = response as? [Any?] else {
+        completion(.failure(createConnectionError(withChannelName: channelName)))
+        return
+      }
+      if listResponse.count > 1 {
+        let code: String = listResponse[0] as! String
+        let message: String? = nilOrValue(listResponse[1])
+        let details: String? = nilOrValue(listResponse[2])
+        completion(.failure(PigeonError(code: code, message: message, details: details)))
+      } else {
+        completion(.success(()))
+      }
+    }
+  }
+}

mobile/ios/Runner/Background/BackgroundWorker.swift

@@ -0,0 +1,202 @@
+import BackgroundTasks
+import Flutter
+
+enum BackgroundTaskType { case localSync, refreshUpload, processingUpload }
+
+/*
+ * DEBUG: Testing Background Tasks in Xcode
+ * 
+ * To test background task functionality during development:
+ * 1. Pause the application in Xcode debugger
+ * 2. In the debugger console, enter one of the following commands:
+
+ ## For local sync (short-running sync):
+ 
+ e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"app.alextran.immich.background.localSync"]
+ 
+ ## For background refresh (short-running sync):
+ 
+ e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"app.alextran.immich.background.refreshUpload"]
+ 
+ ## For background processing (long-running upload):
+ 
+ e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"app.alextran.immich.background.processingUpload"]
+
+ * To simulate task expiration (useful for testing expiration handlers):
+ 
+ e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"app.alextran.immich.background.localSync"]
+ 
+ e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"app.alextran.immich.background.refreshUpload"]
+ 
+ e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"app.alextran.immich.background.processingUpload"]
+ 
+ * 3. Resume the application to see the background code execute
+ * 
+ * NOTE: This must be tested on a physical device, not in the simulator.
+ * In testing, only the background processing task can be reliably simulated.
+ * These commands submit the respective task to BGTaskScheduler for immediate processing.
+ * Use the expiration commands to test how the app handles iOS terminating background tasks.
+ */
+
+
+/// The background worker which creates a new Flutter VM, communicates with it
+/// to run the backup job, and then finishes execution and calls back to its callback handler.
+/// This class manages a separate Flutter engine instance for background execution,
+/// independent of the main UI Flutter engine.
+class BackgroundWorker: BackgroundWorkerBgHostApi {
+  private let taskType: BackgroundTaskType
+  /// The maximum number of seconds to run the task before timing out
+  private let maxSeconds: Int?
+  /// Callback function to invoke when the background task completes
+  private let completionHandler: (_ success: Bool) -> Void
+  
+  /// The Flutter engine created specifically for background execution.
+  /// This is a separate instance from the main Flutter engine that handles the UI.
+  /// It operates in its own isolate and doesn't share memory with the main engine.
+  /// Must be properly started, registered, and torn down during background execution.
+  private let engine = FlutterEngine(name: "BackgroundImmich")
+  
+  /// Used to call methods on the flutter side
+  private var flutterApi: BackgroundWorkerFlutterApi?
+  
+  /// Flag to track whether the background task has completed to prevent duplicate completions
+  private var isComplete = false
+  
+  /**
+   * Initializes a new background worker with the specified task type and execution constraints.
+   * Creates a new Flutter engine instance for background execution and sets up the necessary
+   * communication channels between native iOS and Flutter code.
+   *
+   * - Parameters:
+   *   - taskType: The type of background task to execute (upload or sync task)
+   *   - maxSeconds: Optional maximum execution time in seconds before the task is cancelled
+   *   - completionHandler: Callback function invoked when the task completes, with success status
+   */
+  init(taskType: BackgroundTaskType, maxSeconds: Int?, completionHandler: @escaping (_ success: Bool) -> Void) {
+    self.taskType = taskType
+    self.maxSeconds = maxSeconds
+    self.completionHandler = completionHandler
+    // Should be initialized only after the engine starts running
+    self.flutterApi = nil
+  }
+  
+  /**
+   * Starts the background Flutter engine and begins execution of the background task.
+   * Retrieves the callback handle from UserDefaults, looks up the Flutter callback,
+   * starts the engine, and sets up a timeout timer if specified.
+   */
+  func run() {
+    // Retrieve the callback handle stored by the main Flutter app
+    // This handle points to the Flutter function that should be executed in the background
+    let callbackHandle = Int64(UserDefaults.standard.string(
+      forKey: BackgroundWorkerApiImpl.backgroundUploadCallbackHandleKey) ?? "0") ?? 0
+
+    if callbackHandle == 0 {
+      // Without a valid callback handle, we cannot start the Flutter background execution
+      complete(success: false)
+      return
+    }
+    
+    // Use the callback handle to retrieve the actual Flutter callback information
+    guard let callback = FlutterCallbackCache.lookupCallbackInformation(callbackHandle) else {
+      // The callback handle is invalid or the callback was not found
+      complete(success: false)
+      return
+    }
+           
+    // Start the Flutter engine with the specified callback as the entry point
+    let isRunning = engine.run(
+      withEntrypoint: callback.callbackName,
+      libraryURI: callback.callbackLibraryPath
+    )
+    
+    // Verify that the Flutter engine started successfully
+    if !isRunning {
+      complete(success: false)
+      return
+    }
+    
+    // Register plugins in the new engine
+    GeneratedPluginRegistrant.register(with: engine)
+    // Register custom plugins
+    AppDelegate.registerPlugins(binaryMessenger: engine.binaryMessenger)
+    flutterApi = BackgroundWorkerFlutterApi(binaryMessenger: engine.binaryMessenger)
+    BackgroundWorkerBgHostApiSetup.setUp(binaryMessenger: engine.binaryMessenger, api: self)
+    
+    // Set up a timeout timer if maxSeconds was specified to prevent runaway background tasks
+    if maxSeconds != nil {
+        // Schedule a timer to cancel the task after the specified timeout period
+        Timer.scheduledTimer(withTimeInterval: TimeInterval(maxSeconds!), repeats: false) { _ in
+          self.cancel()
+        }
+    }
+  }
+  
+  /**
+   * Called by the Flutter side when it has finished initialization and is ready to receive commands.
+   * Routes the appropriate task type (refresh or processing) to the corresponding Flutter method.
+   * This method acts as a bridge between the native iOS background task system and Flutter.
+   */
+  func onInitialized() throws {
+    switch self.taskType {
+    case .refreshUpload, .processingUpload:
+      flutterApi?.onIosUpload(isRefresh: self.taskType == .refreshUpload,
+                              maxSeconds: maxSeconds.map { Int64($0) }, completion: { result in
+        self.handleHostResult(result: result)
+      })
+    case .localSync:
+      flutterApi?.onLocalSync(maxSeconds: maxSeconds.map { Int64($0) }, completion: { result in
+        self.handleHostResult(result: result)
+      })
+    }
+  }
+
+  /**
+   * Cancels the currently running background task, either due to timeout or external request.
+   * Sends a cancel signal to the Flutter side and sets up a fallback timer to ensure
+   * the completion handler is eventually called even if Flutter doesn't respond.
+   */
+  func cancel() {
+    if isComplete {
+      return
+    }
+
+    isComplete = true
+    flutterApi?.cancel { result in
+      self.complete(success: false)
+    }
+
+    // Fallback safety mechanism: ensure completion is called within 2 seconds
+    // This prevents the background task from hanging indefinitely if Flutter doesn't respond
+    Timer.scheduledTimer(withTimeInterval: 2, repeats: false) { _ in
+      self.complete(success: false)
+    }
+  }
+  
+  /**
+   * Handles the result from Flutter API calls and determines the success/failure status.
+   * Converts Flutter's Result type to a simple boolean success indicator for task completion.
+   *
+   * - Parameter result: The result returned from a Flutter API call
+   */
+  private func handleHostResult(result: Result<Void, PigeonError>) {
+    switch result {
+      case .success(): self.complete(success: true)
+      case .failure(_): self.cancel()
+    }
+  }
+
+  /**
+   * Cleans up resources by destroying the Flutter engine context and invokes the completion handler.
+   * This method ensures that the background task is marked as complete, releases the Flutter engine,
+   * and notifies the caller of the task's success or failure. This is the final step in the
+   * background task lifecycle and should only be called once per task instance.
+   *
+   * - Parameter success: Indicates whether the background task completed successfully
+   */
+  private func complete(success: Bool) {
+    isComplete = true
+    engine.destroyContext()
+    completionHandler(success)
+  }
+}

mobile/ios/Runner/Background/BackgroundWorkerApiImpl.swift

@@ -0,0 +1,155 @@
+import BackgroundTasks
+
+class BackgroundWorkerApiImpl: BackgroundWorkerFgHostApi {
+  func enableSyncWorker() throws {
+    BackgroundWorkerApiImpl.scheduleLocalSync()
+    print("BackgroundUploadImpl:enableSyncWorker Local Sync worker scheduled")
+  }
+  
+  func enableUploadWorker(callbackHandle: Int64) throws {
+    BackgroundWorkerApiImpl.updateUploadEnabled(true)
+    // Store the callback handle for later use when starting background Flutter isolates
+    BackgroundWorkerApiImpl.updateUploadCallbackHandle(callbackHandle)
+    
+    BackgroundWorkerApiImpl.scheduleRefreshUpload()
+    BackgroundWorkerApiImpl.scheduleProcessingUpload()
+    print("BackgroundUploadImpl:enableUploadWorker Scheduled background upload tasks")
+  }
+  
+  func disableUploadWorker() throws {
+    BackgroundWorkerApiImpl.updateUploadEnabled(false)
+    BackgroundWorkerApiImpl.cancelUploadTasks()
+    print("BackgroundUploadImpl:disableUploadWorker Disabled background upload tasks")
+  }
+  
+  public static let backgroundUploadEnabledKey = "immich:background:backup:enabled"
+  public static let backgroundUploadCallbackHandleKey = "immich:background:backup:callbackHandle"
+  
+  private static let localSyncTaskID = "app.alextran.immich.background.localSync"
+  private static let refreshUploadTaskID = "app.alextran.immich.background.refreshUpload"
+  private static let processingUploadTaskID = "app.alextran.immich.background.processingUpload"
+
+  private static func updateUploadEnabled(_ isEnabled: Bool) {
+    return UserDefaults.standard.set(isEnabled, forKey: BackgroundWorkerApiImpl.backgroundUploadEnabledKey)
+  }
+
+  private static func updateUploadCallbackHandle(_ callbackHandle: Int64) {
+    return UserDefaults.standard.set(String(callbackHandle), forKey: BackgroundWorkerApiImpl.backgroundUploadCallbackHandleKey)
+  }
+
+  private static func cancelUploadTasks() {
+    BackgroundWorkerApiImpl.updateUploadEnabled(false)
+    BGTaskScheduler.shared.cancel(taskRequestWithIdentifier: refreshUploadTaskID);
+    BGTaskScheduler.shared.cancel(taskRequestWithIdentifier: processingUploadTaskID);
+  }
+
+  public static func registerBackgroundProcessing() {
+      BGTaskScheduler.shared.register(
+          forTaskWithIdentifier: processingUploadTaskID, using: nil) { task in
+          if task is BGProcessingTask {
+            handleBackgroundProcessing(task: task as! BGProcessingTask)
+          }
+      }
+
+      BGTaskScheduler.shared.register(
+          forTaskWithIdentifier: refreshUploadTaskID, using: nil) { task in
+          if task is BGAppRefreshTask {
+            handleBackgroundRefresh(task: task as! BGAppRefreshTask, taskType: .refreshUpload)
+          }
+      }
+    
+    BGTaskScheduler.shared.register(
+        forTaskWithIdentifier: localSyncTaskID, using: nil) { task in
+        if task is BGAppRefreshTask {
+          handleBackgroundRefresh(task: task as! BGAppRefreshTask, taskType: .localSync)
+        }
+    }
+  }
+  
+  private static func scheduleLocalSync() {
+    let backgroundRefresh = BGAppRefreshTaskRequest(identifier: localSyncTaskID)
+      backgroundRefresh.earliestBeginDate = Date(timeIntervalSinceNow: 5 * 60) // 5 mins
+
+      do {
+          try BGTaskScheduler.shared.submit(backgroundRefresh)
+      } catch {
+          print("Could not schedule the local sync task \(error.localizedDescription)")
+      }
+  }
+  
+  private static func scheduleRefreshUpload() {
+    let backgroundRefresh = BGAppRefreshTaskRequest(identifier: refreshUploadTaskID)
+      backgroundRefresh.earliestBeginDate = Date(timeIntervalSinceNow: 5 * 60) // 5 mins
+
+      do {
+          try BGTaskScheduler.shared.submit(backgroundRefresh)
+      } catch {
+          print("Could not schedule the refresh upload task \(error.localizedDescription)")
+      }
+  }
+
+  private static func scheduleProcessingUpload() {
+    let backgroundProcessing = BGProcessingTaskRequest(identifier: processingUploadTaskID)
+    
+    backgroundProcessing.requiresNetworkConnectivity = true
+    backgroundProcessing.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60) // 15 mins
+    
+    do {
+        try BGTaskScheduler.shared.submit(backgroundProcessing)
+    } catch {
+        print("Could not schedule the processing upload task \(error.localizedDescription)")
+    }
+  }
+  
+  private static func handleBackgroundRefresh(task: BGAppRefreshTask, taskType: BackgroundTaskType) {
+    scheduleRefreshUpload()
+    // Restrict the refresh task to run only for a maximum of 20 seconds
+    runBackgroundWorker(task: task, taskType: taskType, maxSeconds: 20)
+  }
+  
+  private static func handleBackgroundProcessing(task: BGProcessingTask) {
+    scheduleProcessingUpload()
+    // There are no restrictions for processing tasks. Although, the OS could signal expiration at any time
+    runBackgroundWorker(task: task, taskType: .processingUpload, maxSeconds: nil)
+  }
+  
+  /**
+   * Executes the background worker within the context of a background task.
+   * This method creates a BackgroundWorker, sets up task expiration handling,
+   * and manages the synchronization between the background task and the Flutter engine.
+   *
+   * - Parameters:
+   *   - task: The iOS background task that provides the execution context
+   *   - taskType: The type of background operation to perform (refresh or processing)
+   *   - maxSeconds: Optional timeout for the operation in seconds
+   */
+  private static func runBackgroundWorker(task: BGTask, taskType: BackgroundTaskType, maxSeconds: Int?) {
+    let semaphore = DispatchSemaphore(value: 0)
+    var isSuccess = true
+    
+    let backgroundWorker = BackgroundWorker(taskType: taskType, maxSeconds: maxSeconds) { success in
+      isSuccess = success
+      semaphore.signal()
+    }
+
+    task.expirationHandler = {
+      DispatchQueue.main.async {
+        backgroundWorker.cancel()
+      }
+      isSuccess = false
+      
+      // Schedule a timer to signal the semaphore after 2 seconds
+      Timer.scheduledTimer(withTimeInterval: 2, repeats: false) { _ in
+        semaphore.signal()
+      }
+    }
+
+    DispatchQueue.main.async {
+      backgroundWorker.run()
+    }
+
+    semaphore.wait()
+    task.setTaskCompleted(success: isSuccess)
+    print("Background task completed with success: \(isSuccess)")
+  }
+}