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
- 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 {
}
}
- On app module level, add compile dependencies inside file build.gradle:
implementation 'com.github.stroeer:locator-android:0.0.1'
-
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.
-
Configure multi-language information.
android {
defaultConfig {
resConfigs "en", "zh-rCN",""Other languages to be supported.""
}
}
Client development
- 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" />
- 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()
}
}
}