Fix/243 bg task processing (fluttercommunity#279)

* Activate iOS BG Task Processing

Author: ened

.art/ios_background_mode_background_processing.png

@@ -17,7 +17,7 @@ If for some reason you can't upgrade yet we still support the [older way of embe
 Debugging a background task can be difficult, Android decides when is the best time to run.  
 There is no guaranteed way to enforce a run of a job even in debug mode.  
 
-However to facilitate debugging, the plugin provides an `isInDebugMode` flag when initializing the plugin: `Workmanager.initialize(callbackDispatcher, isInDebugMode: true)`  
+However to facilitate debugging, the plugin provides an `isInDebugMode` flag when initializing the plugin: `Workmanager().initialize(callbackDispatcher, isInDebugMode: true)`  
 
 Once this flag is enabled you will receive a notification whenever a background task was triggered.  
 This way you can keep track whether that task ran successfully or not.  

ANDROID_SETUP.md

@@ -1,3 +1,12 @@
+# 0.5.0-dev.3
+
+* Documentation for BGTaskScheduler added
+* Throw standard errors when scheduling a task on iOS failed
+
+# 0.5.0-dev.2
+
+* iOS: Modern-style task processing using BGTaskScheduler is now supported. Please see the updated instructions in IOS_SETUP.md.
+
 # 0.5.0-dev.1
 
 * Android: Load Flutter environment asynchronously in the Worker task

CHANGELOG.md

@@ -4,9 +4,57 @@
 
 This plugin is compatible with **Swift 4.2** and up. Make sure you are using **Xcode 10.3** or higher and have set your minimum deployment target to **iOS 10** or higher by defining a platform version in your podfile: `platform :ios, '10.0'`
 
+
+## Enable BGTaskScheduler
+
+> ⚠️ BGTaskScheduler is similar to Background Fetch described below and brings a similar set of constraints. Most notably, there are no guarantees when the background task will be run. Excerpt from the documentation:
+> 
+> Schedule a processing task request to ask that the system launch your app when conditions are favorable for battery life to handle deferrable, longer-running processing, such as syncing, database maintenance, or similar tasks. The system will attempt to fulfill this request to the best of its ability within the next two days as long as the user has used your app within the past week.
+
+![Screenshot of Background Fetch Capabilities tab in Xcode ](.art/ios_background_mode_background_processing.png)
+
+This will add the **UIBackgroundModes** key to your project's `Info.plist`:
+
+``` xml
+<key>UIBackgroundModes</key>
+<array>
+	<string>processing</string>
+</array>
+```
+
+Additionally, you must configure the background task identifiers. The default identifier is `workmanager.background.task` in the host Apps Info.plist:
+
+``` xml
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+	<string>workmanager.background.task</string>
+</array>
+</plist>
+```
+
+And will set the correct *SystemCapabilities* for your target in the `project.pbxproj` file:
+
+```
+SystemCapabilities = {
+	com.apple.BackgroundModes = {
+		enabled = 1;
+	};
+};
+```
+
+## Testing BGTaskScheduler
+
+Follow the instructions on https://developer.apple.com/documentation/backgroundtasks/starting_and_terminating_tasks_during_development.
+
+The exact command to trigger the WorkManager default BG Task is:
+
+```
+e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"workmanager.background.task"]
+```
+
 ## Enabling Background Fetch
 
->  ⚠️  Background fetch this is currently the *only* supported way to do background work on iOS with work manager: **One off tasks** or **Periodic tasks** are available on Android only for now! (see #109)
+> ⚠️ Background fetch is one supported way to do background work on iOS with work manager: **Periodic tasks** are available on Android only for now! (see #109)
 
 Background fetching is very different compared to Android's Background Jobs.  
 In order for your app to support Background Fetch, you have to add the *Background Modes* capability in Xcode for your app's Target and check *Background fetch*:
@@ -72,7 +120,7 @@ Here is an example of a Flutter entrypoint called `callbackDispatcher`:
 
 ```dart
 void callbackDispatcher() {
-  Workmanager.executeTask((task, inputData) {
+  Workmanager().executeTask((task, inputData) {
     switch (task) {
       case Workmanager.iOSBackgroundTask:
         stderr.writeln("The iOS background fetch was triggered");
@@ -105,7 +153,7 @@ If you launched your app using the Flutter command line tools or another IDE lik
 To make background work more visible when developing, the WorkManager plugin provides an `isInDebugMode` flag when initializing the plugin:
 
 ```dart
-Workmanager.initialize(callbackDispatcher, isInDebugMode: true)
+Workmanager().initialize(callbackDispatcher, isInDebugMode: true)
 ```
 
 If `isInDebugMode` is `true`, a local notification will be displayed whenever a background fetch was triggered by iOS. In the example gif below, two background fetches were *simulated* in quick succession. Both completing succesfully after a few seconds in this case:

IOS_SETUP.md

@@ -39,21 +39,45 @@ void main() {
 
 > 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.
+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 (Android only!) 
+# Customisation (iOS - BGTaskScheduler only)
+iOS supports **One off tasks** with a few basic constraints:
+
+```dart
+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](https://developer.apple.com/documentation/backgroundtasks).
+
+# Customisation (Android) 
 Not every `Android WorkManager` feature is ported.
 
 Two kinds of background tasks can be registered :

README.md

@@ -195,14 +195,14 @@ object Extractor {
 
     private fun extractExistingWorkPolicyFromCall(call: MethodCall): ExistingWorkPolicy =
             try {
-                ExistingWorkPolicy.valueOf(call.argument<String>(REGISTER_TASK_EXISTING_WORK_POLICY_KEY)!!.toUpperCase())
+                ExistingWorkPolicy.valueOf(call.argument<String>(REGISTER_TASK_EXISTING_WORK_POLICY_KEY)!!.uppercase())
             } catch (ignored: Exception) {
                 defaultOneOffExistingWorkPolicy
             }
 
     private fun extractExistingPeriodicWorkPolicyFromCall(call: MethodCall): ExistingPeriodicWorkPolicy =
             try {
-                ExistingPeriodicWorkPolicy.valueOf(call.argument<String>(REGISTER_TASK_EXISTING_WORK_POLICY_KEY)!!.toUpperCase())
+                ExistingPeriodicWorkPolicy.valueOf(call.argument<String>(REGISTER_TASK_EXISTING_WORK_POLICY_KEY)!!.uppercase())
             } catch (ignored: Exception) {
                 defaultPeriodExistingWorkPolicy
             }
@@ -221,7 +221,7 @@ object Extractor {
         }
 
         val backoffPolicy = try {
-            BackoffPolicy.valueOf(call.argument<String>(REGISTER_TASK_BACK_OFF_POLICY_TYPE_KEY)!!.toUpperCase())
+            BackoffPolicy.valueOf(call.argument<String>(REGISTER_TASK_BACK_OFF_POLICY_TYPE_KEY)!!.uppercase())
         } catch (ignored: Exception) {
             defaultBackOffPolicy
         }
@@ -240,7 +240,7 @@ object Extractor {
     private fun extractConstraintConfigFromCall(call: MethodCall): Constraints {
         fun extractNetworkTypeFromCall(call: MethodCall) =
                 try {
-                    NetworkType.valueOf(call.argument<String>(REGISTER_TASK_CONSTRAINTS_NETWORK_TYPE_KEY)!!.toUpperCase())
+                    NetworkType.valueOf(call.argument<String>(REGISTER_TASK_CONSTRAINTS_NETWORK_TYPE_KEY)!!.uppercase())
                 } catch (ignored: Exception) {
                     defaultNetworkType
                 }

android/src/main/kotlin/be/tramckrijte/workmanager/Extractor.kt

@@ -43,7 +43,7 @@ private object RegisterTaskHandler : CallHandler<WorkManagerCall.RegisterTask> {
                             "You should ensure you have called the 'initialize' function first! " +
                             "Example: \n" +
                             "\n" +
-                            "`Workmanager.initialize(\n" +
+                            "`Workmanager().initialize(\n" +
                             "  callbackDispatcher,\n" +
                             " )`" +
                             "\n" +

android/src/main/kotlin/be/tramckrijte/workmanager/WorkmanagerCallHandler.kt

@@ -168,7 +168,7 @@
 				TargetAttributes = {
 					97C146ED1CF9000F007C117D = {
 						CreatedOnToolsVersion = 7.3.1;
-						DevelopmentTeam = 79BMQESM94;
+						DevelopmentTeam = GPGRWN6G4J;
 						LastSwiftMigration = 1110;
 					};
 				};
@@ -506,7 +506,7 @@
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
 				CLANG_ENABLE_MODULES = YES;
 				CURRENT_PROJECT_VERSION = "$(FLUTTER_BUILD_NUMBER)";
-				DEVELOPMENT_TEAM = 79BMQESM94;
+				DEVELOPMENT_TEAM = GPGRWN6G4J;
 				ENABLE_BITCODE = NO;
 				FRAMEWORK_SEARCH_PATHS = (
 					"$(inherited)",

example/ios/Runner.xcodeproj/project.pbxproj

@@ -2,9 +2,9 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-	<key>UIBackgroundModes</key>
+	<key>BGTaskSchedulerPermittedIdentifiers</key>
 	<array>
-		<string>fetch</string>
+		<string>workmanager.background.task</string>
 	</array>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>$(DEVELOPMENT_LANGUAGE)</string>
@@ -26,6 +26,11 @@
 	<string>1.0</string>
 	<key>LSRequiresIPhoneOS</key>
 	<true/>
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>fetch</string>
+		<string>processing</string>
+	</array>
 	<key>UILaunchStoryboardName</key>
 	<string>LaunchScreen</string>
 	<key>UIMainStoryboardFile</key>

example/ios/Runner/Info.plist

@@ -55,6 +55,10 @@ void callbackDispatcher() {
         print(
             "You can access other plugins in the background, for example Directory.getTemporaryDirectory(): $tempPath");
         break;
+      case Workmanager.iOSBackgroundProcessingTask:
+        print("The iOS Background processing task was called");
+        await Future.delayed(Duration(seconds: 2));
+        break;
     }
 
     return Future.value(true);
@@ -107,6 +111,28 @@ class _MyAppState extends State<MyApp> {
                     );
                   }),
               SizedBox(height: 16),
+              Text("BG Processing Tasks (iOS only)",
+                  style: Theme.of(context).textTheme.headline),
+              //This task runs once.
+              //Most likely this will trigger immediately
+              PlatformEnabledButton(
+                platform: _Platform.ios,
+                child: Text("Perform a BG Task"),
+                onPressed: () {
+                  Workmanager().registerOneOffTask(
+                    "1",
+                    simpleTaskKey,
+                    inputData: <String, dynamic>{
+                      'int': 1,
+                      'bool': true,
+                      'double': 1.0,
+                      'string': 'string',
+                      'array': [1, 2, 3],
+                    },
+                  );
+                },
+              ),
+
               Text("One Off Tasks (Android only)",
                   style: Theme.of(context).textTheme.headline),
               //This task runs once.

example/lib/main.dart

@@ -0,0 +1,34 @@
+//
+//  BackgroundTaskOperation.swift
+//  workmanager
+//
+//  Created by Sebastian Roth on 10/06/2021.
+//
+
+import Foundation
+
+class BackgroundTaskOperation : Operation {
+    
+    private let identifier: String
+    private let flutterPluginRegistrantCallback: FlutterPluginRegistrantCallback?
+
+    init(_ identifier: String, flutterPluginRegistrantCallback: FlutterPluginRegistrantCallback?) {
+        self.identifier = identifier
+        self.flutterPluginRegistrantCallback = flutterPluginRegistrantCallback
+    }
+    
+    override func main() {
+        let semaphore = DispatchSemaphore(value: 0)
+        
+        DispatchQueue.main.async {
+            let worker = BackgroundWorker(mode: .backgroundTask(identifier: self.identifier),
+                                          flutterPluginRegistrantCallback: self.flutterPluginRegistrantCallback)
+            
+            worker.performBackgroundRequest { _ in
+                semaphore.signal()
+            }
+        }
+
+        semaphore.wait()
+    }
+}