Guides
SIGN INSIGN UP

SDK for Android app

Download the Android Telematics SDK and install it in your environment

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, trip metadata, and migration away from deprecated APIs.

Skill repository: Mobile-Telematics/damoov-telematics-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.1.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.
Compile SDK version is 37.
Target SDK 36 is supported.

compileSdkVersion 37
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 and device settings

Make sure you request runtime permissions and enable the required device settings 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)

Device location must be enabled. The app must also be excluded from battery optimization for reliable SDK startup and background tracking. android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS must remain in the merged manifest so the system battery optimization screen can be opened. It is a manifest permission, not a runtime permission.

On Android 13 and later, request android.Manifest.permission.POST_NOTIFICATIONS separately so the SDK foreground service notification can be displayed. This permission does not block SDK enablement and is not requested by the Permissions Wizard.

The Permissions Wizard handles device location, foreground and background location, Physical Activity, and battery optimization.

The SDK provides a full Permissions Wizard activity, a status-only DialogFragment, and a status-only Compose dialog. Wizard text can be customized through Android string resources, and the UI supports System, Light, and Dark themes. These 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.

Register an Activity Result launcher in your activity or fragment:

private val permissionsWizardLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    when (result.resultCode) {
        TrackingPermissionsWizardActivity.WIZARD_RESULT_ALL_GRANTED -> {
            // Required permissions and device settings are ready.
        }
        TrackingPermissionsWizardActivity.WIZARD_RESULT_CANCELED,
        TrackingPermissionsWizardActivity.WIZARD_RESULT_NOT_ALL_GRANTED -> {
            // At least one required item is still unavailable.
        }
    }
}

Launch the wizard:

permissionsWizardLauncher.launch(
    TrackingPermissionsWizardActivity.getStartWizardIntent(
        context = this,
        themeMode = TrackingPermissionsWizardThemeMode.System,
        blockEarlyExit = false,
        skipWizardPages = false
    )
)

blockEarlyExit prevents closing the wizard before all required items are available. skipWizardPages opens the status screen directly.

To show the status-only DialogFragment from an AppCompatActivity:

TrackingPermissionsWizardStatusDialogFragment
    .newInstance(
        themeMode = TrackingPermissionsWizardThemeMode.System,
        blockEarlyExit = false
    )
    .show(
        supportFragmentManager,
        TrackingPermissionsWizardStatusDialogFragment.TAG
    )

To show the status-only dialog from a Compose screen:

var showPermissionsStatus by rememberSaveable { mutableStateOf(true) }

if (showPermissionsStatus) {
    TrackingPermissionsWizardStatusDialog(
        themeMode = TrackingPermissionsWizardThemeMode.System,
        blockEarlyExit = false,
        onDismissRequest = { showPermissionsStatus = false }
    )
}

Both status dialogs display all required items and let the user fix missing permissions or device settings. blockEarlyExit = true prevents dismissal until all required items are available.

The legacy PermissionsWizardActivity and PermissionsDialogFragment APIs are deprecated in 4.1.0.

Learn more about the activity, DialogFragment, and Compose dialog options in Wizard for Android apps.

Enabling and disabling the SDK

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

  1. Set the DeviceID
  2. Enable the SDK

DeviceID must be a valid non-empty GUID.

val trackingApi = TrackingApi.getInstance()
if (trackingApi.areAllRequiredPermissionsAndSensorsGranted()) {
   trackingApi.setDeviceID(deviceId)
   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()

Returns the full SDK version in major.minor.patch.build format, for example 4.1.0.15.

Passive detection

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

Trip metadata

Version 4.1.0 adds three trip metadata features:

  • Properties attach persistent metadata to trips. Updating Properties during an active trip completes the current trip and starts a new one.
  • SubUnits classify trips, for example by driver, vehicle, or session, without splitting the active trip.
  • Activity Log records business events within an active trip without stopping or splitting it.

Use setProperties(), setSubUnits(), and addActivityLog() to add this data. Future Track Tag APIs are deprecated; use Properties for trip metadata instead.

Learn more in Methods for Android apps.

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

Updated 20 days ago

Next Steps

Did this page help you?