Android Native Integration

repositories {
    maven {
        url "https://github.com/TRUE-Metrics-io/truemetrics_android_SDK_p_maven/raw/"
    }
}

dependencies {
    implementation 'io.truemetrics:truemetricssdk:1.5.4'
}

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

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

val sdk = TruemetricsSdk.getInstance()

// Start recording sensor data
sdk.startRecording()

// Stop recording
sdk.stopRecording()

// Check recording status
if (sdk.isRecordingInProgress()) {
    // Recording is active
}

Uninitialized ──► Initializing ──► Initialized
                       │
                       ├──► Error(AUTHENTICATION_ERROR)   (invalid/expired/revoked API key)
                       │
                       └──► stays in Initializing, retrying every 30s
                            (network unreachable, 5xx from backend, timeouts)

import io.truemetrics.truemetricssdk.engine.state.Status
import kotlinx.coroutines.flow.first

suspend fun awaitSdkReady(): String {
    val sdk = TruemetricsSdk.getInstance()
    val ready = sdk.observeSdkStatus().first { status ->
        status is Status.Initialized ||
        status is Status.RecordingInProgress ||
        status is Status.DelayedStart ||
        status is Status.Error
    }
    if (ready is Status.Error) {
        throw IllegalStateException("SDK init failed: ${ready.errorCode} ${ready.message}")
    }
    return sdk.getDeviceId()!!
}

sdk.observeSdkStatus().collect { status ->
    when (status) {
        is Status.Initializing -> showSpinner()
        is Status.Initialized -> enableStartButton(status.deviceId)
        is Status.Error -> showError(status.errorCode, status.message)
        else -> {}
    }
}

if (sdk.getDeviceId() != null) {
    // SDK is initialized
}

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

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_sensors)
            .setOngoing(true)
            .build()
    }
}

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

val sdk = TruemetricsSdk.getInstance()

// Start recording
sdk.startRecording()

// Stop recording
sdk.stopRecording()

// Check recording status
val isRecording = sdk.isRecordingInProgress()
val isStopped = sdk.isRecordingStopped()

// Get recording start time
val startTime = sdk.getRecordingStartTime() // Returns timestamp in milliseconds

val deviceId = sdk.getDeviceId()

// Or get from Status
sdk.observeSdkStatus().collect { status ->
    when (status) {
        is Status.Initialized -> println("Device ID: ${status.deviceId}")
        is Status.RecordingInProgress -> println("Device ID: ${status.deviceId}")
        else -> {}
    }
}

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",
    extra = mapOf("type_vehicle" to "car")
))

// Enable/disable all sensors
sdk.setAllSensorsEnabled(true)

// Check if sensors are enabled
val enabled = sdk.getAllSensorsEnabled()

// Observe available sensors
sdk.sensorInfo.collect { sensors ->
    sensors.forEach { sensor ->
        println("Sensor: ${sensor.sensorName}, Status: ${sensor.sensorStatus}")
        println("Frequency: ${sensor.frequency} Hz")
        if (sensor.missingPermissions.isNotEmpty()) {
            println("Missing permissions: ${sensor.missingPermissions}")
        }
    }
}

sdk.deinitialize()

sdk.observeSdkStatus().collect { status ->
    when (status) {
        is Status.Uninitialized -> {
            // SDK not yet initialized
        }
        is Status.Initializing -> {
            // SDK is fetching config from server
            // Retries automatically on network errors or server 5xx
        }
        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
        }
    }
}

val uploadStats = sdk.getUploadStatistics()
if (uploadStats != null) {
    println("Successful uploads: ${uploadStats.successfulUploadsCount}")
    println("Last upload: ${uploadStats.lastSuccessfulUploadTimestamp}")
}

val sensorStats = sdk.getSensorStatistics()
sensorStats?.forEach { stat ->
    println("Sensor: ${stat.sensorName}")
    println("Configured: ${stat.configuredFrequencyHz} Hz")
    println("Actual: ${stat.actualFrequencyHz} Hz")
    println("Quality: ${stat.quality}")
}

sdk.observeSdkStatus().collect { status ->
    when (status) {
        is Status.Error -> {
            Log.e("SDK", "Error: ${status.errorCode} - ${status.message}")
        }
        is Status.ReadingsDatabaseFull -> {
            Log.w("SDK", "Storage full")
        }
        else -> {}
    }
}

fun checkSdkHealth() {
    val uploadStats = sdk.getUploadStatistics()
    if (uploadStats != null && uploadStats.successfulUploadsCount == 0) {
        Log.w("SDK", "No successful uploads yet")
    }

    val sensorStats = sdk.getSensorStatistics()
    sensorStats?.filter { it.quality == SensorDataQuality.BAD }?.forEach {
        Log.w("SDK", "Bad quality for: ${it.sensorName}")
    }
}