locationAuthorizationRequest property

String? locationAuthorizationRequest

Defines the desired location-authorization request you wish for the user to authorize:

• Always
• WhenInUse
• Any

locationAuthorizationRequest tells the plugin the mode it expects to have been authorized with by the user. Defaults to Always. If you don't care what the user authorizes, you may configure locationAuthorizationRequest: "Any".

If you configure locationAuthorizationRequest: 'Always' but the user authorizes only [When in Use] , the plugin will detect this and show the locationAuthorizationAlert dialog (see disableLocationAuthorizationAlert to disable this behaviour).

iOS

---

iOS 13 introduced a significant modification to location authorization (See this blog entry). No longer will the [Always allow] option appear on the initial authorization dialog. Instead, iOS will prompt the user with a second "authorization upgrade" dialog, asking the user if they'd like to grant [Keep Only While Using ] or [Change to Always Allow].

1. locationAuthorizationRequest: 'Always':

If your app requests locationAuthorizationRequest: 'Always', the user must first authorize [Alow While Using App], followed immediately by a second dialog prompting the user to upgrade location authorization with [Change to Always Allow]:

If the user denies Always authorization, the locationAuthorizationAlert will be shown (see disableLocationAuthorizationAlert to disable this behaviour).

2. locationAuthorizationRequest: 'WhenInUse':

Only the initial dialog will be shown:

However, if your app later uses setConfig to change locationAuthorizationRequest: 'Always', iOS will immediately show the "authorization upgrade" dialog:

3. locationAuthorizationRequest: 'Any':

The SDK will request Always authorization. The initial location authorization dialog will be shown:

However, at some unknown time in the future, iOS will prompt the user with the location authorization upgrade dialog:

Example

initPlatformState() async {
  // Initially configure for 'WhenInUse'.
  BackgroundGeolocation.ready(Config(
    locationAuthorizationRequest: 'WhenInUse',
    .
    .
    .
  });
}

onClickStartTracking() async {
  // Initial location authorization dialog for "When in Use" authotization
  // will be shown here.
  await BackgroundGeolocation.start();
  // some time later -- could be immediately after, hours later, days later, etc.,
  // you can upgrade the config to 'Always' whenever you wish:
  _upgradeToAlwaysAllow();
}

_upgradeToAlwaysAllow {
  // Simply update `locationAuthorizationRequest` to "Always" -- the SDK
  // will cause iOS to immediately show the authorization upgrade dialog
  // for "Change to Always Allow":
  BackgroundGeolocation.setConfig(Config(
    locationAuthorizationRequest: 'Always'
  ));
}

Android

---

Android 10

Like iOS 12, Android 10 now forces your app to offer both [Allow all the time] and [Allow only while using] options.

Android 11+ (with targetSdkVersion 30+)

Just as in iOS 13/14, Android 11 has changed location authorization and no longer offers the [Allow all the time] button on the location authorization dialog. Instead, Android now offers a hook to present a custom dialog to the user where you will explain exactly why you require "Allow all the time" location permission.

This dialog can forward the user directly to your application's Location Permissions screen, where the user must explicity authorize [Allow all the time]. The Background Geolocation SDK will present this dialog, which can be customized with Config.backgroundPermissionRationale.

• Android will offer the Config.backgroundPermissionRationale dialog just once. Once the user presses the positiveAction on the dialog, it will not be shown again (pressing [Cancel] button does not count).
• If the user resets your application's Location Permissions to [Ask every time], the Config.backgroundPermissionRationale can be shown once again.

BackgroundGeolocation.ready(Config(
 locationAuthorizationRequest: 'Always',
 backgroundPermissionRationale: PermissionRationale(
   title: "Allow access to this device's location in the background?",
   message: "In order to allow X, Y and Z, please enable 'Allow all the time permission",
   positiveAction: "Change to Allow all the time",
   negativeAction: "Cancel"
 )
));

1. locationAuthorizationRequest: 'Always':

If your app requests locationAuthorizationRequest: 'Always', the user must first authorize [While using the app], followed ///immediately* by the Config.backgroundPermissionRationale dialog prompting the user to upgrade location permission with [Allow all the time]:

2. locationAuthorizationRequest: 'WhenInUse':

Only the initial dialog will be shown:

However, if your app later uses setConfig to change locationAuthorizationRequest: 'Always', the SDK will immediately show the Config.backgroundPermissionRationale dialog:

3. locationAuthorizationRequest: 'Any':

Same as Always

Android 11+ (with targetSdkVersion <=29)

Just to add a bit more confusion, for Android 11+ devices and your app built with targetSdkVersion 29, Android will present an extra dialog after the user clicks through on the Config.backgroundPermissionRationale dialog, where the user is prompted with a link _"Allow in Settings"*, rather than forwarding them directly to the Location Permissions screen, as with targetSdkVersion 30+:

Implementation

String? locationAuthorizationRequest;