permission_handler/README.md

On most operating systems, permissions aren't just granted to apps at install time. Rather, developers have to ask the user for permissions 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 a permission.
On Android, you can show a rationale for requesting a permission.

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.

Android

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 behaviour. Most common known error is the permission_handler not returning after calling the .request() method on a 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

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

android {
  compileSdkVersion 33
  ...
}

1. 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's a debug, main and profile version 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.

iOS

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 analyser (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.

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

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

1. Add the following to your Podfile file:

   post_install do |installer|
     installer.pods_project.targets.each do |target|
       ... # Here are some configurations automatically generated by flutter
   
       # Start of the permission_handler configuration
       target.build_configurations.each do |config|
   
         # You can enable the permissions needed here. For example to enable camera
         # permission, just remove the `#` character in front so it looks like this:
         #
         # ## dart: PermissionGroup.camera
         # 'PERMISSION_CAMERA=1'
         #
         #  Preprocessor definitions can be found in: https://github.com/Baseflow/flutter-permission-handler/blob/master/permission_handler_apple/ios/Classes/PermissionHandlerEnums.h
         config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
           '$(inherited)',
   
           ## dart: PermissionGroup.calendar
           # 'PERMISSION_EVENTS=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',
   
           ## dart: [PermissionGroup.location, PermissionGroup.locationAlways, PermissionGroup.locationWhenInUse]
           # 'PERMISSION_LOCATION=1',
   
           ## 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'
         ]
   
       end 
       # End of the permission_handler configuration
     end
   end
   

2. Remove the # character in front of the permission you do want to use. For example if you need access to the calendar make sure the code looks like this:

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

3. 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:

   Permission	Info.plist	Macro
   PermissionGroup.calendar	NSCalendarsUsageDescription	PERMISSION_EVENTS
   PermissionGroup.reminders	NSRemindersUsageDescription	PERMISSION_REMINDERS
   PermissionGroup.contacts	NSContactsUsageDescription	PERMISSION_CONTACTS
   PermissionGroup.camera	NSCameraUsageDescription	PERMISSION_CAMERA
   PermissionGroup.microphone	NSMicrophoneUsageDescription	PERMISSION_MICROPHONE
   PermissionGroup.speech	NSSpeechRecognitionUsageDescription	PERMISSION_SPEECH_RECOGNIZER
   PermissionGroup.photos	NSPhotoLibraryUsageDescription	PERMISSION_PHOTOS
   PermissionGroup.location, PermissionGroup.locationAlways, PermissionGroup.locationWhenInUse	NSLocationUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSLocationWhenInUseUsageDescription	PERMISSION_LOCATION
   PermissionGroup.notification	PermissionGroupNotification	PERMISSION_NOTIFICATIONS
   PermissionGroup.mediaLibrary	NSAppleMusicUsageDescription, kTCCServiceMediaLibrary	PERMISSION_MEDIA_LIBRARY
   PermissionGroup.sensors	NSMotionUsageDescription	PERMISSION_SENSORS
   PermissionGroup.bluetooth	NSBluetoothAlwaysUsageDescription, NSBluetoothPeripheralUsageDescription	PERMISSION_BLUETOOTH
   PermissionGroup.appTrackingTransparency	NSUserTrackingUsageDescription	PERMISSION_APP_TRACKING_TRANSPARENCY
   PermissionGroup.criticalAlerts	PermissionGroupCriticalAlerts	PERMISSION_CRITICAL_ALERTS

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 or permanentlyDenied.

var status = await Permission.camera.status;
if (status.isDenied) {
  // We didn't ask for permission yet or the permission has been denied before but not permanently.
}

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

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.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, you can show a rationale for using a 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.

Issues

Please file any issues, bugs or feature request 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