Methods for Android app | Damoov Developer Docs

SDK initialization

Initialize the SDK once in the main application process, preferably in the Application class.

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        TrackingApi.getInstance().initialize(this)
    }
}

You can check whether initialization has completed:

val isInitialized = TrackingApi.getInstance().isInitialized()

Log in

Set the device ID received from your backend, then enable the SDK. The device ID must be a valid GUID. It is stored by the SDK and does not need to be set again after every application launch.

val trackingApi = TrackingApi.getInstance()
val deviceId = getDeviceIdFromYourBackend() // Must be a valid GUID
trackingApi.setDeviceID(deviceId)

if (trackingApi.areAllRequiredPermissionsAndSensorsGranted()) {
    trackingApi.setEnableSdk(true)
}

Log out

Logout disables the SDK, clears the device ID, Properties, and Sub-units.

trackingApi.logout()

Enable/Disable SDK

Enable SDK

val trackingApi = TrackingApi.getInstance()
if (trackingApi.areAllRequiredPermissionsAndSensorsGranted()) {
    trackingApi.setEnableSdk(true)
}

Disable SDK

Starting from 3.0.0, disabling the SDK triggers the following actions:

stops tracking
stops heartbeats
forces unsent data upload
disables the SDK

trackingApi.setEnableSdk(false)

Disabling the SDK does not clear the device ID. Use logout() when the user signs out.

Check SDK status

val isSdkEnabled = trackingApi.isSdkEnabled()

After setEnableSdk(false), the SDK may finish uploading pending data before it is fully disabled:

val isDisablePending = trackingApi.isSdkDisablePending()

Check required permissions status

Check both Android permissions and required device settings such as Location and battery optimization:

val isReady = trackingApi.areAllRequiredPermissionsAndSensorsGranted()

To check Android runtime permissions only:

val permissionsGranted = trackingApi.areAllRequiredPermissionsGranted()

Enable/ Disable Tracking

These methods are not applicable to Android. Use Enable/Disable SDK.

Manual start/ stop tracking

Tracking mode overview

TrackingMode.Persistent

In this mode, all tracks started in both manual and automatic modes will be 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 will be recorded as standard. Track recording continues until trackingApi.stopTracking() is called or the motion stop detector is triggered.

Set tracking mode

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

Get tracking mode

val mode = 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()

Manual start

trackingApi.startTracking()

trackingApi.startTracking() starts tracking using the currently configured TrackingMode.

Manual stop

trackingApi.stopTracking()

Start a persistent track once

trackingApi.startTrackAsPersistent()

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

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

Check current track state

val isTracking = trackingApi.isTracking()

Get tracking state

val trackingState = trackingApi.getTrackingState()

Response:

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

enum class TrackingStatus {
    ENABLED,
    DEVICE_ID_NOT_SET,
    SDK_DISABLED,
    DISABLED_BY_SETTINGS,
    DISABLED_BY_SERVER,
    DISABLED_BY_SCHEDULE
}

Trip metadata

Use trip metadata to associate recorded trips with business entities such as an order, driver, vehicle, or shift.

Properties

Properties are a persistent flat key-value map attached to trips. Calling setProperties() replaces the whole map.

When Properties change during an active trip, the SDK completes the current trip and starts a new one with the updated Properties. Passing the same map does not restart tracking. Properties remain active for subsequent trips until replaced or cleared.

Set Properties

trackingApi.setProperties(
    mapOf(
        "order_id" to "12345",
        "shift" to "morning"
    )
)

Get Properties

val properties = trackingApi.getProperties()

Clear Properties

trackingApi.clearProperties()

Properties must contain from 1 to 20 entries. Keys and values must be non-blank and no longer than 255 characters. Use clearProperties() to remove all Properties.

Sub-units

Sub-units are a persistent flat key-value map for analytical trip classification, for example a driver, vehicle, or session.

Updating or clearing Sub-units does not restart an active trip. Changes made during tracking apply to the next trip. Sub-units remain active until replaced or cleared.

Set Sub-units

trackingApi.setSubUnits(
    mapOf(
        "DriverId" to "D-001",
        "VehicleId" to "V-042"
    )
)

Get Sub-units

val subUnits = trackingApi.getSubUnits()

Clear Sub-units

trackingApi.clearSubUnits()

Sub-units must contain from 1 to 5 entries. Keys and values must be non-blank and no longer than 255 characters. Use clearSubUnits() to remove all Sub-units.

Properties and Sub-units are cleared automatically on logout() or when the device ID is cleared or changed.

Activity Log

Use Activity Log to attach business events to the current active trip without stopping or splitting it, for example a delivery, checkpoint, or depot arrival.

trackingApi.addActivityLog(
    text = "Delivered order #101",
    data = mapOf("order_id" to "101")
)

The data parameter is optional:

trackingApi.addActivityLog(text = "Arrived at depot")

Activity Log entries can be added only while tracking is active. Each trip supports up to 100 entries. The text parameter must be non-blank and no longer than 1,000 characters. The optional data map supports up to 20 entries; its keys and values must be non-blank and no longer than 255 characters.

The SDK attaches the last known location when available. The call may take up to one second, so call it from a background thread when blocking the calling thread would affect the UI.

When Properties change during tracking, existing Activity Log entries remain attached to the completed trip. The new trip starts with an empty Activity Log.

Device ID registration state

val deviceIdRegistrationState = trackingApi.getDeviceIdRegistrationState()

Response:

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

checkedAtMillis contains the Unix timestamp in milliseconds of the latest registration check. It is null until the status has been checked.

enum class DeviceIdRegistrationStatus {
    NOT_SET,
    UNKNOWN,
    REGISTERED,
    NOT_REGISTERED
}

SDK version

val sdkVersion = trackingApi.getSdkVersion()

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

Enable or disable Accident Detection

Accident Detection is disabled by default. Enable the SDK before changing this setting.

trackingApi.setAccidentDetectionEnabled(true)
trackingApi.setAccidentDetectionEnabled(false)

Check the current state:

val enabled = trackingApi.isAccidentDetectionEnabled()

Accident Detection Sensitivity

Set sensitivity

trackingApi.setAccidentDetectionMode(AccidentDetectionSensitivity.Normal)

Sets the sensitivity level for accident detection.

Available values:

AccidentDetectionSensitivity.Sensitive
AccidentDetectionSensitivity.Normal
AccidentDetectionSensitivity.Tough

Reset accident detection settings

trackingApi.resetAccidentDetectionSettings()

Get the current settings:

val settings = trackingApi.getAccidentDetectionSettings()

Passive detection

Check passive detection state

val enabled = trackingApi.isPassiveDetectionEnabled()

Enable or disable passive detection

trackingApi.setPassiveDetectionEnabled(true)
trackingApi.setPassiveDetectionEnabled(false)

Future Tags (deprecated)

The Future Tag APIs are deprecated in 4.1.0:

addFutureTrackTag()
getFutureTrackTags()
removeFutureTrackTag()
removeAllFutureTrackTags()

Use Properties for persistent trip metadata instead.

Get tracks

/**
 * Returns tracks information. Tracks are cached in local DB.
 *
 * @param locale Language in which tracks are to arrive.
 * @param startDate Start date format "yyyy-MM-dd'T'HH:mm:ss ZZ" or null.
 * @param endDate End date format "yyyy-MM-dd'T'HH:mm:ss ZZ" or null.
 * @param offset Offset number for pagination.
 * @param limit Maximum number of items for pagination.
 */

// IMPORTANT! Do not call this method on the Main thread.
fun getTracks(
    locale: Locale,
    startDate: String? = null,
    endDate: String? = null,
    offset: Int,
    limit: Int
): Array<Track>

Response

data class Track(
    var addressStart: String?,
    var addressEnd: String?,
    var endDate: String?,
    var startDate: String?,
    var trackId: String?,
    var accelerationCount: Int,
    var decelerationCount: Int,
    var distance: Double,
    var duration: Double,
    var rating: Double,
    var phoneUsage: Double,
    var originalCode: String?,
    var hasOriginChanged: Boolean,
    var midOverSpeedMileage: Double,
    var highOverSpeedMileage: Double,
    var drivingTips: String?,
    var shareType: String?,
    var cityStart: String?,
    var cityFinish: String?,
    var ratingCornering: Double,
    var ratingAcceleration: Double,
    var ratingBraking: Double,
    var ratingSpeeding: Double,
    var ratingPhoneDistraction: Double,
    var ratingTimeOfDay: Double,
    var rating100: Double,
    var ratingCornering100: Double,
    var ratingAcceleration100: Double,
    var ratingBraking100: Double,
    var ratingSpeeding100: Double,
    var ratingPhoneDistraction100: Double,
    var ratingTimeOfDay100: Double,
    val addressStartParts: AddressParts?,
    val addressFinishParts: AddressParts?,
    val tags: Array<TrackTag>?
)

data class AddressParts(
    var countryCode: String?,
    var country: String?,
    var county: String?,
    var postalCode: String?,
    var state: String?,
    var city: String?,
    var distinct: String?,
    var street: String?,
    var house: String?
)

data class TrackTag(
    var name: String? = null,
    var sourceType: String? = null,
    var source: String? = null
)

Get trip details

/**
 * Returns detailed track information. Track details are cached in local DB.
 *
 * @param locale Language in which track data should be returned.
 * @param trackId Track ID.
 */

// IMPORTANT! Do not call this method on the Main thread.
fun getTrackDetails(trackId: String, locale: Locale): TrackDetails

Response

data class TrackDetails(
    val addressStart: String?,
    val addressEnd: String?,
    val endDate: String?,
    val startDate: String?,
    val trackId: String?,
    val accelerationCount: Int,
    val decelerationCount: Int,
    val distance: Double,
    val duration: Double,
    val rating: Double,
    val phoneUsage: Double,
    val originalCode: String?,
    val hasOriginChanged: Boolean,
    val midOverSpeedMileage: Double,
    val highOverSpeedMileage: Double,
    val points: Array<TrackPoint>?,
    val drivingTips: String?,
    val shareType: String?,
    val cityStart: String?,
    val cityFinish: String?,
    val ratingCornering: Double,
    val ratingAcceleration: Double,
    val ratingBraking: Double,
    val ratingSpeeding: Double,
    val ratingPhoneDistraction: Double,
    val ratingTimeOfDay: Double,
    val rating100: Double,
    val ratingCornering100: Double,
    val ratingAcceleration100: Double,
    val ratingBraking100: Double,
    val ratingSpeeding100: Double,
    val ratingPhoneDistraction100: Double,
    val ratingTimeOfDay100: Double,
    val addressStartParts: AddressParts?,
    val addressFinishParts: AddressParts?,
    val tags: Array<TrackTag>?
)

Change transportation type

/**
 * Allows you to change the track type to a type from the dictionary.
 *
 * @param trackToken Track ID
 * @param newCode New track type code from the track origin dictionary.
 */
fun changeTrackOrigin(trackToken: String, newCode: String): Boolean

Dictionary

OriginalDriver
Passenger
Bus
Motorcycle
Train
Taxi
Bicycle
Other

Upload unsent trips

The SDK uploads trips automatically. Use this method to request an immediate upload of locally stored unsent trips:

trackingApi.uploadUnsentTrips()

Get unsent trips

val unsentTrips = trackingApi.getUnsentTrips()

Get only the number of unsent trips:

val unsentTripCount = trackingApi.getUnsentTripCount()

Send a custom heartbeat

trackingApi.sendCustomHeartbeats(reason = "CustomHeartbeat")