SDK for Android app

Download the Android Telematics SDK and install it in your environment

Introduction

Here you can find a short video guide, how to add Telematics SDK to your Android 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"

Information about the latest version is available in changelog

Proguard:

-keep public class com.raxeltelematics.** {*;}

For the new versions of the SDK you can face an issue like this:

Annotation processors must be explicitly declared now. The following dependencies on the compile classpath are found to contain annotation processor. Please add them to the annotationProcessor configuration.
 - classes.jar (com.telematicssdk:tracking:x.x.xxx)

Alternatively, set android.defaultConfig.javaCompileOptions.annotationProcessorOptions.includeCompileClasspath = true to continue with previous behavior.  Note that this option is deprecated and will be removed in the future

To resolve this issue just update your gradle version or specify this parameter in the build.gradle file of the app:

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

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

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

🚧

deviceToken

Empty or nil DeviceToken is not allowed.
To get a unique deviceToken for each user, you need to

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

Update SDK

We regularly make announcement emails for all registered in DataHub users about new critical SDK updates.
Stay in touch with the help of our detailed Changelog: https://docs.telematicssdk.com/changelog/sdk-for-android

  • follow to build.gradle
  • enter the actual SDK number (from Changelog)
implementation "com.telematicssdk:tracking:$SdkVersion"

Did this page help you?