SDK for Android app

Add the Android SDK to your project and include it in your app.

Adding the SDK to your project

While you could manually download and install the SDK, we recommend using Maven to link the SDK into your project.

📘

Since v.2.0.48, the Telematics SDK requires using AndroidX

Minimum supported Android SDK version is 18. Target version is 30

...
defaultConfig {
        minSdkVersion 18
        targetSdkVersion 30
        ...
}
...

Add the SDK to the build.gradle file of your module

maven {
    url "https://s3.us-east-2.amazonaws.com/android.telematics.sdk.production/"
}

and

implementation "com.telematicssdk:tracking:x.x.x"

Setting up the SDK

This stage consist of three steps

  • Initialization
  • Request permissions
  • Enable/Disable SDK

Initialization


Create a Settings instance

This object will be used in the next step

/**
* Default Setting constructor
* Stop tracking time is 5 minute.
* Parking radius is 100 meters.
* Auto start tracking is true.
* hfOn - true if HIGH FREQUENCY data recording from sensors (acc, gyro) is ON and false otherwise.
* isElmOn - true if data recording from ELM327 devices is ON and false otherwise.
*/
val settings = Settings(Settings.stopTrackingTimeHigh, Settings.accuracyHigh, true, true, true)

Create a TrackingApi instance

Initialize the object using the previously created Settings object

// call this in your Application class
val api = TrackingApi.getInstance()
api.initialize(this, settings)

Requesting permissions


🚧

Important

Make sure you request runtime permissions before enabling the SDK, as shown below

android.Manifest.permission.ACCESS_FINE_LOCATION,
android.Manifest.permission.ACCESS_COARSE_LOCATION,
android.Manifest.permission.ACCESS_BACKGROUND_LOCATION (for Android >=10 (Q))
android.Manifest.permission.ACTIVITY_RECOGNITION (for Android >=10 (Q))
android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS

Note that the SDK has a built-in Permissions Wizard and a Permissions Dialog that are fully customizable. Both options are fully aligned with the New Google politics and contain the necessary UI and UX to ask for necessary permissions.

Setting up the permission wizard

📘

if you want to use your own way to request permissions, you can skip this part

To start the Permission Wizard from your activity or fragment, please use the code below :point-down:

startActivityForResult(
       PermissionsWizardActivity
               .getStartWizardIntent(
                       context = this,
                       enableAggressivePermissionsWizard  = false,
                       enableAggressivePermissionsWizardPage  = false
               ),
       PermissionsWizardActivity.WIZARD_PERMISSIONS_CODE
)

And after that you can get the result in onActvityResult method by this way:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
   super.onActivityResult(requestCode, resultCode, data) 
   // don’t forget to call here and in all base activity/fragments
   if (requestCode == PermissionsWizardActivity.WIZARD_PERMISSIONS_CODE) {
       when (resultCode) {
           WIZARD_RESULT_ALL_GRANTED -> {
               /* when user finished wizard with all required permissions
granted - enable SDK if Device ID is exist*/
               enableSDK()
           }
           WIZARD_RESULT_CANCELED -> {
               // when user canceled wizard
               Toast.makeText(this, "Wizard closed!",
Toast.LENGTH_SHORT).show()
           }
           WIZARD_RESULT_NOT_ALL_GRANTED -> {
               /* when user finished wizard with not all required permissions
granted*/
               Toast.makeText(this, "NOT All Required Permissions Granted!",
Toast.LENGTH_SHORT).show()
           }
       }
   }
}

The permission wizard supports flexible UX parameters, including parameters that enforce users to grant permissions. Learn more about Permissions Wizard and Permissions Dialog :point-right: Wizard for Android apps

Enabling and Disabling the SDK


Again, make sure the permissions are requested as described above.
Then,

  1. Add the DeviceToken (line 3),
  • Use a deviceToken of the test SDK user, created via UserDataHub earlier (follow this guide)
  • OR create a user via API (proceed with this guide)
  1. Enable the SDK (line 4)
val trackingApi = TrackingApi.getInstance()
if (trackingApi.isAllRequiredPermissionsAndSensorsGranted()) {
   trackingApi.setDeviceID("DeviceToken") // User DeviceToken
   trackingApi.setEnableSdk(true) //false to disable SDK
}

Log out

SDK exists as a part of the Host app and follows the main rules. Hence, when a user logouts from the host app, you need to log out from the SDK as well. Please follow the procedure described below, otherwise, it can cause the app crash:

  • Disable the SDK
  • Clear the DeviceID.
trackingApi.setEnableSdk(false)
trackingApi.clearDeviceID()

Did this page help you?