Can background tasks not be triggered at all when an app is killed by iOS?

[zhujianguo]

I'm a software developer mainly working on the Android side and I'm not very familiar with the mechanisms on the iOS side. So I'd like to ask you, is it completely impossible to use this plugin when the iOS app is killed?

[vietnguyentuan2019]

Hi @zhujianguo,

Thank you for reaching out. Regarding your question about tasks running after an app is killed:

1. On Android: We have successfully implemented a fix in v1.2.6. By using our new Foreground Service (FGS) Bypass (setting isHeavyTask: true with a ForegroundNotificationConfig), tasks can now execute reliably even after the app is killed or swiped away.
2. On iOS: This is a strict platform limitation enforced by Apple. If a user manually force-quits (swipes up) an app, iOS cancels all pending background tasks and will not wake the app again until the user manually relaunches it. This is a security and battery policy that third-party developers cannot bypass.

Please upgrade to v1.2.6 to enjoy the enhanced reliability on Android.

---

感谢您的提问。关于应用程序被终止（Killed）后任务运行的问题：

1. 在 Android 上：我们已在 v1.2.6 中成功实现了修复。通过使用我们全新的 前台服务 (FGS) 绕过 功能（设置 isHeavyTask: true 并配置 ForegroundNotificationConfig），即使应用被终止或从任务列表中滑掉，任务现在也可以可靠地执行。
2. 在 iOS 上：这是苹果强制执行的严格平台限制。如果用户手动强制退出（向上滑动）应用，iOS 会取消所有挂起的后台任务，并且在用户再次手动启动应用之前，系统不会唤醒该应用。这是第三方开发者无法逾越的安全和电池策略。

请升级到 v1.2.6 以体验 Android 上增强的可靠性。

[vietnguyentuan2019]

In addition to the previous response, we would like to highlight why native_workmanager (v1.2.6) provides a superior experience on iOS compared to other Flutter background libraries:

1. Maximized Execution Time (Zero-Engine Architecture)
Traditional libraries (like flutter_workmanager) waste 1-2 seconds booting a full Flutter Engine for every task. On iOS, where background time is strictly limited to ~30 seconds, this overhead is critical. Our library runs 100% native Swift code with <50ms startup, giving your logic nearly 100% of the allocated time budget.

2. Resilience Against System Purge
When iOS kills an app process to reclaim RAM (System Purge), most libraries lose their task state. native_workmanager uses a high-performance Native SQLite store. Even after a system-level kill, our Swift engine automatically recovers the task queue from disk the moment iOS grants a background execution window.

3. Industrial-Grade Stability (New in v1.2.6)
We have implemented Serial Dispatch Queues and Defensive Scheduling Delays to prevent deadlocks in BGTaskScheduler. This ensures that complex task chains (TaskGraphs) execute reliably without being "dropped" by the OS due to rapid re-registration.

---

除了之前的回复，我们还想强调为什么 native_workmanager (v1.2.6) 在 iOS 上的表现优于其他 Flutter 后台库：

1. 最大化执行时间（零引擎架构）
传统的库（如 flutter_workmanager）会为每个任务浪费 1-2 秒来启动完整的 Flutter 引擎。在 iOS 上，后台时间被严格限制在约 30 秒，这种开销是致命的。我们的库运行 100% 原生 Swift 代码，启动时间 <50ms，为您的逻辑提供了近 100% 的分配时间预算。

2. 抵御系统清除的韧性
当 iOS 为了回收内存而终止应用进程（系统清除）时，大多数库会丢失其任务状态。native_workmanager 使用高性能的 原生 SQLite 存储。即使在系统级终止后，我们的 Swift 引擎也会在 iOS 授予后台执行窗口的瞬间，自动从磁盘恢复任务队列。

3. 工业级稳定性（v1.2.6 新品）
我们实现了 串行调度队列 (Serial Dispatch Queues) 和 防御性调度延迟，以防止 BGTaskScheduler 中的死锁。这确保了复杂的任务链（TaskGraphs）能够可靠执行，而不会因为快速重新注册而被操作系统“丢弃”。

[zhujianguo]

Should both allowWhileIdle = true and isHeavyTask = true be set simultaneously?

[zhujianguo]

Is your implementation based on starting a foreground service? Because from my testing, when system resources are insufficient, foreground services basically stop being triggered, and sometimes they never get triggered again afterward.

I previously tested this with flutter_background_service
. After opening many apps, my background tasks would basically stop executing.

So I'm not sure whether your implementation works the same way as flutter_background_service or if the underlying mechanism is different.

[vietnguyentuan2019]

Hi @zhujianguo,

That is an excellent question! The underlying mechanism of native_workmanager is fundamentally different from flutter_background_service. Your concern about the OS killing Foreground Services under memory pressure (OOM) is completely valid for traditional Flutter libraries, but native_workmanager is designed specifically to solve this.

Here is the deep architectural difference regarding OOM (Out of Memory) kills and why our implementation survives:

1. The Raw Persistent Service Flaw (flutter_background_service)
   Traditional libraries manually call Context.startForegroundService() and return a START_STICKY flag to keep a raw Service alive 24/7. When the system runs out of memory, the OS kills it because the Flutter Engine is heavy (50MB - 100MB+).
   Because of START_STICKY, the OS tries to restart the service immediately. Booting the heavy Flutter engine again drains RAM, so it gets killed again. This creates a "Crash/Restart Loop". Android has a strict internal protection mechanism: if a service constantly crashes/restarts, the OS will permanently blacklist it, meaning it will never trigger again.

2. The native_workmanager Architecture (Zero-Engine + WorkManager)
   We do not start a standalone raw service. Instead, we hand your task over to Android's official WorkManager (JobScheduler). The OS securely saves your task in its internal SQLite database.

   • Event-Driven: When the OS decides the system has enough resources, it triggers our ForegroundNativeWorker (written in pure Kotlin, consuming only ~2MB RAM). Only after the task starts running do we dynamically call setForeground() to protect it.
   • No Blacklisting (Crash Recovery): Crucially, if extreme memory pressure forces the OS to kill our worker mid-execution, your task is not lost. WorkManager registers this as a "stopped" task, not a crash. It handles the failure, applies your BackoffPolicy (exponential retry), and will automatically reschedule the task to run again when the system recovers. It never gets blacklisted because the OS itself manages the scheduling safely.

In summary, native_workmanager works with the OS by being incredibly lightweight and using the official scheduling APIs, rather than trying to force a heavy Flutter Engine to stay alive permanently.

---

你好 @zhujianguo，

这是一个非常好的问题！native_workmanager 的底层架构与 flutter_background_service 截然不同。你所担心的在内存压力 (OOM) 下操作系统会彻底终止并拉黑前台服务的问题，对于传统的 Flutter 库来说是完全成立的，但 native_workmanager 的设计正是为了解决这个问题。

以下是关于 OOM (内存不足) 终止进程的深层架构差异，以及为什么我们的库能存活下来：

1. 原始持久服务的缺陷 (flutter_background_service)
   传统的库手动调用 Context.startForegroundService() 并返回 START_STICKY 标志来保持一个原始的 Service 24/7 运行。当系统内存不足时，由于 Flutter 引擎非常笨重（50MB - 100MB+），操作系统会将其终止。
   由于 START_STICKY 的作用，操作系统会立即尝试重启它。但是再次启动沉重的 Flutter 引擎会继续耗尽 RAM，导致它再次被杀。这就形成了一个“崩溃/重启循环 (Crash/Restart Loop)”。Android 有一个严格的内部保护机制：如果一个服务不断崩溃/重启，操作系统会将其 永久拉入黑名单 (Blacklisted)，这意味着它永远不会再被触发。

2. native_workmanager 架构 (零引擎 + WorkManager)
   我们 不会 启动一个独立的原始服务。相反，我们将您的任务完全移交给 Android 官方的 WorkManager（底层是 JobScheduler）。操作系统会将您的任务安全地保存在其内部的 SQLite 数据库中。

   • 事件驱动： 只有当操作系统认为系统资源充足时，它才会触发我们的 ForegroundNativeWorker（用纯 Kotlin 编写，仅消耗约 2MB 内存）。只有在任务开始运行 之后，我们才会动态调用 setForeground() 在运行期间保护自己。
   • 无黑名单机制 (崩溃恢复)： 最关键的是，如果极端的内存压力迫使操作系统在任务执行到一半时杀死了我们的 worker，您的任务也不会丢失。WorkManager 会将此记录为“停止 (stopped)”的任务，而不是崩溃。它会接管这次失败，应用您的 BackoffPolicy（指数退避重试机制），并会在系统资源恢复后自动重新调度该任务。它永远不会被拉入黑名单，因为是操作系统本身在安全地管理这些调度。

简而言之，native_workmanager 通过极其轻量级的设计并使用官方的调度 API 来与操作系统协同工作，而不是试图强行让笨重的 Flutter 引擎永久保持存活。

[vietnguyentuan2019]

Hi @zhujianguo,

No, you do not need to set both simultaneously. In fact, it is recommended to choose only one depending on your use case, because combining them is redundant and can cause constraint conflicts in Android's WorkManager.

Here is the difference and when to use which:

1. isHeavyTask: true (Foreground Service - FGS)

• What it does: On Android, this promotes your task to a full Foreground Service (when combined with ForegroundNotificationConfig). On iOS, it maps to a BGProcessingTask.
• Behavior: It completely bypasses Doze mode, ignores battery quotas, and survives the app being killed. It represents the highest priority execution Android allows.
• Trade-off: It requires showing a visible notification to the user while running.
• When to use: For critical, long-running tasks that MUST finish reliably (e.g., uploading large files, complex syncing).

2. allowWhileIdle: true (Expedited Work)

• What it does: On Android, this uses WorkManager's Expedited Work mechanism. (It has no effect on iOS).
• Behavior: It allows the task to run even if the device is locked or in Doze mode, without showing a persistent foreground notification.
• Trade-off: It is strictly regulated by Android's App Standby Buckets (quotas). If your app exceeds its quota, the OS will downgrade the task to a normal background job. Furthermore, WorkManager rejects Expedited jobs if you use certain constraints (like requiresCharging: true).
• When to use: For short, fast tasks (under 1 minute) that you want to trigger during Doze mode silently without bothering the user.

Summary

If you are already using isHeavyTask: true to start a Foreground Service, the task inherently bypasses Doze mode. Adding allowWhileIdle: true is redundant and may cause Android to reject the task if you have other constraints.

---

你好 @zhujianguo，

不需要同时设置这两个参数。 事实上，建议您根据具体的使用场景选择其中一个，因为同时使用它们是多余的，而且可能会导致 Android WorkManager 中的约束冲突。

以下是两者的区别以及何时使用它们：

1. isHeavyTask: true (前台服务 - FGS)

• 作用： 在 Android 上，结合 ForegroundNotificationConfig，它会将您的任务提升为完整的前台服务。在 iOS 上，它映射为 BGProcessingTask。
• 行为： 它完全绕过 Doze（打盹）模式，无视电池配额限制，并在应用程序被终止后存活。它代表了 Android 允许的最高优先级执行。
• 代价： 运行时必须向用户显示可见的通知。
• 使用场景： 用于必须可靠完成的关键、长时间运行的任务（例如：上传大文件、复杂的数据同步）。

2. allowWhileIdle: true (加急工作 - Expedited Work)

• 作用： 在 Android 上，这会使用 WorkManager 的 Expedited Work（加急工作） 机制。（它对 iOS 没有影响）。
• 行为： 即使设备处于锁定或 Doze 模式下，它也允许任务运行，而且 不需要 显示持久的前台通知。
• 代价： 它受到 Android 应用程序待机存储分区（系统配额）的严格管制。如果您的应用程序超出配额，操作系统会将该任务降级为普通后台作业。此外，如果您使用某些约束条件（如 requiresCharging: true），WorkManager 会拒绝加急作业。
• 使用场景： 适用于短时间、快速的任务（不到 1 分钟），您希望在 Doze 模式下静默触发，而不打扰用户。

总结

如果您已经在使用 isHeavyTask: true 启动前台服务，那么该任务本身就已经绕过了 Doze 模式。此时再添加 allowWhileIdle: true 是多余的，并且如果您有其他的约束条件，可能会导致 Android 拒绝调度该任务。