Quick Start
Get started with Flutter Workmanager in minutes
Installation
Add workmanager
to your pubspec.yaml
:
dependencies:
workmanager: ^0.8.0
Then run:
flutter pub get
Option A: Periodic Tasks (Recommended for most use cases)
For regular data sync, notifications, cleanup - uses iOS Background Fetch:
- Enable Background Modes in Xcode target capabilities (Xcode Help) and add to Info.plist:
<key>UIBackgroundModes</key>
<array>
<string>fetch</string>
</array>
- No AppDelegate configuration needed - works automatically from Dart code
iOS Background Fetch scheduling: iOS completely controls when Background Fetch runs (typically once per day based on user app usage patterns). You cannot force immediate execution - it's designed for non-critical periodic updates like refreshing content.
Option B: Processing Tasks (For complex operations)
For file uploads, data processing, longer tasks - uses BGTaskScheduler:
- Enable Background Modes in Xcode target capabilities (Xcode Help) and add to Info.plist:
<key>UIBackgroundModes</key>
<array>
<string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>com.yourapp.processing_task</string>
</array>
- Configure AppDelegate.swift (required for BGTaskScheduler):
import workmanager_apple
// In application didFinishLaunching
WorkmanagerPlugin.registerBGProcessingTask(
withIdentifier: "com.yourapp.processing_task"
)
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.
Option C: Periodic Tasks with Custom Frequency
For periodic tasks with more control than Background Fetch - uses BGTaskScheduler with frequency:
- Enable Background Modes in Xcode target capabilities (Xcode Help) and add to Info.plist:
<key>UIBackgroundModes</key>
<array>
<string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>com.yourapp.periodic_task</string>
</array>
- Configure AppDelegate.swift (with frequency control):
import workmanager_apple
// In application didFinishLaunching
WorkmanagerPlugin.registerPeriodicTask(
withIdentifier: "com.yourapp.periodic_task",
frequency: NSNumber(value: 20 * 60) // 20 minutes (15 min minimum)
)
Which option to choose?
- Option A (Background Fetch) for non-critical updates that can happen once daily (data sync, content refresh)
- Option B (BGTaskScheduler) for one-time tasks, file uploads, or immediate task scheduling
- Option C (Periodic Tasks) for regular tasks with custom frequency control (15+ minutes)
1. Create Background Task Handler
@pragma('vm:entry-point')
void callbackDispatcher() {
Workmanager().executeTask((task, inputData) async {
switch (task) {
case "data_sync":
await syncDataWithServer();
break;
case "cleanup":
await cleanupOldFiles();
break;
case Workmanager.iOSBackgroundTask:
// iOS Background Fetch task
await handleBackgroundFetch();
break;
default:
// Handle unknown task types
break;
}
return Future.value(true);
});
}
Important: The callbackDispatcher
must be a top-level function (not inside a class) since it runs in a separate isolate.
2. Initialize in main()
import 'package:flutter/foundation.dart';
void main() {
Workmanager().initialize(callbackDispatcher);
runApp(MyApp());
}
3. Schedule Tasks
// Schedule a one-time task
Workmanager().registerOneOffTask(
"sync-task",
"data_sync",
initialDelay: Duration(seconds: 10),
);
// Schedule a periodic task
Workmanager().registerPeriodicTask(
"cleanup-task",
"cleanup",
frequency: Duration(hours: 24),
);
Task Results
Your background tasks can return:
Future.value(true)
- ✅ Task successfulFuture.value(false)
- 🔄 Task should be retriedFuture.error(...)
- ❌ Task failed
Key Points
- Callback Dispatcher: Must be a top-level function (not inside a class)
- Separate Isolate: Background tasks run in isolation - initialize dependencies inside the task
- Platform Differences:
- Android: Reliable background execution, 15-minute minimum frequency
- iOS: 30-second limit, execution depends on user patterns and device state
Next Steps
- Task Customization - Advanced configuration with constraints, input data, and management
- Debugging Guide - Learn how to debug and troubleshoot background tasks
- Example App - Complete working demo