GroundTruth Documentation

The Groundtruthco Developer Hub

Welcome to the Groundtruthco developer hub. You'll find comprehensive guides and documentation to help you start working with Groundtruthco as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Android SDK Integration

This is the integration document for the GroundTruth Location SDK.

The Location SDK collects location signals from a device on which the publisher app is installed.
Our platform uses the location data for audience creation, ads serving, offline visit attribution and brand insights generation.

Suggest Edits

Changelog

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)

Integration

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

@Override
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.

@Override
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;

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions,@NonNull 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.

@Override
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=");