SDK Interface

Setup and Maven Repository

Project requires Java 17. If necessary, adjust your Java version in your IDE, typically in IDE's File -> Project structure -> SDK Location. Update your project-level settings.gradle file and dependencyResolutionManagement section:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
    repositories {
        // other repositories
        maven {
            name = 'truemetrics SDK'
            url = "https://github.com/TRUE-Metrics-io/truemetrics_android_SDK_p_maven/raw/main"
        }
    }
}

Declare Dependency

Inside your build.gradle add the following dependency:

implementation 'io.truemetrics:truemetricssdk:1.6.0'

Initialize SDK

SDK behaves like a singleton object that manages its own internal state. Initialize it in your Application class:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val config = SdkConfiguration.Builder("YOUR_API_KEY").build()
        TruemetricsSdk.init(this, config)
    }
}

Custom Foreground Notification

The SDK runs as a foreground service and shows a notification while recording. You can customize this notification using the SDK’s notification channel:

class CustomNotificationFactory : ForegroundNotificationFactory {
    override fun createNotification(context: Context): Notification {
        // Use SDK's notification channel ID
        return NotificationCompat.Builder(context, "FOREGROUND_SERVICE")
            .setContentTitle("Truemetrics SDK Running")
            .setContentText("Collecting sensor data...")
            .setSmallIcon(R.drawable.ic_notification)
            .setOngoing(true)
            .build()
    }
}

val config = SdkConfiguration.Builder("YOUR_API_KEY")
    .foregroundNotificationFactory(CustomNotificationFactory())
    .build()

Make sure to ask user for notification permission if device runs Android 13 or later.

Observing SDK Status

Use the observeSdkStatus() Flow to monitor SDK state changes:

val sdk = TruemetricsSdk.getInstance()

sdk.observeSdkStatus().collect { status ->
    when (status) {
        is Status.Uninitialized -> {
            // SDK not yet initialized
        }
        is Status.Initialized -> {
            // SDK initialized, deviceId available
            val deviceId = status.deviceId
        }
        is Status.RecordingInProgress -> {
            // Recording is active
            val deviceId = status.deviceId
        }
        is Status.RecordingStopped -> {
            // Recording has stopped
        }
        is Status.DelayedStart -> {
            // Waiting for auto-start delay
            val deviceId = status.deviceId
            val delayMs = status.delayMs
        }
        is Status.TrafficLimitReached -> {
            // Traffic limit reached
        }
        is Status.ReadingsDatabaseFull -> {
            // Device storage full
        }
        is Status.Error -> {
            // SDK encountered an error
            val errorCode = status.errorCode
            val message = status.message
        }
        is Status.AskForPermissions -> {
            // SDK requesting permissions
            val permissions = status.permissions
        }
    }
}

Error Codes

When Status.Error is received, the errorCode indicates what went wrong:

Error Code	Description
AUTHENTICATION_ERROR	API key is not valid, expired or revoked
UPLOAD_ERROR	Recordings couldn’t be uploaded after exhausting all attempts
STORAGE_FULL	Device storage is full which prevents saving sensor readings
MISSING_NOTIFICATION_PERMISSION	Notification permission not granted, foreground service cannot start
CONFIG_ERROR	Configuration error
TRAFFIC_USED_UP	All allotted traffic has been used
SENSORS_NOT_WORKING	Some sensors are not working. Check if permissions are missing
NOT_INITIALIZED	`startRecording()` was called before `init()`, so there is nothing to record with

Start Recording

val sdk = TruemetricsSdk.getInstance()
sdk.startRecording()

Starting the recording also starts the Foreground service and shows the notification. Recording continues even when the app exits. init() on its own does not start recording. A recording that was started is resumed automatically the next time the app initializes the SDK, so a restart or an app update does not lose it. To have the SDK start on its own instead, configure delayAutoStartRecording — see Recording lifecycle.

Changed in 1.6.0. Releases 1.3.0 through 1.5.x started recording on init() by default. If your app relied on that, pass delayAutoStartRecording(SdkConfiguration.AUTO_START_ON_INIT).

Stop Recording

sdk.stopRecording()

Stopping recording also stops the Foreground service and removes the notification.

Check Recording Status

val isRecording = sdk.isRecordingInProgress()
val isStopped = sdk.isRecordingStopped()
val startTime = sdk.getRecordingStartTime() // milliseconds since epoch

Device ID

Get the unique device identifier (available after initialization):

val deviceId = sdk.getDeviceId()

Log Metadata

Log standardized delivery/pickup event metadata:

import io.truemetrics.truemetricssdk.metadata.StandardMetadata

sdk.logMetadata(StandardMetadata(
    eventTime = "2025-01-15T14:30:00",
    eventType = "delivery_successful",
    deliveryId = "parcel_123",
    tourId = "tour_456",
    waypointLatitude = "52.5200",
    waypointLongitude = "13.4050",
    referenceLatitude = "52.5201",
    referenceLongitude = "13.4051",
    address = "Pflanzstrasse 5, 10762 Berlin"
))

The map-based logMetadata(Map<String, String>) overload is deprecated. Use logMetadata(StandardMetadata) instead. For advanced metadata management with templates and tags, see the metadata chapter.

Statistics API

Monitor upload and sensor health:

// Upload statistics
val uploadStats = sdk.getUploadStatistics()
uploadStats?.let {
    println("Successful uploads: ${it.successfulUploadsCount}")
    println("Last upload: ${it.lastSuccessfulUploadTimestamp}")
}

// Sensor statistics with quality assessment
val sensorStats = sdk.getSensorStatistics()
sensorStats?.forEach { stat ->
    println("Sensor: ${stat.sensorName}")
    println("Quality: ${stat.quality}") // EXCELLENT, GOOD, POOR, BAD, or UNKNOWN
}

Deinitialize SDK

sdk.deinitialize()

De-initialization stops recording if in progress and tears down the SDK. Warning: After calling deinitialize(), the SDK instance becomes unusable. You must call init() again to use the SDK.

Getting Started

SDK integration

Data Export

Last Meter Visualisation

Setup and Maven Repository

Declare Dependency

Initialize SDK

Custom Foreground Notification

Observing SDK Status

Error Codes

Start Recording

Stop Recording

Check Recording Status

Device ID

Log Metadata

Statistics API

Deinitialize SDK

​Setup and Maven Repository

​Declare Dependency

​Initialize SDK

​Custom Foreground Notification

​Observing SDK Status

​Error Codes

​Start Recording

​Stop Recording

​Check Recording Status

​Device ID

​Log Metadata

​Statistics API

​Deinitialize SDK

Setup and Maven Repository

Declare Dependency

Initialize SDK

Custom Foreground Notification

Observing SDK Status

Error Codes

Start Recording

Stop Recording

Check Recording Status

Device ID

Log Metadata

Statistics API

Deinitialize SDK