Skip to content

Commit

Permalink
chore(release): Global refactor update for release 4.0
Browse files Browse the repository at this point in the history
  • Loading branch information
quentin7b authored Jul 21, 2020
2 parents 0f0a9cc + 148e7b0 commit 0df77b1
Show file tree
Hide file tree
Showing 25 changed files with 336 additions and 792 deletions.
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
.DS_Store
.gradle
.idea
local.properties
build
15 changes: 15 additions & 0 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
language: android
android:
components:
# The SDK version used to compile your project
- android-30
- build-tools-30.0.0
licenses:
- 'android-sdk-license-.+'
before_install:
- yes | sdkmanager "platforms;android-30"
- yes | sdkmanager "build-tools;30.0.0"
- chmod +x gradlew
script:
- ./gradlew :slt:check
- ./gradlew :slt:assembleRelease
196 changes: 64 additions & 132 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,13 @@ repositories {
}
dependencies {
compile 'com.github.quentin7b:android-location-tracker:3.2'
compile 'com.github.quentin7b:android-location-tracker:4.0'
}
```

Don't forget to add the following permissions to your *AndroidManifest.xml*

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
```
Expand All @@ -33,162 +32,95 @@ Be aware of `Android Marshmallow`'s new [permission system](https://developer.an

```xml
<permission-group
android:name="android.permission-group.LOCATION"
android:label="A label for your permission"
android:description="A description for the permission" />
android:name="android.permission-group.LOCATION"
android:label="A label for your permission"
android:description="A description for the permission" />
```


### Use

As its name says, it's a *simple* library.
To create a tracker you just need to add the below code in your Android Activity/Service

```java
// You can pass an ui Context but it is not mandatory getApplicationContext() would also works
// Be aware if you target android 23, you'll need to handle the runtime-permissions !
// see http://developer.android.com/reference/android/support/v4/content/ContextCompat.html
if ( ContextCompat.checkSelfPermission(ctx, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED
&& ContextCompat.checkSelfPermission(ctx, Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
// You need to ask the user to enable the permissions
} else {
LocationTracker tracker = new LocationTracker(ctx) {
@Override
public void onLocationFound(Location location) {
// Do some stuff
}
};
tracker.startListening();
}
```
To create a tracker you just need to add the below code in your Android Activity / Service / WorkManager

And it's done, as soon as a location has been found, it will call the `onLocationFound()` method and you can do the job.
> Be aware, you'll have to manage runtime permissions on Manifest.permission.ACCESS_FINE_LOCATION & Manifest.permission.ACCESS_COARSE_LOCATION
### Provide custom use
#### Create the tracker

You can call a `LocationTracker` with custom parameters.
To do this, use the following constructor
Constructor is defined as this

```java
LocationTracker(Context context, TrackerSettings settings)
```kotlin
val locationTracker = LocationTracker(
val minTimeBetweenUpdates: Long = 5 * 60 * 1000.toLong(),
val minDistanceBetweenUpdates: Float = 100f,
val shouldUseGPS: Boolean = true,
val shouldUseNetwork: Boolean = true,
val shouldUsePassive: Boolean = true
)
```

As an example:
```java
LocationTracker tracker = new LocationTracker(
context,
new TrackerSettings()
.setUseGPS(true)
.setUseNetwork(false)
.setUsePassive(false)
) {

@Override
public void onLocationFound(Location location) {
// Do some stuff when a new GPS Location has been found
}
};
tracker.startListening()
```
#### Add a listener

This, will call a location tracker that is looking *ONLY* for *GPS* updates.
*Network* and *Passive* updates will not be catched by the Tracker.

### Providers AND metrics custom use

`LocationTracker` allows you to define some custom metrics like
<ul>
<li> The minimum time interval between location updates, in milliseconds </li>
<li> The minimum distance between location updates, in meters </li>
</ul>

To specify those parameters, `LocationTracker` you can set more settings.
Here is an example of call:
```java
TrackerSettings settings =
new TrackerSettings()
.setUseGPS(true)
.setUseNetwork(true)
.setUsePassive(true)
.setTimeBetweenUpdates(30 * 60 * 1000)
.setMetersBetweenUpdates(100);

LocationTracker tracker = new LocationTracker(context, settings) {

@Override
public void onLocationFound(Location location) {
// Do some stuff when a new location has been found.
}
};
tracker.startListening();
```

In this case, when a location is found, the tracker will not call `onLocationFound()` again during *30 minutes*.
Moreover, if the distance between the new location and the older one is less than 100m, `onLocationFound()` will not be called.
```kotlin
locationTracker.addListener(object: Listener {

Be aware that the *time* parameter's priority is higher than the *distance* parameter. So even if the user has moved from 2km, the `tracker` will call `onLocationFound()` only after *30 minutes*.
fun onLocationFound(location: Location) {
}

### Manage the tracker
fun onProviderError(providerError: ProviderError) {
}

By default, after a `LocationTracker` is created, it automatically starts listening to updates... and never stops.
`LocationTracker` has two methods to *start* and *stop* listening for updates.
});
```

If you want to *stop* listening for updates, just call the `stopListening()` method.
For example, if you need a *one shot* position, you can do that:

```java
LocationTracker tracker = new LocationTracker(context) {
#### Start and stop listening

@Override
public void onLocationFound(Location location) {
// Stop listening for updates
stopListening()
// Do some stuff when a new GPS Location has been found
}
};
tracker.startListening();
```kotlin
locationTracker.startListening(context)
//and
locationTracker.stopListening()
```

You can also do it in the `onPause()` Activity method if you want.
### Provide custom use

```java
@Override
protected void onPause() {
if(myTracker != null) {
myTracker.stopListening();
}
super.onPause();
}
```
You can create a `LocationTracker` with custom parameters.

REMEMBER! A `LocationTracker` never stops untill you tell it to do so.
- `minTimeBetweenUpdates` minimum time between two locations to respect before notifying the listeners in milliseconds). Default is *5 minutes*
- `minDistanceBetweenUpdates` minimum distance between two locations to respect before notifying the listeners in meters). Default is *100 meters*
- `shouldUseGPS` specifies if the tracker should use the GPS locations or not. Default is *true*
- `shouldUseNetwork` specifies if the tracker should use the GPS locations or not. Default is *true*
- `shouldUsePassive` specifies if the tracker should use the passive locations or not. Default is *true*

You may want to start listening for updates after all. To do that, `LocationTracker` has a public method named `startListening()`, call it when you want.
With the default parameters, when a location is found, the tracker will not call `onLocationFound()` again during *5 minutes*.
Moreover, if the distance between the new location and the older one is less than *100m*, `onLocationFound()` will not be called.

For example, in the `onResume()` Activity method:
```java
@Override
protected void onResume() {
if(myTracker != null) {
myTracker.startListening();
}
super.onResume();
}
```
### Overriding
> Be aware that the priority of the **time** parameter is higher than the priority of the *distance* parameter.
> So even if the user has moved from 200km, the `tracker` will call `onLocationFound()` only after *30 minutes*.
`LocationTracker` implements Android's [LocationListener](http://developer.android.com/reference/android/location/LocationListener.html) interface.
### Cleaning

By default, it does nothing but logging.
> Be aware! A `LocationTracker` never stops running until you tell it to do so.
Excepts the `onLocationChanged()` method, you can override all the [LocationListener](http://developer.android.com/reference/android/location/LocationListener.html)'s metods, so here is the list:
<ul>
<li>onProviderDisabled(String provider)</li>
<li>onProviderEnabled(String provider)</li>
<li>onStatusChanged(String provider, int status, Bundle extras)</li>
</ul>
If the tracker is running in foreground and not in a service, it might be a good idea to link to the `lifecycle`

### Contact & Questions
The `stopListening` method has an optional parameter `cleanListeners` that is *false* by default.
(calling `stopListening(false)` is the same as calling `stopListening()`).

If you have any questions, fell free to send me a mail.
You can also fork this project, or open an issue :)
When calling `stopListening` we do not remove the listeners you've set, so they will be notified once you start listening again.
But calling `stopListening(true)` will clear the list of registered listeners (same as calling `removeListener` for every registered listener).

```kotlin
tracker.addListener(listener)
tracker.startListening(context)
// listener will be notified
...
tracker.stopListening()
// listener won't receive updated
tracker.startListening(context)
// listener will be notified
...
tracker.stopListening(cleanListeners = true)
// listener won't receive updated for ever
tracker.startListening(context)
// listener won't be notified
```
23 changes: 23 additions & 0 deletions build.gradle
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
// Top-level build file where you can add configuration options common to all sub-projects/modules.


buildscript {
ext.kotlin_version = '1.3.72'
repositories {
google()
mavenCentral()
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:4.0.1'
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
}

allprojects {
repositories {
google()
mavenCentral()
jcenter()
}
}
1 change: 1 addition & 0 deletions gradle.properties
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
android.useAndroidX=true
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-2.2.1-all.zip
distributionUrl=https\://services.gradle.org/distributions/gradle-6.1.1-all.zip
File renamed without changes.
File renamed without changes.
File renamed without changes.
12 changes: 0 additions & 12 deletions simple-location-tracker/.gitignore

This file was deleted.

11 changes: 0 additions & 11 deletions simple-location-tracker/build.gradle

This file was deleted.

36 changes: 0 additions & 36 deletions simple-location-tracker/slt/build.gradle

This file was deleted.

Loading

0 comments on commit 0df77b1

Please sign in to comment.