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.
To use the Android SDK in a project, add the SDK as a build dependency and sync the project.
Go to Android Studio > New Project > Minimum SDK
Select API 16: Android 4.1.0 (Jelly Bean) or higher and create a project
After you create a new project, open Gradle Scripts > build.gradle (Project: <your_project>) and do the following:
Add the following to the build script {repositories {}} section of the build.gradle (Project)file:
mavenCentral()
Sync and close build.gradle (Project: <your_project>)
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.
Download and unzip GeoSpark SDK
Open Android Studio and add the SDK GeoSpark.aar
as a module using File > New > New Module > Import .JAR/.AAR Package.
Once Gradle is finished click File > Project Structure again.
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.
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 }}
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.
GeoSpark.initialize(this, "YOUR SDK KEY GOES HERE")
GeoSpark.initialize(this, "YOUR SDK KEY GOES HERE");
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.
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()}})
GeoSpark.createUser("SET USER DESCRIPTION HERE", new GeoSparkCallback() {@Overridepublic void onSuccess(GeoSparkUser geosparkUser) {// do something when create user success// access geospark user id with geosparkUser.getUserId()// access geospark user description with geosparkUser.getDescription()}@Overridepublic 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.
GeoSpark.setDescription("SET USER DESCRIPTION HERE")
GeoSpark.setDescription("SET USER DESCRIPTION HERE");
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.
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()}})
GeoSpark.getUser("GEOSPARK USER ID", new GeoSparkCallback() {@Overridepublic void onSuccess(GeoSparkUser geosparkUser) {// do something when get user success// access geospark user id with geosparkUser.getUserId()// access geospark user description with geosparkUser.getDescription()}@Overridepublic void onFailure(GeoSparkError error) {// do something when get user failure// access geospark error code with error.getCode()// access geospark error message with error.getMessage()}});
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.
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}})
GeoSpark.toggleListener(locations, events, new GeoSparkCallback() {@Overridepublic void onSuccess(GeoSparkUser geosparkUser) {// do something when toggle listener success// access locations listener status with geosparkUser.getLocationListenerStatus()// access events listener status with geosparkUser.getEventListenerStatus()}@Overridepublic void onFailure(GeoSparkError geosparkError ) {// do something when toggle listener failure}});
To start tracking the location below Android 10.
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()}
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()}
GeoSpark.startTracking(TrackingMode)
GeoSpark.startTracking(TrackingMode);
Use the tracking modes while you use the startTracking method GeoSpark.startTracking
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 |
// active trackingGeoSpark.startTracking(GeoSparkTrackingMode.ACTIVE)// balanced trackingGeoSpark.startTracking(GeoSparkTrackingMode.BALANCED)// passive trackingGeoSpark.startTracking(GeoSparkTrackingMode.PASSIVE)
// active trackingGeoSpark.startTracking(GeoSparkTrackingMode.ACTIVE);// balanced trackingGeoSpark.startTracking(GeoSparkTrackingMode.BALANCED);// passive trackingGeoSpark.startTracking(GeoSparkTrackingMode.PASSIVE);
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:
//Update location based on distance between locations.val trackingMode = GeoSparkTrackingMode.Builder("DISTANCE IN METERS", "STATIONARY DURATION IN SECONDS").setDesiredAccuracy(GeoSparkTrackingMode.DesiredAccuracy.HIGH).build()
//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:
//Update location based on time interval.val trackingMode = GeoSparkTrackingMode.Builder("INTERVAL IN SECONDS").setDesiredAccuracy(GeoSparkTrackingMode.DesiredAccuracy.HIGH).build()
//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.
To stop the tracking use the below method.
GeoSpark.stopTracking()
GeoSpark.stopTracking();
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.
val geoSparkPublish = GeoSparkPublish.Builder().build()GeoSpark.publishAndSave(geoSparkPublish)
GeoSparkPublish geoSparkPublish = new GeoSparkPublish.Builder().build();GeoSpark.publishAndSave(geoSparkPublish);
To stop publishing locations.
GeoSpark.stopPublishing()
GeoSpark.stopPublishing();
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.
GeoSpark.subscribe(TYPE, "USER-ID")
GeoSpark.subscribe(TYPE, "USER-ID");
GeoSpark.unSubscribe(TYPE, "USER-ID")
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. |