PermissionRationale Android only¶

class PermissionRationale

Configures the background location permission rationale dialog on Android 11 and later.

Android 11 removed the Allow all the time option from the system location permission dialog. Apps may instead show a custom rationale dialog that explains why background access is needed and routes the user to the system Location Permissions screen to grant it explicitly.

Overview¶

The SDK presents this dialog automatically when GeoConfig.locationAuthorizationRequest is "Always" and AppConfig.backgroundPermissionRationale is configured.

Selecting the dialog's positive action sends the user directly to the system Location Permissions screen, where they must enable Allow all the time themselves.

The dialog is shown once only. After the user presses the positive action it will not appear again. Pressing Cancel does not count as acceptance.
If the user later resets your app's Location permission to Ask every time, the dialog becomes eligible to be shown again.

BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    locationAuthorizationRequest: 'Always'
  ),
  app: AppConfig(
    backgroundPermissionRationale: PermissionRationale(
      title: "Allow {applicationName} to access this device's location in the background?",
      message: "To track your activity in the background, please enable {backgroundPermissionOptionLabel} location access.",
      positiveAction: "Change to {backgroundPermissionOptionLabel}",
      negativeAction: "Cancel"
    )
  )
));

Template tags¶

Embed the following variables inside any rationale field using {tagName} syntax:

Template Tag	Default value	Description
`{backgroundPermissionOptionLabel}`	"Allow all the time"	(API 30+) Localized label for the background location permission option.
`{applicationName}`	App name	Localized application name from `AndroidManifest`.

Members¶

message¶

String? message

Body text of the dialog. Explain why your app needs background location access, similar in purpose to the iOS NSLocationAlwaysAndWhenInUseUsageDescription.

negativeAction¶

String? negativeAction

Text to display on the negative action button (e.g. "Cancel").

positiveAction¶

String? positiveAction

Text to display on the positive action button.

title¶

String? title

Title for the Android background location permission dialog.