requestPermission static method

Future<int> requestPermission([
  1. Permission? permission
])

Requests location and motion permission — together, or each one separately.

With no argument, requests everything the current configuration requires: location per GeoConfig.locationAuthorizationRequest, then the motion permission — the same set start requests — and resolves with the location authorization status (the motion outcome stays silent). Pass a Permission to request one permission at a time and control exactly when each system dialog appears:

Argument Requests Resolves with
(none) Location per configuration, then motion The location status; motion silent
Permission.location Location only — motion untouched The location status
Permission.motion Motion only ProviderChangeEvent.AUTHORIZATION_STATUS_ALWAYS when granted

The location forms resolve when either WhenInUse or Always is granted, regardless of the configured level, and resolve immediately when permission is already granted. Denial errors the Future with the bare authorization status int.

Each call is independently awaitable and the SDK serializes permission requests internally — await one call, then issue the next, and each dialog appears in order, never stacked.

Android

A motion denial errors with ProviderChangeEvent.AUTHORIZATION_STATUS_DENIED while a new request can still show the system dialog, and with ProviderChangeEvent.AUTHORIZATION_STATUS_DENIED_ALWAYS once Android permanently denies the permission (two user denials) — after that, only the device's app-settings screen can restore it.

iOS

The motion permission is one-shot — iOS never re-prompts. A user denial errors with ProviderChangeEvent.AUTHORIZATION_STATUS_DENIED_ALWAYS: the state is permanent and only the Settings app can restore it (the motion form never errors with plain ProviderChangeEvent.AUTHORIZATION_STATUS_DENIED). The error can also carry ProviderChangeEvent.AUTHORIZATION_STATUS_RESTRICTED (system-wide Fitness Tracking is off or the hardware is absent — not recoverable from the app's own Settings page) or ProviderChangeEvent.AUTHORIZATION_STATUS_NOT_DETERMINED (no dialog could be shown, e.g. the app was backgrounded). If the location dialog has already been shown and the current grant does not match the configured request, the SDK presents an alert offering to direct the user to the app's Settings screen.

⚠️ Note:

  • The SDK will already request permission from the user when you execute start, startGeofences, getCurrentPosition, etc. Calling this method first resolves the dialogs ahead of time, so those methods find everything granted and show nothing.

Example

// Request each permission separately:
int locationStatus = await BackgroundGeolocation.requestPermission(Permission.location);
print("[requestPermission] location: $locationStatus");

try {
  int motionStatus = await BackgroundGeolocation.requestPermission(Permission.motion);
  print("[requestPermission] motion: $motionStatus");
} catch (status) {
  if (status == ProviderChangeEvent.AUTHORIZATION_STATUS_DENIED_ALWAYS) {
    // Only the app-settings screen can restore the motion permission now.
  }
}

// Or request everything at once:
await BackgroundGeolocation.ready(Config(
  locationAuthorizationRequest: 'Always'
));

try {
  int status = await BackgroundGeolocation.requestPermission();
  print("[requestPermission] status: $status");
} catch (status) {
  print("[requestPermission] DENIED: $status");
}

ℹ️ See also:

Implementation

static Future<int> requestPermission([Permission? permission]) async {
  try {
    return (await _methodChannel.invokeMethod<int>(
        'requestPermission', permission?.value))!;
  } on PlatformException catch (e) {
    // (WO-007) Cross-platform contract: the Future errors with the bare
    // authorization status (carried in the PlatformException details).
    throw (e.details is int) ? e.details as int : e;
  }
}