permission_handler

Readme

pub package Build status style: effective dart codecov

On most operating systems, permissions aren't just granted to apps at install time. Rather, developers have to ask the user for permission while the app is running.

This plugin provides a cross-platform (iOS, Android) API to request permissions and check their status. You can also open the device's app settings so users can grant permission.
On Android, you can show a rationale for requesting permission.

See the FAQ section for more information on common questions when using the permission_handler plugin.

Setup

While the permissions are being requested during runtime, you'll still need to tell the OS which permissions your app might potentially use. That requires adding permission configuration to Android* and iOS-specific files.

Upgrade pre-1.12 Android projects

Since version 4.4.0 this plugin is implemented using the Flutter 1.12 Android plugin APIs. Unfortunately, this means App developers also need to migrate their Apps to support the new Android infrastructure. You can do so by following the Upgrading pre 1.12 Android projects migration guide. Failing to do so might result in unexpected behavior. The most common known error is the permission_handler not returning after calling the .request() method on permission.

AndroidX

As of version 3.1.0, the permission_handler plugin switched to the AndroidX version of the Android Support Libraries. This means you need to make sure your Android project is also upgraded to support AndroidX. Detailed instructions can be found here.

The TL;DR version is:

1. Add the following to your "gradle.properties" file:

android.useAndroidX=true
android.enableJetifier=true

2. Make sure you set the compileSdkVersion in your "android/app/build.gradle" file to 35:

android {
  compileSdkVersion 35
  ...
}

3. Make sure you replace all the android. dependencies to their AndroidX counterparts (a full list can be found here).

Add permissions to your AndroidManifest.xml file. There are debug, main, and profile versions which are chosen depending on how you start your app. In general, it's sufficient to add permission only to the main version. Here's an example AndroidManifest.xml with a complete list of all possible permissions.

Requires Flutter 3.24.0 or higher and Xcode 15.0 or higher.

With SPM, Package.swift automatically detects which permissions to enable by reading your app's Info.plist. A permission is compiled in when its corresponding usage description key is present:

Because you must already add these keys to Info.plist for any permission to work, a single-flavor app needs no additional configuration.

Info.plist files are located through the INFOPLIST_FILE setting of your Xcode project and .xcconfig files, so build-configuration specific plists (Info-Debug.plist, Runner/Info-$(CONFIGURATION).plist, …) are picked up as well. When an app has several of them, the keys are merged: a permission declared in any one of them is compiled into every build configuration.

Special cases: permissions without an Info.plist key

PermissionGroup.notification has no required Info.plist key and is enabled by default. To opt out, disable it via environment variable before building:

# When building from terminal (flutter run / flutter build)
export PERMISSION_NOTIFICATIONS=0

# When building from Xcode GUI (set once per Mac session, then restart Xcode)
launchctl setenv PERMISSION_NOTIFICATIONS 0

PermissionGroup.criticalAlerts requires a special entitlement granted by Apple and is disabled by default to avoid compiling unused code into apps that don't need it. Enable it explicitly:

# When building from terminal
export PERMISSION_CRITICAL_ALERTS=1

# When building from Xcode GUI
launchctl setenv PERMISSION_CRITICAL_ALERTS 1

After changing any env var or Info.plist key, clear Xcode's package cache once so Package.swift is re-evaluated:

rm -rf ~/Library/Developer/Xcode/DerivedData

Then run flutter build ios or rebuild in Xcode as usual.

Apps with flavors

Merging is wrong when your flavors need different permissions: a permission declared only in Info-dev.plist is compiled into your production binary too, which is grounds for App Store rejection (ITMS-90683). Declare a permission_handler.yaml next to your pubspec.yaml to give each flavor its own Info.plist, and select the flavor before building:

strict: true
flavors:
  dev:
    info-plist: ios/Runner/Info-dev.plist
    configurations: [Debug-dev, Profile-dev, Release-dev]
  prod:
    info-plist: ios/Runner/Info-prod.plist
    configurations: [Debug-prod, Profile-prod, Release-prod]

dart run permission_handler_apple:select prod
flutter run --flavor prod

Only the selected flavor's Info.plist is read and nothing is merged, so a flavor can never inherit another flavor's permissions. See Per-flavor permissions for the build phase that catches a stale selection.

Builds started from Xcode.app

Automatic detection finds your app through the build's working directory, which points at the Flutter project for flutter run, flutter build ios and xcodebuild. Builds started from Xcode.app run with / as their working directory and cannot be detected, so point the manifest at your Info.plist explicitly:

launchctl setenv PERMISSION_HANDLER_INFO_PLIST /absolute/path/to/ios/Runner/Info.plist
rm -rf ~/Library/Developer/Xcode/DerivedData

Troubleshooting

If no Info.plist is found, every permission is compiled out and all permission checks report denied. Xcode discards Swift package manifest output, so the warning about this only reaches you from the command line:

cd your_app
PERMISSION_HANDLER_VERBOSE=1 swift package --manifest-cache none \
  --package-path ios/Flutter/ephemeral/Packages/.packages/permission_handler_apple \
  dump-package > /dev/null

That prints the Info.plist files that were used, the active flavor if you declared one, and the value every PERMISSION_* macro resolved to.

More detail

The permission_handler_apple README documents this in full, including every PERMISSION_HANDLER_* environment variable and the per-flavor workflow.

Add permission to your Info.plist file. Here's an example Info.plist with a complete list of all possible permissions.

IMPORTANT: You will have to include all permission options when you want to submit your App. This is because the permission_handler plugin touches all different SDKs and because the static code analyzer (run by Apple upon App submission) detects this and will assert if it cannot find a matching permission option in the Info.plist. More information about this can be found here. This has been fixed since version 8.0.0, now permission_handler by default excludes all permissions and developers only have to enable those that the app really needs.

The permission_handler plugin use macros to control whether a permission is enabled.

You must list the permission you want to use in your application:

1. Add the following to your Podfile's post_install block:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)

    target.build_configurations.each do |config|
      # You can remove unused permissions here
      # for more information: https://github.com/Baseflow/flutter-permission-handler/blob/main/permission_handler_apple/ios/Classes/PermissionHandlerEnums.h
      # When you don't need a permission, just change its value to 0
      # e.g. 'PERMISSION_CAMERA=0' instead of 'PERMISSION_CAMERA=1'
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',

        ## dart: PermissionGroup.calendar
        'PERMISSION_EVENTS=1',
        
        ## dart: PermissionGroup.calendarFullAccess
        'PERMISSION_EVENTS_FULL_ACCESS=1',

        ## dart: PermissionGroup.reminders
        'PERMISSION_REMINDERS=1',

        ## dart: PermissionGroup.contacts
        'PERMISSION_CONTACTS=1',

        ## dart: PermissionGroup.camera
        'PERMISSION_CAMERA=1',

        ## dart: PermissionGroup.microphone
        'PERMISSION_MICROPHONE=1',

        ## dart: PermissionGroup.speech
        'PERMISSION_SPEECH_RECOGNIZER=1',

        ## dart: PermissionGroup.photos
        'PERMISSION_PHOTOS=1',

        ## The 'PERMISSION_LOCATION' macro enables the `locationWhenInUse` and `locationAlways` permission. If
        ## the application only requires `locationWhenInUse`, only specify the `PERMISSION_LOCATION_WHENINUSE`
        ## macro.
        ##
        ## dart: [PermissionGroup.location, PermissionGroup.locationAlways, PermissionGroup.locationWhenInUse]
        'PERMISSION_LOCATION=1',
        'PERMISSION_LOCATION_WHENINUSE=0',

        ## dart: PermissionGroup.notification
        'PERMISSION_NOTIFICATIONS=1',

        ## dart: PermissionGroup.mediaLibrary
        'PERMISSION_MEDIA_LIBRARY=1',

        ## dart: PermissionGroup.sensors
        'PERMISSION_SENSORS=1',

        ## dart: PermissionGroup.bluetooth
        'PERMISSION_BLUETOOTH=1',

        ## dart: PermissionGroup.appTrackingTransparency
        'PERMISSION_APP_TRACKING_TRANSPARENCY=1',

        ## dart: PermissionGroup.criticalAlerts
        'PERMISSION_CRITICAL_ALERTS=1',

        ## dart: PermissionGroup.assistant
        'PERMISSION_ASSISTANT=1',
      ]

    end
  end
end

2. For the permissions you want to use, keep them as is. For example, if you need access to the calendar make sure the code looks like this:

           ## dart: PermissionGroup.calendar
           'PERMISSION_EVENTS=1',
   

3. When you DON'T need a permission, change its value to 0 e.g. 'PERMISSION_CAMERA=0' instead of 'PERMISSION_CAMERA=1'

4. And delete the corresponding permission description in Info.plist e.g. when you don't need camera permission, just delete 'NSCameraUsageDescription'

The following lists the relationship between Permission and The key of Info.plist:

4. Clean & Rebuild

How to use

There are a number of Permissions. You can get a Permission's status, which is either granted, denied, restricted, permanentlyDenied, limited, or provisional.

var status = await Permission.camera.status;
if (status.isDenied) {
  // We haven't asked for permission yet or the permission has been denied before.
  // On Android this also covers a permanently denied permission: the OS does not
  // expose the difference without requesting, so call `request()` to find out.
}

// You can also directly ask permission about its status.
if (await Permission.location.isRestricted) {
  // The OS restricts access, for example, because of parental controls.
}

Can use also this style for better readability of your code when using the Permission class.

await Permission.camera
  .onDeniedCallback(() {
    // Your code
  })
  .onGrantedCallback(() {
    // Your code
  })
  .onPermanentlyDeniedCallback(() {
    // Your code
  })
  .onRestrictedCallback(() {
    // Your code
  })
  .onLimitedCallback(() {
    // Your code
  })
  .onProvisionalCallback(() {
    // Your code
  })
  .request();

Call request() on a Permission to request it. If it has already been granted before, nothing happens.
request() returns the new status of the Permission.

if (await Permission.contacts.request().isGranted) {
  // Either the permission was already granted before or the user just granted it.
}

// You can request multiple permissions at once.
Map<Permission, PermissionStatus> statuses = await [
  Permission.location,
  Permission.storage,
].request();
print(statuses[Permission.location]);

Some permissions, for example, location or acceleration sensor permissions, have an associated service, which can be enabled or disabled.

if (await Permission.locationWhenInUse.serviceStatus.isEnabled) {
  // Use location.
}

You can also open the app settings:

if (await Permission.speech.request().isPermanentlyDenied) {
  // The user opted to never again see the permission request dialog for this
  // app. The only way to change the permission's status now is to let the
  // user manually enable it in the system settings.
  openAppSettings();
}

On Android, only the result of request() can be permanentlyDenied; status reports denied instead. Android does not expose whether a permission is permanently denied: a permission that was never requested, one that the user reset to "Ask every time" in the app settings and a permanently denied one all look the same to the app. Requesting a permanently denied permission is cheap, the OS resolves it immediately without showing a dialog. The Android "permanently denied" guide covers this in full: what each status means on Android, the request-driven pattern to use instead, and how to audit an existing app for code that relies on the old behavior.

On Android, you can show a rationale for using permission:

bool isShown = await Permission.contacts.shouldShowRequestRationale;

Some permissions will not show a dialog asking the user to allow or deny the requested permission.
This is because the OS setting(s) of the app are being retrieved for the corresponding permission.
The status of the setting will determine whether the permission is granted or denied.

The following permissions will show no dialog:

• Notification
• Bluetooth

The following permissions will show no dialog, but will open the corresponding setting intent for the user to change the permission status:

• manageExternalStorage
• systemAlertWindow
• requestInstallPackages
• accessNotificationPolicy

The locationAlways permission can not be requested directly, the user has to request the locationWhenInUse permission first. Accepting this permission by clicking on the 'Allow While Using App' gives the user the possibility to request the locationAlways permission. This will then bring up another permission popup asking you to Keep Only While Using or to Change To Always Allow.

FAQ

Permission.status never returns permanentlyDenied on Android. What can I do?

That is intentional as of permission_handler_android 14.1.0. Android does not expose whether a permission is permanently denied, so a status check reports denied for every denied runtime permission. Call request() and branch on its result: it returns permanentlyDenied without showing a dialog when the permission really is permanently denied. See the Android "permanently denied" guide for the full behavior table, the pattern to use and an audit checklist for existing apps.

Requesting "storage" permissions always returns "denied" on Android 13+. What can I do?

On Android, the Permission.storage permission is linked to the Android READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE permissions. Starting from Android 10 (API 29) the READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE permissions have been marked deprecated and have been fully removed/disabled since Android 13 (API 33).

If your application needs access to media files Google recommends using the READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, or READ_MEDIA_AUDIO permissions instead. These can be requested using the Permission.photos, Permission.videos, and Permission.audio respectively. To request these permissions make sure the compileSdkVersion in the android/app/build.gradle file is set to 33.

If your application needs access to Android's file system, it is possible to request the MANAGE_EXTERNAL_STORAGE permission (using Permission.manageExternalStorage). As of Android 11 (API 30), the MANAGE_EXTERNAL_STORAGE permission is considered a high-risk or sensitive permission. Therefore it is required to declare the use of these permissions if you intend to release the application via the Google Play Store.

Requesting Permission.locationAlways always returns "denied" on Android 10+ (API 29+). What can I do?

Starting with Android 10, apps are required to first obtain permission to read the device's location in the foreground, before requesting to read the location in the background as well. When requesting the 'location always' permission directly, or when requesting both permissions at the same time, the system will ignore the request. So, instead of calling only Permission.location.request(), make sure to first call either Permission.location.request() or Permission.locationWhenInUse.request(), and obtain permission to read the GPS. Once you obtain this permission, you can call Permission.locationAlways.request(). This will present the user with the option to update the settings so the location can always be read in the background. For more information, visit the Android documentation on requesting location permissions.

onRequestPermissionsResult is called without results. What can I do?

It is probably caused by a difference between compileSdkVersion and targetSdkVersion. It can be depending on the flutter version that you use. targetSdkVersion = flutter.targetSdkVersion in the app/build.gradle indicates that the targetSdkVersion is flutter version dependant. For more information: issue 1222

Checking or requesting a permission terminates the application on iOS. What can I do?

First of all make sure all that the ios/Runner/Info.plist file contains entries for all the permissions the application requires. If an entry is missing iOS will terminate the application as soon as the particular permission is being checked or requested.

If the application requires access to SiriKit (by requesting the Permission.assistant permission), also make sure to add the com.apple.developer.siri entitlement to the application configuration. To do so create a file (if it doesn't exists already) called Runner.entitlements in the ios/Runner folder that is part of the project. Open the file and add the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.developer.siri</key>
	<true/>
</dict>
</plist>

The important part here is the key with value com.apple.developer.siri and the element <true/>. It is possible that this file also contains other entitlements depending on the needs of the application.

Issues

Please file any issues, bugs, or feature requests as an issue on our GitHub page. Commercial support is available if you need help with integration with your app or services. You can contact us at hello@baseflow.com.

Want to contribute

If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug, or adding a cool new feature), please carefully review our contribution guide and send us your pull request.

Author

This Permission handler plugin for Flutter is developed by Baseflow. You can contact us at hello@baseflow.com