app property

Application & lifecycle configuration.

AppConfig groups options that control how the SDK integrates with your app’s lifecycle: start/stop behavior on terminate and reboot, headless/background behavior, periodic heartbeats, scheduler windows, foreground notification, and the Android background-permission rationale dialog.

Use this class via Config.app.

BackgroundGeolocation.ready(Config(
  app: AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
  }
));

What belongs in AppConfig?

• Whether tracking stops on app terminate: see AppConfig.stopOnTerminate.
• Whether tracking starts after device reboot: see AppConfig.startOnBoot.
• Running in headless mode on Android: see AppConfig.enableHeadless.
• Periodic heartbeat callback: see AppConfig.heartbeatInterval.
• Scheduler windows for automatic start/stop: see AppConfig.schedule and AppConfig.scheduleUseAlarmManager.
• Foreground notification options (Android): see AppConfig.notification.
• Background-permission rationale (Android 10+): see AppConfig.backgroundPermissionRationale.
• iOS background preventSuspend switch for heartbeats: see AppConfig.preventSuspend.

Platform notes

iOS

• With AppConfig.stopOnTerminate set to false, the SDK creates a stationary geofence and iOS will relaunch your app in the background upon exiting that region.
• AppConfig.preventSuspend is required for heartbeats and has a battery cost. Use sparingly.

Android

• With AppConfig.enableHeadless set to true, the native background service continues working even when your Flutter UI process is terminated. Pair this with HttpConfig.url to keep uploads flowing.
• The scheduler uses AlarmManager by default; control this with AppConfig.scheduleUseAlarmManager.

Examples

Configure once at startup:

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

void main() async {
  final config = bg.Config(
    app: bg.AppConfig(
      stopOnTerminate: false,
      startOnBoot: true,
      enableHeadless: true,
      heartbeatInterval: 60,
      backgroundPermissionRationale: bg.PermissionRationale(
        title: "Allow {applicationName} to access this device's location even when the app is closed or not in use.",
        message: "This app collects location data to enable recording your trips to work and calculate distance-travelled.",
        positiveAction: 'Change to "{backgroundPermissionOptionLabel}"',
        negativeAction: 'Cancel',
      ),
      notification: bg.Notification(
        title: 'Background Geolocation',
        text: 'Tracking location',
        smallIcon: 'mipmap/ic_launcher',
      ),
      schedule: [ '1-5 09:00-17:00' ], // Weekdays 9–5
      scheduleUseAlarmManager: true,
    ),
  );

  await bg.BackgroundGeolocation.ready(config);
}

Update later at runtime:

await bg.BackgroundGeolocation.setConfig(bg.Config(
  app: bg.AppConfig(
    heartbeatInterval: 120, // slow down heartbeats
  ),
));

Migration from flat Config properties

The following legacy properties are deprecated on Config and should now be set via Config.app: Config.stopOnTerminate, Config.startOnBoot, Config.enableHeadless, Config.heartbeatInterval, Config.schedule, Config.scheduleUseAlarmManager, Config.notification, Config.backgroundPermissionRationale.