# Использование модуля определения местоположения Pushwoosh в приложениях Android

<Aside type="caution">
Обратите внимание, что гео-сообщения недоступны для устройств HMS (Huawei Mobile Services), поскольку они основаны на сервисах определения местоположения Google.
</Aside>

В Android существуют две категории доступа к местоположению:

*   **Доступ к местоположению в активном режиме (Foreground)**
*   **Доступ к местоположению в фоновом режиме (Background)**

Для обновления местоположения пользователя в **активном режиме (foreground)** должно быть выполнено одно из следующих условий:

*   Одна из активностей приложения активна
*   Запущен Foreground service с `foregroundServiceType = “location”` для приложения

**Доступ в фоновом режиме (background)** позволяет приложению получать геолокацию пользователя, когда приложение неактивно и для него не запущены Foreground services типа “location”.

## Доступ к местоположению в активном режиме (Foreground)

Если вы собираетесь использовать модуль определения местоположения 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>

Чтобы запустить **ForegroundService** при вызове метода `startLocationTracking`, что позволяет получать геолокацию пользователя, когда ваше приложение работает в фоновом режиме, выполните шаги, описанные в [предыдущем параграфе](#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="Мой текст уведомления" />
    <meta-data
        android:name="com.pushwoosh.foreground_service_notification_channel_name"
        android:value="Мое название канала уведомлений" />
...
</application>
...
```

## Доступ к местоположению в фоновом режиме (Background)

Для обновления геолокации в фоновом режиме без запуска 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))

В версии модуля `pushwoosh-location` 6.3.2 мы включили дополнительный метод, который открывает экран настроек разрешений местоположения, если выполняются следующие условия:

*   Для приложения предоставлено разрешение на местоположение в активном режиме;
*   Разрешение пользователя `ACCESS_BACKGROUND_LOCATION` присутствует в AndroidManifest.xml приложения.

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