workmanager 0.5.0-dev.5

Flutter Workmanager. This plugin allows you to schedule background work on Android and iOS.

Flutter Workmanager

Flutter WorkManager is a wrapper around Android's WorkManager, iOS' performFetchWithCompletionHandler and iOS BGAppRefreshTask, effectively enabling headless execution of Dart code in the background.

This is especially useful to run periodic tasks, such as fetching remote data on a regular basis.

This plugin was featured in this Medium blogpost

Platform Setup

In order for background work to be scheduled correctly you should follow the Android and iOS setup first.

• Android Setup
• iOS Setup

How to use the package?

See sample folder for a complete working example.
Before registering any task, the WorkManager plugin must be initialized.

void callbackDispatcher() {
  Workmanager().executeTask((task, inputData) {
    print("Native called background task: $backgroundTask"); //simpleTask will be emitted here.
    return Future.value(true);
  });
}

void main() {
  Workmanager().initialize(
    callbackDispatcher, // The top level function, aka callbackDispatcher
    isInDebugMode: true // If enabled it will post a notification whenever the task is running. Handy for debugging tasks
  );
  Workmanager().registerOneOffTask("1", "simpleTask"); //Android only (see below)
  runApp(MyApp());
}

The callbackDispatcher needs to be either a static function or a top level function to be accessible as a Flutter entry point.

Android tasks are identified using their taskName, whereas two default constants are provided for iOS background operations, depending on whether background fetch or BGTaskScheduler is used: Workmanager.iOSBackgroundTask & Workmanager.iOSBackgroundProcessingTask.

---

Work Result

The Workmanager().executeTask(... block supports 3 possible outcomes:

1. Future.value(true): The task is successful.
2. Future.value(false): The task did not complete successfully and needs to be retried. On Android, the retry is done automatically. On iOS (when using BGTaskScheduler), the retry needs to be scheduled manually.
3. Future.error(...): The task failed.

On Android, the BackoffPolicy will configure how WorkManager is going to retry the task.

Refer to the example app for a successful, retrying and a failed task.

Customisation (iOS - BGTaskScheduler only)

iOS supports One off tasks with a few basic constraints:

Workmanager().registerOneOffTask(
  "1", // Ignored on iOS
  simpleTaskKey, // Ignored on iOS
  initialDelay: Duration(minutes: 30),
  constraints: Constraints(
    // connected or metered mark the task as requiring internet
    networkType: NetworkType.connected,
    // require external power
    requiresCharging: true,
  ),
  inputData: ... // fully supported
);

Tasks registered this way will appear in the callback dispatcher using as Workmanager.iOSBackgroundProcessingTask.

For more information see the BGTaskScheduler documentation.

Customisation (Android)

Not every Android WorkManager feature is ported.

Two kinds of background tasks can be registered :

• One off task : runs only once
• Periodic tasks : runs indefinitely on a regular basis

// One off task registration
Workmanager().registerOneOffTask(
    "1", 
    "simpleTask"
);

// Periodic task registration
Workmanager().registerPeriodicTask(
    "2", 
    "simplePeriodicTask", 
    // When no frequency is provided the default 15 minutes is set.
    // Minimum frequency is 15 min. Android will automatically change your frequency to 15 min if you have configured a lower frequency.
    frequency: Duration(hours: 1),
)

Each task must have an unique name;
This allows cancellation of a started task.
The second parameter is the String that will be send to your callbackDispatcher function, indicating the task's type.

Tagging

You can set the optional tag property.
Handy for cancellation by tag.
This is different from the unique name in that you can group multiple tasks under one tag.

Workmanager().registerOneOffTask("1", "simpleTask", tag: "tag");

Existing Work Policy

Indicates the desired behaviour when the same task is scheduled more than once.
The default is KEEP

Workmanager().registerOneOffTask("1", "simpleTask", existingWorkPolicy: ExistingWorkPolicy.append);

Initial Delay

Indicates how along a task should waitbefore its first run.

Workmanager().registerOneOffTask("1", "simpleTask", initialDelay: Duration(seconds: 10));

Constraints

Not all constraints are mapped.

Workmanager().registerOneOffTask(
    "1", 
    "simpleTask", 
    constraints: Constraints(
        networkType: NetworkType.connected,
        requiresBatteryNotLow: true,
        requiresCharging: true,
        requiresDeviceIdle: true,
        requiresStorageNotLow: true
    )
);

InputData

Add some input data for your task. Valid value types are: int, bool, double, String and their list

 Workmanager().registerOneOffTask(
    "1",
    "simpleTask", 
    inputData: {
    'int': 1,
    'bool': true,
    'double': 1.0,
    'string': 'string',
    'array': [1, 2, 3],
    },
);

BackoffPolicy

Indicates the waiting strategy upon task failure.
The default is BackoffPolicy.exponential.
You can also specify the delay.

Workmanager().registerOneOffTask("1", "simpleTask", backoffPolicy: BackoffPolicy.exponential, backoffPolicyDelay: Duration(seconds: 10));

Cancellation

A task can be cancelled in different ways :

By Tag

Cancels the task that was previously registered using this Tag, if any.

Workmanager().cancelByTag("tag");

By Unique Name

Workmanager().cancelByUniqueName("<MyTask>");

All

Workmanager().cancelAll();