03/13/2019 Version 3.0.4 released:
- Fixed a bug in the SDK's LocationComponent (potentially affected 2% of all users)
- Fixed a bug in the SDK's LocationService
- Added null checks and exception handling (did not affect SDK's functionality)
10/11/2018 Version 3.0.3 released:
- New SDK logic for improving coverage, data accuracy and performance (reduced battery consumption and background activity)
Requirements
- Android 4.4+ (API Level 19+)
- The App must have legitimate interest in collecting users location data
Step 1 - Obtain GT Access Key & Password
your account manager will provide you will a unique access_key & password.
If you did not receive them, please contact your GT account manager before integrating.
Step 2 - Import SDK AAR file
Please add following maven URL in build.gradle of your project:
allprojects {
repositories {
jcenter()
maven {
url "https://groundtruth.bintray.com/pubsvcs/"
}
google()
}
}Grab the AAR from Maven Central by adding it as a dependency in your build.gradle file:*
dependencies {
...
implementation 'com.groundtruth.sdk:locationsdk:3.0.4'
implementation 'com.firebase:firebase-jobdispatcher:0.8.5'
implementation 'com.squareup.okhttp3:okhttp:3.4.1'
implementation 'com.google.android.gms:play-services-ads:12.0.0'
implementation 'com.google.android.gms:play-services-maps:12.0.0'
implementation 'com.google.android.gms:play-services-location:12.0.0'
implementation 'com.google.code.gson:gson:2.7'
...
}Step 3(a) - for Android versions earlier than Android M (Android SDK version < 23):
In the MainActivity class, please call LocationService.start() in the onCreate() function with the provided access_key, password, birthdate (optional), and gender (optional).
protected void onCreate(Bundle savedInstanceState) {
...
new LocationServiceClient(ACCESS_KEY, AES_PASSWORD)
.birthday(1988, LocationServiceClient.ARP, 15)
.gender(Gender.Female)
.start(this);
...
}Important
Since the Location SDK will be running as a background service, it's neither necessary nor safe to start it more than once. Please do not place LocationServiceClient.start() and LocationServiceClient.stop() in more than one place.
Step 3(b) - for Android versions Android M or Later (Android SDK version >= 23):
In the MainActivity class, please implement: ActivityCompat.OnRequestPermissionsResultCallback, and create a function named requestPermissionAndStartService() to request permission and start the location service.
protected void onCreate(Bundle savedInstanceState) {
...
//Request location permission and start location service
requestPermissionAndStartService();
}
public void requestPermissionAndStartService() {
if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.M &&
ContextCompat.checkSelfPermission(this,
android.Manifest.permission.ACCESS_FINE_LOCATION)
!= PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this,
new String[]{android.Manifest.permission.ACCESS_FINE_LOCATION}, REQUEST_FOR_LOCATION);
} else {
new LocationServiceClient(ACCESS_KEY, AES_PASSWORD)
.birthday(1988, LocationServiceClient.ARP, 15)
.gender(Gender.Female)
.start(this);
}
...
}
private static final int REQUEST_FOR_LOCATION = 0;
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
if(requestCode == REQUEST_FOR_LOCATION && grantResults.length >= 0 ) {
if(grantResults[0] == PackageManager.PERMISSION_GRANTED) {
new LocationServiceClient(ACCESS_KEY, AES_PASSWORD)
.birthday(1988, LocationServiceClient.ARP, 15)
.gender(Gender.Female)
.start(this);
} else {
if(ActivityCompat.shouldShowRequestPermissionRationale(this,android.Manifest.permission.ACCESS_FINE_LOCATION)) {
//Show dialog to let user be aware of the necessity of location
ActivityCompat.requestPermissions(this,
new String[]{android.Manifest.permission.ACCESS_FINE_LOCATION}, 0);
} else {
//Show dialog to notify user location sdk is not enabled,
//And try to guide user turn on location permission in settings.
}
}
}
}
...
Step 4 - stop the background service (optional):
In order to stop the SDK's background service, call LocationServiceClient.stop() in the onDestroy() function.
This is optional since LocationService can run in the background indefinitely.
protected void onDestroy() {
...
LocationServiceClient.stop(this);
...
}Notes
If you require additional assistance with the integration process, please enable the debugging log by calling: Logger.setLevel(Logger.Level.DEBUG);
Make sure this method is called before enable location service.
COPPA Compliance
GroundTruth is COPPA Compliant. Users age can be passed to the SDK by the App developer, and the SDK will not be initialized for users under the age of 13.
If no birthdate is specified, tracking will be enabled.
GDPR Compliance
Publishers are required to update GT whether a user is subjected to GDPR as well as his consent to their data sharing, in 2 dedicated fields: GDPR and consent.
If the user is from the EU/EEA the publisher must set GDPR to true, otherwise it should be set to false. When the user is from EU/EEA consent must include a value, if not it should be set to null.
Example of user in EU/EEA with a consent string:
new LocationServiceClient(ACCESS_KEY, AES_PASSWORD)
.birthday(1988, LocationServiceClient.ARP, 15)
.gender(Gender.Female)
.enableGDPRWithConsent("Y29uc2VudF9zdHJpbmc=")
.start(this);Consent can be changed with:
LocationServiceClient.setConsent(true, "Y29uc2VudF9zdHJpbmc=");