Common A3L Location APIs
This page describes common A3L Location APIs you can use in your app to support the primary functions of A3L Location described in Integrate A3L Location SDK.
- Check settings
- Get location availability
- Request continuous location updates
- Stop location updates
- Related resources
Check settings
To get the current state of the location settings, call the A3LLocationSettingsResponse.getLocationSettingsStates()
method.
To make sure the system settings of a user's device are in a state that allow location services to successfully perform location requests, use the checkLocationSettings()
API. If the API determines that the required settings aren't enabled on the device, you can choose to display a dialog to the user that guides them to enable the setting.
Before you can check the system settings, you must create an A3LLocationSettingsRequest.Builder
object that includes the A3LLocationRequest
objects that your app uses. The following code shows an example of creating an A3LLocationSettingsRequest.Builder
object with two location requests.
A3LLocationSettingsRequest.Builder builder = new A3LLocationSettingsRequest.Builder()
.addLocationRequest(mLocationRequestHighAccuracy)
.addLocationRequest(mLocationRequestBalancedPowerAccuracy);
If your app uses Bluetooth Low Energy (BLE) for location, build your A3LLocationSettingsRequest.Builder
object using the setNeedBle()
method, as shown in the following code.
builder.setNeedBle(true);
To check the system settings in your app, build the A3LLocationSettingsRequest
object and pass it to the checkLocationSettings()
method of the A3LSettingsClient
class, as shown in the following example.
Task<A3LLocationSettingsResponse> result =
A3LLocationServices.getSettingsClient(this).checkLocationSettings(builder.build());
Add an on complete listener to the Task
to handle the result. If the result throws an exception, your app can conditionally check the status codes to determine if the issue can be resolved. If the status code is RESOLUTION_REQUIRED
, you can show a dialog to the user to ask them to allow the required setting. To do this, call ResolvableApiException.startResolutionForResult()
, as shown in the following example.
result.addOnCompleteListener(new OnCompleteListener<A3LLocationSettingsResponse>() {
@Override
public void onComplete(Task<A3LLocationSettingsResponse> task) {
try {
A3LLocationSettingsResponse response = task.getResult(ApiException.class);
// System settings can allow location services.
...
} catch (ApiException exception) {
switch (exception.getStatusCode()) {
case A3LLocationSettingsStatusCodes.RESOLUTION_REQUIRED:
// System settings are not in a state to allow location services, but
// can be resolved.
try {
// Cast to a resolvable exception.
ResolvableApiException resolvable = (ResolvableApiException) exception;
// Show a dialog to the user to resolve - verify results in onActivityResult().
resolvable.startResolutionForResult(
OuterClass.this,
REQUEST_CHECK_SETTINGS);
} catch (SendIntentException e) {
// Ignore
} catch (ClassCastException e) {
// Ignore
}
break;
case A3LLocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
// System settings are not in a state to allow location services and
// can't be resolved.
...
break;
}
}
}
});
For more information on status codes, see the API documentation for A3LLocationSettingsStatusCodes
.
The following example shows how to verify the results of startResolutionForResult()
in the onActivityResult()
method.
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
switch (requestCode) {
case REQUEST_CHECK_SETTINGS:
switch (resultCode) {
case Activity.RESULT_OK:
// User changed required settings
...
break;
case Activity.RESULT_CANCELED:
// User did not change required settings
...
break;
default:
break;
}
break;
}
}
Get location availability
To determine if location data is available, use the getLocationAvailability()
method. A successful Task
result returns an A3LLocationAvailability
object. To get a Boolean that indicates the likelihood that location data can be retrieved, use the isLocationAvailable()
method. A true
response doesn't guarantee the location is available, but it indicates the location data is likely to be available. Similarly, a false
response doesn't confirm the location is unavailable, but it indicates the location data is likely to be unavailable. The following code shows an example of how to get location availability.
// getLocationAvailability
Task<A3LLocationAvailability> a3LLocationAvailability = a3LLocationProviderClient.getLocationAvailability();
a3LLocationAvailability.addOnCompleteListener(new OnCompleteListener<A3LLocationAvailability>() {
@Override
public void onComplete(@NonNull Task<A3LLocationAvailability> task) {
// Code to execute on completion
// ...
if(task.isSuccessful()) {
// Use isLocationAvailable() to check if location APIs can retrieve a location.
// The result does not guarantee that the APIs can fetch a location, but it's likely to get one.
Boolean locationAvailable = task.getResult().isLocationAvailable();
}
}
});
For Android devices without Google Play services, the getLocationAvailability()
method only verifies whether the location is enabled or disabled.
Request continuous location updates
The requestLocationUpdates()
method allows your app to repeatedly get location updates. If your app tracks users' locations over time, this API can handle that use case. The requestLocationUpdates()
method takes an A3LLocationRequest
, an A3LLocationListener
and a Looper
. The API delivers results to the listener on the looper provided. If your app makes a location update request and your app previously made a location update request using the same listener, the new request replaces the previous one. The following code shows an example of how to request location updates.
// Request location updates
A3LLocationListener a3lLocationListener = new A3LLocationListener() {
@Override
public void onLocationChanged(@NonNull Location location) {
// Custom code to be executed once location is received.
}
};
// The value of 1000L is an example. Use any value for A3LLocationRequest intervalMillis or use
// other builder constructors. For other options, see the Javadoc API reference.
A3LLocationRequest a3lLocationRequest = new A3LLocationRequest.Builder(1000L).build();
// A different looper can be provided. If looper is null, it uses the looper associated with the calling thread.
Task<Void> locationUpdates = a3LLocationProviderClient.requestLocationUpdates(a3lLocationRequest, a3lLocationListener, null);
Stop location updates
To stop location updates on a listener, use the removeLocationUpdates()
method, as shown in the following code. The removeLocationUpdates()
takes an A3lLocationListener
object.
// Remove location updates
Task<Void> removeLocationUpdatesTask = a3LLocationProviderClient.removeLocationUpdates(a3lLocationListener);
Related resources
Last updated: Sep 13, 2023