• Stars
    star
    328
  • Rank 128,352 (Top 3 %)
  • Language
    Kotlin
  • License
    Apache License 2.0
  • Created about 6 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An Awesome Kotlin Location library to retrieve location merely in 3 lines of code

banner

Locus-Android

License language Platform API Release

Locus is a tiny kotlin library for android which makes it super very easy to retrieve location with just few lines of code. Everything including permission model and Location settings resolution is handled internally which removes a lot of boilerplate code any developer have to write every time.

Looking for Maintainers

Its been a long time since I moved away from native Android development so I am finding it hard to keep up with the latest changes with the location permissions in newever Android versions and fix issues reported here. I'd love someone to actively maintain this library and look into the issues. If you are interested and up to the task, drop a mail at [email protected] or comment on this issue. Thanks!

Documentation:

See Wiki for more information and configuration!

Read blog here:

The Legendary Task of Retrieving Location in Just 3 lines of code.

Features

  • Android R support (Please report if any issue is found)
  • 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 Rationale Dialog configuration
  • Custom Permission Blocked Dialog configuration

IMPORTANT:

Breaking Changes from v4.0.0

Text Customizations using Locus.configure{} block which were deprecated in v3.2.0 have been now removed completely. This means rationaleText, rationaleTitle, blockedTitle, blockedText, resolutionTitle, and resolutionText no longer exist on Locus.configure{}. Migration would be to customize/override them from strings.xml.

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>
<string name="grant">Grant</string>
<string name="deny">Deny</string>

checkout strings.xml.

How to disable background location permission if you don't use it.

It has been brought to my attention recently that this library includes background location permission in its AndroidManifest.xml file. This could cause a problem when publishing app on Google Play Store in a case where your does not actually request or use background location. If that happens then this is what you need to do.

Just add this line in your app's AndroidManifest.xml file and you should be good to go.

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

Feel free to re-open #53 issue or file a new one if this does not work for you.

Gradle Dependency

  1. Add the JitPack repository.

For Classic Android Project:

Add this in your project's build.gradle file.

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' } // add this line only
    }
}

For Compose Android Project:

Add this in your project's settings.gradle file.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        ...
        maven { url 'https://jitpack.io' } // add this line only
    }
}
  1. Add the dependency in your app's build.gradle file

Release

dependencies {
    implementation 'com.github.BirjuVachhani:locus-android:latest-version'
    implementation 'com.google.android.gms:play-services-location:latest-version'
}

Usage

See Wiki on how to get started with Locus.

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" />

Pull Request

To generate a pull request, please consider following Pull Request Template.

Issues

To submit an issue, please check the Issue Template.

Code of Conduct

Code of Conduct

Contribution

You are most welcome to contribute to this project!

Please have a look at Contributing Guidelines, before contributing and proposing a change.

Buy Me A Coffee

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.

More Repositories

1

adaptive_theme

Easiest way to add support for light and dark theme in your flutter app.
Dart
315
star
2

spider

A small dart library to generate Assets dart code from assets folder.
Dart
163
star
3

target_mate

A companion app for Toggl track to track & manage your working hours to achieve your monthly goals.
Dart
65
star
4

screwdriver

A dart package aiming to provide useful extensions and helper functions to ease and speed up development.
Dart
20
star
5

expanding_flex_cards

A Flutter project that expands a card when clicked and collapses others.
Dart
17
star
6

pluto

A minimal new tab for Chrome/Edge.
Dart
17
star
7

bext

A kotlin extensions library to remove boilerplate code using Kotlin DSL. See wiki for more examples...
Kotlin
17
star
8

freedom

Freedom is an Android library to handle runtime permissions in easiest way.
Kotlin
16
star
9

gitmoji-android-live-templates

Awesome Android Studio Live Templates to decorate your git commit messages
15
star
10

gradle-utils

A small utility for gradle dependency management that saves a lot of precious time of developer wasted on finding required dependencies for Android libraries.
Kotlin
8
star
11

revix-android

Kotlin
7
star
12

login-mvvm-final-code

Kotlin
7
star
13

gradle_properties

A dart package allowing to work with Gradle properties files.
Dart
6
star
14

flutter-vs-jetpack-compose-ui

Kotlin
6
star
15

android-studio-settings

All about Android Studio settings that I use.
6
star
16

flutter_screwdriver

A flutter package aiming to provide useful extensions and helper functions to ease and speed up development.
Dart
5
star
17

char_animated_text

A char animated text that shows random characters before showing actual ones when hovered.
Dart
5
star
18

flutter_not_paid

Client did not pay? Add opacity to the body tag and decrease it every day until their site completely fades away. Set a due date and customize the number of days you offer them until the website is fully vanished.
Dart
5
star
19

gradle-kotlin-dsl-demo

An example of Gradle Kotlin DSL scripts for Android Project.
Kotlin
4
star
20

kiosk-demo-android

Shows how to use device policies manager to enable kiosk(lockdown) mode in Android
Kotlin
4
star
21

adbwifi-cli

A small cli app built using node to connect android devices wirelessly for easy development.
JavaScript
3
star
22

Socio

Social Integrations made easy.
Kotlin
3
star
23

awesome-animations-android

Java
2
star
24

vector-animations-android

Kotlin
2
star
25

login-mvvm-starter

Kotlin
2
star
26

birjuvachhani

2
star
27

retrofit-demo

Java
2
star
28

ndk-secure-keys-android

CMake
2
star
29

flutter_animated

A showcase of animated widgets.
Dart
2
star
30

qlocktwo

An intriguing clock that features a unique grid of 110 letter to display the time.
Dart
2
star
31

cursor_trail

A pictures stack that follow your cursor.
Dart
1
star
32

android-studio-settings-test

Dart
1
star
33

python-practicals

Basic Python practicals to begin with python
Python
1
star
34

spider-plugin

Kotlin
1
star
35

cursor_blob

A background gradient blob that follows your cursor. Inspired by poppr.be
Dart
1
star
36

bottom-dialog-android

Kotlin
1
star
37

login-sample-ktor

Kotlin
1
star