Home

Locus-Android

Locus is a life-cycle aware android library for retrieving location updates by writing just a few lines. It uses Google's FusedLocationProviderApi to retrieve location and uses LiveData to notify observers on location updates.

Topics

• Features
• Installation
• Usage

Features

• Android Q support
• Completely written in Kotlin
• Easy Initialization
• Handles Permission Model
• No Boilerplate
• Built on Kotlin DSL
• Manifest Permission Check
• Life-Cycle Aware Location Updates
• Location Settings Check
• Location Settings Request
• Custom Location Options Configuration
• Custom Relation Dialog configuration
• Custom Permission Blocked Dialog configuration

IMPORTANT: Deprecation from v3.2.0

Text Customizations using Locus.configure{} block is deprecated in v3.2.0. That means rationaleText, rationaleTitle, blockedTitle, blockedText, resolutionTitle, and resolutionText are deprecated. Migration would be to customize/override them from strings.xml.

It is deprecated in v3.2.0 and will be removed completely in next release.

Before

Locus.configure {
    rationaleTitle = "Rationale Title"
    rationaleTitle = "This is a rationale message."
    blockedTitle = "Permission Blocked Title"
    blockedText = "This is a permission blocked message."
    resolutionTitle = "Permission Resolution Title"
    resolutionText = "This is a permission resolution message."
}

Now

strings.xml

<string name="locus_rationale_title">Rationale Title</string>
<string name="locus_rationale_message">This is a rationale message.</string>
<string name="locus_permission_blocked_title">Permission Blocked Title</string>
<string name="locus_permission_blocked_message">This is a permission blocked message.</string>
<string name="locus_location_resolution_title">Permission Resolution Title</string>
<string name="locus_location_resolution_message">This is a permission resolution message.</string>

checkout strings.xml.

Installation

Gradle Dependency

• Add the JitPack repository to your project level build.gradle file.

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

• Add the library dependency in your app level build.gradle file.

dependencies {
    implementation 'com.github.BirjuVachhani:locus-android:3.0.1'
}

Usage

Continuous Updates

Locus.startLocationUpdates(this) { result ->
    result.location?.let { /* Received location update */ }
    result.error?.let { /* Received error! */ }
}

Single Update

Locus.getCurrentLocation(this) { result ->
    result.location?.let { /* Received location update */ }
    result.error?.let { /* Received error! */ }
}

Handle errors:

when {
    error.isDenied -> { /* Permission denied */ }
    error.isPermanentlyDenied -> { /* Permission is permanently denied */ }
    error.isFatal -> { /* Something else went wrong! */ }
    error.isSettingsDenied -> { /* Settings resolution denied by the user */ }
    error.isSettingsResolutionFailed -> { /* Settings resolution failed! */ }
}

3. Stop Receiving Location

Locus.stopTrackingLocation()

So easy right? That's what we wanted to achieve: a hassle free location retrieval process.

Background Location Permission Removal

This package adds background location permission to the manifest file regardless whether you are using it or not. If you are not requesting background location permission and you are not planning to use it in future, consider adding this line into your manifest file. This is only required when you publish your app to Google Playstore because they might reject your app because of this. See realted issue #53.

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

License

   Copyright © 2019 BirjuVachhani

   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.