Request location permissions (original) (raw)

To protect user privacy, apps that use location services must request location permissions.

Multiple permissions are 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 explains how to request location permissions in each case.

To request location permissions, follow the best practices for allruntime permissions.

Types of location access

Each permission has a combination of the following characteristics:

• Category: Either foreground location or background location.
• Accuracy: Either precise location or approximate location.

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, you should declare a foreground service type oflocation, 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 theACCESS_COARSE_LOCATION permission or the ACCESS_FINE_LOCATIONpermission, as shown in the following snippet:

<manifest ... >
  <!-- Always include this permission -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

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 theforeground location section. The background location precision is the same as the foreground location precision, which depends on the location permissions that your app declares.

On Android 10 (API level 29) and higher, you must declare theACCESS_BACKGROUND_LOCATION permission in your app's manifest in order torequest 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>

Accuracy

Android supports the following levels of location accuracy:

Approximate

Provides a device location estimate. If this location estimate is from the LocationManagerService or FusedLocationProvider, this estimate is accurate to within about 3 square kilometers (about 1.2 square miles). Your app can receive locations at this level of accuracy when you declare the ACCESS_COARSE_LOCATION permission but not theACCESS_FINE_LOCATION permission.

Precise

Provides a device location estimate that is as accurate as possible. If the location estimate is from LocationManagerService orFusedLocationProvider, this estimate is usually within about 50 meters (160 feet) and is sometimes as accurate as within a few meters (10 feet) or better. Your app can receive locations at this level of accuracy when you declare the ACCESS_FINE_LOCATION permission.

If the user grants the approximate location permission, your app only has access to approximate location, regardless of which location permissions your app declares.

Your app should still work when the user grants only approximate location access. If a feature in your app absolutely requires access to precise location using the ACCESS_FINE_LOCATION permission, you can ask the user to allow your app to access precise location.

Reminder of background location grant

On Android 10 (API level 29) 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 8.

Check for location requirements in your app's SDK dependencies

Check whether your app uses any SDKs that depend on location permissions, especially the ACCESS_FINE_LOCATION permission. Read the Getting to know the behaviors of your SDK dependencies blog post on Medium for more.

Additional resources

For more information about location permissions in Android, view the following materials:

Codelabs

• Privacy best practices

Videos

• How to find possible background location usage

Samples

• Sample appto demonstrate the use of location permissions.