[iOS] iOS no longer requires manual setup in AppDelegate.m for registering custom tasks with [fetchManager registerBGProcessingTask]

Author: christocracy

CHANGELOG.md

@@ -1,4 +1,12 @@
-## 0.5.0 - 2020-01-03
+## 0.5.1 - 2020-02-19
+
+## Minor Breaking Change for iOS Setup 
+
+* [iOS] It's no longer necessary to `registerBGProcessingTask` in `AppDelegate.m` for tasks registered for use with `#scheduleTask`.  The SDK now reads the App `.plist` and automatically registers those tasks found in  *"Permitted background task scheduler identifiers"*.  Remove **all** code in your `AppDelegate.m` that references `TSBackgroundFetch`.
+![](https://dl.dropboxusercontent.com/s/t5xfgah2gghqtws/ios-setup-permitted-identifiers.png?dl=1)
+
+
+## 0.5.0 - 2020-02-03
 * [Added] [Android] New option `forceAlarmManager` for bypassing `JobScheduler` mechanism in favour of `AlarmManager` for more precise scheduling task execution.
 * [Changed] Migrate iOS deprecated "background-fetch" API to new [BGTaskScheduler](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler?language=objc).  See new required steps in iOS Setup.
 * [Added] Added new `BackgroundFetch.scheduleTask` method for scheduling custom "onehot" and periodic tasks in addition to the default fetch-task.

README.md

@@ -8,11 +8,15 @@ By [**Transistor Software**](http://transistorsoft.com), creators of [**Flutter
 
 Background Fetch is a *very* simple plugin which will awaken an app in the background about **every 15 minutes**, providing a short period of background running-time.  This plugin will execute your provided `callbackFn` whenever a background-fetch event occurs.
 
+:new: Background Fetch now provides a [__`scheduleTask`__](#executing-custom-tasks) method for scheduling arbitrary "one-shot" or periodic tasks.
+
 ### iOS
-There is **no way** to increase the rate which a fetch-event occurs and this plugin sets the rate to the most frequent possible — you will **never** receive an event faster than **15 minutes**.  The operating-system will automatically throttle the rate the background-fetch events occur based upon usage patterns.  Eg: if user hasn't turned on their phone for a long period of time, fetch events will occur less frequently.
+- There is **no way** to increase the rate which a fetch-event occurs and this plugin sets the rate to the most frequent possible — you will **never** receive an event faster than **15 minutes**.  The operating-system will automatically throttle the rate the background-fetch events occur based upon usage patterns.  Eg: if user hasn't turned on their phone for a long period of time, fetch events will occur less frequently.
+- [__`scheduleTask`__](#executing-custom-tasks) seems only to fire when the device is plugged into power. 
 
 ### Android
-The Android plugin provides a [Headless](https://pub.dartlang.org/documentation/background_fetch/latest/background_fetch/BackgroundFetchConfig/enableHeadless.html) implementation allowing you to continue handling events even after app-termination.
+- The Android plugin provides a [Headless](https://pub.dartlang.org/documentation/background_fetch/latest/background_fetch/BackgroundFetchConfig/enableHeadless.html) implementation allowing you to continue handling events even after app-termination.
+ 
 
 # Contents
 
@@ -29,7 +33,7 @@ The Android plugin provides a [Headless](https://pub.dartlang.org/documentation/
 
 ```yaml
 dependencies:
-  background_fetch: '^0.5.0'
+  background_fetch: '^0.5.1'
 ```
 
 ### Or latest from Git:
@@ -214,7 +218,7 @@ BackgroundFetch.configure(BackgroundFetchConfig(
   
   // Use a switch statement to route task-handling.
   switch (taskId) {
-    case 'com.foo.customtask':
+    case 'com.transistorsoft.customtask':
       print("Received custom task");
       break;
     default:
@@ -224,9 +228,9 @@ BackgroundFetch.configure(BackgroundFetchConfig(
   BackgroundFetch.finish(taskId);
 });
 
-// Step 2:  Schedule a custom "oneshot" task "com.foo.customtask" to execute 5000ms from now.
+// Step 2:  Schedule a custom "oneshot" task "com.transistorsoft.customtask" to execute 5000ms from now.
 BackgroundFetch.scheduleTask(TaskConfig(
-  taskId: "com.foo.customtask",
+  taskId: "com.transistorsoft.customtask",
   delay: 5000  // <-- milliseconds
 ));
 ```
@@ -235,22 +239,22 @@ BackgroundFetch.scheduleTask(TaskConfig(
 
 ### iOS
 
-#### New `BGTaskScheduler` API for iOS 13+
-- The old command *Debug->Simulate Background Fetch* no longer works with new `BGTaskSCheduler` API. 
-- At the time of writing, the new task simulator does not yet work in Simulator; Only real devices.
+#### :new: `BGTaskScheduler` API for iOS 13+
+
+- :warning: At the time of writing, the new task simulator does not yet work in Simulator; Only real devices.
 - See Apple docs [Starting and Terminating Tasks During Development](https://developer.apple.com/documentation/backgroundtasks/starting_and_terminating_tasks_during_development?language=objc)
 - After running your app in XCode, Click the `[||]` button to initiate a *Breakpoint*.
-
-![](https://dl.dropboxusercontent.com/s/zr7w3g8ivf71u32/ios-simulate-bgtask-pause.png?dl=1)
-
 - In the console `(lldb)`, paste the following command (**Note:**  use cursor up/down keys to cycle through previously run commands):
 ```obj-c
 e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.transistorsoft.fetch"]
 ```
-![](https://dl.dropboxusercontent.com/s/87c9uctr1ka3s1e/ios-simulate-bgtask-paste.png?dl=1)
-
 - Click the `[ > ]` button to continue.  The task will execute and the Callback function provided to **`BackgroundFetch.configure`** will receive the event.
 
+
+![](https://dl.dropboxusercontent.com/s/zr7w3g8ivf71u32/ios-simulate-bgtask-pause.png?dl=1)
+
+![](https://dl.dropboxusercontent.com/s/87c9uctr1ka3s1e/ios-simulate-bgtask-paste.png?dl=1)
+
 ![](https://dl.dropboxusercontent.com/s/bsv0avap5c2h7ed/ios-simulate-bgtask-play.png?dl=1)
  
 #### Old `BackgroundFetch` API

example/ios/Runner/AppDelegate.m

@@ -8,9 +8,7 @@ - (BOOL)application:(UIApplication *)application
     didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   [GeneratedPluginRegistrant registerWithRegistry:self];
   // Override point for customization after application launch.
-  TSBackgroundFetch *fetch = [TSBackgroundFetch sharedInstance];
-  [fetch registerBGProcessingTask:@"com.transistorsoft.customtask"];
-    
+      
   return [super application:application didFinishLaunchingWithOptions:launchOptions];
 }
 

example/lib/main.dart

@@ -103,16 +103,18 @@ class _MyAppState extends State<MyApp> {
       });
     });
 
+    // Schedule a "one-shot" custom-task in 10000ms.
+    // These are fairly reliable on Android (particularly with forceAlarmManager) but not iOS,
+    // where device must be powered (and delay will be throttled by the OS).
     BackgroundFetch.scheduleTask(TaskConfig(
         taskId: "com.transistorsoft.customtask",
-        delay: 5000,
+        delay: 10000,
         periodic: false,
         forceAlarmManager: true,
         stopOnTerminate: false,
         enableHeadless: true
     ));
 
-
     // Optionally query the current BackgroundFetch status.
     int status = await BackgroundFetch.status;
     setState(() {
@@ -137,6 +139,7 @@ class _MyAppState extends State<MyApp> {
     prefs.setString(EVENTS_KEY, jsonEncode(_events));
 
     if (taskId == "flutter_background_fetch") {
+      // Schedule a one-shot task when fetch event received (for testing).
       BackgroundFetch.scheduleTask(TaskConfig(
           taskId: "com.transistorsoft.customtask",
           delay: 5000,

help/INSTALL-IOS.md

@@ -11,42 +11,21 @@
 
 
 ## Configure `Info.plist`
-1.  Open your `Info.plist` and the key *"Permitted background task scheduler identifiers"*
+1.  Open your __`Info.plist`__ and add the key *"Permitted background task scheduler identifiers"*
 
 ![](https://dl.dropboxusercontent.com/s/t5xfgah2gghqtws/ios-setup-permitted-identifiers.png?dl=1)
 
 2.  Add the **required identifier `com.transistorsoft.fetch`**.
 
 ![](https://dl.dropboxusercontent.com/s/kwdio2rr256d852/ios-setup-permitted-identifiers-add.png?dl=1)
 
-3.  If you intend to execute your own custom tasks via **`BackgroundFetch.scheduleTask`**, you must add those custom identifiers as well.  For example, if you intend to execute a custom **`taskId: 'com.foo.customtask'`**, you must add the identifier **`com.foo.customtask`** to your *"Permitted background task scheduler identifiers"*, as well.
+3.  If you intend to execute your own [custom tasks](#executing-custom-tasks) via **`BackgroundFetch.scheduleTask`**, you must add those custom identifiers as well.  For example, if you intend to execute a custom **`taskId: 'com.transistorsoft.customtask'`**, you must add the identifier **`com.transistorsoft.customtask`** to your *"Permitted background task scheduler identifiers"*, as well.
+
+:warning: A task identifier can be any string you wish, but it's a good idea to prefix them now with `com.transistorsoft.` —  In the future, the `com.transistorsoft` prefix **may become required**.
 
 ```dart
 BackgroundFetch.scheduleTask(TaskConfig(
-  taskId: 'com.foo.customtask',
+  taskId: 'com.transistorsoft.customtask',
   delay: 60 * 60 * 1000  //  In one hour (milliseconds) 
 ));
 ```
-
-## `AppDelegate.m`
-
-**If** you added custom *Background Processing* identifier(s) in your `Info.plist` and intend to use **`BackgroundFetch.scheduleTask`**, you must register those custom identifier(s) in your **`AppDelegate`** method **`didFinishLaunchingWithOptions`**:
-
-__Note:__ The SDK *automatically* registers its required fetch-task **`com.transistorsoft.fetch`** — You need only register **your own** custom task idenfifiers here.
-
-```obj-c
-- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
-  [GeneratedPluginRegistrant registerWithRegistry:self];
-  .
-  .
-  .
-  // [BackgroundFetch] Register your custom Background Processing task(s)
-  TSBackgroundFetch *fetch = [TSBackgroundFetch sharedInstance];
-  [fetch registerBGProcessingTask:@"com.foo.customtask"];
-  .
-  .
-  .  
-  return [super application:application didFinishLaunchingWithOptions:launchOptions];
-}
-
-```

ios/Classes/BackgroundFetchPlugin.m

@@ -28,13 +28,12 @@ @implementation BackgroundFetchPlugin {
 -(BOOL)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
 {
     NSLog(@"BackgroundFetch AppDelegate received fetch event");
-    TSBackgroundFetch *fetchManager = [TSBackgroundFetch sharedInstance];
-    [fetchManager performFetchWithCompletionHandler:completionHandler applicationState:application.applicationState];
+    [[TSBackgroundFetch sharedInstance] performFetchWithCompletionHandler:completionHandler applicationState:application.applicationState];
     return YES;
 }
 
 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
-    [[TSBackgroundFetch sharedInstance] registerAppRefreshTask];    
+    [[TSBackgroundFetch sharedInstance] didFinishLaunching];
     return YES;
 }
 
@@ -118,11 +117,11 @@ -(void) start:(FlutterResult)result {
 -(void) stop:(NSString*)taskId result:(FlutterResult)result {
     TSBackgroundFetch *fetchManager = [TSBackgroundFetch sharedInstance];
     if (!taskId) {
+        // Remove fetch listener.
         [fetchManager removeListener:PLUGIN_ID];
-        [fetchManager stop:nil];
-    } else {
-        [fetchManager stop:taskId];
     }
+    // Calling stop with nil taskId will cause TSBackgroundFetch to stop all custom-tasks from #scheduleTask
+    [fetchManager stop:taskId];
     [self status:result];
 }
 

ios/TSBackgroundFetch.framework/Headers/TSBackgroundFetch.h

@@ -15,9 +15,11 @@
 @property (nonatomic) BOOL stopOnTerminate;
 @property (readonly) BOOL configured;
 @property (readonly) BOOL active;
+@property (readonly) NSString *fetchTaskId;
 
 + (TSBackgroundFetch *)sharedInstance;
 
+-(void) didFinishLaunching;
 -(void) registerAppRefreshTask;
 -(void) registerBGProcessingTask:(NSString*)identifier;
 

ios/TSBackgroundFetch.framework/TSBackgroundFetch

@@ -1,6 +1,6 @@
 name: background_fetch
 description: Periodic callbacks in the background for both iOS and Android.  Includes Android Headless implementation.
-version: 0.5.0
+version: 0.5.1
 homepage: https://github.com/transistorsoft/flutter_background_fetch
 
 environment: