Skip to content

Latest commit

 

History

History
126 lines (93 loc) · 4.66 KB

README.md

File metadata and controls

126 lines (93 loc) · 4.66 KB
Raw

Coroutines Location API Library for Android

Build Status codecov Maven Central API

This library wraps the Location APIs in Kotlin coroutines and Flow.

Usage

Create a CoLocation or CoGeocoding instance, preferably by using a dependency injection framework. CoLocation is very similar to the classes provided by the Location APIs. Instead of LocationServices.getFusedLocationProviderClient(context).lastLocation you can use coLocation.getLastLocation(). Make sure to have the Location permission from Marshmallow on, if they are needed by your API requests.

Example:

val coLocation = CoLocation.from(context);
val coGeocoder = CoGeocoder.from(context);

val locationRequest = LocationRequest.create()
        .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY)
        .setInterval(5000)

val locationUpdates: MutableLiveData<Location> = MutableLiveData()
val addressUpdates: LiveData<Address?> = locationUpdates.switchMap { location ->
        liveData { emit(coGeocoder.getAddressFromLocation(location)) }
    }

val job = viewModelScope.launch {
    try {
        coLocation.getLocationUpdates(locationRequest).collect(mutableLocationUpdates::postValue)
    } catch (e: CancellationException) {
        // Location updates cancelled
    }
}

// The updates get canceled automatically when viewModelScope is cancelled.
// If you want to cancel it before that, save the job and cancel it.
job.cancel()

The following APIs are wrapped by this library:

  • FusedLocationProviderClient via CoLocation
  • SettingsClient via CoLocation
  • Geocoder via CoGeocoder

Checking the location settings is simplified with this library, by providing a SettingsResult via coLocation.checkLocationSettings(locationRequest):

val settingsResult = coLocation.checkLocationSettings(locationRequest)

when (settingsResult) {
    SettingsResult.Satisfied -> startLocationUpdates()
    is SettingsResult.Resolvable -> settingsResult.resolve(activity, REQUEST_SHOW_SETTINGS)
    else -> { /* Ignore for now, we can't resolve this anyway */ }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_SHOW_SETTINGS && resultCode == Activity.RESULT_OK) {
        // Resolution success, location settings are now satisfied
        startLocationUpdates()
    }
}

Sample

A basic sample app is available in the sample project.

Setup

The library is available on Maven Central. Add the following to your build.gradle:

dependencies {
    implementation 'com.patloew.colocation:colocation:1.1.1'
    implementation 'com.google.android.gms:play-services-location:21.0.1'
}

If you want to use a newer version of Google Play Services, declare the newer version in your build.gradle. This then overrides the version declared in the library.

CoLocation only works with Android Gradle Plugin 3.0.0 or higher, since it uses Java 8 language features. Don't forget to set the source code compatibility to Java 8:

android {
  compileOptions {
      sourceCompatibility JavaVersion.VERSION_1_8
      targetCompatibility JavaVersion.VERSION_1_8
  }
  kotlinOptions {
      jvmTarget = "1.8"
  }
}

Testing

When unit testing your app's classes, CoLocation and CoGeocoder behavior can be mocked easily. See MainViewModelTest in the sample project for an example test.

Donations

If you like the library and want to support the creator for development/maintenance, you can make a donation in Bitcoin to bc1q5uejfyl2kskhhveg7lx4fcwgv8hz88r92yzjsu. Thank you!

License

Copyright 2020 Patrick Löwenstein

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.