Android SDK Integration

Latest Release (Version 5.1.17)

Change Logs

GSON Parsing crash fix

Requirements

Android 4.4+ (API Level 19+)
The App must have legitimate interest in collecting users location data

Integration

Step 1 - Obtain GT Access Key & Password
Your account manager will provide you with a unique access_key & password.
If you have not received them, please contact your GT account manager.

Step 2 - Adding the Location SDK to your Project
a) Please add the following in your top-level build.gradle file:

allprojects {
    repositories {
        jcenter()
        google()
        maven {
            url "https://packages.weatherbug.net/groundtruth-maven"
        }
    }
}

b) Add the following line to the dependencies element in your application module’s build.gradle.

dependencies {
    implementation 'com.groundtruth.sdk:locationsdk:5.1.17'
}

c) Add the following in your application module’s build.gradle under android.

android {
  ...
	compileOptions {
		sourceCompatibility JavaVersion.VERSION_1_8
		targetCompatibility JavaVersion.VERSION_1_8
	}
  ...
}

d) Sync your Gradle project to ensure that the dependency is downloaded by the build system.

Step 3 - Granting Permissions
a) Required Permissions: Location SDK is strongly dependent on the location permissions. Including them will allow the Location SDK to initialise.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- for Android Q and above only -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

b) Optional Permissions: It is used to evaluate whether a user is stationary or not. This is not a mandatory permission; however, including it will enable SDK to work more accurately.

<!-- for Android Q and above only --> 
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />

To ask these runtime permissions in Android, please follow this https://developer.android.com/training/permissions/requesting

Step 4 - Initialize Location SDK
After granting the runtime permissions, have your app initialize the Location SDK.

Here's an example of how to initialize the Location SDK in an Activity:

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    // Initialize the SDK
    LocationSDK.Builder(this)
      
                // Your account's Access Key and Password (Required) 
                .with(ACCESS_KEY, AES_PASSWORD)
                    
                // Start the Location SDK (Required)   
                .start()
   ...
 }

@Override
protected void onCreate(Bundle savedInstanceState) {
  ...
  // Initialize the SDK
  new LocationSDK.Builder(this)
      
                // Your account's Access Key and Password (Required) 
                .with(ACCESS_KEY, AES_PASSWORD)
                    
                // Start the Location SDK (Required)   
                .start();
  ...
}

You are done with the basic integration of the Location SDK!!

Additional Options

Add User Information
The user's birthday and gender can be shared with the Location SDK. Here's an example of how to add the user information in an Activity:

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    // Initialize the SDK
    LocationSDK.Builder(this)
                .with(ACCESS_KEY, AES_PASSWORD)

                // Add user information
                .setBirthday(1988, Month.APR, 15)
                .setGender(Gender.Female)
                     
                .start()
   ...
 }

@Override
protected void onCreate(Bundle savedInstanceState) {
  ...
  // Initialize the SDK
  new LocationSDK.Builder(this)
                .with(ACCESS_KEY, AES_PASSWORD)

                // Add user information
                .setBirthday(1988, Month.APR, 15)
                .setGender(Gender.Female)
                     
                .start();
  ...
}

Stop the Location SDK
In order to stop the SDK's background service, call LocationSDK.getInstance(this).stop() in the onDestroy() function.
This is optional since Location SDK can run in the background indefinitely.

override fun onDestroy() {
  ...
  LocationSDK.getInstance(this).stop()
  ...
}

@Override
protected void onDestroy() {
  ...
  LocationSDK.getInstance(this).stop();
  ...
}

Enable Logs
This option can be used to check the Location SDK status logs. Here's an example of how to enable logs in an Activity:

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    // Initialize the SDK
    LocationSDK.Builder(this)
                .with(ACCESS_KEY, AES_PASSWORD)

                // Enable logs
                .enableLogs()
                     
                .start()
   ...
 }

@Override
protected void onCreate(Bundle savedInstanceState) {
  ...
  // Initialize the SDK
  new LocationSDK.Builder(this)
                .with(ACCESS_KEY, AES_PASSWORD)

                // Enable logs
                .enableLogs()
                      
                .start();
  ...
}

You can download sample app from here GTLocationSDKDemo

Troubleshooting and FAQs

Multidex
When your app and the libraries it references exceed 65,536 methods, you encounter a build error that indicates your app has reached the limit of the Android build architecture.

You can enable Multidex by following this guide: https://developer.android.com/studio/build/multidex