Skip to content

Commit 300cbbf

Browse files
authored
Fix iOS task identifier mismatch in Quick Start documentation
## Problem The current Quick Start guide shows task identifiers that don't match between Dart and iOS native code, which causes `BGTaskSchedulerErrorDomain Code 3` errors on iOS. **Current Issue:** - Info.plist: `com.yourapp.processing_task` - AppDelegate: `com.yourapp.processing_task` - Dart code: `"data_sync"` ❌ (doesn't match!) This mismatch prevents iOS background tasks from being scheduled successfully. ## Solution Update documentation to show that **all three locations must use the same identifier**: - Info.plist: `com.yourapp.processing_task` - AppDelegate: `com.yourapp.processing_task` - Dart code: `com.yourapp.processing_task` ✅ ## Testing Tested on iOS 26 with BGTaskScheduler - background tasks now schedule successfully without Code 3 errors.
1 parent 7f4f870 commit 300cbbf

1 file changed

Lines changed: 14 additions & 5 deletions

File tree

docs/quickstart.mdx

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,10 @@ WorkmanagerPlugin.registerBGProcessingTask(
7777
)
7878
```
7979

80+
<Warning>
81+
**iOS Task Identifier Matching:** The task name in your Dart code must **exactly match** the identifier in Info.plist and AppDelegate. Using short names like `"data_sync"` in Dart while having `com.yourapp.processing_task` in native code will cause `BGTaskSchedulerErrorDomain Code 3` errors.
82+
</Warning>
83+
8084
<Info>
8185
**Why BGTaskScheduler registration is needed:** iOS requires explicit registration of background task identifiers for security and system resource management. The task identifier in Info.plist tells iOS which background tasks your app can schedule, while the AppDelegate registration connects the identifier to the actual task handler. Background Fetch (Option A) doesn't require this since it uses the simpler, system-managed approach.
8286
</Info>
@@ -108,6 +112,10 @@ WorkmanagerPlugin.registerPeriodicTask(
108112
)
109113
```
110114

115+
<Warning>
116+
**iOS Task Identifier Matching:** The task name in your Dart code must **exactly match** the identifier in Info.plist and AppDelegate. Using short names like `"cleanup"` in Dart while having `com.yourapp.periodic_task` in native code will cause `BGTaskSchedulerErrorDomain Code 3` errors.
117+
</Warning>
118+
111119
<Success>
112120
**Which option to choose?**
113121
- **Option A (Background Fetch)** for non-critical updates that can happen once daily (data sync, content refresh)
@@ -124,10 +132,10 @@ WorkmanagerPlugin.registerPeriodicTask(
124132
void callbackDispatcher() {
125133
Workmanager().executeTask((task, inputData) async {
126134
switch (task) {
127-
case "data_sync":
135+
case "com.yourapp.processing_task": // Must match Info.plist and AppDelegate
128136
await syncDataWithServer();
129137
break;
130-
case "cleanup":
138+
case "com.yourapp.periodic_task": // Must match Info.plist and AppDelegate
131139
await cleanupOldFiles();
132140
break;
133141
case Workmanager.iOSBackgroundTask:
@@ -166,14 +174,14 @@ void main() {
166174
// Schedule a one-time task
167175
Workmanager().registerOneOffTask(
168176
"sync-task",
169-
"data_sync",
177+
"com.yourapp.processing_task", // Must match Info.plist and AppDelegate
170178
initialDelay: Duration(seconds: 10),
171179
);
172180
173181
// Schedule a periodic task
174182
Workmanager().registerPeriodicTask(
175183
"cleanup-task",
176-
"cleanup",
184+
"com.yourapp.periodic_task", // Must match Info.plist and AppDelegate
177185
frequency: Duration(hours: 24),
178186
);
179187
```
@@ -191,6 +199,7 @@ Your background tasks can return:
191199

192200
- **Callback Dispatcher**: Must be a top-level function (not inside a class)
193201
- **Separate Isolate**: Background tasks run in isolation - initialize dependencies inside the task
202+
- **iOS Task Identifiers**: When using BGTaskScheduler (Options B & C), task names in Dart must exactly match identifiers in Info.plist and AppDelegate
194203
- **Platform Differences**:
195204
- Android: Reliable background execution, 15-minute minimum frequency
196205
- iOS: 30-second limit, execution depends on user patterns and device state
@@ -200,4 +209,4 @@ Your background tasks can return:
200209

201210
- **[Task Customization](customization)** - Advanced configuration with constraints, input data, and management
202211
- **[Debugging Guide](debugging)** - Learn how to debug and troubleshoot background tasks
203-
- **[Example App](https://github.com/fluttercommunity/flutter_workmanager/tree/main/example)** - Complete working demo
212+
- **[Example App](https://github.com/fluttercommunity/flutter_workmanager/tree/main/example)** - Complete working demo

0 commit comments

Comments
 (0)