permission_handler 5.0.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 100

pub package Build Status style: effective dart

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

The current version of the plugin requires 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 28:
android {
  compileSdkVersion 28
  ...
}
  1. Make sure you replace all the android. dependencies to their AndroidX counterparts (a full list can be found here: https://developer.android.com/jetpack/androidx/migrate).

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 supported. By default, all the permissions listed here are supported.

You can remove permissions you don't use:

  1. Add the following to your Podfile file:
    post_install do |installer|
      installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
          ... # Here are some configurations automatically generated by flutter
    
          # You can remove unused permissions here
          # for more infomation: https://github.com/BaseflowIT/flutter-permission-handler/blob/develop/ios/Classes/PermissionHandlerEnums.h
          # e.g. when you don't need camera permission, just add 'PERMISSION_CAMERA=0'
          config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
            '$(inherited)',
    
            ## dart: PermissionGroup.calendar
            # 'PERMISSION_EVENTS=0',
    
            ## dart: PermissionGroup.reminders
            # 'PERMISSION_REMINDERS=0',
    
            ## dart: PermissionGroup.contacts
            # 'PERMISSION_CONTACTS=0',
    
            ## dart: PermissionGroup.camera
            # 'PERMISSION_CAMERA=0',
    
            ## dart: PermissionGroup.microphone
            # 'PERMISSION_MICROPHONE=0',
    
            ## dart: PermissionGroup.speech
            # 'PERMISSION_SPEECH_RECOGNIZER=0',
    
            ## dart: PermissionGroup.photos
            # 'PERMISSION_PHOTOS=0',
    
            ## dart: [PermissionGroup.location, PermissionGroup.locationAlways, PermissionGroup.locationWhenInUse]
            # 'PERMISSION_LOCATION=0',
    
            ## dart: PermissionGroup.notification
            # 'PERMISSION_NOTIFICATIONS=0',
    
            ## dart: PermissionGroup.mediaLibrary
            # 'PERMISSION_MEDIA_LIBRARY=0',
    
            ## dart: PermissionGroup.sensors
            # 'PERMISSION_SENSORS=0'
          ]
    
        end
      end
    end
    
  2. 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 |
  3. Clean & Rebuild

How to use #

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

var status = await Permission.camera.status;
if (status.isUndetermined) {
  // We didn't ask for permission yet.
}

// 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;

Issues #

Please file any issues, bugs or feature request as an issue on our GitHub page.

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

5.0.0 #

  • BREAKING: Implemented more intuitive API exposed by permission_handler_platform_interface: 2.0.0 (#230).

4.4.0+hotfix.2 #

  • Issue #235: Solved a bug which made it impossible to request service status on Android 7;
  • Issue #237: Solved a bug which crashes the application when cancelling the "Ignore battery optimizations" request for permissions.

4.4.0+hotfix.1 #

  • Issue #233: Solved a bug that prevented Android applications running in the background to check the permission status.

4.4.0 #

  • Updated plugin structure to confirm to the Flutter federated plugin architecture. This will make it easier to add new platform implementations (see: https://medium.com/flutter/how-to-write-a-flutter-web-plugin-part-2-afdddb69ece6);
  • Android: Migrate to FlutterPlugin Android API (better support for Add-to-App);
  • Android: Suppress JAVA warnings which are generated to old platform code (only executes on older platforms);
  • Android: Fixed issue which sometimes resulting in illegal cast exception.

4.3.0 #

  • Allow requesting location permissions when location services are disabled (on iOS this will redirect the user to the Location settings page);
  • Android: Add support for requesting Activity Recognition permissions;
  • Confirm to Effective Dart guidelines;
  • Documented all public API members;
  • Fixed several typos in the README.md.

4.2.0+hotfix.3 #

  • Android: Fixes a bug which in some cases caused the permission neverAskAgain to be returned incorrectly.

4.2.0+hotfix.2 #

  • Android: Fixes a bug where permissions are reported as neverAskAgain incorrectly after calling requestPermissions method.

4.2.0+hotfix.1 #

  • Android: Fixes a bug where permissions are reported as neverAskAgain incorrectly.

4.2.0 #

  • Android: Methods checkPermissionStatus and requestPermissions now support addition neverAskAgain status.

4.1.0 #

  • iOS: Added option to exclude permissions logic using macros. This allows developers to submit their app to the AppStore without having to include all permissions in their Info.plist;
  • Android: Support ANSWER_PHONE_CALLS permission for API 26 and higher;
  • Android: Support ACCESS_MEDIA_LOCATION permission for API 26 and higher;
  • Android: Synchronized Gradle version with Flutter stable (1.12.13+hotfix.5).

4.0.0 #

  • iOS: Added support for requesting permissions on the DOCUMENTS and DOWNLOADS folder (thanks to @phranck);
  • Androis: Fix the PROCESS_OUTGOING_CALLS permissions which have been deprecated in API 29.

3.3.0 #

  • Android: Add support for requesting the background location permission within the locationAlways group.
  • Android: Update AGP, Gradle and AndroidX dependencies

3.2.2 #

  • Fixed problem with dependency on specific version of gradle wrapper on Android.

3.2.1+1 #

  • Reverted the update of the 'meta' plugin since Flutter SDK depends on version 1.1.6

3.2.1 #

  • Updated dependecy on 'meta' to latest version.

3.2.0 #

  • Add support for Androids' "ignore battery optimizations" permission;
  • Improve error logging;
  • Documented support for AndroidX.

3.1.0 #

  • Support service status inquiry for phone permission on iOS & Android.

3.0.2 #

  • Fixed bug when rapidly requesting permissions (#23);
  • Rename Enums.h to PermissionHandlerEnums.h to prevent conflicts with geolocator (#104);
  • Update the Android permission request code to prevent conflicts with geolocator (#111);
  • Update Gradle infrastructure.

3.0.1 #

  • Mark the Swift pod as static

3.0.0 #

  • Converted the iOS version from Swift to Objective-C, reducing the size of the final binary considerably.

2.2.0 #

  • Added new method checkServiceStatus to allow users to check if the location services (on Android and iOS) and motion services (iOS only) are enabled;
  • When checking permission status (using checkPermissionStatus) return PermissionStatus.disabled when permissions are granted or denied and the location services (on Android and iOS) or the motion services (iOS only) are disabled.

2.1.3 #

  • Fixed bug on iOS where result of the openAppSettings call always returned false;
  • Upgrade Android plugin to support AndroidX and latest Gradle and Kotlin versions;
  • Added Swift version number to the Podfile of the plugin;
  • Updated flutter static analyzes to conform to latest recommendations.

2.1.2 #

  • Make sure the Permission Handler compiles with latest iOS SDK

2.1.1 #

  • Update to the latest version of Swift (4.2);
  • Make sure that the correct Swift version is set in the Podfile of consuming Apps;
  • Updated configuration for statis code analyses, so it complies with the Flutter recommendations.

2.1.0 #

  • Added Android support to check if location services are enabled. If location services are not running the permission check returns PermissionStatus.DISABLED.

2.0.1 #

  • Fix bug with dependency on com.android.support:support-compat library
  • Update used Kotlin and Gradle versions

2.0.0 #

  • Make methods non static so users can create an instance or override

1.0.1 #

  • Converted the plugin into a library so that developers don't have to import additional files;
  • Updated the README.md to fix example code.

1.0.0 #

  • Initial release.

example/lib/main.dart

import 'dart:io';

import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';

void main() => runApp(MyApp());

/// Example Flutter Application demonstrating the functionality of the
/// Permission Handler plugin.
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Plugin example app'),
          actions: <Widget>[
            IconButton(
              icon: const Icon(Icons.settings),
              onPressed: () async {
                var hasOpened = openAppSettings();
                debugPrint('App Settings opened: ' + hasOpened.toString());
              },
            )
          ],
        ),
        body: Center(
          child: ListView(
              children: Permission.values
                  .where((Permission permission) {
                    if (Platform.isIOS) {
                      return permission != Permission.unknown &&
                          permission != Permission.sms &&
                          permission != Permission.storage &&
                          permission != Permission.ignoreBatteryOptimizations &&
                          permission != Permission.accessMediaLocation;
                    } else {
                      return permission != Permission.unknown &&
                          permission != Permission.mediaLibrary &&
                          permission != Permission.photos &&
                          permission != Permission.reminders;
                    }
                  })
                  .map((permission) => PermissionWidget(permission))
                  .toList()),
        ),
      ),
    );
  }
}

/// Permission widget which displays a permission and allows users to request
/// the permissions.
class PermissionWidget extends StatefulWidget {
  /// Constructs a [PermissionWidget] for the supplied [Permission].
  const PermissionWidget(this._permission);

  final Permission _permission;

  @override
  _PermissionState createState() => _PermissionState(_permission);
}

class _PermissionState extends State<PermissionWidget> {
  _PermissionState(this._permission);

  final Permission _permission;
  PermissionStatus _permissionStatus = PermissionStatus.undetermined;

  @override
  void initState() {
    super.initState();

    _listenForPermissionStatus();
  }

  void _listenForPermissionStatus() async {
    final status = await _permission.status;
    setState(() => _permissionStatus = status);
  }

  Color getPermissionColor() {
    switch (_permissionStatus) {
      case PermissionStatus.denied:
        return Colors.red;
      case PermissionStatus.granted:
        return Colors.green;
      default:
        return Colors.grey;
    }
  }

  @override
  Widget build(BuildContext context) {
    return ListTile(
      title: Text(_permission.toString()),
      subtitle: Text(
        _permissionStatus.toString(),
        style: TextStyle(color: getPermissionColor()),
      ),
      trailing: IconButton(
          icon: const Icon(Icons.info),
          onPressed: () {
            checkServiceStatus(context, _permission);
          }),
      onTap: () {
        requestPermission(_permission);
      },
    );
  }

  void checkServiceStatus(BuildContext context, Permission permission) async {
    Scaffold.of(context).showSnackBar(SnackBar(
      content: Text((await permission.status).toString()),
    ));
  }

  Future<void> requestPermission(Permission permission) async {
    final status = await permission.request();

    setState(() {
      print(status);
      _permissionStatus = status;
      print(_permissionStatus);
    });
  }
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  permission_handler: ^5.0.0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:permission_handler/permission_handler.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
99
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
100
Learn more about scoring.

We analyzed this package on Jul 4, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13
  • Flutter: 1.17.5

Analysis suggestions

Package does not support Flutter platform linux

Because of import path [package:permission_handler/permission_handler.dart] that declares support for platforms: android, ios

Package does not support Flutter platform macos

Because of import path [package:permission_handler/permission_handler.dart] that declares support for platforms: android, ios

Package does not support Flutter platform web

Because of import path [package:permission_handler/permission_handler.dart] that declares support for platforms: android, ios

Package does not support Flutter platform windows

Because of import path [package:permission_handler/permission_handler.dart] that declares support for platforms: android, ios

Package not compatible with SDK dart

because of import path [permission_handler] that is in a package requiring null.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
flutter 0.0.0
meta ^1.1.6 1.1.8
permission_handler_platform_interface ^2.0.0 2.0.1
Transitive dependencies
collection 1.14.12 1.14.13
sky_engine 0.0.99
typed_data 1.1.6 1.2.0
vector_math 2.0.8
Dev dependencies
effective_dart ^1.2.1
plugin_platform_interface ^1.0.1 1.0.2