# 在 Android 应用中使用 Pushwoosh 位置模块

<Aside type="caution">
请注意，基于地理位置的消息功能不适用于 HMS (Huawei Mobile Services) 设备，因为它基于 Google 位置服务构建。
</Aside>

Android 中有两种位置访问类别：

*   **前台**位置访问
*   **后台**位置访问

要在**前台**更新用户位置，应满足以下条件之一：

*   应用的某个活动处于活动状态
*   为应用启动了 foregroundServiceType = “location” 的前台服务

**后台**访问允许应用在不活动时获取用户地理位置，且未为该应用启动“location”类型的前台服务。

## 前台位置访问

如果您打算仅在应用处于活动状态时使用 Pushwoosh 位置模块更新用户位置，请将 `pushwoosh-location` 模块添加到您的 **app/build.gradle** 中：

```java title="build.gradle"
implementation 'com.pushwoosh:pushwoosh-location:6.+'
```

<Aside>
在 Pushwoosh Github 仓库中获取最新模块版本：[https://github.com/Pushwoosh/pushwoosh-android-sdk/releases](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases)
</Aside>

要启动该模块，请使用 `startLocationTracking` 方法：

<Tabs>
<TabItem label="Java">
```java
PushwooshLocation.startLocationTracking();
```
</TabItem>

<TabItem label="Kotlin">
```kotlin
PushwooshLocation.startLocationTracking()
```
</TabItem>
</Tabs>

<Aside type="note">
`pushwoosh-location` 模块将向用户请求所有必要的权限 (ACCESS\_COARSE\_LOCATION, ACCESS\_FINE\_LOCATION)。
</Aside>

## 在应用处于后台时使用 ForegroundService 发出位置请求

<Aside type="caution" title="已弃用">

由于 Android 12 更新，ForegroundService 无法正常运行，因此它已被弃用，并将从 Pushwoosh SDK 中移除。

以下是一些在后台跟踪用户位置的变通方法：

1.  使用 targetSdkVersion 30 而不是 31。请记住，在这种情况下，Android 12 中存在的功能将不可用。
2.  要求您的用户禁用应用的电池优化功能，以允许 ForegroundService 在后台启动。
</Aside>

要在调用 `startLocationTracking` 方法时启动 **ForegroundService**（这允许在应用处于后台时获取用户地理位置），请按照[上一段](#foreground-location-access)中描述的步骤操作，然后将以下元数据添加到您的 **AndroidManifest.xml** 中：

```txt
...
<application>
....
    <meta-data
        android:name="com.pushwoosh.start_foreground_service"
        android:value="true" />
...
</application>
...
```

当 **ForegroundService** 启动时，会创建一个通知。您可以通过在项目的 **AndroidManifest.xml** 中指定附加元数据来自定义通知：

```txt
...
<application>
....
    <meta-data
        android:name="com.pushwoosh.foreground_service_notification_text"
        android:value="My notification text" />
    <meta-data
        android:name="com.pushwoosh.foreground_service_notification_channel_name"
        android:value="My notification channel name" />
...
</application>
...
```

## 后台位置访问

要在没有 ForegroundService 启动的情况下在后台更新地理位置，您需要满足以下条件：

*   获得 Google Play 对您的应用在后台访问位置的批准（详情请参阅 [https://support.google.com/googleplay/android-developer/answer/9799150?hl=en](https://support.google.com/googleplay/android-developer/answer/9799150?hl=en)）
*   将权限添加到您的 AndroidManifest.xml 中：

```txt
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
```

*   在前台位置权限获得后，请求用户在后台更新位置的权限（请在 Android 开发者文档中查找指南：[https://developer.android.com/training/location/permissions#background-dialog-target-android-11](https://developer.android.com/training/location/permissions#background-dialog-target-android-11)）

在 6.3.2 版本的 `pushwoosh-location` 模块中，我们包含了一个额外的方法，如果满足以下条件，该方法将打开位置权限设置屏幕：

*   应用已获得前台位置权限；
*   应用的 AndroidManifest.xml 中存在 `ACCESS_BACKGROUND_LOCATION` 用户权限。

<Aside type="caution">
请务必向用户清楚解释您的应用为何以及出于何种目的需要访问其后台位置。详情请参阅 [Android 开发者指南](https://developer.android.com/training/location/permissions#background-dialog-target-android-11)。
</Aside>

按如下方式调用该方法：

<Tabs>
<TabItem label="Java">
```java
PushwooshLocation.requestBackgroundLocationPermission();
```
</TabItem>

<TabItem label="Kotlin">
```
PushwooshLocation.requestBackgroundLocationPermission()
```
</TabItem>
</Tabs>

## Android 12+ 权限类型

[从 Android 12 开始](https://developer.android.com/about/versions/12/approximate-location)，当被要求授予前台位置访问权限时，用户可以选择应用获取用户位置的频率和精度。

有两种类型的权限：

1.  大致位置，等同于 ACCESS\_COARSE\_LOCATION
2.  精确位置，等同于 ACCESS\_FINE\_LOCATION 和 ACCESS\_COARSE\_LOCATION

<Aside type="caution">
请注意，来自仅具有 Manifest.permission.ACCESS\_COARSE\_LOCATION 而没有 Manifest.permission.ACCESS\_FINE\_LOCATION 权限的应用的位置请求将自动限制为较慢的间隔，并且位置对象将被混淆，仅显示粗略的精度级别。详情请参阅 [https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest](https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest)。
</Aside>

<Aside type="note">
请记住，精度级别取决于您请求的权限：

*   ACCESS\_COARSE\_LOCATION – 提供设备位置的估计值，精度约为 1 英里（1.6 公里）。
*   ACCESS\_FINE\_LOCATION – 提供设备位置的尽可能精确的估计值，通常在约 160 英尺（50 米）以内，有时甚至精确到 10 英尺（几米）或更小。

来源：[https://developer.android.com/training/location/permissions](https://developer.android.com/training/location/permissions)
</Aside>

## 与我们分享您的反馈

您的反馈有助于我们创造更好的体验，因此如果您在 SDK 集成过程中遇到任何问题，我们很乐意听取您的意见。如果您遇到任何困难，请随时[通过此表单](https://docs.google.com/forms/d/e/1FAIpQLSd\_0b8jwn-V\_JmoPLIxIFYbHACCQhrzidOZV3ELywoQPXRSxw/viewform)与我们分享您的想法。