flutter_foreground_task

Description:

flutter foreground task

This plugin is used to implement a foreground service on the Android platform.





Features #

Can perform repetitive tasks with the foreground service.
Supports two-way communication between the foreground service and UI.
Provides widget that minimize the app without closing it when the user presses the soft back button.
Provides useful utilities that can use while performing tasks.
Provides option to automatically resume the foreground service on boot.

Getting started #
To use this plugin, add flutter_foreground_task as a dependency in your pubspec.yaml file. For example:
dependencies:
flutter_foreground_task: ^8.8.1+1
copied to clipboard
After adding the flutter_foreground_task plugin to the flutter project, we need to specify the permissions and service to use for this plugin to work properly.
🐤 Android #
Open the AndroidManifest.xml file and specify the service inside the <application> tag as follows.
If you want the foreground service to run only when the app is running, add android:stopWithTask="true" option.
As it is mentioned in the Android Guidelines, in Android 14, to start a FG service, you need to specify android:foregroundServiceType.
You can read all the details in the Android Developer Page : https://developer.android.com/about/versions/14/changes/fgs-types-required
If you want to target Android 14 phones, you need to add a few lines to your manifest.
Change the type with your type (all types are listed in the link above).
<!-- required -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<!-- foregroundServiceType: dataSync -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />

<!-- foregroundServiceType: remoteMessaging -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_REMOTE_MESSAGING" />

<!-- Warning: Do not change service name. -->
<service
android:name="com.pravera.flutter_foreground_task.service.ForegroundService"
android:foregroundServiceType="dataSync|remoteMessaging"
android:exported="false" />
copied to clipboard
Check runtime requirements before starting the service. If this requirement is not met, the foreground service cannot be started.

🐤 iOS #
We can also launch flutter_foreground_task on the iOS platform. However, it has the following limitations.

Works only on iOS 12.0 or later.
If you force close an app in recent apps, the task will be destroyed immediately.
The task cannot be started automatically on boot like Android OS.
The task will run in the background for approximately 30 seconds due to background processing limitations. but it works fine in the foreground.

Objective-C:


To use this plugin developed in Swift language in a project using Objective-C, you need to add a bridge header. If you don't have an ios/Runner/Runner-Bridging-Header.h file in your project, check this page.


Open the ios/Runner/AppDelegate.swift file and add the commented code.


#import "AppDelegate.h"
#import "GeneratedPluginRegistrant.h"

// here
#import <flutter_foreground_task/FlutterForegroundTaskPlugin.h>

// here
void registerPlugins(NSObject<FlutterPluginRegistry>* registry) {
[GeneratedPluginRegistrant registerWithRegistry:registry];
}

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[GeneratedPluginRegistrant registerWithRegistry:self];

// here, without this code the task will not work.
[FlutterForegroundTaskPlugin setPluginRegistrantCallback:registerPlugins];
if (@available(iOS 10.0, *)) {
[UNUserNotificationCenter currentNotificationCenter].delegate = (id<UNUserNotificationCenterDelegate>) self;
}

return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

copied to clipboard
Swift:

Declare the import statement below in the ios/Runner/Runner-Bridging-Header.h file.

#import <flutter_foreground_task/FlutterForegroundTaskPlugin.h>
copied to clipboard

Open the ios/Runner/AppDelegate.swift file and add the commented code.

import UIKit
import Flutter

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
GeneratedPluginRegistrant.register(with: self)

// here, without this code the task will not work.
SwiftFlutterForegroundTaskPlugin.setPluginRegistrantCallback(registerPlugins)
if #available(iOS 10.0, *) {
UNUserNotificationCenter.current().delegate = self as? UNUserNotificationCenterDelegate
}

return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}

// here
func registerPlugins(registry: FlutterPluginRegistry) {
GeneratedPluginRegistrant.register(with: registry)
}
copied to clipboard
Configuring background execution modes
Background mode settings are required for tasks to be processed in the background.
See this page for settings.
How to use #
🐥 step by step #

Initialize port for communication between TaskHandler and UI.

void main() {
// Initialize port for communication between TaskHandler and UI.
FlutterForegroundTask.initCommunicationPort();
runApp(const ExampleApp());
}
copied to clipboard

Write a TaskHandler and a callback to request starting a TaskHandler.

// The callback function should always be a top-level function.
@pragma('vm:entry-point')
void startCallback() {
// The setTaskHandler function must be called to handle the task in the background.
FlutterForegroundTask.setTaskHandler(MyTaskHandler());
}

class MyTaskHandler extends TaskHandler {
// Called when the task is started.
@override
void onStart(DateTime timestamp) {
print('onStart');
}

// Called by eventAction in [ForegroundTaskOptions].
// - nothing() : Not use onRepeatEvent callback.
// - once() : Call onRepeatEvent only once.
// - repeat(interval) : Call onRepeatEvent at milliseconds interval.
@override
void onRepeatEvent(DateTime timestamp) {
// Send data to main isolate.
final Map<String, dynamic> data = {
"timestampMillis": timestamp.millisecondsSinceEpoch,
};
FlutterForegroundTask.sendDataToMain(data);
}

// Called when the task is destroyed.
@override
void onDestroy(DateTime timestamp) {
print('onDestroy');
}

// Called when data is sent using [FlutterForegroundTask.sendDataToTask].
@override
void onReceiveData(Object data) {
print('onReceiveData: $data');
}

// Called when the notification button is pressed.
@override
void onNotificationButtonPressed(String id) {
print('onNotificationButtonPressed: $id');
}

// Called when the notification itself is pressed.
//
// AOS: "android.permission.SYSTEM_ALERT_WINDOW" permission must be granted
// for this function to be called.
@override
void onNotificationPressed() {
FlutterForegroundTask.launchApp('/');
print('onNotificationPressed');
}

// Called when the notification itself is dismissed.
//
// AOS: only work Android 14+
// iOS: only work iOS 10+
@override
void onNotificationDismissed() {
print('onNotificationDismissed');
}
}
copied to clipboard

Add a callback to receive data sent from the TaskHandler. If the screen or controller is disposed, be sure to call the removeTaskDataCallback function.

void _onReceiveTaskData(Object data) {
if (data is Map<String, dynamic>) {
final dynamic timestampMillis = data["timestampMillis"];
if (timestampMillis != null) {
final DateTime timestamp =
DateTime.fromMillisecondsSinceEpoch(timestampMillis, isUtc: true);
print('timestamp: ${timestamp.toString()}');
}
}
}

@override
void initState() {
super.initState();
// Add a callback to receive data sent from the TaskHandler.
FlutterForegroundTask.addTaskDataCallback(_onReceiveTaskData);
}

@override
void dispose() {
// Remove a callback to receive data sent from the TaskHandler.
FlutterForegroundTask.removeTaskDataCallback(_onReceiveTaskData);
super.dispose();
}
copied to clipboard

Request permissions and initialize the service.

Future<void> _requestPermissions() async {
// Android 13+, you need to allow notification permission to display foreground service notification.
//
// iOS: If you need notification, ask for permission.
final NotificationPermission notificationPermission =
await FlutterForegroundTask.checkNotificationPermission();
if (notificationPermission != NotificationPermission.granted) {
await FlutterForegroundTask.requestNotificationPermission();
}

if (Platform.isAndroid) {
// "android.permission.SYSTEM_ALERT_WINDOW" permission must be granted for
// onNotificationPressed function to be called.
//
// When the notification is pressed while permission is denied,
// the onNotificationPressed function is not called and the app opens.
//
// If you do not use the onNotificationPressed or launchApp function,
// you do not need to write this code.
if (!await FlutterForegroundTask.canDrawOverlays) {
// This function requires `android.permission.SYSTEM_ALERT_WINDOW` permission.
await FlutterForegroundTask.openSystemAlertWindowSettings();
}

// Android 12+, there are restrictions on starting a foreground service.
//
// To restart the service on device reboot or unexpected problem, you need to allow below permission.
if (!await FlutterForegroundTask.isIgnoringBatteryOptimizations) {
// This function requires `android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` permission.
await FlutterForegroundTask.requestIgnoreBatteryOptimization();
}

// Use this utility only if you provide services that require long-term survival,
// such as exact alarm service, healthcare service, or Bluetooth communication.
//
// This utility requires the "android.permission.SCHEDULE_EXACT_ALARM" permission.
// Using this permission may make app distribution difficult due to Google policy.
if (!await FlutterForegroundTask.canScheduleExactAlarms) {
// When you call this function, will be gone to the settings page.
// So you need to explain to the user why set it.
await FlutterForegroundTask.openAlarmsAndRemindersSettings();
}
}
}

void _initService() {
FlutterForegroundTask.init(
androidNotificationOptions: AndroidNotificationOptions(
channelId: 'foreground_service',
channelName: 'Foreground Service Notification',
channelDescription:
'This notification appears when the foreground service is running.',
channelImportance: NotificationChannelImportance.LOW,
priority: NotificationPriority.LOW,
),
iosNotificationOptions: const IOSNotificationOptions(
showNotification: false,
playSound: false,
),
foregroundTaskOptions: ForegroundTaskOptions(
eventAction: ForegroundTaskEventAction.repeat(5000),
autoRunOnBoot: true,
autoRunOnMyPackageReplaced: true,
allowWakeLock: true,
allowWifiLock: true,
),
);
}

@override
void initState() {
super.initState();
// Add a callback to receive data sent from the TaskHandler.
FlutterForegroundTask.addTaskDataCallback(_onReceiveTaskData);

WidgetsBinding.instance.addPostFrameCallback((_) {
// Request permissions and initialize the service.
_requestPermissions();
_initService();
});
}
copied to clipboard

Use FlutterForegroundTask.startService to start the service. startService provides the following options:


serviceId: The unique ID that identifies the service.
notificationTitle: The title to display in the notification.
notificationText: The text to display in the notification.
notificationIcon: The icon to display in the notification. (only work Android)
notificationButtons: The buttons to display in the notification. (can add 0~3 buttons)
callback: A top-level function that calls the setTaskHandler function.

Future<ServiceRequestResult> _startService() async {
if (await FlutterForegroundTask.isRunningService) {
return FlutterForegroundTask.restartService();
} else {
return FlutterForegroundTask.startService(
serviceId: 256,
notificationTitle: 'Foreground Service is running',
notificationText: 'Tap to return to the app',
notificationIcon: null,
notificationButtons: [
const NotificationButton(id: 'btn_hello', text: 'hello'),
],
callback: startCallback,
);
}
}
copied to clipboard

Note
iOS Platform, notificationButtons is not displayed directly in notification.
When the user slides down the notification, the button is displayed, so you need to guide the user on how to use it.
https://developer.apple.com/documentation/usernotifications/declaring-your-actionable-notification-types
If you know a better implementation, please let me know on GitHub :)


Use FlutterForegroundTask.updateService to update the service. The options are the same as the start function.

@pragma('vm:entry-point')
void startCallback() {
FlutterForegroundTask.setTaskHandler(FirstTaskHandler());
}

class FirstTaskHandler extends TaskHandler {
int _count = 0;

@override
void onStart(DateTime timestamp) {
// some code
}

@override
void onRepeatEvent(DateTime timestamp) {
_count++;

if (_count == 10) {
FlutterForegroundTask.updateService(
foregroundTaskOptions: ForegroundTaskOptions(
eventAction: ForegroundTaskEventAction.repeat(1000),
),
callback: updateCallback,
);
} else {
FlutterForegroundTask.updateService(
notificationTitle: 'FirstTask',
notificationText: timestamp.toString(),
);

// Send data to main isolate.
final Map<String, dynamic> data = {
"timestampMillis": timestamp.millisecondsSinceEpoch,
};
FlutterForegroundTask.sendDataToMain(data);
}
}

@override
void onDestroy(DateTime timestamp) {
// some code
}
}

@pragma('vm:entry-point')
void updateCallback() {
FlutterForegroundTask.setTaskHandler(SecondTaskHandler());
}

class SecondTaskHandler extends TaskHandler {
@override
void onStart(DateTime timestamp) {
// some code
}

@override
void onRepeatEvent(DateTime timestamp) {
FlutterForegroundTask.updateService(
notificationTitle: 'SecondTask',
notificationText: timestamp.toString(),
);

// Send data to main isolate.
final Map<String, dynamic> data = {
"timestampMillis": timestamp.millisecondsSinceEpoch,
};
FlutterForegroundTask.sendDataToMain(data);
}

@override
void onDestroy(DateTime timestamp) {
// some code
}
}
copied to clipboard

If you no longer use the service, call FlutterForegroundTask.stopService.

Future<ServiceRequestResult> _stopService() async {
return FlutterForegroundTask.stopService();
}
copied to clipboard
🐥 deepening #
This plugin supports two-way communication between TaskHandler and UI.
The send function can only send primitive type(int, double, bool), String, Collection(Map, List) provided by Flutter.
If you want to send a custom object, send it in String format using jsonEncode and jsonDecode.
JSON and serialization >> https://docs.flutter.dev/data-and-backend/serialization/json
// TaskHandler
@override
void onStart(DateTime timestamp) {
// TaskHandler -> Main(UI)
FlutterForegroundTask.sendDataToMain(Object);
}

// Main(UI)
void _onReceiveTaskData(Object data) {
print('onReceiveTaskData: $data');
}
copied to clipboard
// Main(UI)
void _sendDataToTask() {
// Main(UI) -> TaskHandler
//
// The Map collection can only be sent in json format, such as Map<String, dynamic>.
FlutterForegroundTask.sendDataToTask(Object);
}

// TaskHandler
@override
void onReceiveData(Object data) {
print('onReceiveData: $data');

// You can cast it to any type you want using the Collection.cast<T> function.
if (data is List<dynamic>) {
final List<int> intList = data.cast<int>();
}
}
copied to clipboard
And there are some functions for storing and managing data that are only used in this plugin.
void function() async {
await FlutterForegroundTask.getData(key: String);
await FlutterForegroundTask.getAllData();
await FlutterForegroundTask.saveData(key: String, value: Object);
await FlutterForegroundTask.removeData(key: String);
await FlutterForegroundTask.clearAllData();
}
copied to clipboard
If the plugin you want to use provides a stream, use it like this:
class MyTaskHandler extends TaskHandler {
StreamSubscription<Location>? _streamSubscription;

@override
void onStart(DateTime timestamp) {
_streamSubscription = FlLocation.getLocationStream().listen((location) {
final String message = '${location.latitude}, ${location.longitude}';
FlutterForegroundTask.updateService(notificationText: message);

// Send data to main isolate.
final String locationJson = jsonEncode(location.toJson());
FlutterForegroundTask.sendDataToMain(locationJson);
});
}

@override
void onRepeatEvent(DateTime timestamp) {
// not use
}

@override
void onDestroy(DateTime timestamp) {
_streamSubscription?.cancel();
_streamSubscription = null;
}
}
copied to clipboard
🐥 other example #

internal_plugin_service (Recommend)
location_service
record_service

More Documentation #
Go here to learn about the models provided by this plugin.
Go here to learn about the utility provided by this plugin.
Go here to migrate to the new version.
Support #
If you find any bugs or issues while using the plugin, please register an issues on GitHub. You can also contact us at [email protected].