From 15da751a2445f16277d32a4881cb2f7ce333a533 Mon Sep 17 00:00:00 2001 From: Sebastian Roth Date: Sat, 1 Aug 2026 13:56:23 +0100 Subject: [PATCH 1/2] docs: add platform capability matrix and clarify callbackDispatcher - Overview: add a platform capability matrix covering task types, initialDelay, inputData, taskName semantics, constraints, cancellation, killed-state behavior, and run-time budgets on Android vs iOS. - Quick Start: explain what callbackDispatcher is, why it must be a top-level/static function, and how to dispatch tasks; clarify that one-off tasks need no AppDelegate registration on iOS. - Customization: document that periodic initialDelay is a best-effort hint on Android (androidx.work behavior) and iOS, with a workaround. Fixes #381 Fixes #404 Refs #594 --- docs/customization.mdx | 13 +++++++++++-- docs/index.mdx | 37 ++++++++++++++++++++++++++++++++++++ docs/quickstart.mdx | 43 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 90 insertions(+), 3 deletions(-) diff --git a/docs/customization.mdx b/docs/customization.mdx index 69db3cbc..b27f25fa 100644 --- a/docs/customization.mdx +++ b/docs/customization.mdx @@ -140,11 +140,20 @@ Workmanager().registerPeriodicTask( "hourly-sync", "data_sync", frequency: Duration(hours: 1), // Android: minimum 15 minutes - initialDelay: Duration(minutes: 5), // Wait before first execution + initialDelay: Duration(minutes: 5), // Best-effort hint for the first run (see warning below) inputData: {'syncType': 'incremental'} ); ``` + +**Periodic `initialDelay` is best-effort.** WorkManager (Android) treats it as a +hint: depending on the `androidx.work` version, the first run can happen anywhere +within the first interval. On iOS it becomes the earliest-begin hint for +BGTaskScheduler, which iOS may ignore entirely. If you need the *first* execution +to happen at a specific time, schedule a one-off task with `initialDelay` that +registers the periodic task when it runs. + + ## Advanced Configuration ### Task Identification @@ -279,4 +288,4 @@ void callbackDispatcher() { **Pro Tip:** Always initialize dependencies inside your background task callback since it runs in a separate isolate from your main app. - \ No newline at end of file + diff --git a/docs/index.mdx b/docs/index.mdx index 8545bd68..4bce6fed 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -22,6 +22,43 @@ Execute Dart code in the background, even when your app is closed. Perfect for d | Web | ❌ Not supported | Background execution not available | | Windows/Linux | ❌ Not supported | No background task APIs | +## Platform Capability Matrix + +Not every feature behaves the same on Android and iOS. The table below +summarizes what works where, so you can design your tasks around the +capabilities of each platform. + +| Feature | Android | iOS | +|---|---|---| +| One-off tasks (`registerOneOffTask`) | ✅ Scheduled by the OS; survives app restarts | ⚠️ Runs via `beginBackgroundTask` while the app is alive (foreground or shortly after backgrounding). Not guaranteed after the app is terminated | +| Periodic tasks (`registerPeriodicTask`) | ✅ Reliable, 15-minute minimum frequency | ⚠️ Best-effort. iOS decides when (and whether) background fetch runs, based on app usage; 15-minute minimum hint | +| Processing tasks (`registerProcessingTask`) | ❌ Not supported | ✅ BGProcessingTask (longer work, requires registration in AppDelegate) | +| `initialDelay` | ✅ Honored for one-off tasks. For periodic tasks it is best-effort (see below) | ⚠️ One-off: honored while the app stays alive. Periodic: used as the earliest-begin hint for BGTaskScheduler | +| `inputData` | ✅ All supported types | ✅ Supported for one-off and periodic tasks | +| `taskName` in callback | ✅ The value you passed as `taskName` | ✅ One-off tasks receive the `taskName` you passed. Periodic/processing tasks receive the BGTaskScheduler identifier (the `uniqueName` you registered) | +| `frequency` | ✅ Configured from Dart | ❌ Configured in `AppDelegate.swift` via `registerPeriodicTask(withIdentifier:frequency:)` | +| Constraints (network, charging, battery) | ✅ Supported | ❌ iOS applies its own system-level constraints | +| `cancelByUniqueName` / `cancelAll` | ✅ | ✅ Only cancels BGTaskScheduler requests (periodic/processing) | +| `cancelByTag` | ✅ | ❌ Not supported (no-op) | +| Task execution after app is killed | ✅ Yes (one-off/periodic) | ❌ No — iOS does not run tasks after the app is terminated | +| Minimum run time budget | No hard limit, but WorkManager may defer work | ~30 seconds per task execution | + + +**Periodic `initialDelay` on Android:** WorkManager treats the initial delay of a +periodic task as a hint. Depending on the `androidx.work` version, the first run +may happen anywhere within the first interval rather than exactly after the +delay. If you need a task to run exactly once at a specific time and then repeat, +schedule a one-off task with the desired `initialDelay` and re-register the +periodic task from inside its callback. + + + +**iOS one-off `initialDelay`:** The delay is honored only while the app remains +alive. iOS may suspend or terminate the app before the delay elapses, in which +case the task does not run. For work that must run later regardless, use a +processing task. + + ## Common Use Cases | Use Case | Description | diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 9d01c499..fc69e465 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -156,6 +156,47 @@ void callbackDispatcher() { **Important:** The `callbackDispatcher` must be a top-level function (not inside a class) since it runs in a separate isolate. +### What is `callbackDispatcher`? + +`callbackDispatcher` is the *entry point* of your background isolate. It is not +the task itself: it is the function that iOS and Android start whenever a +scheduled task becomes due, and inside it you tell the plugin which handler to +run via `Workmanager().executeTask(...)`. + +```dart +@pragma('vm:entry-point') +void callbackDispatcher() { + Workmanager().executeTask((task, inputData) async { + // This closure is where your background work actually runs. + switch (task) { + case 'data_sync': + await syncData(inputData); + break; + } + return Future.value(true); + }); +} +``` + +Requirements and behavior: + +- It must be a **top-level function** or a **static method**. Flutter needs to + look it up by handle when the app is started from the background, which is + only possible for top-level/static functions (`PluginUtilities.getCallbackHandle` + returns `null` for anything else). +- It must be annotated with `@pragma('vm:entry-point')` so the Dart compiler + keeps it reachable for background starts. +- It runs in a **separate isolate** from your UI. Initialize plugins and + dependencies (e.g. `DartPluginRegistrant.ensureInitialized()`, + `SharedPreferences`, `Firebase.initializeApp`) *inside* the handler, not in + `main()`. +- You register exactly one dispatcher per app (in `main()`) and dispatch on + `task` inside it. You do not need a separate `callbackDispatcher` per task. + +The name can be confusing: the function is really your *task runner*, but the +name is kept for historical reasons. Feel free to name it `taskRunner` or +`backgroundTaskHandler` in your own code. + ### 2. Initialize in main() ```dart @@ -174,7 +215,7 @@ void main() { // Schedule a one-time task Workmanager().registerOneOffTask( "sync-task", - "com.yourapp.processing_task", // Must match Info.plist and AppDelegate + "data_sync", // taskName: the value your callback receives (no AppDelegate setup needed) initialDelay: Duration(seconds: 10), ); From 14619e55267ee2c6f6bd1dd61630167f5b61027e Mon Sep 17 00:00:00 2001 From: Sebastian Roth Date: Sat, 1 Aug 2026 13:58:01 +0100 Subject: [PATCH 2/2] docs: warn that iOS registerPeriodicTask needs BGTaskScheduler setup Follow-up on #660: clarify that on iOS registerPeriodicTask submits the uniqueName to BGTaskScheduler and therefore requires the identifier in Info.plist and an AppDelegate registration; also use the correct 'fetch' background mode for BGAppRefreshTask in Option C. --- docs/quickstart.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index fc69e465..d6eac6fd 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -92,7 +92,7 @@ For periodic tasks with more control than Background Fetch - uses BGTaskSchedule ```xml UIBackgroundModes - processing + fetch BGTaskSchedulerPermittedIdentifiers @@ -239,6 +239,16 @@ Workmanager().registerPeriodicTask( ); ``` + +**iOS: `registerPeriodicTask` requires BGTaskScheduler setup.** On iOS the +`uniqueName` you pass here is submitted to BGTaskScheduler, so it must appear in +`BGTaskSchedulerPermittedIdentifiers` in Info.plist **and** be registered in +AppDelegate via `WorkmanagerPlugin.registerPeriodicTask(withIdentifier:)` +(see Option C above). Without that you'll get `BGTaskSchedulerErrorDomain +Code 3` ("not advertised in the application's Info.plist"). On Android no +native setup is needed. + + ## Task Results Your background tasks can return: