Guides
SIGN INSIGN UP

SDK for Android app

Download the Android Telematics SDK and install it in your environment

Suggest Edits

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

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 31. Target version 34 is supported starting from SDK version 2.2.260

...
compileSdkVersion 34
defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
        ...
}
...

Setting up the SDK

This stage consists of three steps

  • Initialization
  • Request permissions
  • Enable/Disable SDK

Initialization

❗️

Initialize the SDK in a class that extends the Application, within the onCreate method

Initialize the SDK in a class that extends the Application, within the onCreate method. This is a crucial step for Android development, as the Application class serves as the base class for maintaining global application state. Placing the SDK initialization in the onCreate method of this class ensures that it is properly set up before the app starts and any activity is created. This approach helps in managing the lifecycle of the entire application effectively, making your app more stable and efficient

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.
* isAdOn - false to keep accident detection disabled
*/
val settings = Settings(Settings.stopTrackingTimeHigh, Settings.accuracyHigh, true, true, false, false)

If your project doesn't require integration with Bluetooth devices, we suggest removing the FOREGROUND_SERVICE_CONNECTED_DEVICE permission. To fully remove it, please refer to the GUIDE.


Create a TrackingApi instance

Initialize the object using the previously created Settings object

TrackingApi.getInstance().initialize(context, 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

📘

Without these permissions SDK can not be enabled.

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 👇 

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 👉 Wizard for Android apps.

Enabling and Disabling the SDK

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

  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"

Removing Unused Permissions and Redundant Functions

FOREGROUND_SERVICE_CONNECTED_DEVICE

If you do not use connection with Bluetooth devices in your project, we recommend to fully remove FOREGROUND_SERVICE_CONNECTED_DEVICE permission from your application

Manifest

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_HEALTH" />

<uses-permission
    android:name="android.permission.BLUETOOTH_SCAN"
    tools:node="remove" />
<uses-permission
    android:name="android.permission.BLUETOOTH_CONNECT"
    tools:node="remove" />
<uses-permission
    android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE"
    tools:node="remove" />

Application

<service
    android:name="com.raxeltelematics.v2.sdk.services.main.SdkService"
    android:foregroundServiceType="dataSync|location|health"
    android:enabled="true"
    android:exported="false"
    tools:replace="android:foregroundServiceType" />

Updated 2 months ago

Next Steps