Getting location on Android

This lib is an easy way to get the location inside Android applications. The new thing about it, it uses Google Play Services.

Location use cases

Handling locations is complex. This lib handles all known use cases on Android devices, when trying to get the location.

S1 - success szenario

Given: No location permission granted

Permission dialog becomes visible.

User grants permission.

Location search starts and a progress indicator appears.

The current location is found.

The location can be used inside application.

S2 - location not found

Given: No location permission granted

Permission dialog becomes visible.

User grants permission.

Location search starts and a progress indicator appears.

The current location cannot be found.

The location cannot be used inside application.

S3 - location permission denied

Given: No location permission granted

Permission dialog becomes visible.

User denies permission.

The location cannot be used inside application.

S4 - location authorisation is later revoked

Given: Location permission granted before, but was later revoked via app settings

Permission dialog becomes visible again.

Next: either S1, S2, or S3

S5 - location has been deactivated throughout the OS

Given: Location detection is disabled on device.

Message becomes visible, that location detection is disabled and a link to OS settings can be clicked.

The location cannot be used inside application.

Integration steps

Development preparation

1. Go to allprojects > repositories and buildscript > repositories, and configure the Maven repository address for HMS SDK.

// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
    repositories {
        
    }
}

allprojects {
    repositories {
        
    }
}

2. On app module level, add compile dependencies inside file build.gradle:

implementation 'com.github.stroeer:locator-android:0.0.1'

3. Re-open the modified build.gradle file. You will find a Sync Now link in the upper right corner of the page. Click Sync Now and wait until synchronization has completed.

4. Configure multi-language information.

android {
    defaultConfig {
        resConfigs "en", "zh-rCN"，""Other languages to be supported.""
    }
}

Client development

1. Assigning App Permissions

The Android OS provides two location permissions: ACCESS_COARSE_LOCATION (approximate location permission) and ACCESS_FINE_LOCATION (precise location permission). You need to apply for the permissions in the Manifest file.

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

In Android Q, if your app needs to continuously locate the device location when it runs in the background, you need to apply for the ACCESS_BACKGROUND_LOCATION permission in the Manifest file.

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

2. Ask for permissions and handle permisson, device state, and location events

Define text resources when asking the user for permissions:

This lib is an easy way to get the location inside Android applications.

Integration steps

On app module level, edit build.gradle:

implementation 'com.github.stroeer:locator-android:0.0.1'

Define text for getting permissions:

    LocationPermissionRationaleMessage(
        getString(R.string.error_location_disabled_short),
        getString(R.string.error_location_disabled),
        getString(R.string.error_location_disabled_goto_settings),
        getString(R.string.error_location_disabled_cancel)
    )

Example for German strings when requesting permissions:

<resources>
    <string name="error_location_disabled_short">Standortbestimmung deaktiviert</string>
    <string name="error_location_disabled">Die Standortbestimmung ist auf Ihrem Gerät deaktiviert. Sie können dies unter Einstellungen ändern.</string>
    <string name="error_location_disabled_cancel">Abbrechen</string>
    <string name="error_location_disabled_goto_settings">Einstellungen</string>
</resources>

Inside your Kotlin file:

    Locator.getCurrentLocation(this, permissionRationale) { locationEvent ->
        when (locationEvent) {
            is Event.Location -> handleLocationEvent(locationEvent)
            is Event.Permission -> handlePermissionEvent(locationEvent)
        }
    }

Handling events:

private fun handleLocationEvent(locationEvent: Event.Location) {
        val location = locationEvent.locationData
        if (location == null) {
            onLocationNotFound()
         } else {
            processLatLong(location.latitude, location.longitude)
         }
     }

private fun handlePermissionEvent(permissionEvent: Event.Permission) {
        when (permissionEvent.event) {
            EventType.LOCATION_PERMISSION_GRANTED -> {
                floating_search_view.showProgress()
            }

            EventType.LOCATION_PERMISSION_NOT_GRANTED -> {
               onLocationDisabled()
            }

           EventType.LOCATION_DISABLED_ON_DEVICE -> {
                onLocationStillDisabled()
            }
        }
    }