Flutter Workmanager

Flutter WorkManager is a wrapper around Android's WorkManager.
It allows for headless background work to be processed in Dart.

An example of where this would be handy is when you have periodic job that fetches the latest articles every hour.

Note that this library only contains the necessary code to let this work on Android. Since iOS has a vastly different approach you should therefore wrap every call:

if (Platform.isAndroid) { ... }

How to use

See sample folder for a complete working example.

Before you can register any jobs you need to initialize the plugin.

//Provide a top level function or static function.
//This function will be called by Android and will return the value you provided when you registered the task.
//See below
void callbackDispatcher() {
  Workmanager.defaultCallbackDispatcher((echoValue) {
    print("Native echoed: $echoValue");
    return Future.value(true);
  });
}

Workmanager.initialize(
    callbackDispatcher, //the top level function.
    isInDebugMode: true //If enabled it will post a notificiation whenever the job is running. Handy for debugging jobs
)

The callbackDispatcher needs to be either a static function or a top level function for it to work. You should return a boolean value whether the job was successful or not.

Now you can register two different kinds of background work:

  • One off task: These run once
  • Periodic tasks: These run indefinitely with a defined fixed rate
// One off task registration
Workmanager.registerOneOffTask(
    "1", 
    "simpleTask"
);

// Periodic task registration
Workmanager.registerPeriodicTask(
    "2", 
    "simplePeriodicTask", 
    frequency: Duration(hours: 1), //When no frequency is provided the default 15 minutes is set.
)

You will need to provide a unique name; this comes in handy when you want to cancel this task later on.
The second parameter is the String that will be returned to your callbackDispatcher function.
You can use this String to identify which work needs to be done.

Customisation

Not every WorkManager feature is ported.

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 jobs under one tag.

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

Existing Work Policy

What should happen when you schedule the same job twice?
The default is KEEP

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

Initial Delay

The minimum amount a job should wait before its first run.

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

Constraints

Not all constraints are mapped.

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

BackoffPolicy

When a job should fail this specifies the waiting strategy it should use.
The default is BackoffPolicy.exponential.
You can also specify the delay.

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

Cancellation

You can cancel jobs in different ways.

By Tag

If you have provided job with a tag, you can cancel it that way too.

Workmanager.cancelByTag("tag");

By Unique Name

Workmanager.cancelByUniqueName("tag");

All

Workmanager.cancelAll();

Libraries

workmanager

Dart

dart:ui
Built-in types and core primitives for a Flutter application. [...]

Core

dart:async
Support for asynchronous programming, with classes such as Future and Stream. [...]
dart:collection
Classes and utilities that supplement the collection support in dart:core. [...]
dart:convert
Encoders and decoders for converting between different data representations, including JSON and UTF-8. [...]
dart:core
Built-in types, collections, and other core functionality for every Dart program. [...]
dart:developer
Interact with developer tools such as the debugger and inspector. [...]
dart:math
Mathematical constants and functions, plus a random number generator. [...]
dart:typed_data
Lists that efficiently handle fixed sized data (for example, unsigned 8 byte integers) and SIMD numeric types. [...]

VM

dart:io
File, socket, HTTP, and other I/O support for non-web applications. [...]
dart:isolate
Concurrent programming using isolates: independent workers that are similar to threads but don't share memory, communicating only via messages. [...]