Guides
SIGN INSIGN UP

SDK for Android app

Introduction

Here you can find a short video guide on how to add Telematics SDK to your Android app:

AI agent integration skill

We provide an AI agent skill that helps integrate Damoov TelematicsSDK into Android applications. The skill can guide coding agents such as Claude Code, OpenAI Codex, and other AI coding tools through verified TelematicsSDK integration patterns, including dependency setup, lifecycle forwarding, tracking flows, tags, and migration away from deprecated APIs.

Skill repository: Mobile-Telematics/telematics-sdk-skills.

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 2.0.48, the Telematics SDK requires AndroidX.

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

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

Add the SDK dependency:

implementation "com.telematicssdk:tracking:4.0.0"

Information about the latest version is available in the changelog.

Proguard

-keep public class com.telematicssdk.tracking.** {*;}

Supported Android versions

Minimum supported Android SDK version is 23.
Target SDK 36 is supported.

compileSdkVersion 36
defaultConfig {
    minSdkVersion 23
    targetSdkVersion 36
}

If you use build.gradle.kts, add:

android {
    packaging {
        resources {
            excludes += setOf(
                "META-INF/INDEX.LIST",
                "META-INF/io.netty.versions.properties"
            )
        }
    }
}

If you use build.gradle, add:

android {
    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}

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 Application, inside onCreate().

Create a Settings instance

This object will be used in the next step.

Settings() creates an instance with the following default values:

  • accuracy = Settings.accuracyHigh (100 meters)
  • stopTrackingTimeout = Settings.stopTrackingTimeHigh (5 minutes)
  • autoStartOn = true
  • adOn = false
  • passiveDetectionOn = false

To change these values, use the builder functions shown below.

val settings = Settings()
    .accuracy(Settings.accuracyHigh)
    .stopTrackingTimeout(Settings.stopTrackingTimeHigh)
    .autoStartOn(true)
    .adOn(false)
    .passiveDetectionOn(false)

Builder functions:

  • accuracy(value: Int) sets the parking radius / location accuracy threshold used by the SDK. Available presets are Settings.accuracyLow, Settings.accuracyNormal, and Settings.accuracyHigh.
  • stopTrackingTimeout(value: Int) sets the timeout in minutes used before stopping tracking after motion inactivity. Available presets are Settings.stopTrackingTimeLow, Settings.stopTrackingTimeNormal, and Settings.stopTrackingTimeHigh.
  • autoStartOn(value: Boolean) enables or disables automatic track start.
  • adOn(value: Boolean) enables or disables accident detection.
  • passiveDetectionOn(value: Boolean) enables or disables passive detection.

The old Settings(...) constructors with HF and ELM parameters are not used in 4.0.0.

Create a TrackingApi instance

Initialize the object using the previously created Settings object:

TrackingApi.getInstance().initialize(context, settings)

Requesting permissions

The SDK declares the following permissions in its Android manifest:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

Important:

  • These permissions are merged into your application during build via the Android manifest merge process.
  • The final set of permissions may be affected by other dependencies in your project.
  • The SDK does not apply any maxSdkVersion restrictions to these permissions.

If any permission is:

  • removed
  • restricted, for example via maxSdkVersion
  • overridden by another dependency

it may lead to runtime crashes or incorrect SDK behavior.

Always verify the merged manifest after integrating or updating the SDK.

Runtime permissions

Make sure you request runtime permissions before enabling the SDK.

Required runtime permissions

android.Manifest.permission.ACCESS_FINE_LOCATION
android.Manifest.permission.ACCESS_COARSE_LOCATION
android.Manifest.permission.ACCESS_BACKGROUND_LOCATION // Android 10+ (Q)
android.Manifest.permission.ACTIVITY_RECOGNITION       // Android 10+ (Q)
android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS

Without these permissions, the SDK cannot be enabled.

The SDK has a built-in Permissions Wizard and a Permissions Dialog that are fully customizable. Both options are aligned with the Google Play policy.

Setting up the permission wizard

If you want to use your own permission request flow, you can skip this part.

To start the Permissions Wizard from your activity or fragment:

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

Then handle the result in onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
   super.onActivityResult(requestCode, resultCode, data)
   if (requestCode == PermissionsWizardActivity.WIZARD_PERMISSIONS_CODE) {
       when (resultCode) {
           WIZARD_RESULT_ALL_GRANTED -> {
               enableSDK()
           }
           WIZARD_RESULT_CANCELED -> {
               Toast.makeText(this, "Wizard closed!", Toast.LENGTH_SHORT).show()
           }
           WIZARD_RESULT_NOT_ALL_GRANTED -> {
               Toast.makeText(this, "Not all required permissions granted!", Toast.LENGTH_SHORT).show()
           }
       }
   }
}

Learn more about Permissions Wizard and Permissions Dialog in Wizard for Android apps.

Enabling and disabling the SDK

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

  1. Add the DeviceToken
  2. Enable the SDK

Empty or null DeviceToken is not allowed.

val trackingApi = TrackingApi.getInstance()
if (trackingApi.isAllRequiredPermissionsAndSensorsGranted()) {
   trackingApi.setDeviceID("DeviceToken")
   trackingApi.setEnableSdk(true)
}

The setEnableSdk(enable: Boolean, withCheckingPermissions: Boolean) overload is not available in 4.0.0.

To disable the SDK:

trackingApi.setEnableSdk(false)

Tracking modes

Version 4.0.0 adds explicit tracking mode control.

Set tracking mode

trackingApi.setTrackingMode(TrackingMode.Persistent)
trackingApi.setTrackingMode(TrackingMode.Standard)

Get tracking mode

val trackingMode = trackingApi.getTrackingMode()

Configure persistent tracking interval

The allowed interval is from 5 to 600 minutes. The default interval is 240 minutes (4 hours).

trackingApi.setMaxPersistentTrackingInterval(240)
val maxInterval = trackingApi.getMaxPersistentTrackingInterval()

Start tracking

trackingApi.startTracking()

startTracking() starts tracking using the current TrackingMode.

Start a persistent track once

trackingApi.startTrackAsPersistent()

startTrackAsPersistent() starts a persistent track once in manual mode, regardless of the configured TrackingMode.

startPersistentTracking() is deprecated in 4.0.0. Use startTrackAsPersistent() instead.

Stop tracking

trackingApi.stopTracking()

Read tracking state

val trackingState = trackingApi.getTrackingState()

Read device ID registration state

val deviceIdRegistrationState = trackingApi.getDeviceIdRegistrationState()

Additional SDK state APIs

Get SDK version

val sdkVersion = trackingApi.getSdkVersion()

Passive detection

val enabled = trackingApi.isPassiveDetectionEnabled()
trackingApi.setPassiveDetectionEnabled(true)

Log out

SDK exists as a part of the host app and follows the same session rules. When a user logs out from the host app, log out from the SDK as well:

trackingApi.logout()

This clears the DeviceID, disables the SDK, and stops tracking-related processing safely.

Update SDK

We regularly announce critical SDK updates to users registered in DataHub. Stay in touch using the detailed changelog:

https://docs.telematicssdk.com/changelog/sdk-for-android

Update the dependency version in build.gradle:

implementation "com.telematicssdk:tracking:4.0.0"

Removed legacy integration items

The following are no longer part of the 4.0.0 integration flow:

  • ELM / Bluetooth OBD setup
  • Advertising ID methods
  • HF-related Settings parameters
  • Bluetooth permission handling

Bluetooth-related permissions are already removed from the SDK, so you do not need to remove anything else from your app-level manifest for this feature.