To protect user privacy, apps that use location services must request location permissions.
When you request location permissions, follow the same best practices as you would for any other runtime permission. One important difference when it comes to location permissions is that the system includes multiple permissions related to location. Which permissions you request, and how you request them, depend on the location requirements for your app's use case.
This page describes the different types of location requirements and provides guidance on how to request location permissions in each case.
Types of location access
Android's location permissions deal with the following categories of location access:
This section describes the situations when your app uses each category.
Foreground location
If your app contains a feature that shares or receives location information only once, or for a defined amount of time, then that feature requires foreground location access. Some examples include the following:
- Within a navigation app, a feature allows users to get turn-by-turn directions.
- Within a messaging app, a feature allows users to share their current location with another user.
The system considers your app to be using foreground location if a feature of your app accesses the device's current location in one of the following situations:
- An activity that belongs to your app is visible.
Your app is running a foreground service. When a foreground service is running, the system raises user awareness by showing a persistent notification. Your app retains access when it's placed in the background, such as when the user presses the Home button on their device or turns their device's display off.
Additionally, it's recommended that you declare a foreground service type of
location, as shown in the following code snippet. On Android 10 (API level 29) and higher, you must declare this foreground service type.<!-- Recommended for Android 9 (API level 28) and lower. --> <!-- Required for Android 10 (API level 29) and higher. --> <service android:name="MyNavigationService" android:foregroundServiceType="location" ... > <!-- Any inner elements would go here. --> </service>
You declare a need for foreground location when your app requests either the
ACCESS_COARSE_LOCATION
permission or the
ACCESS_FINE_LOCATION
permission, as shown in the following snippet:
<manifest ... > <!-- To request foreground location access, declare one of these permissions. --> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> </manifest>
The level of precision depends on which permission you request:
ACCESS_COARSE_LOCATION- Provides location accuracy to within a city block.
ACCESS_FINE_LOCATION- Provides a more accurate location than one provided when you request
ACCESS_COARSE_LOCATION. This permission is necessary for some connectivity tasks, such as connecting to nearby devices over Bluetooth Low Energy (BLE).
Background location
An app requires background location access if a feature within the app constantly shares location with other users or uses the Geofencing API. Several examples include the following:
- Within a family location sharing app, a feature allows users to continuously share location with family members.
- Within an IoT app, a feature allows users to configure their home devices such that they turn off when the user leaves their home and turn back on when the user returns home.
The system considers your app to be using background location if it accesses the device's current location in any situation other than the ones described in the foreground location section.
On Android 10 (API level 29) and higher, you must declare the
ACCESS_BACKGROUND_LOCATION
permission in your app's manifest in order to request background location
access at runtime. On earlier versions of
Android, when your app receives foreground location access, it automatically
receives background location access as well.
<manifest ... >
<!-- Required only when requesting background location access on
Android 10 (API level 29) and higher. -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>
Request location access at runtime
When a feature in your app needs location access, wait until the user interacts with the feature before making the permission request. This workflow follows the best practice of asking for runtime permissions in context, as described in the guide that explains how to request app permissions.
Figure 1 shows an example of how to perform this process. The app contains a "share location" feature that requires foreground location access. The app doesn't request the location permission, however, until the user selects the Share location button.
Even if several features in your app require location access, it's likely that only some of them require background location access. Therefore, it's recommended that your app performs incremental requests for location permissions, asking for foreground location access and then background location access. By performing incremental requests, you give users more control and transparency because they can better understand which features in your app need background location access.
Figure 2 shows an example of an app that's designed to handle incremental requests. Both the "show current location" and "recommend nearby places" features require foreground location access. Only the "recommend nearby places" feature, however, requires background location access.
The process for performing incremental requests is as follows:
-
At first, your app should guide users to the features that require foreground location access, such as the "share location" feature in Figure 1 or the "show current location" feature in Figure 2.
It's recommended that you disable user access to features that require background location access until your app has foreground location access.
-
At a later time, when the user explores functionality that requires background location access, you can request background location access.
Request background location
When a feature in your app requests background location on a device that runs Android 10 (API level 29), the system permissions dialog includes an option named Allow all the time. If the user selects this option, the feature in your app gains background location access.
On Android 11 (API level 30) and higher, however, the system dialog doesn't include the Allow all the time option. Instead, users must enable background location on a settings page, as shown in figure 3.
You can help users navigate to this settings page by following best practices when requesting the background location permission. The process for granting the permission depends on your app's target SDK version.
App targets Android 11 or higher
If your app hasn't been granted the ACCESS_BACKGROUND_LOCATION permission, and
shouldShowRequestPermissionRationale()
returns true, show an educational UI to users that includes the following:
- A clear explanation of why your app's feature needs access to background location.
- The user-visible label of the settings option that grants background location
(for example, Allow all the time in figure 3). You can call
getBackgroundPermissionOptionLabel()to get this label. The return value of this method is localized to the user's device language preference. - An option for users to decline the permission. If users decline background location access, they should be able to continue using your app.
App targets Android 10 or lower
When a feature in your app requests background location access, users see a system dialog. This dialog includes an option to navigate to your app's location permission options on a settings page.
As long as your app already follows best practices for requesting location permissions, you don't need to make any changes to support this behavior.
Reminder of background location grant
On Android 10 and higher, when a feature in your app accesses device location in the background for the first time after the user grants background location access, the system schedules a notification to send to the user. This notification reminds the user that they've allowed your app to access device location all the time. An example notification appears in figure 4.
Additional resources
For more information about location permissions in Android, view the following materials: