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.

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

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.

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() {
    @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.

GeoSpark.setDescription("SET USER DESCRIPTION HERE")

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.

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() {
    @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.

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() {
    @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.

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()
}

Location Tracking

Start Tracking

GeoSpark.startTracking(TrackingMode)

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.

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

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

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.

Stop Tracking

To stop the tracking use the below method.

GeoSpark.stopTracking()

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.

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();

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

GeoSpark.subscribe(TYPE, "USER-ID")

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

UnSubscribe

GeoSpark.unSubscribe(TYPE, "USER-ID")

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