enableHeadless property

bool? enableHeadless
getter/setter pair

[Android only] Enables "Headless" operation allowing you to respond to events after you app has been terminated with stopOnTerminate:false.

Defaults to false. In this Android terminated state, where only the plugin's foreground-service remains running, you can respond to all the plugin's events with your own Dart callback.

Note:

  • Requires stopOnTerminate:false.
  • If you've configured stopOnTerminate:false, BackgroundGeolocation will continue to record locations (and post them to your configured url) regardless of enabledHeadless: true. You should enable this option only if you have to perform some custom work during the headless state (for example, posting a local notification).
  • With enableHeadless: true, you must also register a function to be executed in headless-state with BackgroundGeolocation.registerHeadlessTask.

For more information, see:

Android Setup

See Wiki Android Headless Mode

In your main.dart, BackgroundGeolocation.registerHeadlessTask:

import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;

/// Receives all events from BackgroundGeolocation while app is terminated:
/// Be sure to annotate your callback function to avoid issues in release mode on Flutter >= 3.3.0
@pragma('vm:entry-point')
void headlessTask(bg.HeadlessEvent headlessEvent) async {
  print('[HeadlessTask]: ${headlessEvent}');

  // Implement a `case` for only those events you're interested in.
  switch(headlessEvent.name) {
    case bg.Event.TERMINATE:
      bg.State state = headlessEvent.event;
      print('- State: ${state}');
      break;
    case bg.Event.HEARTBEAT:
      bg.HeartbeatEvent event = headlessEvent.event;
      print('- HeartbeatEvent: ${event}');
      break;
    case bg.Event.LOCATION:
      bg.Location location = headlessEvent.event;
      print('- Location: ${location}');
      break;
    case bg.Event.MOTIONCHANGE:
      bg.Location location = headlessEvent.event;
      print('- Location: ${location}');
      break;
    case bg.Event.GEOFENCE:
      bg.GeofenceEvent geofenceEvent = headlessEvent.event;
      print('- GeofenceEvent: ${geofenceEvent}');
      break;
    case bg.Event.GEOFENCESCHANGE:
      bg.GeofencesChangeEvent event = headlessEvent.event;
      print('- GeofencesChangeEvent: ${event}');
      break;
    case bg.Event.SCHEDULE:
      bg.State state = headlessEvent.event;
      print('- State: ${state}');
      break;
    case bg.Event.ACTIVITYCHANGE:
      bg.ActivityChangeEvent event = headlessEvent.event;
      print('ActivityChangeEvent: ${event}');
      break;
    case bg.Event.HTTP:
      bg.HttpEvent response = headlessEvent.event;
      print('HttpEvent: ${response}');
      break;
    case bg.Event.POWERSAVECHANGE:
      bool enabled = headlessEvent.event;
      print('ProviderChangeEvent: ${enabled}');
      break;
    case bg.Event.CONNECTIVITYCHANGE:
      bg.ConnectivityChangeEvent event = headlessEvent.event;
      print('ConnectivityChangeEvent: ${event}');
      break;
    case bg.Event.ENABLEDCHANGE:
      bool enabled = headlessEvent.event;
      print('EnabledChangeEvent: ${enabled}');
      break;
  }
}

void main() {
  runApp(HelloWorld());

  // Register your headlessTask:
  BackgroundGeolocation.registerHeadlessTask(headlessTask);
}

Implementation

bool? enableHeadless;