Android Documentation

Getting started

You can install the SDK using JCenter or manually.

Note: Version 0.0.3 of the GeoSpark SDK requires a minSdkVersion of at least 14.

Installing with Maven

The best way to add the SDK to your project is via Gradle and JCenter in Android Studio. Add the SDK to the dependencies section of your build.gradle file:


  dependencies {
  	compile 'com.geospark.android:geospark:0.0.3'
  }


The SDK depends on Android Support Library library version 26.1.0 and higher (to support android APIs), Play Services Location library version 11.8.0 and higher (for location services), OkHttp library version 3.10.0 and higher (for HTTP networking) and Firebase JobDispatcher library version 0.8.5 and higher (for scheduling jobs). The newest version of these libraries will be automatically included as transitive dependencies.

To exclude transitive dependencies to resolve version conflicts, you can exclude the transitive dependencies from the SDK dependency and include the dependencies separately, then clear your Gradle cache and sync your project. For example:


  dependencies {
  compile 'com.android.support:appcompat-v7:26.1.0'
  compile 'com.google.android.gms:play-services-location:11.8.0'
  compile 'com.firebase:firebase-jobdispatcher:0.8.5'
  compile 'com.squareup.okhttp3:okhttp:3.10.0'
  compile('com.geospark.android:geospark:0.0.3') {
    exclude module: 'support-v7'
    exclude module: 'play-services-location'
    exclude module: 'firebase-jobdispatcher'
    exclude module: 'okhttp'
   }
  }


Manual Installation

You can also add the SDK to your project manually, though this is not recommended. Download the current release and unzip the package. The package contains an aar file. In Android Studio, add the SDK as a module using File > New Module > Import .JAR/.AAR Package.

Once Gradle is finished (only a few seconds), click File > Project Structure again. Click on app, then Dependencies tab, then click the plus icon in the bottom left, select Module dependency, click on GeoSpark, then press Ok and wait for Gradle to sync again.

And include the dependencies separately, then clear your Gradle cache and sync your project.


  dependencies {
	  compile 'com.google.android.gms:play-services-location:11.8.0'
	  compile 'com.firebase:firebase-jobdispatcher:0.8.5'
	  compile 'com.squareup.okhttp3:okhttp:3.10.0'
  }


The SDK currently supports API level 14 and higher.

Initialize the SDK

To initialize the SDK, you must call the GeoSpark.initialize method when your app is started.


  GeoSpark.initialize(context,"YOUR-SDK-KEY","YOUR-SECRET");


You should call this method in your Main Activity's onCreate method. Put in your own sdk key and secret here.

Enable Location and Run-time permissions

To enable location, call the requestPermissions and requestLocationServices method. For Android 6.0 and above, calling this method will trigger a location permission popup that the user has to allow.


  /**
  * Call this method to check Location Settings before proceeding for User
  * Login
  */
     
  if(!GeoSpark.checkPermission(context)) {
	   GeoSpark.requestPermission(this);
  } else if (!GeoSpark.checkLocationServices(context)) {
	   GeoSpark.requestLocationServices(this);
  } else {
	   GeoSpark.startLocationTracking(context);
  }

  @Override
      public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
          switch (requestCode) {
              case GeoSpark.REQUEST_CODE_PERMISSION:
                if (grantResults.length > 0
                        && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    if (ContextCompat.checkSelfPermission(context,
                            android.Manifest.permission.ACCESS_FINE_LOCATION)
                            == PackageManager.PERMISSION_GRANTED) {
                    }
                }
                break;
          }
      }

  @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
          super.onActivityResult(requestCode, resultCode, data);
          if (requestCode == GeoSpark.REQUEST_CODE_LOCATION_ENABLED) {
          }
      }

Set up Firebase and the FCM SDK (Optional)

  1. If you haven't already, add Firebase to your Android project.
  2. In Android Studio, add the FCM dependency to your app-level build.gradle file:
    	
      dependencies {
        compile 'com.google.firebase:firebase-messaging:11.8.0'
      }
    	
    
  3. Add the following to your app's manifest: A service that extends FirebaseInstanceIdService to handle the creation, rotation, and updating of registration tokens. This is required for sending to specific devices or for creating device groups.
    	
      <service>
        android:name=".MyFirebaseInstanceIDService">
        <intent-filter>
            <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
        </intent-filter>
      </service>
    	
    
  4. When you need to retrieve the current token, call FirebaseInstanceId.getInstance().getToken(). This method returns null if the token has not yet been generated.

Create User

The SDK needs an User ID object to identify the device. The SDK has a convenience method createUser() to create a user which returns User ID.

Method parameters
Parameter Description
deviceToken Device Token
  
  //Create a User for given deviceToken on GeoSpark Server. 

  GeoSpark.createUser(context, deviceToken,
    new GeoSparkCallBack() {
            @Override
            public void success(SuccessResponse successResponse) {
               successResponse.getUserID();
                
               // Handle createUser success here, if required
               // On UserLogin success
               onUserLoginSuccess();
            }

            @Override
            public void failure(ErrorResponse errorResponse) {
                // Handle createUser Failure here, if required
                errorResponse.getErrorMessage();
                        
            }
        }); 
  

To set an optional description for the user, displayed in the dashboard, call:

  
  GeoSpark.setDescription(context, description);
  

Get User

If you already have an User ID object. The SDK has a convenience method getUser() to start the session for the existing user.

Method parameters
Parameter Description
userID User ID from your API Server
deviceToken Device Token

  /**
  *Implement your API call for User Login and get back a GeoSpark
  *UserId from your API Server to be configured in the GeoSpark SDK
  *along with deviceToken.
  */

  GeoSpark.getUser(context,userID, deviceToken,
    new GeoSparkCallBack() {
            @Override
            public void success(SuccessResponse successResponse) {
               successResponse.getUserID();
                
               // Handle getUser success here, if required
               // On UserLogin success
               onUserLoginSuccess();
            }

            @Override
            public void failure(ErrorResponse errorResponse) {
                // Handle getUser Failure here, if required
                errorResponse.getErrorMessage();
                        
            }
        });  


Start Location Tracking

To start tracking the location, use the startLocationTracking() method. You can keep SDK to track location, or turn it off if you want to stop tracking the user at any point of time using the stopLocationTracking() method.

	
  GeoSpark.startLocationTracking(context);
	

Location Listener

To listen for location in the background, create a class that extends GeoSparkReceiver. Then, register the receiver by adding a receiver element to the application element in your manifest:

	
  <application android:label="@string/app_name" ...>
	  ...
	<receiver
	    android:name=".MyGeoSparkReceiver"
	    android:enabled="true"
	    android:exported="false">
	    <intent-filter>
	    <action android:name="com.geospark.android.RECEIVED" />
	   	</intent-filter>
	</receiver>
	  ...
  </application>
	

Your receiver should implement the following:

	
  public class MyGeoSparkReceiver extends GeoSparkReceiver {

	  @Override
	  public void onLocationUpdated(Context context, Location location, GeoSparkUser user) {
	    // do something with context, location, user
	  }
  }
	

Stop Location Tracking

You can stop tracking the user at any point of time using the stopLocationTracking() method.

	
  GeoSpark.stopLocationTracking(context);
	

View Dashboard

Install your app with the GeoSpark SDK on a device and begin tracking on the Dashboard. You would see the user's current state on the GeoSpark dashboard. If you click on the user, you should be able to view the user's location history.

Service Notification

Why?

Android O is coming up with restrictions on background updates and GeoSpark SDK needs use of Service Notification which will run as a service and send location updates to GeoSpark SDK.

You can customize this notification by following our below customize guide.

Customize

Use these basic UI customizations to edit the icon or text when the notification will not change dynamically.

Notification icon

You can customise the icons by adding drawable resources in your application with the same name as follows:

  • For the small icon, add an icon with the name ic_gspk_service_notification_small

Notification text

By default, the notification title is "App is running". You can customise the text by adding string resources in your application with the same name as gspk_service_notification_title

	
  <?xml version="1.0" encoding="utf-8"?>
	<resources>
	    <string name="gspk_service_notification_title">App is running </string>
	</resources>