DeviceSettings Android only

class DeviceSettings

API for directing users to Android device settings screens that can affect background geolocation performance.

Many Android manufacturers apply aggressive battery optimizations that can kill background services, including the geolocation SDK. This API surfaces the relevant settings screens so users can whitelist your app.

For a comprehensive list of affected devices and manufacturers, see dontkillmyapp.com.

final isIgnoring = await BackgroundGeolocation.deviceSettings.isIgnoringBatteryOptimizations();
if (!isIgnoring) {
  final req = await BackgroundGeolocation.deviceSettings.showIgnoreBatteryOptimizations();
  if (!req.seen) {
    final confirmed = await showMyConfirmDialog();
    if (confirmed) {
      await BackgroundGeolocation.deviceSettings.show(req);
    }
  }
}

---

Members

isIgnoringBatteryOptimizations

static Future<bool> get isIgnoringBatteryOptimizations

Android only Returns true if the OS is ignoring battery optimizations for your app.

In most cases the SDK performs acceptably even when battery optimizations are active, but aggressive manufacturer-specific restrictions may interfere with background operation.

bool isIgnoring = await DeviceSettings.isIgnoringBatteryOptimizations;

show

static Future<bool> show(DeviceSettingsRequestrequest)

Android only Execute a previously prepared DeviceSettingsRequest to open the target settings screen.

Resolves true if the redirect was attempted.

final req = await BackgroundGeolocation.deviceSettings.showPowerManager();
if (!req.seen) {
  await BackgroundGeolocation.deviceSettings.show(req);
}

showIgnoreBatteryOptimizations

static Future<DeviceSettingsRequest> showIgnoreBatteryOptimizations()

Android only Prepare a request to show the Android Ignore Battery Optimizations settings screen.

Returns a DeviceSettingsRequest rather than immediately redirecting, so you can inspect DeviceSettingsRequest.seen and decide whether to prompt the user.

Warning

On some devices and OS versions this screen may not be available. Always wrap calls to DeviceSettings.show in a try/catch.

See also - isIgnoringBatteryOptimizations - show

// Is Android device ignoring battery optimizations?
bool isIgnoring = await DeviceSettings.isIgnoringBatteryOptimizations;
if (!isIgnoring) {
  DeviceSettings.showIgnoreBatteryOptimizations().then((DeviceSettingsRequest request) {
    print("- Screen seen? ${request.seen} ${request.lastSeenAt}");
    print("- Device: ${request.manufacturer} ${request.model} ${request.version}");

    // If we've already shown this screen to the user, we don't want to annoy them.
    if (request.seen) {
      return;
    }

    // It's your responsibility to instruct the user what exactly
    // to do here, perhaps with a Confirm Dialog:
    showMyConfirmDialog(
      title: "Settings request",
      text: "Please disable battery optimizations for your device"
    ).then((bool confirmed) {
      if (confirmed) {
        // User clicked [Confirm] button.  Execute the redirect to settings screen:
        DeviceSettings.show(request);
      }
    });
  }).catchError((dynamic error) {
    // Depending on Manufacturer/Model/OS Version, a Device may not implement
    // a particular Settings screen.
    print(error);
  });
}

showPowerManager

static Future<DeviceSettingsRequest> showPowerManager()

Android only Prepare a request to show a vendor-specific Power Manager settings screen (Huawei, Xiaomi, Vivo, Oppo, etc.).

Returns a DeviceSettingsRequest rather than immediately redirecting.

Warning

Not all manufacturers or OS versions implement this screen. Always wrap calls to DeviceSettings.show in a try/catch.

See also - show

DeviceSettings.showPowerManager().then((DeviceSettingsRequest request) {
  print("- Screen seen? ${request.seen} ${request.lastSeenAt}");
  print("- Device: ${request.manufacturer} ${request.model} ${request.version}");

  // If we've already shown this screen to the user, we don't want to annoy them.
  if (request.seen) {
    return;
  }
  // It's your responsibility to instruct the user what exactly
  // to do here, perhaps with a Confirm Dialog:
  showMyConfirmDialog(
    title: "Device Power Management",
    text: "Please white-list the app in your Device's Power Management settings by clicking this then selecting that."
  ).then((bool confirmed) {
    if (confirmed) {
      // User clicked [Confirm] button.  Execute the redirect to settings screen:
      DeviceSettings.show(request);
    }
  });
}).catchError((dynamic error) {
  // Depending on Manufacturer/Model/OS Version, a Device may not implement
  // a particular Settings screen.
  print(error);
});