Permissions Dispatcher provides a simple annotation-based API to handle runtime permissions in Android Marshmallow, 100% reflection-free.
This library lifts the burden that comes with writing a bunch of check statements whether a permission has been granted or not from you, in order to keep your code clean and safe.
Permissions Dispatcher
Usage
Here’s a minimum example, in which we register a MainActivity
which requires Manifest.permission.CAMERA
.
0. Prepare AndroidManifest
Add the following line to AndroidManifest.xml
:
<uses-permission android:name="android.permission.CAMERA" />
1. Attach annotations
PermissionsDispatcher introduces only a few annotations, keeping its general API concise:
NOTE: Annotated methods must not be
private
.
Annotation | Required | Description |
---|---|---|
@RuntimePermissions |
✓ | Register an Activity or Fragment to handle permissions |
@NeedsPermission |
✓ | Annotate a method which performs the action that requires one or more permissions |
@OnShowRationale |
Annotate a method which explains why the permission/s is/are needed. It passes in a PermissionRequest object which can be used to continue or abort the current permission request upon user input |
|
@OnPermissionDenied |
Annotate a method which is invoked if the user doesn’t grant the permissions | |
@OnNeverAskAgain |
Annotate a method which is invoked if the user chose to have the device “never ask again” about a permission |
1 |
|
2. Delegate to generated class
Upon compilation, PermissionsDispatcher generates a class for MainActivityPermissionsDispatcher
([Activity Name] + PermissionsDispatcher), which you can use to safely access these permission-protected methods.
The only step you have to do is delegating the work to this helper class:
1 |
|
Check out the sample and generated class for more details.
Getting Special Permissions
PermissionsDispatcher takes care of special permissions Manifest.permission.SYSTEM_ALERT_WINDOW
and Manifest.permission.WRITE_SETTINGS
.
The following sample is to grant SYSTEM_ALERT_WINDOW
.
0. Prepare AndroidManifest
Add the following line to AndroidManifest.xml
:
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
1. Attach annotations
It’s the same as other permissions:
1 |
|
2. Delegate to generated class
Unlike other permissions, special permissions require to call the delegation method at onActivityResult
:
1 |
|
maxSdkVersion
\<uses-permission> has an attribute call maxSdkVersion
. PermissionsDispatcher support the feature as well.
The following sample is for declaring Manifest.permisison.WRITE_EXTERNAL_STORAGE
up to API level 18.
0. AndroidManifest
Declare the permission with maxSdkVersion
attribute
1 | <uses-permission |
1. Attach annotations with maxSdkVersion
1 |
|
Note
- PermissionsDispatcher depends on the
support-v4
library by default, in order to be able to use some permission compat classes. - You can use this library with JDK 1.6 or up, but we test library’s behaviour on the JDK 1.8 because it has been becoming the default of Android development.
PermissionsDispatcher bundles ProGuard rules in its aar. No extra settings are required.
Fragment Support
PermissionsDispatcher is supported on API levels 4 and up, with which you get support for annotating
android.app.Activity
andandroid.support.v4.app.Fragment
sub-classes out of the box.In case you rely on
android.app.Fragment
in your app, you can use these with PermissionsDispatcher as well!Simply add a dependency on the
support-v13
library alongside PermissionsDispatcher in your project, and it will enable support for native fragments.For AndroidAnnotations users
If you use AndroidAnnotations, you need to add AndroidAnnotationsPermissionsDispatcherPlugin to your dependencies so PermissionsDispatcher’s looks for AA’s subclasses (your project won’t compile otherwise).
Download
To add it to your project, include the following in your app module
build.gradle
file:1
2
3
4dependencies {
compile 'com.github.hotchemi:permissionsdispatcher:${latest.version}'
annotationProcessor 'com.github.hotchemi:permissionsdispatcher-processor:${latest.version}'
}Snapshots of the development version are available in JFrog’s snapshots repository.
Add the repo below to downloadSNAPSHOT
releases.1
2
3
4repositories {
jcenter()
maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
}