Android Migration Guide from SDK 3.x to SDK 4.0.0+

Use this guide when upgrading an existing Android integration from any 3.x version to 4.0.0.

Update dependency

Update the SDK dependency in your app module:

implementation "com.telematicssdk:tracking:4.0.0"

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

Migration Matrix

Settings migration

Replace old constructors with the builder-style API.

Old:

val settings = Settings(
    Settings.stopTrackingTimeHigh,
    Settings.accuracyHigh,
    true,
    true,
    false,
    false
)

New:

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

Settings() default values:

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

Builder functions:

• accuracy(value: Int) sets the parking radius / location accuracy threshold.
• stopTrackingTimeout(value: Int) sets the timeout in minutes used before stopping tracking after motion inactivity.
• 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.

Enable and disable SDK

Old:

trackingApi.setEnableSdk(true, true)

New:

trackingApi.setEnableSdk(true)

To disable the SDK:

trackingApi.setEnableSdk(false)

setDisableWithUpload() is deprecated in 4.0.0. Use setEnableSdk(false).

Tracking modes

4.0.0 adds explicit tracking modes.

TrackingMode.Persistent

In this mode, all tracks started in both manual and automatic modes are recorded as persistent. Track recording continues until trackingApi.stopTracking() is called or the maximum persistent tracking interval is reached.

In this mode, you can manually start a persistent track using either:

trackingApi.startTracking()
trackingApi.startTrackAsPersistent()

TrackingMode.Standard

In this mode, all tracks started in both manual and automatic modes are recorded as standard. Track recording continues until trackingApi.stopTracking() is called or the motion stop detector is triggered.

Set the tracking mode:

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

Read the tracking mode:

val mode = trackingApi.getTrackingMode()

Configure the persistent tracking interval:

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

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

Start a persistent track once:

trackingApi.startTrackAsPersistent()

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

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

New state APIs

Use these APIs instead of app-side inferred state checks.

val trackingState = trackingApi.getTrackingState()
val deviceIdRegistrationState = trackingApi.getDeviceIdRegistrationState()
val sdkVersion = trackingApi.getSdkVersion()

Tracking state response:

data class TrackingState(
    val automaticTrackingStatus: TrackingStatus,
    val manualTrackingStatus: TrackingStatus
)

Device ID registration response:

data class DeviceIdRegistrationState(
    val status: DeviceIdRegistrationStatus,
    val checkedAtMillis: Long?
)

enum class DeviceIdRegistrationStatus {
    UNKNOWN,
    NOT_SET,
    VALID,
    INVALID
}

Removed APIs

Remove these APIs from the host app integration:

• setAdvertisingId(...)
• clearAdvertisingId()
• setElmDevicesEnabled(...)
• isElmDevicesEnabled()
• getElmManager()
• setHfRecordingEnabled(...)
• isHfRecordingOn()
• setEnableSdk(enable, withCheckingPermissions)

Remove ELM / Bluetooth OBD screens, flows, imports, and related business logic. Bluetooth permissions are no longer needed for SDK 4.0.0.

Migration Checklist

• Update the dependency to com.telematicssdk:tracking:4.0.0.
• Make sure the host app uses minSdkVersion 23 or higher.
• Replace old Settings(...) constructors with Settings() and builder functions.
• Remove HF and ELM settings arguments.
• Replace setEnableSdk(enable, withCheckingPermissions) with setEnableSdk(enable).
• Replace setDisableWithUpload() with setEnableSdk(false).
• Remove Advertising ID API calls.
• Remove ELM327 / Bluetooth OBD API calls and UI.
• Replace startPersistentTracking() with startTrackAsPersistent().
• Add setTrackingMode(...) if the app needs explicit standard or persistent mode behavior.
• Add persistent interval configuration if the default 240 minutes is not suitable.
• Use getTrackingState() for tracking status UI or diagnostics.
• Use getDeviceIdRegistrationState() for device ID registration UI or diagnostics.
• Use getSdkVersion() for runtime SDK version checks.
• Remove usage of TrackPoint.vehicleIndicators.
• Update direct DTO imports from old *ServerModel / *Dto names to current *Response / *Request names if the app references them.
• Run a clean build and fix removed-method compile errors.
• Re-test login, SDK enable/disable, automatic tracking, manual tracking, persistent tracking, logout, and trip upload flows.

Notes for apps migrating from v2

If your app is still using old com.raxeltelematics.v2.sdk imports, first migrate imports to:

import com.telematicssdk.tracking...

Then apply the 3.x to 4.0.0 migration steps above.