Skip to content

quickstart.mdx

Latest commit

 

History

History
216 lines (169 loc) · 6.62 KB

quickstart.mdx

File metadata and controls

216 lines (169 loc) · 6.62 KB
title Quick Start
description Get started with Flutter Workmanager in minutes

Installation

Add workmanager to your pubspec.yaml:

dependencies:
  workmanager: ^0.8.0

Then run:

flutter pub get

Platform Setup

Android

Android works automatically - no additional setup required! ✅

iOS

**iOS Minimum Deployment Target:** iOS 14.0 or later is required. Update your project's deployment target in Xcode: 1. Open `ios/Runner.xcodeproj` in Xcode 2. Select the Runner target 3. Set "Minimum Deployments" to iOS 14.0 or later 4. Or edit `ios/Runner.xcodeproj/project.pbxproj` and set `IPHONEOS_DEPLOYMENT_TARGET = 14.0;`

iOS requires a 5-minute setup in Xcode. Choose your approach based on your needs:

Option A: Periodic Tasks (Recommended for most use cases)

For regular data sync, notifications, cleanup - uses iOS Background Fetch:

  1. Enable Background Modes in Xcode target capabilities (Configuration Guide) and add to Info.plist (UIBackgroundModes reference):
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
</array>
  1. 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:

  1. Enable Background Modes in Xcode target capabilities (Configuration Guide) and add to Info.plist (UIBackgroundModes reference):
<key>UIBackgroundModes</key>
<array>
    <string>processing</string>
</array>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.yourapp.processing_task</string>
</array>
  1. 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:

  1. Enable Background Modes in Xcode target capabilities (Configuration Guide) and add to Info.plist (UIBackgroundModes reference):
<key>UIBackgroundModes</key>
<array>
    <string>processing</string>
</array>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.yourapp.periodic_task</string>
</array>
  1. 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)

Basic Usage

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),
);

// Schedule a periodic task with input data
Workmanager().registerPeriodicTask(
  "sync-task",
  "data_sync",
  frequency: Duration(hours: 6),
  inputData: <String, dynamic>{
    'server_url': 'https://api.example.com',
    'sync_type': 'full',
    'max_retries': 3,
  },
);

## Task Results

Your background tasks can return:

- `Future.value(true)` - ✅ Task successful
- `Future.value(false)` - 🔄 Task should be retried
- `Future.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](customization)** - Advanced configuration with constraints, input data, and management
- **[Debugging Guide](debugging)** - Learn how to debug and troubleshoot background tasks  
- **[Example App](https://github.com/fluttercommunity/flutter_workmanager/tree/main/example)** - Complete working demo