​
Architecture overview

The following diagram gives a general overview: architecture and main function

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

As next step update your project-level settings.gradle file and dependencyResolutionManagement section by the following:

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 on TruemetricsSDK

Inside your build.gradle add the following dependency:

implementation 'io.truemetrics:truemetricssdk:1.0.4'

​
Foreground service and notification

In order to reliably collect data, SDK starts a Foreground service and shows a notification while recording is in progress.

SDK manages Foreground service but needs existing notification channel and a notification that will be shown so integrating your app needs to create a notification channel, provide a notification in Config parameter and ask user for notification permission if device runs Android 13 or later.

Creating a notification channel using NotificationManagerCompat:

private val notificationManager = NotificationManagerCompat.from(context)

notificationManager.createNotificationChannel(
    NotificationChannelCompat.Builder("FOREGROUND_SERVICE_CHANNEL", NotificationManagerCompat.IMPORTANCE_LOW)
        .setName("Foreground service notification title")
        .setShowBadge(false)
        .build()
)

Creating a notification:

val notification = NotificationCompat.Builder(context, "FOREGROUND_SERVICE_CHANNEL")
            .setContentTitle("Foreground notification title")
            .setSmallIcon(R.drawable.ic_notification_logo)
            .setOngoing(true)
						.build()

You can find example snippets for creating a notification channel and accompanying notification in the Demo app.

​
Initialize SDK

SDK behaves like a singleton object that manages its own internal state. Before actually using the SDK you need to initialize it:

TruemetricsSDK.initialize(
    this,
    Config(
        apiKey = "YOUR-API-KEY",
        foregroundNotification = notification
    )
)

foregroundNotification parameter is a notification that will be shown when Foreground service is running, i.e. when recording is in progress.

​
Status callback

Set SDK status callback to get notified about SDK state changes and potential errors:

TruemetricsSDK.setStatusListener(object : StatusListener{
    override fun onStateChange(state: State) {}
    override fun onError(errorCode: ErrorCode, message: String?) {}
    override fun askPermissions(permissions: List<String>) {}
})

onError callback will be invoked when something happens that prevents SDK from operating, e.g. API KEY authorization fails, device storage gets full, etc.

Possible error codes:

Error codeDescription
AUTHENTICATION_ERRORAPI key is not valid, expired or revoked
UPLOAD_ERRORRecordings couldn’t be uploaded after exhausting all attempts
STORAGE_FULLDevice storage is full which prevents saving sensor readings
MISSING_NOTIFICATION_PERMISSIONPermission to post notification is not granted which means that Foreground service cannot be started

askPermissions callback will be invoked based on necesarry permissions for enabled sensors in remote configuration. At the moment, list of permission can include:

  • android.permission.READ_PHONE_STATE
  • android.permission.ACTIVITY_RECOGNITION
  • android.permission.ACCESS_COARSE_LOCATION
  • android.permission.ACCESS_FINE_LOCATION
  • android.permission.ACCESS_BACKGROUND_LOCATION

​
Start recording

TruemetricsSDK.startRecording()

Starting the recording also starts Foreground service and shows notification supplied in Config in system’s status bar. Recording will continue even when app exits.

​
Stop recording

TruemetricsSDK.stopRecording()

Stopping recording also stops Foreground service and removes notification.

​
Log metadata

TruemetricsSDK.logMetadata(payload: Map<String, String>)

SDK will serialize payload into JSON.

Most of our customers query the data by customer adresses. That means, that most costumers call the entrance endpoint by using the customer’s address as an identifier. Other customers seek more flexibility and also want to query data by an identifier for a route or a courier.

By sending this information from your app to our SDK, we enable you to filter the results by these identifiers later on. If you’re unsure about best practices for your use case, reach out, and we’ll guide you to the best solution.

​
Deinitialize SDK

TruemetricsSDK.deinitialize()

De-initialization stops recording if in progress and tears down the SDK and cancels all scheduled uploads.

Quickstart