# Usando o módulo de localização do Pushwoosh em aplicativos Android

<Aside type="caution">
Esteja ciente de que as mensagens baseadas em geolocalização não estão disponíveis para dispositivos HMS (Huawei Mobile Services), pois são baseadas nos serviços de localização do Google.
</Aside>

Existem duas categorias de acesso à localização no Android:

*   **Acesso à localização em primeiro plano**
*   **Acesso à localização em segundo plano**

Para atualizar a localização do usuário em **primeiro plano**, uma das seguintes condições deve ser atendida:

*   Uma das atividades do aplicativo está ativa
*   O serviço em primeiro plano do tipo foregroundServiceType = “location” é iniciado para o aplicativo

O acesso em **segundo plano** permite que o aplicativo obtenha a geolocalização do usuário enquanto o aplicativo está inativo e nenhum serviço em primeiro plano do tipo “location” é iniciado para esse aplicativo.

## Acesso à localização em primeiro plano

Se você for usar o módulo de localização do Pushwoosh para atualizar a localização do usuário apenas quando seu aplicativo estiver ativo, adicione o módulo `pushwoosh-location` ao seu **app/build.gradle**:

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

<Aside>
Obtenha a versão mais recente do módulo no repositório do Pushwoosh no Github: [https://github.com/Pushwoosh/pushwoosh-android-sdk/releases](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases)
</Aside>

Para iniciar o módulo, use o método `startLocationTracking`:

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

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

<Aside type="note">
O módulo `pushwoosh-location` solicitará todas as permissões necessárias do usuário (ACCESS\_COARSE\_LOCATION, ACCESS\_FINE\_LOCATION).
</Aside>

## Usando o ForegroundService para fazer solicitações de localização quando seu aplicativo está em segundo plano

<Aside type="caution" title="Obsoleto">

Devido às atualizações do Android 12, o ForegroundService não pode funcionar corretamente, por isso está obsoleto e será removido do SDK do Pushwoosh futuramente.

Aqui estão algumas soluções alternativas para rastrear a localização dos usuários em segundo plano:

1.  Use targetSdkVersion 30 em vez de 31. Lembre-se de que os recursos presentes no Android 12 não estarão disponíveis nesse caso.
2.  Peça aos seus usuários para desativar a otimização da bateria para o seu aplicativo para permitir que o ForegroundService inicie em segundo plano.
</Aside>

Para iniciar o **ForegroundService** quando o método `startLocationTracking` é chamado, o que permite obter a geolocalização do usuário quando seu aplicativo está em segundo plano, siga os passos descritos no [parágrafo anterior](#acesso-à-localização-em-primeiro-plano), depois adicione os seguintes metadados ao seu **AndroidManifest.xml**:

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

Quando o **ForegroundService** é iniciado, uma notificação é criada. Você pode personalizar a notificação especificando os metadados adicionais no **AndroidManifest.xml** do seu projeto:

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

## Acesso à localização em segundo plano

Para atualizar a geolocalização em segundo plano sem iniciar o ForegroundService, você precisará do seguinte:

*   Obter a aprovação do Google Play para o acesso do seu aplicativo à localização em segundo plano (consulte [https://support.google.com/googleplay/android-developer/answer/9799150?hl=en](https://support.google.com/googleplay/android-developer/answer/9799150?hl=en) para detalhes)
*   Adicionar a permissão ao seu AndroidManifest.xml:

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

*   Solicitar a permissão do usuário para atualizar a localização em segundo plano após a permissão de localização em primeiro plano ser recebida (encontre as diretrizes na documentação do desenvolvedor 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))

Na versão 6.3.2 do módulo `pushwoosh-location`, incluímos um método adicional que abre a tela de configurações de permissão de localização se as seguintes condições forem atendidas:

*   Há a permissão de localização em primeiro plano concedida para o aplicativo;
*   A permissão do usuário `ACCESS_BACKGROUND_LOCATION` está presente no AndroidManifest.xml do aplicativo.

<Aside type="caution">
Certifique-se de explicar claramente aos usuários por quais motivos e propósitos seu aplicativo precisa de acesso à localização deles em segundo plano. Consulte os [guias do desenvolvedor Android](https://developer.android.com/training/location/permissions#background-dialog-target-android-11) para obter detalhes.
</Aside>

Chame o método da seguinte forma:

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

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

## Tipos de permissão do Android 12+

[A partir do Android 12](https://developer.android.com/about/versions/12/approximate-location), ao ser solicitado a permissão de acesso à localização em primeiro plano, um usuário pode escolher com que frequência e com que precisão o aplicativo obterá a localização do usuário.

Existem dois tipos dessas permissões:

1.  Localização aproximada, que é igual a ACCESS\_COARSE\_LOCATION
2.  Localização precisa, que é igual a ACCESS\_FINE\_LOCATION e ACCESS\_COARSE\_LOCATION

<Aside type="caution">
Leve em consideração que as solicitações de localização de aplicativos com Manifest.permission.ACCESS\_COARSE\_LOCATION e não Manifest.permission.ACCESS\_FINE\_LOCATION serão automaticamente limitadas a um intervalo mais lento, e o objeto de localização será ofuscado para mostrar apenas um nível de precisão aproximado. Consulte[ https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest](https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest) para detalhes.
</Aside>

<Aside type="note">
Lembre-se de que o nível de precisão depende de qual permissão você solicita:

*   ACCESS\_COARSE\_LOCATION – Fornece uma estimativa da localização do dispositivo, com uma precisão de cerca de 1,6 km (1 milha).
*   ACCESS\_FINE\_LOCATION – Fornece uma estimativa da localização do dispositivo que é a mais precisa possível, geralmente dentro de cerca de 50 metros (160 pés) e às vezes tão precisa quanto dentro de alguns metros (10 pés) ou melhor.

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

## Compartilhe seu feedback conosco

Seu feedback nos ajuda a criar uma experiência melhor, então adoraríamos ouvir de você se tiver algum problema durante o processo de integração do SDK. Se você enfrentar alguma dificuldade, não hesite em compartilhar suas opiniões conosco [através deste formulário](https://docs.google.com/forms/d/e/1FAIpQLSd\_0b8jwn-V\_JmoPLIxIFYbHACCQhrzidOZV3ELywoQPXRSxw/viewform).