permission_handler 4.0.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 100

Flutter Permission handler Plugin #

pub package

A permissions plugin for Flutter. This plugin provides a cross-platform (iOS, Android) API to request and check permissions.

BranchBuild Status
developBuild Status
masterBuild Status

Features #

  • Check if a permission is granted.
  • Request permission for a specific feature.
  • Open app settings so the user can enable a permission.
  • Show a rationale for requesting permission (Android).

Usage #

To use this plugin, add permission_handler as a dependency in your pubspec.yaml file. For example:

dependencies:
  permission_handler: '^4.0.0'

NOTE: 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).

Android and iOS specific permissions #

For this plugin to work you will have to add permission configuration to your AndroidManifest.xml (Android) and Info.plist (iOS) files. This will tell the platform which hardware or software features your app needs. Complete lists of these permission options can be found in our example app here:

  • AndroidManifest.xml (note that there is a debug, main and profile version which are used depending on how you start your App. In general it is sufficient to add permissions only to the main version);
  • Info.plist

IMPORTANT: On iOS 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. Unfortunately we don't have a good solution for this.

API #

Requesting permission #

import 'package:permission_handler/permission_handler.dart';

Map<PermissionGroup, PermissionStatus> permissions = await PermissionHandler().requestPermissions([PermissionGroup.contacts]);

Checking permission #

import 'package:permission_handler/permission_handler.dart';

PermissionStatus permission = await PermissionHandler().checkPermissionStatus(PermissionGroup.contacts);

Checking service status #

import 'package:permission_handler/permission_handler.dart';

ServiceStatus serviceStatus = await PermissionHandler().checkServiceStatus(PermissionGroup.location);

Checking the service status only makes sense for the PermissionGroup.location on Android and the PermissionGroup.location, PermissionGroup.locationWhenInUser, PermissionGroup.locationAlways or PermissionGroup.sensors on iOS. All other permission groups are not backed by a separate service and will always return ServiceStatus.notApplicable.

Open app settings #

import 'package:permission_handler/permission_handler.dart';

bool isOpened = await PermissionHandler().openAppSettings();

Show a rationale for requesting permission (Android only) #

import 'package:permission_handler/permission_handler.dart';

bool isShown = await PermissionHandler().shouldShowRequestPermissionRationale(PermissionGroup.contacts);

This will always return false on iOS.

List of available permissions #

Defines the permission groups for which permissions can be checked or requested.

enum PermissionGroup {
  /// The unknown permission only used for return type, never requested
  unknown,

  /// Android: Calendar
  /// iOS: Calendar (Events)
  calendar,

  /// Android: Camera
  /// iOS: Photos (Camera Roll and Camera)
  camera,

  /// Android: Contacts
  /// iOS: AddressBook
  contacts,

  /// Android: Fine and Coarse Location
  /// iOS: CoreLocation (Always and WhenInUse)
  location,

  /// Android: Microphone
  /// iOS: Microphone
  microphone,

  /// Android: Phone
  /// iOS: Nothing
  phone,

  /// Android: Nothing
  /// iOS: Photos
  photos,

  /// Android: Nothing
  /// iOS: Reminders
  reminders,

  /// Android: Body Sensors
  /// iOS: CoreMotion
  sensors,

  /// Android: Sms
  /// iOS: Nothing
  sms,

  /// Android: External Storage
  /// iOS: Nothing
  storage,

  /// Android: Microphone
  /// iOS: Speech
  speech,

  /// Android: Fine and Coarse Location
  /// iOS: CoreLocation - Always
  locationAlways,

  /// Android: Fine and Coarse Location
  /// iOS: CoreLocation - WhenInUse
  locationWhenInUse,

  /// Android: None
  /// iOS: MPMediaLibrary
  mediaLibrary

  /// Android: Check notification enable
  /// iOS: Check and request notification permission
  notification
}

Status of the permission #

Defines the state of a permission group

enum PermissionStatus {
  /// Permission to access the requested feature is denied by the user.
  denied,

  /// Permissions to access the feature is granted by the user but the feature is disabled.
  disabled,

  /// Permission to access the requested feature is granted by the user.
  granted,

  /// The user granted restricted access to the requested feature (only on iOS).
  restricted,

  /// Permission is in an unknown state
  unknown
}

Overview of possible service statuses #

Defines the state of the backing service for the supplied permission group

/// Defines the state of a service related to the permission group
enum ServiceStatus {
  /// The unknown service status indicates the state of the service could not be determined.
  unknown,

  /// There is no service for the supplied permission group.
  notApplicable,

  /// The service for the supplied permission group is disabled.
  disabled,

  /// The service for the supplied permission group is enabled.
  enabled
}

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

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/README.md

permission_handler_example #

Demonstrates how to use the permission_handler plugin.

Getting Started #

This project is a starting point for a Flutter application.

A few resources to get you started if this is your first Flutter project:

For help getting started with Flutter, view our online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Use this package as a library

1. Depend on it

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


dependencies:
  permission_handler: ^4.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 Nov 15, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.6.0
  • pana: 0.12.21
  • Flutter: 1.9.1+hotfix.6

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
meta ^1.1.6 1.1.7 1.1.8
Transitive dependencies
collection 1.14.11 1.14.12
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
pedantic ^1.7.0