SettingsClient

  • SettingsClient is the main entry point for interacting with location settings-enabler APIs, making it easy for an app to ensure device system settings are configured for its location needs.

  • This API helps determine if relevant system settings are enabled for location requests and can optionally invoke a dialog for users to enable necessary settings.

  • To use the API, first create a LocationSettingsRequest.Builder with the required LocationRequests, and optionally set if BLE is needed.

  • Check current location settings using checkLocationSettings(), and handle the result in the Task's onCompleteListener, potentially showing a resolution dialog if needed.

  • The isGoogleLocationAccuracyEnabled() method returns true if the Google Location Accuracy setting is currently enabled, which is required for network-based locations on most devices.
public interface SettingsClient implements HasApiKey<Api.ApiOptions.NoOptions>

The main entry point for interacting with the location settings-enabler APIs.

This API makes it easy for an app to ensure that the device's system settings are properly configured for the app's location needs.

When making a request to location services, the device's system settings may be in a state that prevents an app from obtaining the location data that it needs. For example, GPS or Wi-Fi scanning may be switched off. This intent makes it easy to:

  • Determine if the relevant system settings are enabled on the device to carry out the desired location request.
  • Optionally, invoke a dialog that allows the user to enable the necessary location settings with a single tap.

To use this API, first create a LocationSettingsRequest.Builder and add all of the LocationRequests that the app will be using:

 LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder()
     .addLocationRequest(mLocationRequestHighAccuracy)
     .addLocationRequest(mLocationRequestBalancedPowerAccuracy);

If the client is using BLE scans to derive location, it can request that BLE be enabled by calling LocationSettingsRequest.Builder.setNeedBle(boolean):

 builder.setNeedBle(true);

Then check whether current location settings are satisfied:

 Task<LocationSettingsResponse> result =
         LocationServices.getSettingsClient(this).checkLocationSettings(builder.build());

When the Task completes, the client can check the location settings by looking at the status code from the LocationSettingsResponse object. The client can also retrieve the current state of the relevant location settings by calling LocationSettingsResponse.getLocationSettingsStates():

 task.addOnCompleteListener(new OnCompleteListener<LocationSettingsResponse>() {
     @Override
     public void onComplete(Task<LocationSettingsResponse> task) {
         try {
             LocationSettingsResponse response = task.getResult(ApiException.class);
             // All location settings are satisfied. The client can initialize location
             // requests here.
             ...
         } catch (ApiException exception) {
             switch (exception.getStatusCode()) {
                 case LocationSettingsStatusCodes.RESOLUTION_REQUIRED:
                     // Location settings are not satisfied. But could be fixed by showing the
                     // user a dialog.
                     try {
                         // Cast to a resolvable exception.
                         ResolvableApiException resolvable = (ResolvableApiException) exception;
                         // Show the dialog by calling startResolutionForResult(),
                         // and check the result in onActivityResult().
                         resolvable.startResolutionForResult(
                             OuterClass.this,
                             REQUEST_CHECK_SETTINGS);
                     } catch (SendIntentException e) {
                         // Ignore the error.
                     } catch (ClassCastException e) {
                         // Ignore, should be an impossible error.
                     }
                     break;
                 case LocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
                     // Location settings are not satisfied. However, we have no way to fix the
                     // settings so we won't show the dialog.
                     ...
                     break;
              }
         }
     }
 });

If the status code is CommonStatusCodes.RESOLUTION_REQUIRED, the client can call ResolvableApiException.startResolutionForResult(Activity, int) to bring up a dialog, asking for the user's permission to modify the location settings to satisfy those requests. The result of the dialog will be returned via Activity.onActivityResult(int, int, Intent). If the client is interested in which location providers are available, it can retrieve a LocationSettingsStates from the Intent by calling LocationSettingsStates.fromIntent(Intent):

 @Override
 protected void onActivityResult(int requestCode, int resultCode, Intent data) {
     final LocationSettingsStates states = LocationSettingsStates.fromIntent(intent);
     switch (requestCode) {
         case REQUEST_CHECK_SETTINGS:
             switch (resultCode) {
                 case Activity.RESULT_OK:
                     // All required changes were successfully made
                     ...
                     break;
                 case Activity.RESULT_CANCELED:
                     // The user was asked to change settings, but chose not to
                     ...
                     break;
                 default:
                     break;
             }
             break;
     }
 }

Public Method Summary

abstract Task<LocationSettingsResponse>
checkLocationSettings(LocationSettingsRequest locationSettingsRequest)
Checks if the relevant system settings are enabled on the device to carry out the desired location requests.
abstract Task<Boolean>
isGoogleLocationAccuracyEnabled()
Returns true if the Google Location Accuracy setting is currently enabled.

Public Methods

public abstract Task<LocationSettingsResponse> checkLocationSettings (LocationSettingsRequest locationSettingsRequest)

Checks if the relevant system settings are enabled on the device to carry out the desired location requests.

Parameters
locationSettingsRequest an object that contains all the location requirements that the client is interested in.

public abstract Task<Boolean> isGoogleLocationAccuracyEnabled ()

Returns true if the Google Location Accuracy setting is currently enabled. This setting is required for Fused Location Provider APIs to be able to generate network (wifi, cell, etc) based locations. If Google Play services is chosen as the platform LocationManager.NETWORK_PROVIDER (this is the case on all GMS compliant devices, which constitute the vast majority of the Android ecosystem), then this setting is also required for the platform LocationManager.NETWORK_PROVIDER to be enabled.

On Android P and above devices, the Google Location Accuracy setting may be found under location settings. Below Android P, Google Location Accuracy is tied to the device location mode - it will be enabled if the device is in Settings.Secure.LOCATION_MODE_BATTERY_SAVING or Settings.Secure.LOCATION_MODE_HIGH_ACCURACY, and disabled in Settings.Secure.LOCATION_MODE_SENSORS_ONLY.