Quickstart

The GeoSpark Android SDK makes it quick and easy to build a location tracker for your Android app. We provide powerful and customizable tracking modes and features.

Requirements

To use the GeoSpark SDK, the following things are required:

  • Get yourself a free GeoSpark Account. No credit card required.

  • Create a project and add an Android app to the project.

  • You need the SDK_KEY in your project settings which you’ll need to initialize the SDK.

  • Now, you’re ready to integrate the SDK into your Android application.

The GeoSpark Android SDK requires Android Studio 2.0 or later and is compatible with apps targeting Android SDK Version 16 or above.

Android Studio Setup

To use the Android SDK in a project, add the SDK as a build dependency and sync the project.

  1. Go to Android Studio > New Project > Minimum SDK

  2. Select API 16: Android 4.1.0 (Jelly Bean) or higher and create a project

  3. After you create a new project, open Gradle Scripts > build.gradle (Project: <your_project>) and do the following:

    1. Add the following to the build script {repositories {}} section of the build.gradle (Project)file:

      mavenCentral()

Sync and close build.gradle (Project: <your_project>)

Gradle Installation

Install the SDK to your project via Gradle in Android Studio, add the maven below in your project build.gradle file.

repositories {
maven {
url 'https://com-geospark-android.s3.amazonaws.com/'
}
}

add the dependencies below in your app build.gradle file.

dependencies {
implementation 'com.geospark.android:geospark:3.1.5'
}

Then sync Gradle.

Manual Installation

Download and unzip GeoSpark SDK

  1. Open Android Studio and add the SDK GeoSpark.aar as a module using File > New > New Module > Import .JAR/.AAR Package.

  2. Once Gradle is finished click File > Project Structure again.

  3. Click on the Dependencies tab > click App > click the “+” icon in the top left in Declared Dependencies section > select Module Dependency > click on GeoSpark-release > press Ok and wait for Gradle to sync again and include the dependencies separately and sync your project.

  4. Wait for Gradle to sync again and include the dependencies separately and sync your project.

dependencies {
implementation 'com.google.android.gms:play-services-location:17.0.0'
implementation 'com.squareup.retrofit2:retrofit:2.6.2'
implementation 'com.squareup.retrofit2:converter-gson:2.1.0'
implementation("com.amazonaws:aws-android-sdk-iot:[email protected]") {
exclude group: 'org.eclipse.paho', module: 'org.eclipse.paho.client.mqttv3'
transitive = true
}
implementation "org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.4"
implementation('com.amazonaws:aws-android-sdk-mobile-client:[email protected]') { transitive = true }
}

Initialize SDK

Before initializing the SDK, the below must be imported.

import com.geospark.lib.GeoSpark;

After import, add the below code under the Application class onCreate() method. The SDK must be initialised before calling any of the other SDK methods.

Kotlin
Java
Kotlin
GeoSpark.initialize(this, "YOUR SDK KEY GOES HERE")
Java
GeoSpark.initialize(this, "YOUR SDK KEY GOES HERE");

Creating Users

Once the SDK is initialized, we need to create or get a user to start the tracking and use other methods. Every user created will have a unique GeoSpark identifier which will be used later to login and access developer APIs. We can call it as GeoSpark userId.

Kotlin
Java
Kotlin
GeoSpark.createUser("SET USER DESCRIPTION HERE", object : GeoSparkCallback {
override fun onSuccess(geosparkUser: GeoSparkUser) {
// do something when create user success
// access geospark user id with geosparkUser.getUserId()
// access geospark user description with geosparkUser.getDescription()
}
override fun onFailure(geosparkError: GeoSparkError) {
// do something when create user failure
// access geospark error code with geosparkError.getCode()
// access geospark error message with geosparkError.getMessage()
}
})
Java
GeoSpark.createUser("SET USER DESCRIPTION HERE", new GeoSparkCallback() {
@Override
public void onSuccess(GeoSparkUser geosparkUser) {
// do something when create user success
// access geospark user id with geosparkUser.getUserId()
// access geospark user description with geosparkUser.getDescription()
}
@Override
public void onFailure(GeoSparkError geosparkError) {
// do something when create user failure
// access geospark error code with geosparkError.getCode()
// access geospark error message with geosparkError.getMessage()
}
});

The option user description can be used to update your user information such as name, address or add an existing user ID. Make sure the information is encrypted if you are planning to save personal user information like email or phone number.

You can always set or update user descriptions later using the below code.

Kotlin
Java
Kotlin
GeoSpark.setDescription("SET USER DESCRIPTION HERE")
Java
GeoSpark.setDescription("SET USER DESCRIPTION HERE");

Get User

If you already have a GeoSpark userID which you would like to reuse instead of creating a new user, use the below to get user session.

Kotlin
Java
Kotlin
GeoSpark.getUser("GEOSPARK USER ID", object : GeoSparkCallback {
override fun onSuccess(geosparkUser: GeoSparkUser) {
// do something when get user success
// access geospark user id with geosparkUser.getUserId()
// access geospark user description with geosparkUser.getDescription()
}
override fun onFailure(error: GeoSparkError) {
// do something when get user failure
// access geospark error code with error.getCode()
// access geospark error message with error.getMessage()
}
})
Java
GeoSpark.getUser("GEOSPARK USER ID", new GeoSparkCallback() {
@Override
public void onSuccess(GeoSparkUser geosparkUser) {
// do something when get user success
// access geospark user id with geosparkUser.getUserId()
// access geospark user description with geosparkUser.getDescription()
}
@Override
public void onFailure(GeoSparkError error) {
// do something when get user failure
// access geospark error code with error.getCode()
// access geospark error message with error.getMessage()
}
});

Listeners

You can subscribe to locations and events and use the data locally on your device or send it directly to your own backend server.

To do that, you need to set the location and event listener to true using the below method. By default the status will set to false and needs to be set to true in order to stream the location and events updates to the same device or other devices.

Kotlin
Java
Kotlin
GeoSpark.toggleListener(locations, events, object : GeoSparkCallback {
override fun onSuccess(geosparkUser: GeoSparkUser) {
// do something when toggle listener success
// access locations listener status with geosparkUser.getLocationListenerStatus()
// access events listener status with geosparkUser.getEventListenerStatus()
}
override fun onFailure(geosparkError: GeoSparkError) {
// do something when toggle listener failure
}
})
Java
GeoSpark.toggleListener(locations, events, new GeoSparkCallback() {
@Override
public void onSuccess(GeoSparkUser geosparkUser) {
// do something when toggle listener success
// access locations listener status with geosparkUser.getLocationListenerStatus()
// access events listener status with geosparkUser.getEventListenerStatus()
}
@Override
public void onFailure(GeoSparkError geosparkError ) {
// do something when toggle listener failure
}
});

Request Permission

To start tracking the location below Android 10.

Kotlin
Java
Kotlin
if (!GeoSpark.checkLocationServices()) {
GeoSpark.requestLocationServices(this)
} else if (!GeoSpark.checkLocationPermission()) {
GeoSpark.requestLocationPermission(this)
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !GeoSpark.checkBackgroundLocationPermission()) {
GeoSpark.requestBackgroundLocationPermission(this)
} else {
startTracking()
}
Java
if (!GeoSpark.checkLocationServices()) {
GeoSpark.requestLocationServices(this);
} else if (!GeoSpark.checkLocationPermission()) {
GeoSpark.requestLocationPermission(this);
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !GeoSpark.checkBackgroundLocationPermission()) {
GeoSpark.requestBackgroundLocationPermission(this);
} else {
startTracking()
}

Location Tracking

Start Tracking

Kotlin
Java
Kotlin
GeoSpark.startTracking(TrackingMode)
Java
GeoSpark.startTracking(TrackingMode);

Use the tracking modes while you use the startTracking method GeoSpark.startTracking

Tracking Modes

GeoSpark has three default tracking modes along with a custom version. They differ based on the frequency of location updates and battery consumption. The higher the frequency, the higher is the battery consumption. You must use foreground service for continuous tracking.

Mode

Battery usage

Updates every

Optimised for/advised for

Active

6% - 12%

25 ~ 250 meters

Ride Hailing / Sharing

Balanced

3% - 6%

50 ~ 500 meters

On Demand Services

Passive

0% - 1%

100 ~ 1000 meters

Social Apps

Kotlin
Java
Kotlin
// active tracking
GeoSpark.startTracking(GeoSparkTrackingMode.ACTIVE)
// balanced tracking
GeoSpark.startTracking(GeoSparkTrackingMode.BALANCED)
// passive tracking
GeoSpark.startTracking(GeoSparkTrackingMode.PASSIVE)
Java
// active tracking
GeoSpark.startTracking(GeoSparkTrackingMode.ACTIVE);
// balanced tracking
GeoSpark.startTracking(GeoSparkTrackingMode.BALANCED);
// passive tracking
GeoSpark.startTracking(GeoSparkTrackingMode.PASSIVE);

Custom Tracking Modes

The SDK also provides a custom tracking mode that allows you to customize and build your own tracking modes.

Type

Unit

Unit Range

Distance Interval

Meters

1m ~ 2500m

Time Interval

Seconds

10s ~ 10800s

Distance between location updates example code:

Kotlin
Java
Kotlin
//Update location based on distance between locations.
val trackingMode = GeoSparkTrackingMode.Builder("DISTANCE IN METERS", "STATIONARY DURATION IN SECONDS")
.setDesiredAccuracy(GeoSparkTrackingMode.DesiredAccuracy.HIGH)
.build()
Java
//Update location based on distance between locations.
GeoSparkTrackingMode trackingMode = new GeoSparkTrackingMode.Builder("DISTANCE IN METERS", "STATIONARY DURATION IN SECONDS")
.setDesiredAccuracy(GeoSparkTrackingMode.DesiredAccuracy.HIGH)
.build();

Time between location updates example code:

Kotlin
Java
Kotlin
//Update location based on time interval.
val trackingMode = GeoSparkTrackingMode.Builder("INTERVAL IN SECONDS")
.setDesiredAccuracy(GeoSparkTrackingMode.DesiredAccuracy.HIGH)
.build()
Java
//Update location based on time interval.
GeoSparkTrackingMode trackingMode = new GeoSparkTrackingMode.Builder("INTERVAL IN SECONDS")
.setDesiredAccuracy(GeoSparkTrackingMode.DesiredAccuracy.HIGH)
.build();

You may see a delay if the user's device is in low power mode or has connectivity issues.

Stop Tracking

To stop the tracking use the below method.

Kotlin
Java
Kotlin
GeoSpark.stopTracking()
Java
GeoSpark.stopTracking();

Publish Messages

It will publish location data and these data will be sent to Roam servers for further processing and data will be saved in our database servers.

Kotlin
Java
Kotlin
val geoSparkPublish = GeoSparkPublish.Builder()
.build()
GeoSpark.publishAndSave(geoSparkPublish)
Java
GeoSparkPublish geoSparkPublish = new GeoSparkPublish.Builder()
.build();
GeoSpark.publishAndSave(geoSparkPublish);

To stop publishing locations.

Kotlin
Java
Kotlin
GeoSpark.stopPublishing()
Java
GeoSpark.stopPublishing();

Subscribe Messages

Now that you have enabled the location listener, use the below method to subscribe to your own or other user's location updates and events.

Subscribe

Kotlin
Java
Kotlin
GeoSpark.subscribe(TYPE, "USER-ID")
Java
GeoSpark.subscribe(TYPE, "USER-ID");

UnSubscribe

Kotlin
Java
Kotlin
GeoSpark.unSubscribe(TYPE, "USER-ID")
Java
GeoSpark.unSubscribe(TYPE, "USER-ID");

Type

Description

GeoSpark.Subscribe.EVENTS

Subscribe to your own events.

GeoSpark.Subscribe.LOCATION

Subscribe to your own location (or) other user's location updates.

GeoSpark.Subscribe.BOTH

Subscribe to your own events and location (or) other user's location updates.