startBackgroundTask static method

Future<int> startBackgroundTask()

Sends a signal to OS that you wish to perform a long-running task.

The OS will keep your running in the background and not suspend it until you signal completion with the stopBackgroundTask method. Your callback will be provided with a single parameter taskId which you will send to the stopBackgroundTask method.

Example

BackgroundGeolocation.startBackgroundTask().then((int taskId) {
  // Perform some long-running task (eg: HTTP request)
  performLongRunningTask.then(() {
    // When your long-running task is complete, signal completion of taskId.
    BackgroundGeolocation.finish(taskId);
  });
});

iOS

The iOS implementation uses beginBackgroundTaskWithExpirationHandler

⚠️ iOS provides exactly 180s of background-running time. If your long-running task exceeds this time, the plugin has a fail-safe which will automatically [stopBackgroundTask] your taskId to prevent the OS from force-killing your application.

Logging of iOS background tasks looks like this:

✅-[BackgroundTaskManager createBackgroundTask] 1
.
.
.

✅-[BackgroundTaskManager stopBackgroundTask:]_block_invoke 1 OF (
    1
)

Android

The Android implementation launches a WorkManager task.

⚠️ The Android plugin imposes a limit of 3 minutes for your background-task before it automatically FORCE KILLs it.

Logging for Android background-tasks looks like this (when you see an hourglass ⏳ icon, a foreground-service is active)

 I TSLocationManager: [c.t.l.u.BackgroundTaskManager onStartJob] ⏳ startBackgroundTask: 6
 .
 .
 .
 I TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 6

Implementation

static Future<int> startBackgroundTask() async {
  return (await _methodChannel.invokeMethod<int>('startBackgroundTask'))
      as FutureOr<int>;
}