ion-android-geolocation

The ion-android-geolocation is a library built using Kotlin that provides geolocation features for Android applications.

The IONGLOCController class provides the main features of the Library, which are:

• obtaining the location/position of the device a single time;
• adding a watch to obtain periodic location updates;
• clearing/removing a previously added watch, turning off location updates.

Index

• Motivation
• Usage
• Methods

• Obtain the current location of the device

• Add a watch for periodic location updates

• Clear a watch that was added previously
• Troubleshooting
• Contributing
• License
• Support

Motivation

This library is used by the Geolocation Plugin for OutSystems' Cordova Plugin and Ionic's Capacitor Plugin.

Usage

In your app-level gradle file, import the ion-android-geolocation library like so:

dependencies {
    	implementation("io.ionic.libs:iongeolocation-android:2.2.0")
	}

Methods

As mentioned before, the library offers the IONGLOCController class that provides the following methods to interact with:

Obtain the current location of the device

suspend fun getCurrentPosition(
    activity: Activity, 
    options: IONGLOCLocationOptions
): Result<IONGLOCLocationResult>

The method is composed of the following input parameters:

• activity: the Activity from the app using the library to use when obtaining the location.
• options: IONGLOCLocationOptions with the options with which to make the location request with (e.g. timeout).

The method returns a Result containing either an object of type IONGLOCLocationResult, which includes the geolocation data (e.g. latitide, longitude), or an exception that should be handled by the caller app.

Add a watch for periodic location updates

fun addWatch(
    activity: Activity,
    options: IONGLOCLocationOptions,
    watchId: String
): Flow<Result<List<IONGLOCLocationResult>>>

The method is composed of the following input parameters:

• activity: the Activity from the app using the library to use when obtaining the location updates.
• options: IONGLOCLocationOptions with the options with which to make the location updates request with (e.g. timeout).
• watchId: a unique id identifying the watch to add, so that it can be removed later.

The method returns a Flow in which the location updates will be emitted to.

Clear a watch that was added previously

fun clearWatch(id: String): Boolean

The method is composed of the following input parameters:

• id: the watchId identigying the watch to remove.

The method returns a Boolean indicating if the watch was cleared or not (in case the watch isn't found).

Troubleshooting

Common issues and solutions:

• Location updates not received

• Check that location permission is allowed on the device

• Verify location services are enabled on the device

• Ensure the necessary permissions are included in AndroidManifest.xml

• Poor accuracy

• Enable high accuracy mode

• Ensure clear sky view

• Wait for better GPS signal

• Error received when in airplane mode

• Try setting IONGLOCLocationOptions.enableLocationManagerFallback to true - available since version 2.0.0

• Keep in mind that only GPS signal can be used if there's no network, in which case it may only be triggered if the actual GPS coordinates are changing (e.g. walking or driving).

• Timeout received in watchPosition

• Use the IONGLOCLocationOptions.interval parameter, introduced in version 2.1.0, and set it to below timeout, in order to try to receive a first location update before timing out.

• Increase the IONGLOCLocationOptions.timeout value, if your use case can wait for some time.

• Increase IONGLOCLocationOptions.maximumAge to allow to retrieve an older location quickly for the first update.

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

ion-android-geolocation is available under the MIT license. See the LICENSE file for more info.

Support

• Report issues on our Issue Tracker