registerHeadlessTask static method

Future<bool> registerHeadlessTask(Function callback)

Android-only: Registers a global function to execute when your app has been terminated.

Note: requires BackgroundFetchConfig.stopOnTerminate false and BackgroundFetchConfig.enableHeadless true.

Example

• 📂 lib/main.dart

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

import 'package:background_fetch/background_fetch.dart';

// This "Headless Task" is run when app is terminated.
// Headless task should be a top-level or static function
void backgroundFetchHeadlessTask(HeadlessTask task) async {
  String taskId = task.taskId;
  bool isTimeout = task.timeout;
  if (isTimeout) {
    // This task has exceeded its allowed running-time.  You must stop what you're doing and immediately .finish(taskId)
    print("[BackgroundFetch] Headless task timed-out: $taskId");
    BackgroundFetch.finish(taskId);
    return;
  }
  print("[BackgroundFetch] Headless event received: $taskId");
  BackgroundFetch.finish(taskId);
}

void main() {
  // Enable integration testing with the Flutter Driver extension.
  // See https://flutter.io/testing/ for more info.
  runApp(new MyApp());

  // Register to receive BackgroundFetch events after app is terminated.
  // Requires {stopOnTerminate: false, enableHeadless: true}
  BackgroundFetch.registerHeadlessTask(backgroundFetchHeadlessTask);
}

Implementation

static Future<bool> registerHeadlessTask(Function callback) async {
  var completer = Completer<bool>();

  int? callbackHandler =
      PluginUtilities.getCallbackHandle(callback)?.toRawHandle();

  if (callbackHandler == null) {
    print(
        '[BackgroundFetch registerHeadlessTask] ERROR: Failed to get callback id: Check whetever the callback is a op-level or static function');
  }
  // Two callbacks:  the provided headless-task + _headlessRegistrationCallback
  var args = [
    PluginUtilities.getCallbackHandle(_headlessCallbackDispatcher)!
        .toRawHandle(),
    callbackHandler ?? 0
  ];

  _methodChannel
      .invokeMethod('registerHeadlessTask', args)
      .then((dynamic success) {
    completer.complete(true);
  }).catchError((error) {
    var message = error.toString();
    print('[BackgroundFetch registerHeadlessTask] ‼️ $message');
    completer.complete(false);
  });
  return completer.future;
}