请求位置信息权限

为了保护用户隐私,使用位置信息服务的应用必须请求位置信息权限。

请求位置权限时,请遵循与请求任何其他运行时权限相同的最佳实践。请求位置权限时的一个重要区别在于,系统中包含与位置相关的多项权限。具体请求哪项权限以及请求相关权限的方式取决于应用用例的位置信息要求。

本页介绍了不同类型的位置信息要求,并就如何在每种情况下请求位置权限提供了指导。

位置信息访问权限的类型

每项权限都具有以下特征组合:

前台位置信息

如果应用的某项功能仅分享或接收一次位置信息,或者只在特定的一段时间内分享或接收位置信息,则该功能需要前台位置信息访问权限。以下是此类情况的一些示例:

  • 在导航应用中,某项功能可让用户查询精细导航路线。
  • 在即时通讯应用中,某项功能可让用户与其他用户分享自己目前所在的位置。

如果应用的功能在下列某种情况下访问设备当前的位置信息,系统就会认为应用需要使用前台位置信息:

  • 属于应用的某个 activity 可见。
  • 应用的某个前台服务正在运行中。当有前台服务在运行时,系统会显示一条常驻通知来提醒用户注意。当应用被置于后台时(例如当用户按设备上的主屏幕按钮或关闭设备的显示屏时),其位置信息访问权限会得到保留。

    此外,建议您声明 location前台服务类型,如以下代码段所示。在 Android 10(API 级别 29)及更高版本中,您必须声明此前台服务类型。

    <!-- 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>

当应用请求 ACCESS_COARSE_LOCATION 权限或 ACCESS_FINE_LOCATION 权限时(如以下代码段所示),就是在声明需要获取前台位置信息:

<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>

后台位置信息

如果应用中的某项功能会不断与其他用户分享位置信息或使用 Geofencing API,则该应用需要后台位置信息访问权限。以下是此类情况的几个示例:

  • 在家庭位置信息分享应用中,某项功能可让用户与家庭成员持续分享位置信息。
  • 在 IoT 应用中,某项功能可让用户配置自己的家居设备,使其在用户离家时关机并在用户回家时重新开机。

除了前台位置信息部分所述的情况之外,如果应用在任何其他情况下访问设备的当前位置信息,系统就会认为应用需要使用后台位置信息。后台位置信息精确度与前台位置信息精确度相同,具体取决于应用声明的位置信息权限。

在 Android 10(API 级别 29)及更高版本中,您必须在应用的清单中声明 ACCESS_BACKGROUND_LOCATION 权限,以便请求在运行时于后台访问位置信息。在较低版本的 Android 系统中,当应用获得前台位置信息访问权限时,也会自动获得后台位置信息访问权限。

<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>

准确度

Android 支持以下级别的位置信息精确度:

大致位置
提供设备位置的估算值。如果此位置估算值来自 LocationManagerServiceFusedLocationProvider,则该估算值会精确到 3 平方公里(约 1.2 平方英里)以内。如果您声明了 ACCESS_COARSE_LOCATION 权限,但未声明 ACCESS_FINE_LOCATION 权限,您的应用就可以收到该精确度级别的位置信息。
确切位置
提供尽可能准确的设备位置估算值。如果位置估算值来自 LocationManagerServiceFusedLocationProvider,则此估算值通常可以精确到 50 米(160 英尺)以内,有时甚至可以精确到几米(10 英尺)以内。如果您声明了 ACCESS_FINE_LOCATION 权限,您的应用就可以收到该精确度级别的位置信息。

如果用户授予大致位置信息权限,您的应用只能获取大致位置信息(无论它声明了哪些位置信息权限)。

当用户仅授予大致位置信息使用权时,您的应用应该仍会正常工作。如果应用中的某项功能确实需要使用 ACCESS_FINE_LOCATION 权限访问确切位置信息,您可以请求用户允许该应用获取确切位置信息

在运行时请求位置信息访问权限

当应用中的功能需要位置信息访问权限时,请等到用户与该功能互动时再发出权限请求。本工作流遵循在上下文中请求运行时权限的最佳做法,如介绍如何请求应用权限的指南中所述。

图 1 举例说明了如何执行此过程。该应用包含一项“分享位置信息”功能,需要前台位置信息访问权限。不过,在用户选择分享位置信息按钮之前,应用不会请求位置权限。

在用户选择“分享位置信息”按钮后,系统显示位置权限对话框
图 1. 需要前台位置信息访问权限的位置信息分享功能。如果用户选择仅在使用该应用时允许,系统就会启用该功能。

用户只能授予大致位置信息使用权

在 Android 12(API 级别 31)或更高版本中,用户仍可以请求该应用只检索大致位置信息,即使该应用请求 ACCESS_FINE_LOCATION 运行时权限也是如此。

要处理这种可能会出现的用户行为,请勿单独请求 ACCESS_FINE_LOCATION 权限,而应在单个运行时请求中同时请求 ACCESS_FINE_LOCATION 权限和 ACCESS_COARSE_LOCATION 权限。如果您尝试仅请求 ACCESS_FINE_LOCATION,系统会在某些 Android 12 版本上忽略该请求。如果您的应用以 Android 12 或更高版本为目标平台,系统会在 Logcat 中记录以下错误消息:

ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.

当您的应用同时请求 ACCESS_FINE_LOCATIONACCESS_COARSE_LOCATION 时,系统权限对话框将为用户提供以下选项:

  • 确切位置:允许您的应用获取确切位置信息。
  • 大致位置:允许您的应用仅获取大致位置信息。

图 3 显示该对话框包含两个可帮助用户进行选择的视觉提示选项。用户确定位置信息精确度后,他们可以点按三个按钮中的一个来选择权限授予的时长。

在 Android 12 和更高版本中,用户可以前往系统设置,以设置任何应用的首选位置信息精确度,而不管该应用的目标 SDK 版本是什么。即使您的应用安装在搭载 Android 11 或更低版本的设备上,用户随后又将该设备升级到 Android 12 或更高版本,也是如此。

该对话框仅涉及大致位置,并且包含三个按钮,它们上下分布
图 2. 当您的应用仅请求 ACCESS_COARSE_LOCATION 时显示的系统权限对话框。
该对话框包含两组选项,它们上下分布
图 3. 当您的应用在单个运行时请求中同时请求 ACCESS_FINE_LOCATIONACCESS_COARSE_LOCATION 时显示的系统权限对话框。

用户的选择会影响权限授予

下表显示了系统根据用户在运行时权限对话框中选择的选项向您的应用授予的权限:

确切位置 大致位置
仅在使用该应用时允许 ACCESS_FINE_LOCATION
ACCESS_COARSE_LOCATION
ACCESS_COARSE_LOCATION
仅限这一次 ACCESS_FINE_LOCATION
ACCESS_COARSE_LOCATION
ACCESS_COARSE_LOCATION
拒绝 无位置权限 无位置权限

如需确定系统已向您的应用授予的权限,请查看权限请求的返回值。您可以在类似于下面的代码中使用 Jetpack 库,也可以使用平台库,在这种情况下,您自行管理权限请求代码

Kotlin

val locationPermissionRequest = registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { permissions ->
        when {
            permissions.getOrDefault(Manifest.permission.ACCESS_FINE_LOCATION, false) -> {
                // Precise location access granted.
            }
            permissions.getOrDefault(Manifest.permission.ACCESS_COARSE_LOCATION, false) -> {
                // Only approximate location access granted.
            } else -> {
                // No location access granted.
            }
        }
    }

// ...

// Before you perform the actual permission request, check whether your app
// already has the permissions, and whether your app needs to show a permission
// rationale dialog. For more details, see Request permissions.
locationPermissionRequest.launch(arrayOf(
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION))

Java

ActivityResultLauncher<String[]> locationPermissionRequest =
    registerForActivityResult(new ActivityResultContracts
        .RequestMultiplePermissions(), result -> {
            Boolean fineLocationGranted = result.getOrDefault(
                    Manifest.permission.ACCESS_FINE_LOCATION, false);
            Boolean coarseLocationGranted = result.getOrDefault(
                    Manifest.permission.ACCESS_COARSE_LOCATION,false);
            if (fineLocationGranted != null && fineLocationGranted) {
                // Precise location access granted.
            } else if (coarseLocationGranted != null && coarseLocationGranted) {
                // Only approximate location access granted.
            } else {
                // No location access granted.
            }
        }
    );

// ...

// Before you perform the actual permission request, check whether your app
// already has the permissions, and whether your app needs to show a permission
// rationale dialog. For more details, see Request permissions.
locationPermissionRequest.launch(new String[] {
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION
});

请求升级到确切位置

您可以要求用户将应用的访问权限从大致位置升级到确切位置。但是,在让用户将应用的使用权升级到确切位置信息之前,请考虑应用的用例是否确实需要这一级别的精确度。如果您的应用需要通过蓝牙或 Wi-Fi 将某个设备与附近的设备配对,请考虑使用配套设备配对蓝牙权限,而不是请求 ACCESS_FINE_LOCATION 权限。

如需请求用户将应用的位置信息使用权从大致位置信息升级到确切位置信息,请执行以下操作:

  1. 如有必要,请说明您的应用为何需要获取权限
  2. 再次同时请求 ACCESS_FINE_LOCATIONACCESS_COARSE_LOCATION 权限。由于用户已允许系统向您的应用授予大致位置信息使用权,因此这次系统对话框有所不同,如图 4图 5 所示:
该对话框包含“更改为确切位置”“仅限这一次”和“拒绝”选项。
图 4. 用户之前选择了大致位置仅在使用该应用时允许(在图 3 的对话框中)。
该对话框包含“仅限这一次”和“拒绝”选项。
图 5. 用户之前选择了大致位置仅限这一次(在图 3 的对话框中)。

最初仅请求在前台访问位置信息

即使应用中有多项功能需要位置信息访问权限,可能其中也只有部分功能需要后台位置信息访问权限。因此,建议应用对位置权限执行递增请求,先请求前台位置信息访问权限,再请求后台位置信息访问权限。执行递增请求可以为用户提供更大的控制权和透明度,因为他们可以更好地了解应用中的哪些功能需要后台位置信息访问权限。

图 6 显示了旨在处理递增请求的应用示例。“显示当前位置”和“推荐附近的地点”这两项功能都需要前台位置信息访问权限。不过,只有“推荐附近的地点”功能需要后台位置信息访问权限。

启用前台位置信息访问权限的按钮与启用后台位置信息访问权限的按钮相距半个屏幕之远
图 6. 这两项功能都需要位置信息访问权限,但只有“推荐附近的地点”功能需要后台位置信息访问权限。

执行递增请求的过程如下所示:

  1. 首先,应用应该引导用户留意到需要前台位置信息访问权限的功能,例如图 1 中的“分享位置信息”功能或图 2 中的“显示当前位置”功能。

    在应用有权访问前台位置信息之前,建议您停止让用户访问需要后台位置信息访问权限的功能。

  2. 稍后,等到用户探索需要后台位置信息访问权限的功能时,您可以再请求在后台访问位置信息的权限。

根据需要请求在后台访问位置信息

图 7. 设置页面包含一个名为始终允许的选项,用于授予后台位置信息访问权限。

权限对话框内容取决于目标 SDK 版本

在搭载 Android 10(API 级别 29)的设备上,您的应用中的某项功能请求在后台访问位置信息时,系统权限对话框包含一个名为始终允许的选项。如果用户选择此选项,您的应用中的相应功能就会获得在后台访问位置信息的权限。

但是,在 Android 11(API 级别 30)及更高版本中,系统对话框不含始终允许选项。相反,用户必须在设置页面上启用后台位置信息,如图 7 所示。

请求在后台访问位置信息的权限时,您可以遵循最佳做法,帮助用户导航到此设置页面。授予权限的过程取决于应用的目标 SDK 版本。

以 Android 11 或更高版本为目标平台的应用

如果您的应用尚未获得 ACCESS_BACKGROUND_LOCATION 权限并且 shouldShowRequestPermissionRationale() 返回 true,请向用户显示包含以下内容的指导界面:

  • 明确说明应用功能需要在后台访问位置信息的原因。
  • 用于授予后台位置信息访问权限的设置选项的用户可见标签(例如,图 7 中的始终允许)。您可以调用 getBackgroundPermissionOptionLabel() 获取此标签。此方法的返回值会根据用户设备的语言偏好设置进行本地化。
  • 供用户拒绝授予权限的选项。如果用户拒绝应用在后台访问位置信息,他们应该能够继续使用应用。
用户可以通过点按系统通知来更改应用的位置信息设置
图 8. 提醒用户他们已授予应用后台位置信息使用权的通知。

以 Android 10 或更低版本为目标平台的应用

当应用中的某项功能请求后台位置信息访问权限时,用户会看到一个系统对话框。此对话框包含一个选项,可用于导航到设置页面上的应用位置权限选项。

只要您的应用已遵循有关请求位置信息权限的最佳实践,您无需做出任何更改即可支持此行为。

用户可能会影响后台位置信息的准确度

如果用户请求获取大致位置信息,用户在位置信息权限对话框中的选择也适用于后台位置信息。换言之,如果用户向您的应用授予 ACCESS_BACKGROUND_LOCATION 权限,但仅授予在前台访问大致位置信息的权限,那么您的应用在后台也只有大致位置信息的访问权限。

后台位置信息授权提醒

在 Android 10 及更高版本中,当应用中的功能在用户授予后台位置信息访问权限后首次在后台访问设备位置信息时,系统会安排向用户发送一条通知。此通知旨在提醒用户他们已允许应用始终有权访问设备位置信息。示例通知如图 8 所示。

检查应用的 SDK 依赖项中的位置信息要求

检查您的应用是否使用依赖于位置信息权限(尤其是 ACCESS_FINE_LOCATION 权限)的 SDK。请参阅 Medium 上关于了解 SDK 依赖项行为的这篇文章。

其他资源

如需详细了解 Android 中的位置权限,请查看以下资料:

Codelab

视频

示例