flutter_background_executor

Description:

flutter background executor

flutter_background_executor #
This plugin is created for background tasks. It
supports scheduled refresh task
and immediate background task. The refresh task logic is based on
WorkManager for Android
and BackgroundTasks for iOS.
Installation #
In the dependencies: section of your pubspec.yaml, add the following line:
dependencies:
flutter_background_executor: <latest_version>
copied to clipboard
Requirements #
Requires Dart SDK >=2.17.0 <3.0.0
Requires Flutter SDK >=3.0.0
Platforms #
Android #
Requires Android SDK 21+
iOS #
Immediate background task requires iOS 11+
Scheduled refresh task requires iOS 13+
How it works #
To run background tasks, this library creates
new Flutter Engine
. This allows you to run tasks when the application is in the background. In fact, the background
task and the main application are different applications that cannot communicate using basic Flutter
tools. But this is possible if you use the native part of the application and this
is implemented in this library.

Warning: Some libraries may not be ready for this use. But in most cases, you can find a workaround with task management.

Scheduled refresh task #
Flutter #
To schedule a refresh task, call the createRefreshTask function.
class Example {
Future<void> settingRefresh() async {
await FlutterBackgroundExecutor().createRefreshTask(
callback: refresh,
settings: RefreshTaskSettings(
androidDetails: AndroidRefreshTaskDetails(),
iosDetails: IosRefreshTaskDetails(taskIdentifier: 'com.dsr_corporation.refresh-task'),
),
);
}
}
copied to clipboard
In this case, a static function is passed to the callback parameter
class Example {
Future<void> settingRefresh() async {
await FlutterBackgroundExecutor().createRefreshTask(
callback: refresh,
settings: RefreshTaskSettings(
androidDetails: AndroidRefreshTaskDetails(),
iosDetails: IosRefreshTaskDetails(taskIdentifier: 'com.dsr_corporation.refresh-task'),
),
);
}
}

@pragma('vm:entry-point')
Future<void> refresh() async {
print('Called refresh task');
}
copied to clipboard
or
class Example {
Future<void> settingRefresh() async {
await FlutterBackgroundExecutor().createRefreshTask(
callback: refresh,
settings: RefreshTaskSettings(
androidDetails: AndroidRefreshTaskDetails(),
iosDetails: IosRefreshTaskDetails(taskIdentifier: 'com.dsr_corporation.refresh-task'),
),
);
}

@pragma('vm:entry-point')
static Future<void> refresh() async {
print('Called refresh task');
}
}
copied to clipboard

Warning: If you are using Flutter 3.3.0 or newer, you must annotate the refresh task function with @pragma('vm:entry-point').


Note: You can schedule only one refresh task.

Android #
To set up a scheduled refresh task on Android, you can change the following options:



Option
Type
Description
Default value




requiredNetworkType
AndroidNetworkType
The type of network required for the work to run.
AndroidNetworkType.notRequired


requiresCharging
bool
Whether device should be charging for the work to run.
false


requiresDeviceIdle
bool
Whether device should be idle for the work to run(Android SDK 23+).
false


requiresBatteryNotLow
bool
Whether the device's battery level must be acceptable for the work to run.
false


requiresStorageNotLow
bool
Whether the device's available storage should be at an acceptable level for the work to run.
false


minUpdateDelay
Duration
Sets the delay that is allowed from the time a content.
Duration(minutes: 15)


maxUpdateDelay
Duration
Sets the maximum delay that is allowed from the first time a content.
Duration(hours: 1)


initialDelay
Duration
Sets an initial delay for the work.
Duration(minutes: 3)


repeatInterval
Duration
The repeat interval.
Duration(minutes: 15)


flexInterval
Duration
The duration for which this work repeats from the end of the repeatInterval.
Duration(minutes: 15)



iOS #
To set up a background task on iOS, you need to do the following:

Need to add capability Background Modes
Need to select Background fetch and Background processing
Need to set background task identifier in Info.plist
on Permitted background task scheduler identifiers(BGTaskSchedulerPermittedIdentifiers)

The required steps for configuring background work are now complete. But in this case, the task will
be configured only on the second run. This is due to the fact that iOS allows you to configure
background tasks only during the launch of the application itself. In order to set up a task for the
first run, you need to pass the task identifier to the plugin:
@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
SwiftFlutterBackgroundExecutorPlugin.taskIdentifier = "com.dsr-corporation.refresh-task"
...
return super.application(application, didFinishLaunchingWithOptions: launchOptions);
}
}

copied to clipboard
or
@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
UserDefaults.standarхВd.set("com.dsr-corporation.refresh-task", forKey: .taskIdentifierKey)
...
return super.application(application, didFinishLaunchingWithOptions: launchOptions);
}
}
copied to clipboard
For iOS, you can not set the frequency of the background task. The system itself determines the
launch time depending on how the user uses the application and the phone as a whole. To check the
setting, you can use the command:
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"taskID"]
copied to clipboard
Immediate task #
To run a immediately task, call the runImmediatelyBackgroundTask function.
class Example {
Future<void> settingImmediately() async {
await FlutterBackgroundExecutor().runImmediatelyBackgroundTask(
callback: immediately,
taskIdentifier: Tasks.defaultBackground,
currentTaskIdentifier: Tasks.mainApplication,
cancellable: true,
withMessages: true,
);
}
}
copied to clipboard
Similar to the scheduled refresh, only static function can be used as a callback. In this case, a
static function is passed to the callback parameter
class Example {
Future<void> settingRefresh() async {
Future<void> settingImmediately() async {
await FlutterBackgroundExecutor().runImmediatelyBackgroundTask(
callback: immediately,
taskIdentifier: Tasks.defaultBackground,
currentTaskIdentifier: Tasks.mainApplication,
cancellable: true,
withMessages: true,
);
}
}
}

@pragma('vm:entry-point')
Future<void> immediately() async {
print('Called immediately task');
}
copied to clipboard
or
class Example {
Future<void> settingImmediately() async {
await FlutterBackgroundExecutor().runImmediatelyBackgroundTask(
callback: immediately,
taskIdentifier: Tasks.defaultBackground,
currentTaskIdentifier: Tasks.mainApplication,
cancellable: true,
withMessages: true,
);
}

@pragma('vm:entry-point')
static Future<void> immediately() async {
print('Called immediately task');
}
}
copied to clipboard

Warning: If you are using Flutter 3.3.0 or newer, you must annotate the immediate task function with @pragma('vm:entry-point')

To set up a immediate task, you can change the following options:



Option
Type
Description
Default value




taskIdentifier
String
The identifier of the immediate task. It is used to manage background tasks and communicate between background tasks and the application.
'background_task'


currentTaskIdentifier
String
The identifier of the current task. Used to create a connection object.
'main_application'


cancellable
bool
Whether it is allowed to stop the task not only upon its completion, but also by the command.
true


withMessages
bool
Whether it is allowed to send messages to other tasks and receive their messages is allowed.
true




Note: You can run many immediate tasks, but you need to use different task identifier for different tasks.

Communication between tasks #
You can send messages from the application to a background task, from a background task to the
application, and from one background task to another background task. Also, if you need, you can
send a common message that will be send to all tasks except the current one.
Communication between tasks works with EngineConnector object. You can use it for receive message
and send message. For now, you can send only string message, but you can use encode to json and
decode from json for sending objects.
To get an EngineConnector object you can use createConnector method. To work correctly, you must
use the identifier of the current task.
class Example {
static EngineConnector createConnector() {
return FlutterBackgroundExecutor().createConnector(currentTaskIdentifier: [yourIndetifer]);
}
}
copied to clipboard
You can also add an EngineConnector object as a parameter to the task function and the library
will create the object when the task starts.
@pragma('vm:entry-point')
Future<void> immediately(EngineConnector connector) async {
// ...
}
copied to clipboard
Message sending #
To send a message to a specific task you need to use identifier of that task.
Future<bool> sendMessage(Message message, String to) {
return engineConnector.messageSender(to: to, message: jsonEncode(message.toJson()));
}
copied to clipboard
To send a message to all tasks you need to indicate a message as a common message.
Future<bool> sendMessage(Message message) {
return engineConnector.messageSender(commonMessage: true, message: jsonEncode(message.toJson()));
}
copied to clipboard
Message receive #
You can receive messages to your task as stream.
Stream<Message> getMessagesStream() {
return engineConnector.messageStream.map((event) => Message(jsonDecode(event.content)));
}
copied to clipboard

Note: You cannot communicate with the scheduled refresh task.
Warning: For now, you can use communication only for immediate tasks.

Task management #
You can check if a specific task or any tasks are currently running, and you can also stop them.
This is useful for working around the problems with libraries that don`t support in any tasks.

Note: You can manage tasks from any task. Be careful.

Checking running tasks #
To check any tasks:
Future<bool> hasRunningTasks() {
return FlutterBackgroundExecutor().hasRunningTasks();
}
copied to clipboard
To check a specific task:
Future<bool> isTaskRunning([String identifier = Tasks.defaultBackground]) {
return FlutterBackgroundExecutor(identifier).isTaskRunning();
}
copied to clipboard
To check a scheduled refresh task:
Future<bool> isRefreshTaskRunning() {
return FlutterBackgroundExecutor().isRefreshTaskRunning();
}
copied to clipboard
Stopping running task #
To stop any tasks:
Future<bool> stopAllExecutingTasks() {
return FlutterBackgroundExecutor().stopAllExecutingTasks();
}
copied to clipboard
To stop a specific task:
Future<bool> stopExecutingTask([String identifier = Tasks.defaultBackground]) {
return FlutterBackgroundExecutor(identifier).stopExecutingTask();
}
copied to clipboard
To stop a scheduled refresh task:
Future<bool> stopRefreshTask() {
return FlutterBackgroundExecutor().stopRefreshTask();
}
copied to clipboard

Note: You can always cancel a scheduled refresh task.
Warning: If you set the cancellable parameter to false when creating an immediate task, you can`t to stop it.

Cancelling scheduled refresh task #
Also you can cancel the scheduled refresh task and it will not work in future.
To stop a scheduled refresh task, you need to use the identifier returned when the task was created.
Future<bool> cancelTask(String identifier) {
return FlutterBackgroundExecutor().cancelTask(identifier: identifier);
}
copied to clipboard
For now, you can also use the following method to cancel a scheduled refresh task, but it cancels
all scheduled refresh tasks. As long as the plugin only supports one refresh task, it's the same
solution.
Future<bool> cancelAllTasks() {
return FlutterBackgroundExecutor().cancelAllTasks();
}
copied to clipboard