Developer Console
Sign In
Sign In
Developer Console

Integrate A3L Location SDK

Use this guide to integrate your app with the A3L Location SDK.

Permissions

To use location APIs, your app must have access to fine or coarse location. Declare these permissions in your app's manifest file. The following table lists Android permissions your app might request related to location services.

Permission Description
ACCESS_COARSE_LOCATION
Runtime permission that your app must request.		 Allows app to access approximate location while in the foreground.
ACCESS_FINE_LOCATION
Runtime permission that your app must request.		 Allows app to access precise location while in the foreground.
ACCESS_BACKGROUND_LOCATION
Runtime permission that your app must request.		 Allows app to access location while in the background. Must use with ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.
FOREGROUND_SERVICE
Normal permission that the system automatically grants.		 Allows app to maintain a foreground status by showing a status bar notification. For details, see the Android developer documentation on Foreground services.

As a general guideline, request only permissions that are necessary for your app. If your app doesn't require an exact location to work, consider using only the coarse location permission. On Android 12 and higher, a user can choose to allow only access to coarse location in an app. Make sure your app behaves as expected when it has access only to the coarse location permission.

Create an instance of A3LLocationProviderClient

To use A3L Location, create an instance of the A3LLocationProviderClient class. An A3LLocationProviderClient object provides the core methods of A3L Location. To create an instance of this class, use the A3LLocationServices.getA3LLocationProviderClient() method, as shown in the following code.

A3LLocationProviderClient a3LLocationProviderClient = A3LLocationServices.getA3LLocationProviderClient(context);

Get current location of the device

A primary use for location services is to determine the current location of the device. In A3L Location, to get the device's current location, use the getCurrentLocation() method. You can choose to get the current location and pass a priority indicator, or if your app has multiple needs, you can pass an A3LCurrentLocationRequest object. For details on A3LCurrentLocationRequest objects, see Get current location with A3LCurrentLocationRequest.

Get current location with priority

To use getCurrentLocation() with priority, pass an A3LPriority constant. The following table lists the available A3LPriority constants. If you choose to prioritize higher accuracy in your app, the device uses more power. If you choose to prioritize lower power usage, the location has lower accuracy.

A3L priority constant Description
A3LPriority.PRIORITY_BALANCED_POWER_ACCURACY Priority is balanced between power and accuracy.
A3LPriority.PRIORITY_HIGH_ACCURACY Priority is given to high accuracy. Uses more device power.
A3LPriority.PRIORITY_LOW_POWER Priority is given to low power usage. Location is less accurate.
A3LPriority.PRIORITY_PASSIVE App doesn't request location updates.

The following code shows an example to get the current location with balanced priority. Optionally, you can pass a CancellationToken object if you want to be able to cancel the location request. For more information on cancellation tokens, see Create a cancellation token.

// getCurrentLocation with Priority.
Task<Location> currentLocation = a3LLocationProviderClient.getCurrentLocation(A3LPriority.PRIORITY_BALANCED_POWER_ACCURACY, cancellationToken);

Create a cancellation token (optional)

To be able to cancel a location request, you can pass a CancellationToken object in the getCurrentLocation() method. The following code shows an example of how to create a cancellation token. Using a cancellation token is optional.

// Note: CancellationToken is an optional field.
CancellationToken cancellationToken = new CancellationTokenSource().getToken();
cancellationToken.onCanceledRequested(new OnTokenCanceledListener() {
    @Override
    public void onCanceled() {
        // Code to be executed once token cancellation is requested.
    }
});

Get current location with A3LCurrentLocationRequest

To pass more than one parameter in the getCurrentLocation() request, you can build an A3LCurrentLocationRequest object that takes multiple parameters. For example, if you want to set both priority and a request interval, you can build the A3LCurrentLocationRequest and indicate the specific priority and request interval that fits the needs of your app.

The following code shows how to create an A3LCurrentLocationRequest object with multiple parameters. This example builds the object with granularity, max update age, priority, and duration.

// getCurrentLocation with A3LCurrentLocationRequest.
// NOTE: The builder constructor and values in this code are examples. In your implementation,
// use the builder constructor and values required for your app.
A3LCurrentLocationRequest a3LCurrentLocationRequest = new A3LCurrentLocationRequest.Builder()
        .setGranularity(A3LGranularity.GRANULARITY_PERMISSION_LEVEL)
        .setMaxUpdateAgeMillis(1000L)
        .setPriority(A3LPriority.PRIORITY_BALANCED_POWER_ACCURACY)
        .setDurationMillis(1000L)
        .build();
Task<Location> currentLocation = a3LLocationProviderClient.getCurrentLocation(a3LCurrentLocationRequest, cancellationToken);

For a full list of parameters the A3LCurrentLocationRequest object can be built with, see the API Reference for A3LCurrentLocationRequest.Builder().

Get last known location of the device

To provide the most recent historical location currently available, use the getLastLocation() method, as shown in the following code. This method returns null if there is no historical location available.

// getLastLocation
Task<Location> lastKnownLocation = a3LLocationProviderClient.getLastLocation();

Get last known location with A3LLastLocationRequest

Similar to the getCurrentLocation() method, you can customize your getLastLocation() request by passing an A3LLastLocationRequest object that has multiple parameters.

In your last known location request, you can define the granularity of the requested location (fine or coarse), or add a maximum age for the returned location. To do this, build an A3LLastLocationRequest object and pass it to the getLastLocation() method. The following example shows the object built with granularity and max update age.

// getLastLocation with A3LLastLocationRequest
// NOTE: The builder constructor and values in this code are examples. In your implementation,
// use the builder constructor and values required for your app.
A3LLastLocationRequest a3LLastLocationRequest = new A3LLastLocationRequest.Builder()
        .setGranularity(A3LGranularity.GRANULARITY_FINE)
        .setMaxUpdateAgeMillis(1000L)
        .build();
Task<Location> lastKnownLocation2 = a3LLocationProviderClient.getLastLocation(a3LLastLocationRequest);

For a full list of parameters the A3LLastLocationRequest object can be built with, see the API Reference for A3LLastLocationRequest.Builder().

Last updated: Sep 13, 2023