O segundo Visualização do Desenvolvedor do Android 11 já está disponível, teste e compartilhe seu feedback.

Alterar as configurações de localização

Se seu app precisar solicitar a localização ou receber atualizações de permissão, o dispositivo precisará ativar as configurações de sistema adequadas, como GPS ou busca por Wi-Fi. Em vez de ativar diretamente serviços como o GPS do dispositivo, seu app especifica o nível necessário de precisão/consumo de energia e o intervalo de atualização desejado, e o dispositivo faz automaticamente as alterações apropriadas nas configurações do sistema. Essas configurações são definidas pelo objeto de dados LocationRequest.

Esta lição mostra como usar o Cliente de configurações para verificar quais configurações estão ativadas e apresentar a caixa de diálogo "Configurações de localização" para que os usuários atualizem as configurações com um único toque.

Configurar Serviços de localização

Para usar os Serviços de localização oferecidos pelo Google Play Services e o provedor de Localização combinada, conecte seu app usando o Cliente de configurações, verifique as configurações de localização atuais e, se for preciso, solicite que o usuário que ative as configurações necessárias.

Os apps que usam Serviços de localização precisam solicitar permissão de localização. Para esta lição, a detecção de localização aproximada é suficiente. Solicite essa permissão com o elemento uses-permission no manifesto do seu aplicativo, como mostrado no exemplo a seguir:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.google.android.gms.location.sample.locationupdates" >

      <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    </manifest>
    

Se o dispositivo estiver executando o Android 6.0 ou versões posteriores e o SDK de destino do seu app for 23 ou posterior, o app precisará listar as permissões no manifesto e solicitar essas permissões no momento da execução. Para mais informações, consulte Solicitar permissões no momento da execução.

Se seu app for destinado ao Android 10 (API de nível 29) ou versões posteriores e precisar acessar a localização do dispositivo quando estiver operando em segundo plano, você também precisará declarar permissão ACCESS_BACKGROUND_LOCATION. Para saber mais, consulte a seção sobre como solicitar acesso à localização em segundo plano.

Configurar uma solicitação de localização

Para armazenar parâmetros para solicitações ao provedor de Localização combinada, crie uma LocationRequest. Os parâmetros determinam o nível de precisão para solicitações de localização. Para ver detalhes de todas as opções de solicitação de local disponíveis, consulte a referência de classe LocationRequest. Esta lição define o intervalo de atualização, o intervalo de atualização mais rápido e a prioridade, conforme descrito abaixo:

Intervalo de atualização
setInterval(): esse método define a velocidade em milissegundos em que seu app prefere receber atualizações de localização. Observe que as atualizações de localização podem ser um pouco mais rápidas ou mais lentas que essa taxa para otimizar o uso da bateria, ou pode não haver atualizações (se o dispositivo não tiver conectividade, por exemplo).
Intervalo de atualização mais rápido
setFastestInterval(): esse método define a velocidade mais rápida em milissegundos em que seu app pode gerenciar atualizações de localização. A menos que seu app se beneficie do recebimento de atualizações mais rapidamente do que a velocidade especificada em setInterval(), não é necessário chamar esse método.
Prioridade

setPriority(): esse método define a prioridade da solicitação, o que dá uma dica boa aos Serviços de localização do Google Play Services sobre as fontes de localização a serem usadas. Os valores a seguir são compatíveis:

  • PRIORITY_BALANCED_POWER_ACCURACY: use essa configuração para solicitar que a precisão da localização seja de um quarteirão, que é de aproximadamente 100 metros. Isso é considerado um nível aproximado de precisão e provavelmente consumirá menos energia. Com essa configuração, é provável que os Serviços de localização usem Wi-Fi e posicionamento da torre de celular. Observe, no entanto, que a escolha do provedor de localização depende de muitos outros fatores, como as fontes disponíveis.
  • PRIORITY_HIGH_ACCURACY: use essa configuração para solicitar a localização mais precisa possível. Com essa configuração, é provável que os Serviços de localização usem GPS para determinar a localização.
  • PRIORITY_LOW_POWER: use essa configuração para solicitar que a precisão da localização seja de nível de cidade, que é de aproximadamente 10 quilômetros. Isso é considerado um nível aproximado de precisão e provavelmente consumirá menos energia.
  • PRIORITY_NO_POWER: use essa configuração se precisar de um impacto insignificante no consumo de energia, mas quiser receber atualizações de localização quando elas estiverem disponíveis. Com essa configuração, seu app não aciona nenhuma atualização de local, mas recebe os locais acionados por outros apps.

Crie a solicitação de localização e defina os parâmetros conforme mostrado nesta amostra de código:

Kotlin

    fun createLocationRequest() {
        val locationRequest = LocationRequest.create()?.apply {
            interval = 10000
            fastestInterval = 5000
            priority = LocationRequest.PRIORITY_HIGH_ACCURACY
        }
    }
    

Java

    protected void createLocationRequest() {
        LocationRequest locationRequest = LocationRequest.create();
        locationRequest.setInterval(10000);
        locationRequest.setFastestInterval(5000);
        locationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
    }
    

A prioridade de PRIORITY_HIGH_ACCURACY, combinada com a configuração de permissão ACCESS_FINE_LOCATION definida no manifesto do aplicativo e um intervalo de atualização rápido de 5.000 milissegundos (5 segundos), faz com que o provedor de Localização combinada retorne atualizações de local com precisão de poucos metros. Essa abordagem é apropriada para apps de mapeamento que exibem o local em tempo real.

Dica de desempenho: se seu app acessa a rede ou realiza outro trabalho de longa duração após receber uma atualização de local, ajuste o intervalo mais rápido para um valor mais lento. Esse ajuste impede que seu app receba atualizações que não podem ser usadas. Quando o trabalho de longa duração for concluído, defina o intervalo mais rápido novamente com um valor rápido.

Receber as configurações de localização atuais

Depois de se conectar ao Google Play Services e à API dos Serviços de localização, você poderá ver as configurações de localização atuais do dispositivo de um usuário. Para fazer isso, crie um LocationSettingsRequest.Builder e adicione uma ou mais solicitações de local. O snippet de código a seguir mostra como adicionar a solicitação de local que foi criada na etapa anterior:

Kotlin

    val builder = LocationSettingsRequest.Builder()
            .addLocationRequest(locationRequest)
    

Java

    LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder()
         .addLocationRequest(locationRequest);
    

Em seguida, verifique se as configurações de localização atuais são satisfeitas:

Kotlin

    val builder = LocationSettingsRequest.Builder()

    // ...

    val client: SettingsClient = LocationServices.getSettingsClient(this)
    val task: Task<LocationSettingsResponse> = client.checkLocationSettings(builder.build())
    

Java

    LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder();

    // ...

    SettingsClient client = LocationServices.getSettingsClient(this);
    Task<LocationSettingsResponse> task = client.checkLocationSettings(builder.build());
    

Quando a Task for concluída, seu app poderá verificar as configurações de localização pelo código de status do objeto LocationSettingsResponse. Para saber ainda mais detalhes sobre o estado atual das configurações de localização relevantes, seu app pode chamar o método getLocationSettingsStates() do objeto LocationSettingsResponse.

Solicitar que o usuário altere as configurações de localização

Para determinar se as configurações de localização são adequadas para a solicitação de local, adicione um OnFailureListener ao objeto Task que valida as configurações de localização. Em seguida, verifique se o objeto Exception transmitido ao método onFailure() é uma instância da classe ResolvableApiException, o que indica que as configurações precisam ser alteradas. Depois, exiba uma caixa de diálogo que solicite ao usuário permissão para modificar as configurações de localização chamando startResolutionForResult().

O snippet de código a seguir mostra como determinar se as configurações de localização do usuário permitem que os Serviços de localização criem uma LocationRequest, além de mostrar como solicitar permissão ao usuário para alterar as configurações de localização, se necessário:

Kotlin

    task.addOnSuccessListener { locationSettingsResponse ->
        // All location settings are satisfied. The client can initialize
        // location requests here.
        // ...
    }

    task.addOnFailureListener { exception ->
        if (exception is ResolvableApiException){
            // Location settings are not satisfied, but this can be fixed
            // by showing the user a dialog.
            try {
                // Show the dialog by calling startResolutionForResult(),
                // and check the result in onActivityResult().
                exception.startResolutionForResult(this@MainActivity,
                        REQUEST_CHECK_SETTINGS)
            } catch (sendEx: IntentSender.SendIntentException) {
                // Ignore the error.
            }
        }
    }
    

Java

    task.addOnSuccessListener(this, new OnSuccessListener<LocationSettingsResponse>() {
        @Override
        public void onSuccess(LocationSettingsResponse locationSettingsResponse) {
            // All location settings are satisfied. The client can initialize
            // location requests here.
            // ...
        }
    });

    task.addOnFailureListener(this, new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            if (e instanceof ResolvableApiException) {
                // Location settings are not satisfied, but this can be fixed
                // by showing the user a dialog.
                try {
                    // Show the dialog by calling startResolutionForResult(),
                    // and check the result in onActivityResult().
                    ResolvableApiException resolvable = (ResolvableApiException) e;
                    resolvable.startResolutionForResult(MainActivity.this,
                            REQUEST_CHECK_SETTINGS);
                } catch (IntentSender.SendIntentException sendEx) {
                    // Ignore the error.
                }
            }
        }
    });
    

A próxima lição, Como receber atualizações de localização, mostra como receber atualizações de localização periodicamente.