Flutter Workmanager

Flutter Workmanager supports multiple platforms, but features like task types, reliability, and constraints vary significantly.

Platform Support Summary

• Android: Full support. All WorkManager features (one-off, periodic, constraints) are available and reliable.
• iOS: Full support via BGTaskScheduler. Includes registerPeriodicTask, registerProcessingTask, and registerHealthResearchTask. Note that tasks do not run after the app is terminated.
• macOS: Partial support. One-off and periodic tasks run via NSBackgroundActivityScheduler only while the app is running/backgrounded. Constraints are ignored.
• Web: Experimental. Uses Service Workers and Web Workers. Periodic tasks map to Periodic Background Sync (best-effort, ~12h minimum).
• Windows/Linux: Not supported.

Key Feature Differences

Experimental web support uses a workmanager_web package to approximate background execution. Because browsers cannot run a full Dart isolate or Flutter engine inside a Service Worker, the plugin uses different strategies depending on the app state:

• When the page is open: Tasks run in a dedicated Web Worker executing a compiled, Flutter-free callback dispatcher (via dart2js) for real parallel execution.
• When the page is closed (Periodic Background Sync - Chromium only): If the PWA is installed and has user engagement, Chrome wakes the Service Worker roughly every max(frequency, 12h). The Service Worker runs the compiled Dart dispatcher using importScripts and records results in IndexedDB.
• When the page is closed (Web Push): A push message wakes the Service Worker to trigger the execution path (server-initiated).
• When the page is closed (Fetch interception): An opportunistic, best-effort wake mechanism.

Results from these background executions are replayed into the app's log upon the next page load.

workmanager_web uses different mechanisms depending on whether the application page is open or closed:

Results from executions that occurred while the page was closed are recorded in IndexedDB and replayed into the app's backgroundEvents stream when the page is next loaded.

Background tasks transition through several states during their lifecycle. Monitoring these states via debug handlers allows you to track the progress of your background work.

Task Status States

iOS does not have a fixed-interval scheduler. registerPeriodicTask is treated as a BGAppRefreshTaskRequest, where the frequency parameter is ignored. The system decides when and if the task runs based on usage patterns.

To achieve more predictable intervals, use Task Chaining: schedule the next run from inside the current task's callback. This ensures the next link is submitted to the BGTaskScheduler and survives app relaunches.

Chaining Characteristics:

• Intervals are floors, not cadences: Intervals will drift and can stretch to hours.
• Requires successful execution: The chain only advances when a link runs and re-submits. If the app is force-quit, the chain stalls.
• App updates: Requests may not survive updates. It is recommended to re-seed the chain from your app's startup path (e.g., main).
• Failure handling: Returning false from a task tells iOS the task failed, which may cause the system to defer future runs. Implement your own backoff by adjusting the initialDelay in the next scheduled task.

@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask((taskName, inputData) async {
    // ... do the work ...

    // Schedule the next run to maintain the chain
    Workmanager().registerPeriodicTask(
      "com.example.sync",
      "sync",
      initialDelay: Duration(hours: 1),
    );
    return true;
  });
}