SettingsApi

  • This interface, SettingsApi, is deprecated and users should use the GoogleApi-based SettingsClient instead.

  • SettingsApi is the main entry point for interacting with location settings-enabler APIs, helping apps ensure device settings are configured for their location needs.

  • This API allows apps to determine if relevant system settings are enabled for desired location requests and optionally invoke a dialog for the user to enable necessary settings.

  • To use this API, you need to create and connect a GoogleApiClient, build a LocationSettingsRequest with desired location requests, and then check the location settings using checkLocationSettings.

  • The result of checking location settings provides a status code to determine if settings are satisfied, require a resolution dialog, or cannot be fixed.
public interface SettingsApi

This interface is deprecated.
Use GoogleApi-based API SettingsClient instead.

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 GoogleApiClient which supports at least LocationServices.API. Then connect the client to Google Play services:

 mGoogleApiClient = new GoogleApiClient.Builder(context)
     .addApi(LocationServices.API)
     .addConnectionCallbacks(this)
     .addOnConnectionFailedListener(this)
     .build()
 ...
 mGoogleApiClient.connect();

Then 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:

 PendingResult<LocationSettingsResult> result =
         LocationServices.SettingsApi.checkLocationSettings(mGoogleClient, builder.build());

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

 result.setResultCallback(new ResultCallback<LocationSettingsResult>() {
     @Override
     public void onResult(LocationSettingsResult result) {
         final Status status = result.getStatus();
         final LocationSettingsStates states = result.getLocationSettingsStates();
         switch (status.getStatusCode()) {
             case LocationSettingsStatusCodes.SUCCESS:
                 // All location settings are satisfied. The client can initialize location
                 // requests here.
                 ...
                 break;
             case LocationSettingsStatusCodes.RESOLUTION_REQUIRED:
                 // Location settings are not satisfied. But could be fixed by showing the user
                 // a dialog.
                 try {
                     // Show the dialog by calling startResolutionForResult(),
                     // and check the result in onActivityResult().
                     status.startResolutionForResult(
                         OuterClass.this,
                         // An arbitrary constant to disambiguate activity results.
                         REQUEST_CHECK_SETTINGS);
                 } catch (SendIntentException e) {
                     // Ignore the 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 Status.startResolutionForResult(Activity, int) to bring up a dialog, asking for 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(data);
     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
                     if (!state.isGpsUsable()) {
                         // Degrade gracefully depending on what is available
                         ...
                     }
                     break;
                 default:
                     break;
             }
             break;
     }
 }

Public Method Summary

abstract PendingResult<LocationSettingsResult>
checkLocationSettings(GoogleApiClient client, LocationSettingsRequest locationSettingsRequest)
Checks if the relevant system settings are enabled on the device to carry out the desired location requests.

Public Methods

public abstract PendingResult<LocationSettingsResult> checkLocationSettings (GoogleApiClient client, LocationSettingsRequest locationSettingsRequest)

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

Parameters
client an existing GoogleApiClient. It does not need to be connected at the time of this call, but the result will be delayed until the connection is complete.
locationSettingsRequest an object that contains all the location requirements that the client is interested in.
Returns
  • result containing the status of the request.