Requesting Permissions

Some things that your app might want to do — access the Internet, get a GPS fix, get personal information about the user’s contacts, etc. — will require permission from the user. Sometimes the user grants permission implicitly, just by installing your app. Sometimes, the user grants permission explicitly, for things that Google considers to be “dangerous”. And your app will need to deal with these permissions, including the possibility that the user decides not to grant you a permission.

In this chapter, we will explore the basics of Android’s permission system.

Frequently-Asked Questions About Permissions

Permissions are frequently a confusing topic in Android app development, particularly with respect to those “dangerous” permissions. So, here is a FAQ about Android’s permissions system.

What Is a Permission?

A permission is a way for Android (or, sometimes, a third-party app) to require an app developer to notify the user about something that the app will do that might raise concerns with the user. Only if an app holds a certain permission can the app do certain things that are defended by that permission.

Mechanically, permissions take the form of elements in the manifest, in the form of a <uses-permission> element.

When Will I Need a Permission?

Most permissions that you will deal with come from Android itself. Usually, the documentation will tell you when you need to request and hold one of these permissions.

However, occasionally the documentation has gaps.

If you are trying out some code and you crash with a SecurityException the description of the exception may tell you that you need to hold a certain permission — that means you need to add the corresponding <uses-permission> element to your manifest.

Third-party code, including Google’s own Play Services SDK, may define their own custom permissions. Once again, ideally, you find out that you need to request a permission through documentation, and otherwise you find out through crashing during testing.

What Are Some Common Permissions, and What Do They Defend?

There are dozens upon dozens of permissions in Android. Here are some of the more common ones:

• INTERNET, if your application wishes to access the Internet through any means from your own process, using anything from raw Java sockets through the WebView widget
• READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE, for working with files directly on external storage
• ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION, for determining where the device is, such as via GPS
• READ_CONTACTS, to get at personally-identifying information of arbitrary contacts that the user has in their Contacts app
• BLUETOOTH and BLUETOOTH_ADMIN, for communicating with other devices over Bluetooth
• CAMERA, for taking pictures directly using the camera APIs or wrapper libraries like the CameraX library
• RECEIVE_BOOT_COMPLETED, to get control when the device reboots

In this book and in casual conversation, we refer to the permissions using the unique portion of their name (e.g., INTERNET). Really, the full name of a framework permission will usually have android.permission. as a prefix (e.g., android.permission.INTERNET), for Android-defined permissions. Custom permissions from third-party apps should use a different prefix. You will need the full permission name, including the prefix, in your manifest entries.

What Are “Normal” and “Dangerous” Permissions?

In modern versions of Android, a normal permission is one that we have to request via the manifest, but the user does not need to approve explicitly. Just by installing the app, they implicitly grant us the permission. They can find out about these permissions (e.g., via the Play Store listing), but they cannot deny them, other than by uninstalling the app. Generally, normal permissions are ones that have limited user impact (e.g., RECEIVE_BOOT_COMPLETED, which only affects behavior on a reboot). The biggest exception to that rule is the INTERNET permission, which is a normal permission because a lot of apps want to be able to access the Internet.

By contrast, a dangerous permission is one that the user must approve explicitly. On Android 5.1 and older devices, this occurs at install time, either on the device or in the Play Store (for apps distributed through that channel). On Android 6.0+ devices, not only must our app have a <uses-permission> element in the manifest, but we also need to call methods to request that permission at runtime, at the point when we first need the permission. Mostly, dangerous permissions are ones that have privacy or security ramifications.

How Do I Request a Permission?

Put a <uses-permission> element in your manifest, as a direct child of the root <manifest> element (i.e., as a peer element of <application>), with an android:name attribute identifying the permission that you are interested in.

For example, here is a sample manifest, with a request to hold the WRITE_EXTERNAL_STORAGE permission:

<?xml version="1.0" encoding="utf-8"?>
<manifest package="com.commonsware.jetpack.contenteditor"
  xmlns:android="http://schemas.android.com/apk/res/android">

  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

  <application
    android:allowBackup="true"
    android:requestLegacyExternalStorage="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:theme="@style/AppTheme">
    <activity android:name=".MainActivity">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />

        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
    </activity>
  </application>

</manifest>

For normal permissions, this is all that you need. For dangerous permissions — such as WRITE_EXTERNAL_STORAGE — there is more work to be done, as we will explore later in this chapter.

Note that you are welcome to have zero, one, or several such <uses-permission> elements. Also note that some libraries that you elect to use might add their own <uses-permission> elements to your manifest. If you look at the “Merged Manifest” sub-tab of the manifest editor, you will see all of the <uses-permission> elements that will be included in your app and where they come from.