DEV Community: Olubunmi Alegbeleye

Location Services- the Android 14 (maybe 15 too) way

Olubunmi Alegbeleye — Tue, 16 Jul 2024 13:01:38 +0000

Introduction

Location awareness is becoming an essential part of many successful mobile applications. Whether you're building a fitness tracker, a navigation app, a ride-sharing app, a weather app, an augmented reality experience or a service that connects users based on proximity, incorporating location functionality can significantly enhance your app's value and user experience.

This article helps you leverage the Location API in Android, providing a step-by-step approach to accessing the user's location, handling permissions, and setting up real-time location updates. By the end of this tutorial, you'll be well-equipped to integrate location-based features seamlessly into your Android projects.

Setting up your project to use the Location API

If you don't already have a project set up, follow the following steps:

Open Android Studio.

Go to File > New > New Project.

Select Basic Views Activity

Enter a name for your app

Click Finish

Open your app/build.gradle file and add the following dependency

dependencies {
  //Location
  implementation 'com.google.android.gms:play-services-location:20.0.0'
  }

If you use the Gradle Kotlin DSL, add the following to the libs.versions.toml file

[versions]
...
playlocation = "21.3.0"

[libraries]
...
play-location = { group = "com.google.android.gms", name = "play-services-location", version.ref = "playlocation"}

[plugins]
...

And in the app/build.gradle.kts file, add this

dependencies {
    ...
    implementation(libs.play.location)
}

Click on Sync Project with Gradle Files so that the just added dependency is available for use in your code.

Add the following permissions to your AndroidManifest file

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

ACCESS_FINE_LOCATION: Grants access to the device's most precise location data (GPS, Wi-Fi, cell tower triangulation).
ACCESS_COARSE_LOCATION: Provides a less accurate estimate using cell tower and Wi-Fi data (suitable for scenarios where exact coordinates aren't crucial).

Checking If your App has permission

Activity.checkSelfPermission() checks if you have been granted a particular permission. To check if you have the Manifest.permission.ACCESS_FINE_LOCATION permission, you would do:

ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION)

Let's use that to build a function that checks for the two permissions we need.

Add the following to the activity.

(Code snippets are presented first in Kotlin and then in Java)

private fun isLocationPermissionGranted(activity: Activity): Boolean {
    return ActivityCompat.checkSelfPermission(
        activity,
        Manifest.permission.ACCESS_FINE_LOCATION
    ) == PackageManager.PERMISSION_GRANTED ||
            ActivityCompat.checkSelfPermission(
                activity,
                Manifest.permission.ACCESS_COARSE_LOCATION
            ) == PackageManager.PERMISSION_GRANTED
}

private boolean isLocationPermissionGranted(Activity activity) {
    return ActivityCompat.checkSelfPermission(activity, android.Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED ||
            ActivityCompat.checkSelfPermission(activity, android.Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED;
}

This function checks if your app has the permission to access the device's coarse or fine location.

Requesting Permission at runtime

In the activity where location is needed, you must request permission at runtime. We will use an ActivityResultLauncher to request permission and listen for the response to our request. To indicate the kind of request, we have two options. ActivityResultContracts.RequestMultiplePermissions() or ActivityResultContracts.RequestPermission(). We will use the former because we have two permissions to request.

The next function requests for the needed permissions.

private fun requestLocationPermission(callback: (Boolean) -> Unit) {
    val locationPermissionRequest = registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { permissions ->
        val fineLocationGranted: Boolean =
            permissions.getOrDefault(Manifest.permission.ACCESS_FINE_LOCATION, false)
        val coarseLocationGranted: Boolean =
            permissions.getOrDefault(Manifest.permission.ACCESS_COARSE_LOCATION, false)

        if (fineLocationGranted || coarseLocationGranted) {
            callback(true) //permission granted
        } else {
            callback(false) //permission denied
        }

    }

    locationPermissionRequest.launch(
        arrayOf(
            Manifest.permission.ACCESS_FINE_LOCATION,
            Manifest.permission.ACCESS_COARSE_LOCATION
        )
    )
}

private void requestLocationPermission(CallbackListener<Boolean> callbackListener) {

    ActivityResultLauncher<String[]> locationPermissionRequest = registerForActivityResult(
            new ActivityResultContracts.RequestMultiplePermissions(),
            permissions -> {
                Boolean fineLocationGranted = permissions.getOrDefault(android.Manifest.permission.ACCESS_FINE_LOCATION, false);
                Boolean coarseLocationGranted = permissions.getOrDefault(android.Manifest.permission.ACCESS_COARSE_LOCATION, false);
                if (
                        fineLocationGranted != null && fineLocationGranted ||
                                coarseLocationGranted != null && coarseLocationGranted
                ) {
                    // Permission granted
                    callbackListener.onCallback(true);
                } else {
                    // No location access granted.
                    callbackListener.onCallback(false);
                }
            });

    locationPermissionRequest.launch(new String[]{
            android.Manifest.permission.ACCESS_FINE_LOCATION,
            android.Manifest.permission.ACCESS_COARSE_LOCATION
    });
}

The result, permissions, is a Map containing the permissions requested and whether they were granted. We look at the map for the two permissions requested. If either of them were granted, we're good. Else, we cannot use the Location API. You may present the user with a warning to let them know that some features may be unavailable or may not function properly since they have not granted the app the permission to access their device location.

Check Phone's Location Settings

Let's say the user granted the permission to access the device's location, we also need to check if the device's settings satisfy our requirements. For example, the device's location may be off. In this case, we cannot access the location.

First, we build a location request. This is our way of specifying our requirements.

Add the following field to your Activity

private val locationRequest = LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 5000)
    .build()

private final LocationRequest locationRequest = new LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 5000)
        .build();

We use SettingsClient.checkLocationSettings() to check if our requirement is met. If the requirement is met, we can proceed to the next step. If it isn't met, we need to ask the user to update their setting.

For that, we need an ActivityResultLauncher to launch the request and listen for the user's action.

Add this field to your Activity.

private val locationSettingsResult =
    registerForActivityResult(ActivityResultContracts.StartIntentSenderForResult()) { result ->
        when (result.resultCode) {
            Activity.RESULT_OK -> {
                //User has updated the device's setting
            }

            Activity.RESULT_CANCELED -> {
                //Warn user that location is required for some features
            }
        }
    }

private ActivityResultLauncher<IntentSenderRequest> locationSettingsResult;

public void onCreate(@Nullable Bundle savedInstanceState) {
    locationSettingsResult = registerForActivityResult(new ActivityResultContracts.StartIntentSenderForResult(), result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                //User has updated the device's setting
            } else {
                //Warn user that location is required for some features
            }
        });
}

This ActivityResultContracts must be registered before the Activity starts, or the app will crash.

Putting it all together we have this function to check the device's location setting and ask the user to update their location settings if there is a need:

private fun checkPhoneLocationSettings(
    activity: Activity,
    locationSettingsResult: ActivityResultLauncher<IntentSenderRequest>,
    callback: (Boolean) -> Unit
) {
    val builder = LocationSettingsRequest.Builder().addLocationRequest(locationRequest)
    val client = LocationServices.getSettingsClient(activity)
    val task = client.checkLocationSettings(builder.build())

    task.addOnSuccessListener { callback(true) }

    task.addOnFailureListener { exception ->
        if (exception is ResolvableApiException) {
            try {
                locationSettingsResult.launch(
                    IntentSenderRequest.Builder(exception.resolution).build()
                )
            } catch (sendEx: IntentSender.SendIntentException) {
                // Ignore the error.
            }
        }
    }
}

private void checkPhoneLocationSettings(
        Activity activity,
        ActivityResultLauncher<IntentSenderRequest> locationSettingsResult,
        CallbackListener<Boolean> callbackListener) {

    LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder()
            .addLocationRequest(locationRequest);
    SettingsClient client = LocationServices.getSettingsClient(activity);

    Task<LocationSettingsResponse> task = client.checkLocationSettings(builder.build());

    task.addOnSuccessListener(activity, locationSettingsResponse -> {
        //Location settings are fine. You can start listening for location
        callbackListener.onCallback(true);
    });

    task.addOnFailureListener(activity, e -> {
        if (e instanceof ResolvableApiException) {
            locationSettingsResult.launch(new IntentSenderRequest.Builder(((ResolvableApiException) e).getResolution()).build());
        }
    });
}

At this point, we have what we need to check if we have location permission. If we don't we can request the permissions. After which we can check if the settings meet our location requirements. Let's package all of that into a function.

private fun setUpLocationComponentsAndGetLocation(activity: Activity) {
    if (isLocationPermissionGranted(activity)) {
        checkPhoneLocationSettings(activity) { isLocationSettingsOk ->
            if (isLocationSettingsOk) {
                //You can get last known location or request location update here because you have permission
                //and the device settings meet your requirement.
            } else {
                //warn user
            }
        }
    } else {
        requestLocationPermission { permissionGranted ->
            if (permissionGranted) {
                //simply a recursive call
                setUpLocationComponentsAndGetLocation(activity)
            } else {
                //warn user
            }
        }
    }
}

private void setUpLocationComponentsAndGetLocation(Activity activity) {
        if (isLocationPermissionGranted(activity)) {
        checkPhoneLocationSettings(activity, locationSettingsResult, isLocationSettingsOk -> {
            if (isLocationSettingsOk) {
                //You can get last known location or request location update here because you have permission
                //and the device settings meet your requirement.
            } else {
                //You may decide to warn users that some functions may not be available without permission

            }
        });
    } else {
        requestLocationPermission(permissionGranted -> {
            if (permissionGranted) {
                //simply a recursive call
                setUpLocationComponentsAndGetLocation(activity);
            } else {
                //Warn user
            }
        });
    }
}

Accessing Location

At this point, we can now access the device's location. FusedLocationProviderClient is the main entry point for interacting with the Fused Location Provider - the Location API by Google for accessing user location. To begin, add this field to your Activity:

private val mFusedLocationProviderClient: FusedLocationProviderClient by lazy {
    LocationServices.getFusedLocationProviderClient(this)
}

private FusedLocationProviderClient fusedLocationProviderClient;
@Override
    protected void onStart() {
        super.onStart();
        fusedLocationProviderClient = LocationServices.getFusedLocationProviderClient(this);
    }

There are two methods of concern to us in the FusedLocationProviderClient class:

FusedLocationProviderClient.getLastLocation() retrieves the last known location while FusedLocationProviderClient.requestLocationUpdates() listens for Location updates.

For the former, think of Weather apps that get your current city and display the weather in that area. For the latter, think of Bolt or Uber which needs to get updates on the driver and rider's location.

Retrieving the last known location

To retrieve the last known location of the device,

@SuppressLint("MissingPermission")
private fun getLastLocation() {
    mFusedLocationProviderClient.lastLocation.addOnSuccessListener { location ->
        if (location != null) {
            // Logic to handle location object
            Log.d("Location", "Long" + location.longitude)
            Log.d("Location", "Lat" + location.latitude)
        }
    }
}

@SuppressLint("MissingPermission")
private void getLastLocation() {
    fusedLocationProviderClient.getLastLocation().addOnSuccessListener(location -> {
        // Got last known location. In some rare situations this can be null.
        if (location != null) {
            // Logic to handle location object
            Log.d("Location", "Long" + location.getLongitude());
            Log.d("Location", "Lat" + location.getLatitude());
        }
    });
}

Notice that you need to check for null because the last location may be null at some point.

Setting up Location Updates for Real-time tracking

This requires some more work compared to retrieving the last known location because we need to set up a callback and manage lifecycle.

For the callback, add this field to your Activity:

private val locationCallBack = object : LocationCallback() {
    override fun onLocationResult(locationResult: LocationResult) {
        super.onLocationResult(locationResult)
        Log.d("Location", "Long" + locationResult.lastLocation?.longitude)
        Log.d("Location", "Lat" + locationResult.lastLocation?.latitude)
    }
}

private final LocationCallback locationCallback = new LocationCallback() {
    @Override
    public void onLocationResult(@NonNull LocationResult locationResult) {
        super.onLocationResult(locationResult);
        if (locationResult.getLastLocation() != null) {
            Log.d("Location", "Long: " + locationResult.getLastLocation().getLongitude());
            Log.d("Location", "Lat: " + locationResult.getLastLocation().getLatitude());
        }
    }
};

Remember we created a LocationRequest object when checking if the device setting meets our requirement. Well, we need the same object now.

Create this function in your Activity

@SuppressLint("MissingPermission")
private fun requestLocationUpdate(activity: Activity) {
    if (isLocationPermissionGranted(activity)) {
        mFusedLocationProviderClient.requestLocationUpdates(
            locationRequest,
            locationCallBack,
            Looper.getMainLooper()
        )
    }
}

@SuppressLint("MissingPermission")
private void requestLocationUpdate(Activity activity) {
    if (isLocationPermissionGranted(activity)) {
        fusedLocationProviderClient.requestLocationUpdates(
                locationRequest,
                locationCallback,
                Looper.getMainLooper()
        );
    }
}

Connecting it all up

Now that we have the function to Get the last known location and request location updates, it is time to update our setUpLocationComponentsAndGetLocation()
from before. Add the new lines to the setUpLocationComponentsAndGetLocation() function.

private fun setUpLocationComponentsAndGetLocation(activity: Activity) {
    if (isLocationPermissionGranted(activity)) {
        checkPhoneLocationSettings(activity) { isLocationSettingsOk ->
            if (isLocationSettingsOk) {
                getLastLocation() //Add only this line to get the last location
                requestLocationUpdate(activity) //Add only this line, to request location updates
            } else {
                //warn user
            }
        }
    } else {
        requestLocationPermission { permissionGranted ->
            if (permissionGranted) {
                //simply a recursive call
                setUpLocationComponentsAndGetLocation(activity)
            } else {
                //warn user
            }
        }
    }
}

private void setUpLocationComponentsAndGetLocation(Activity activity) {
        if (isLocationPermissionGranted(activity)) {
        checkPhoneLocationSettings(activity, locationSettingsResult, isLocationSettingsOk -> {
            if (isLocationSettingsOk) {
                getLastLocation(); //Add only this line to get the last location
                requestLocationUpdate(activity); //Add only this line, to request location updates
            } else {
                //You may decide to warn users that some functions may not be available without permission

            }
        });
    } else {
        requestLocationPermission(permissionGranted -> {
            if (permissionGranted) {
                //simply a recursive call
                setUpLocationComponentsAndGetLocation(activity);
            } else {
                //Warn user
            }
        });
    }
}

To get location or request location update, all you need do at this point is to call the setUpLocationComponentsAndGetLocation() from the entry point of the Activity that needs location data. Usually, this is the onStart() method.

override fun onStart() {
    super.onStart()
    setUpLocationComponentsAndGetLocation(this)
}

@Override
protected void onStart() {
    super.onStart();
    setUpLocationComponentsAndGetLocation(this);
}

Cleaning up after yourself

One final and important thing. When you no longer require the location updates, you need to unsubscribe. This most likely happens when the user navigates away from the Activity that requires the location update. It is a best practice to stop location updates by removing the location callback. This way, you can avoid unnecessarily draining the device battery.

override fun onStop() {
    mFusedLocationProviderClient.removeLocationUpdates(locationCallBack)
    super.onStop()
}

@Override
protected void onStop() {
    fusedLocationProviderClient.removeLocationUpdates(locationCallback);
    super.onStop();
}

Conclusion

Integrating location functionality into your Android applications can significantly enhance user experience and provide valuable features for a wide range of applications. By following this step-by-step guide, you now know how to access the user's location, handle permissions, set up real-time location updates, and ensure your app meets the necessary location settings requirements. Implementing these features will allow you to create more dynamic and contextually aware applications.

This guide helped you leverage the Android Location API effectively in your mobile applications. It discussed the process of:

Integrating the Location API dependency within your project.
Requesting and handling location permissions at runtime.
Verifying that the device's location settings meet your app's requirements.
Retrieving the user's last known location.
Setting up real-time location updates.
Stopping location updates to optimize battery usage.

By following the steps in this article, you can add location-based functionalities to enhance your Android apps, create more dynamic and contextually aware applications and deliver a superior user experience.

For a complete example, you can refer to the repository at https://github.com/olubunmialegbeleye/Location. Happy coding!

Validating phone numbers using Google's libphonenumber library

Olubunmi Alegbeleye — Wed, 01 Feb 2023 13:36:24 +0000

What is libphonenumber?

Libphonenumber is Google’s library for parsing, formatting, and validating international phone numbers in Java, C++, and JavaScript. That sounds interesting. So, I can use this library to validate the phone numbers of any country.

Libphonenumber is a powerful library — it is a Swiss army knife. We will focus mostly on validating phone numbers with this library.

You can find the Github repo and documentation for the library here.

If you are collecting user phone numbers in your application and need to validate that they are correct, then read on.

Importing the library into an Android Project

To add libphonenumber to your Android Studio Project, add these to your project-level build.gradle file:

Enable Maven Repository in your project if it has not yet been done:
```
repositories {
  mavenCentral()
}
```

Add this line to your app-level build.gradle file to compile the dependencies:

dependencies {
    ...
    implementation 'com.googlecode.libphonenumber:libphonenumber:8.2.0'
}

Rebuild your project so that Gradle can fetch the dependencies. After you have successfully built it, the library will be available for you to use in your app module.

Validating Nigerian Phone Numbers

Now that you have imported the library, let’s use it to validate Nigerian phone numbers.

Import the following in your java/android class:

import com.google.i18n.phonenumbers.PhoneNumberUtil
import com.google.i18n.phonenumbers.Phonenumber

Create an instance of the PhoneNumberUtil class.

//Java
PhoneNumberUtil phoneNumberUtil = PhoneNumberUtil.getInstance();

//Kotlin
private val phoneNumberUtil = PhoneNumberUtil.getInstance()

This is the utility class for formatting, parsing, and validating international phone numbers. In case you like to read Javadocs, here is the link to the class’s Javadoc.

I know, just like me, you don’t, just follow along and I will show you how this works. “I gat you”.

This util class has a method isValidNumber() that returns true if the phone number matches a valid pattern and false otherwise:

//Java
public boolean isValidNumber(Phonenumber.PhoneNumber number)

//Kotlin
fun isValidNumber(number: Phonenumber.PhoneNumber): Boolean

Did I just read pattern and matching? Yes, you read right. Maybe that brings the dreaded regular expression to mind. Luckily for you and me, this util class and its functions replace all of that jargon. So, out with the regex.

The PhoneNumberUtil class also has a method isValidForRegion() that accepts region code in addition to isValidNumber()’s PhoneNumber parameter.

But where does this PhoneNumber.Number number parameter come from? The PhoneNumber class represents/stores a phone number. Javadoc people, here you go again.

Here is how you create an instance of the PhoneNumber class — a PhoneNumber object:

//Java
Phonenumber.PhoneNumber rawPhoneNumber = new Phonenumber.PhoneNumber();

//Kotlin
val rawPhoneNumber = Phonenumber.PhoneNumber()

Next, pass the country code and the national number you got from the user into the object you just created. Usually, you get these from two text fields or a drop-down menu and a text field in your user interface.

You have to parse the country code into an integer and the phone number into a long.

For Nigeria, the country code is “+234” or 234 in integer

and the national number is the user’s phone number in a format that can be dialled locally from Nigeria. That is the format: 080X XXX XXXX or 80X XXX XXXX.

At this point, all you need to do is set the two fields in the Phonenumber object you created, thus:

//Java
Phonenumber.PhoneNumber rawPhoneNumber = new Phonenumber.PhoneNumber();
rawPhoneNumber.setCountryCode(123);
rawPhoneNumber.setNationalNumber(123L);

//Kotlin
val rawPhoneNumber = Phonenumber.PhoneNumber()
rawPhoneNumber.countryCode = countryCodeEditText.text.toString().toInt()
rawPhoneNumber.nationalNumber = phoneEditText.text.toString().toLong()

To validate, pass this phone number object to the isValidNumber() function you came across earlier:

//Java
Phonenumber.PhoneNumber rawPhoneNumber = new Phonenumber.PhoneNumber();
rawPhoneNumber.setCountryCode(123);
rawPhoneNumber.setNationalNumber(123L);
boolean isValidNumber = phoneNumberUtil.isValidNumber(rawPhoneNumber);

//Kotlin
val rawPhoneNumber = Phonenumber.PhoneNumber()
rawPhoneNumber.countryCode = countryCodeEditText.text.toString().toInt()
rawPhoneNumber.nationalNumber = phoneEditText.text.toString().toLong()
val isValid = phoneNumberUtil.isValidNumber(rawPhoneNumber)

To save user details on your server, you can pass both components of the phone number you have collected and validated as a JSON object:

{
  "userPhoneNumber" : {
    "country_code": 234,
    "national_number": 8012345678
  }
}

Or you may want to send it to your server in the international form. For example +23490X XXX XXXX for Nigeria. There is information on how to get the validated phone number in the international format in the sidebar.

In this short article, we saw in action a powerful library that replaces all those ugly regular expressions when validating phone numbers.

Sidebar: Parsing and Formatting phone numbers with libphonenumber

Formatting Phone Numbers

You may need to format the validated phone number in a different format. That is where the PhoneNumberUtil’s formatting ability comes in. Just do this. In this example, we format the phone number as an E.164 number:

//Java
String internationalFormat = phoneNumberUtil.format(rawPhoneNumber, PhoneNumberUtil.PhoneNumberFormat.E164);

//Kotlin
internationalFormat = phoneNumberUtil.format(rawPhoneNumber, PhoneNumberUtil.PhoneNumberFormat.E164)

Don’t be confused with that second parameter. They are constants in the util class that represents different phone number formats: E164, INTERNATIONAL, NATIONAL, and RFC3966.

So, you’re just telling PhoneNumberUtil in what format you want your output.

Parsing Phone Numbers

Let’s briefly learn about parsing phone numbers with PhoneNumberUtil.

If you have your phone number in any format (E164, national, international, etc), even if the phone number is embedded in a string, just invoke the parse function like this:

//Java
Phonenumber.PhoneNumber parsedPhoneNumber = phoneNumberUtil.parse(CharSequence numberToParse, String regionCode);

//Kotlin
val parsedPhoneNumber = PhoneNumberUtil.parse(numberToParse: CharSequence, regionCode: String)

The region code identifies what region the number is expected to be from. That’s NG for Nigeria. And kaboom!, you have phoneNumber in PhonenNumber.PhoneNumber form.

The country code and the national number have been parsed into individual fields like this:

{
  "country_code": 234,
  "national_number": 8012345678
}

Here is a warning!!!

If you pass a string that cannot be parsed into PhoneNumberUtil.parse(), say because it doesn’t contain a valid phone number, a NumberParseException is thrown. Usually, we surround things like this in try-catch blocks, but the ball (or the exception in this case) is in your court.