release: 8.16.0

Author: Dev-hwang

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 8.16.0
+
+* [**BREAKING**] Change `ServiceRequestResult` class to `sealed class` for improved code readability
+* [**BREAKING**] Change method for customizing notification icon
+* [**FEAT**] Add `copyWith` function for models reuse
+* Check [migration_documentation](./documentation/migration_documentation.md) for changes
+
 ## 8.14.0
 
 * [**FEAT**] Support quickboot for HTC devices

README.md

@@ -21,17 +21,13 @@ This plugin is used to implement a foreground service on the Android platform.
 - Android: `5.0+ (minSdkVersion: 21)`
 - iOS: `12.0+`
 
-## Structure
-
-<img src="https://github.com/user-attachments/assets/6fc91bd9-62b2-43b8-9109-26d2e8d809c1" width="800">
-
 ## Getting started
 
 To use this plugin, add `flutter_foreground_task` as a [dependency in your pubspec.yaml file](https://flutter.io/platform-plugins/). For example:
 
 ```yaml
 dependencies:
-  flutter_foreground_task: ^8.14.0
+  flutter_foreground_task: ^8.16.0
 ```
 
 After adding the plugin to your flutter project, we need to declare the platform-specific permissions ans service to use for this plugin to work properly.
@@ -204,10 +200,7 @@ class MyTaskHandler extends TaskHandler {
     print('onStart(starter: ${starter.name})');
   }
 
-  // Called by eventAction in [ForegroundTaskOptions].
-  // - nothing() : Not use onRepeatEvent callback.
-  // - once() : Call onRepeatEvent only once.
-  // - repeat(interval) : Call onRepeatEvent at milliseconds interval.
+  // Called based on the eventAction set in ForegroundTaskOptions.
   @override
   void onRepeatEvent(DateTime timestamp) {
     // Send data to main isolate.
@@ -223,7 +216,7 @@ class MyTaskHandler extends TaskHandler {
     print('onDestroy');
   }
 
-  // Called when data is sent using [FlutterForegroundTask.sendDataToTask].
+  // Called when data is sent using `FlutterForegroundTask.sendDataToTask`.
   @override
   void onReceiveData(Object data) {
     print('onReceiveData: $data');
@@ -330,9 +323,9 @@ void initState() {
   // Add a callback to receive data sent from the TaskHandler.
   FlutterForegroundTask.addTaskDataCallback(_onReceiveTaskData);
 
-  WidgetsBinding.instance.addPostFrameCallback((_) async {
+  WidgetsBinding.instance.addPostFrameCallback((_) {
     // Request permissions and initialize the service.
-    await _requestPermissions();
+    _requestPermissions();
     _initService();
   });
 }
@@ -369,12 +362,18 @@ Future<ServiceRequestResult> _startService() async {
 > 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](https://github.com/Dev-hwang/flutter_foreground_task/issues) :)
 
 6. Use `FlutterForegroundTask.updateService` to update the service. The options are the same as the start function.
 
 ```dart
+final ForegroundTaskOptions defaultTaskOptions = ForegroundTaskOptions(
+  eventAction: ForegroundTaskEventAction.repeat(5000),
+  autoRunOnBoot: true,
+  autoRunOnMyPackageReplaced: true,
+  allowWakeLock: true,
+  allowWifiLock: true,
+);
+
 @pragma('vm:entry-point')
 void startCallback() {
   FlutterForegroundTask.setTaskHandler(FirstTaskHandler());
@@ -394,7 +393,7 @@ class FirstTaskHandler extends TaskHandler {
     
     if (_count == 10) {
       FlutterForegroundTask.updateService(
-        foregroundTaskOptions: ForegroundTaskOptions(
+        foregroundTaskOptions: defaultTaskOptions.copyWith(
           eventAction: ForegroundTaskEventAction.repeat(1000),
         ),
         callback: updateCallback,
@@ -455,7 +454,7 @@ class SecondTaskHandler extends TaskHandler {
 7. If you no longer use the service, call `FlutterForegroundTask.stopService`.
 
 ```dart
-Future<ServiceRequestResult> _stopService() async {
+Future<ServiceRequestResult> _stopService() {
   return FlutterForegroundTask.stopService();
 }
 ```

android/src/main/kotlin/com/pravera/flutter_foreground_task/FlutterForegroundTaskLifecycleListener.kt

@@ -15,7 +15,7 @@ interface FlutterForegroundTaskLifecycleListener {
     /** Called when the task is started. */
     fun onTaskStart(starter: FlutterForegroundTaskStarter)
 
-    /** Called by eventAction in ForegroundTaskOptions. */
+    /** Called based on the eventAction set in ForegroundTaskOptions. */
     fun onTaskRepeatEvent()
 
     /** Called when the task is destroyed. */

documentation/migration_documentation.md

@@ -1,5 +1,72 @@
 ## Migration
 
+### ver 8.16.0
+
+- Change `ServiceRequestResult` class to `sealed class` for improved code readability.
+
+```dart
+void startService() {
+  final ServiceRequestResult result =
+      await FlutterForegroundTask.startService(
+    serviceId: 100,
+    notificationTitle: 'notificationTitle',
+    notificationText: 'notificationText',
+    callback: startLocationService,
+  );
+
+  // before: The distinction between success and failure of the request is unclear.
+  if (result.success) {
+    // The error should not be accessible when the request is successful.
+    final Object? error = result.error;
+  } else {
+    // Handle error
+    final Object? error = result.error;
+  }
+
+  // after: The distinction between success and failure of the request is clear. 
+  switch (result) {
+    case ServiceRequestSuccess():
+      // The error cannot be accessed.
+      // final Object error = result.error;
+      print('success');
+    case ServiceRequestFailure():
+      // The error can only be accessed when the request fails, 
+      // and no null check is required.
+      final Object error = result.error;
+      print('failure($error)');
+  }
+}
+```
+
+- Change method for customizing notification icon. [guide page](./customize_notification_icon.md)
+
+```dart
+void startService() {
+  // before: There was an issue in the foreground service where only the white icon was displayed 
+  // because the icon resource could not be referenced.
+  await FlutterForegroundTask.startService(
+    notificationTitle: 'notificationTitle',
+    notificationText: 'notificationText',
+    notificationIcon: const NotificationIconData(
+      resType: ResourceType.drawable,
+      resPrefix: ResourcePrefix.ic,
+      name: 'snow',
+      backgroundColor: Colors.orange,
+    ),
+  );
+  
+  // after: Enabled static reference to the icon resource through meta-data.
+  await FlutterForegroundTask.startService(
+    notificationTitle: 'notificationTitle',
+    notificationText: 'notificationText',
+    notificationIcon: const NotificationIcon(
+      metaDataName: 'com.your_package.service.SNOW_ICON',
+      backgroundColor: Colors.orange,
+    ),
+  );
+}
+```
+
 ### ver 8.10.0
 
 - Change onStart, onDestroy callback return type from `void` to `Future<void>`.

example/lib/main.dart

@@ -41,10 +41,7 @@ class MyTaskHandler extends TaskHandler {
     _incrementCount();
   }
 
-  // Called by eventAction in [ForegroundTaskOptions].
-  // - nothing() : Not use onRepeatEvent callback.
-  // - once() : Call onRepeatEvent only once.
-  // - repeat(interval) : Call onRepeatEvent at milliseconds interval.
+  // Called based on the eventAction set in ForegroundTaskOptions.
   @override
   void onRepeatEvent(DateTime timestamp) {
     _incrementCount();
@@ -56,7 +53,7 @@ class MyTaskHandler extends TaskHandler {
     print('onDestroy');
   }
 
-  // Called when data is sent using [FlutterForegroundTask.sendDataToTask].
+  // Called when data is sent using `FlutterForegroundTask.sendDataToTask`.
   @override
   void onReceiveData(Object data) {
     print('onReceiveData: $data');
@@ -70,25 +67,6 @@ class MyTaskHandler extends TaskHandler {
   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');
-  }
 }
 
 class ExampleApp extends StatelessWidget {
@@ -126,19 +104,6 @@ class _ExamplePageState extends State<ExamplePage> {
     }
 
     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.
@@ -202,7 +167,7 @@ class _ExamplePageState extends State<ExamplePage> {
     }
   }
 
-  Future<ServiceRequestResult> _stopService() async {
+  Future<ServiceRequestResult> _stopService() {
     return FlutterForegroundTask.stopService();
   }
 
@@ -221,9 +186,9 @@ class _ExamplePageState extends State<ExamplePage> {
     // Add a callback to receive data sent from the TaskHandler.
     FlutterForegroundTask.addTaskDataCallback(_onReceiveTaskData);
 
-    WidgetsBinding.instance.addPostFrameCallback((_) async {
+    WidgetsBinding.instance.addPostFrameCallback((_) {
       // Request permissions and initialize the service.
-      await _requestPermissions();
+      _requestPermissions();
       _initService();
     });
   }

ios/Classes/FlutterForegroundTaskLifecycleListener.swift

@@ -20,7 +20,7 @@ public protocol FlutterForegroundTaskLifecycleListener : AnyObject {
   /** Called when the task is started. */
   func onTaskStart(starter: FlutterForegroundTaskStarter)
 
-  /** Called by eventAction in ForegroundTaskOptions. */
+  /** Called based on the eventAction set in ForegroundTaskOptions. */
   func onTaskRepeatEvent()
 
   /** Called when the task is destroyed. */

lib/task_handler.dart

@@ -5,11 +5,11 @@ abstract class TaskHandler {
   /// Called when the task is started.
   Future<void> onStart(DateTime timestamp, TaskStarter starter);
 
-  /// Called by eventAction in [ForegroundTaskOptions].
+  /// Called based on the eventAction set in [ForegroundTaskOptions].
   ///
-  /// - nothing() : Not use onRepeatEvent callback.
-  /// - once() : Call onRepeatEvent only once.
-  /// - repeat(interval) : Call onRepeatEvent at milliseconds interval.
+  /// - .nothing() : Not use onRepeatEvent callback.
+  /// - .once() : Call onRepeatEvent only once.
+  /// - .repeat(interval) : Call onRepeatEvent at milliseconds interval.
   void onRepeatEvent(DateTime timestamp);
 
   /// Called when the task is destroyed.
@@ -23,14 +23,25 @@ abstract class TaskHandler {
 
   /// Called when the notification itself is pressed.
   ///
-  /// AOS: "android.permission.SYSTEM_ALERT_WINDOW" permission must be granted
-  /// for this function to be called.
+  /// - AOS: This callback is triggered only if the
+  /// "android.permission.SYSTEM_ALERT_WINDOW" permission is declared and granted.
+  ///
+  /// ```dart
+  /// void requestPermission() async {
+  ///   if (!await FlutterForegroundTask.canDrawOverlays) {
+  ///     await FlutterForegroundTask.openSystemAlertWindowSettings();
+  ///   }
+  /// }
+  /// ```
+  ///
+  /// - iOS: only work iOS 12+
   void onNotificationPressed() => FlutterForegroundTask.launchApp();
 
   /// Called when the notification itself is dismissed.
   ///
-  /// AOS: only work Android 14+
-  /// iOS: only work iOS 10+
+  /// - AOS: only work Android 14+
+  ///
+  /// - iOS: only work iOS 12+
   void onNotificationDismissed() {}
 }
 

pubspec.yaml

@@ -1,6 +1,6 @@
 name: flutter_foreground_task
 description: This plugin is used to implement a foreground service on the Android platform.
-version: 8.14.0
+version: 8.16.0
 homepage: https://github.com/Dev-hwang/flutter_foreground_task
 
 environment: