ready static method

Future<State> ready(
  1. Config config
)

Signal to the plugin that your app is launched and ready, proving the default Config.

The supplied Config will be applied only at first install of your app — for every launch thereafter, the plugin will automatically load its last-known configuration from persistent storage. The plugin always remembers the configuration you apply to it.

BackgroundGeolocation.ready(Config(
  desiredAccuracy: Config.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  stopOnTerminate: false,
  startOnBoot: true,
  url: 'http://your.server.com',
  headers: {
    'my-auth-token': 'secret-token'
  }
)).then((State state) {
  print('[ready] success: ${state}');
});

⚠️ Warning: You must call .ready(config) once and only once, each time your app is launched.

  • Do not hide the call to .ready(config) within a view which is loaded only by clicking a UI action. This is particularly important for iOS in the case where the OS relaunches your app in the background when the device is detected to be moving. If you don't ensure that .ready(config) is called in this case, tracking will not resume.

The reset method.

If you wish, you can use the reset method to reset all Config options to documented default-values (with optional overrides):


BackgroundGeolocation.reset();
// Reset to documented default-values with overrides
BackgroundGeolocation.reset(Config(
  distanceFilter:  10
));

Config.reset: false

Configuring the plugin with reset: false should generally be avoided unless you know exactly what it does. People often find this from the /example app. If you do configure reset: false, you'll find that your Config provided to .ready is consumed only at first launch after install. Thereafter, the plugin will ignore any changes you've provided there. The only way to change the config then is to use setConfig.

You will especially not want to use reset: false during development, while you're fine-tuning your Config options.

The reason the /example app uses reset: false is because it hosts an advanced "Settings" screen to tune the Config at runtime and we don't want those runtime changes to be overwritten by .ready(config) each time the app launches.

:warning: If you don't undestand what reset: false does, NO NOT USE IT. If you blindly copy/pasted it from the /example app, REMOVE IT from you Config.

Example

BackgroundGeolocation.ready(Config(
  distanceFilter: 50
)).then((State state) {
  print('[ready] - ${state}')
});

Implementation

static Future<State> ready(Config config) async {
  Map state =
      (await _methodChannel.invokeMapMethod('ready', config.toMap()))!;
  return State(state);
}