Table of Contents
- Installation
- Quick Start
- Configuration
- Core Features
- SDK Status
- Statistics API
- Best Practices
- API Reference
Installation
Add the Truemetrics SDK to your app’sbuild.gradle file:
Quick Start
1. Initialize the SDK in your Application class
2. Start and stop recordings
Configuration
The SDK is configured using theSdkConfiguration.Builder class.
Basic Configuration
Custom Foreground Notification
Customize the notification shown when the SDK is running as a foreground service using the SDK’s notification channel:Core Features
Recording Management
Device ID
Get the unique device identifier (available after initialization):Metadata Logging
Attach custom metadata to your recordings:Sensor Management
Complete Cleanup
deinitialize(), the SDK instance becomes unusable. You must call
init() again to use the SDK.
SDK Status
Monitor the SDK state usingobserveSdkStatus():
Error Codes
| 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 |
Statistics API
Upload Statistics
Monitor upload health:Sensor Statistics
Get detailed sensor data quality:- EXCELLENT: 95-100% of configured frequency
- GOOD: 80-95%
- POOR: 50-80%
- BAD: less than 50%
- UNKNOWN: no data or not recording
Best Practices
1. Initialization
- Always initialize in your
Applicationclass - Use the application context, not activity context
- Initialize once and reuse the singleton instance
2. Error Handling
3. Monitoring SDK Health
API Reference
TruemetricsSdk
| Method | Return Type | Description |
|---|---|---|
init(context, config) | TruemetricsSdk | Initialize SDK (static) |
getInstance() | TruemetricsSdk | Get singleton instance (static) |
startRecording() | Unit | Start sensor recording |
stopRecording() | Unit | Stop sensor recording |
isRecordingInProgress() | Boolean | Check if recording active |
isRecordingStopped() | Boolean | Check if recording stopped |
getRecordingStartTime() | Long | Get recording start timestamp |
getDeviceId() | String? | Get unique device identifier |
logMetadata(payload) | Unit | Log custom metadata |
setAllSensorsEnabled(enabled) | Unit | Enable/disable all sensors |
getAllSensorsEnabled() | Boolean | Get sensor enable status |
getActiveConfig() | Configuration? | Get active backend configuration |
getUploadStatistics() | UploadStatistics? | Get upload stats |
getSensorStatistics() | List<SensorStatistics>? | Get sensor stats |
deinitialize() | Unit | Shutdown SDK completely |
Observable Flows
| Property/Method | Type | Description |
|---|---|---|
sensorInfo | StateFlow<Iterable<SensorInfo>> | Available sensors info |
sdkStatus | StateFlow<Status> | SDK operational status |
observeSdkStatus() | Flow<Status> | Observe SDK status changes |
getActiveConfigFlow() | Flow<Configuration>? | Observe backend config changes |
Data Classes
UploadStatistics
| Property | Type | Description |
|---|---|---|
successfulUploadsCount | Int | Total successful uploads |
lastSuccessfulUploadTimestamp | Long? | Last upload timestamp |
SensorStatistics
| Property | Type | Description |
|---|---|---|
sensorName | SensorName | Sensor identifier |
configuredFrequencyHz | Float | Configured frequency |
actualFrequencyHz | Float | Actual measured frequency |
quality | SensorDataQuality | Quality assessment |
SensorInfo
| Property | Type | Description |
|---|---|---|
sensorName | SensorName | Sensor identifier |
sensorStatus | SensorStatus | Status: ON, OFF, or NA |
frequency | Float | Polling frequency in Hz |
missingPermissions | List<String> | Required permissions not granted |