Android SDK Usage

Initialization

Use the builder pattern to create an SDK instance. The build() function is a suspend function that performs DPoP key pair generation, token activation, and entitlement verification.

import com.vitalera.sdk.VitaleraSdk

val sdk = VitaleraSdk.builder()
    .context(applicationContext)           // Required on Android
    .clientId("your-org-license-key")      // Required -- obtain from sdk@vitalera.com
    .addProvider("omron")                  // Declare which providers to use
    .addProvider("polar")
    .addProvider("standard-ble")
    .connectedMode(true)                   // Optional: enable patient/observation API
    .build()                               // suspend: performs DPoP auth + entitlement check

Handle authentication errors during initialization:

try {
    val sdk = VitaleraSdk.builder()
        .context(applicationContext)
        .clientId("your-org-license-key")
        .build()
} catch (e: SdkAuthException) {
    when (e.errorCode) {
        "activation_failed" -> showInvalidLicenseError()
        "entitlements_expired" -> showConnectToInternetPrompt()
        "no_cache" -> showFirstLaunchOfflineError()
        else -> showGenericError(e.message)
    }
}

Device Discovery

Use DiscoveryFilter to scan for specific device types. Discovery returns a Kotlin Flow<DeviceDescriptor> that emits discovered devices and completes after the timeout.

import com.vitalera.sdk.discovery.DiscoveryFilter
import com.vitalera.sdk.device.DeviceCapability

// Scan for blood pressure monitors across all registered providers
val filter = DiscoveryFilter(
    capabilities = setOf(DeviceCapability.BLOOD_PRESSURE)
)

sdk.devices.discover(filter, timeoutMs = 15_000L).collect { descriptor ->
    // descriptor: DeviceDescriptor(id, name, provider, modelId, rssi, capabilities)
    println("Found: ${descriptor.name} (${descriptor.provider}, ${descriptor.rssi} dBm)")
}

Filter Options

// Only Omron devices
val omronFilter = DiscoveryFilter(providers = setOf("omron"))

// Only devices whose name starts with "Polar"
val polarFilter = DiscoveryFilter(namePrefix = "Polar")

// Combine: Polar heart rate monitors only
val combinedFilter = DiscoveryFilter(
    providers = setOf("polar"),
    capabilities = setOf(DeviceCapability.HEART_RATE),
)

Device Connection

Create a device from a DeviceDescriptor and connect to it. The connect() function is a suspend function with a configurable timeout.

val device = sdk.devices.createDevice(descriptor)

// Connect (suspends until connected or timeout)
device.connect(timeoutMs = 10_000L)

// Observe connection state reactively
launch {
    device.connectionState.collect { state ->
        when (state) {
            is ConnectionState.Disconnected -> showStatus("Disconnected")
            is ConnectionState.Connecting -> showStatus("Connecting...")
            is ConnectionState.Connected -> showStatus("Connected")
            is ConnectionState.Disconnecting -> showStatus("Disconnecting: ${state.reason}")
            is ConnectionState.Error -> showError(state.cause)
        }
    }
}

Data Collection

The collect() method returns a Flow<BaseObservation> of typed observation classes. For single-reading devices (e.g., blood pressure), the Flow emits one observation and completes. For streaming devices (e.g., heart rate), it emits continuously.

device.collect().collect { observation ->
    when (observation) {
        is BloodPressureObservation -> {
            val systolic = observation.systolic
            val diastolic = observation.diastolic
            val pulseRate = observation.pulseRate
            val irregular = observation.irregularPulseDetected
        }
        is HeartRateObservation -> {
            val bpm = observation.heartRate
        }
        is WeightObservation -> {
            val kg = observation.weight
        }
        is TemperatureObservation -> {
            val celsius = observation.temperature
        }
        is OxygenSaturationObservation -> {
            val spo2 = observation.spo2
        }
        is BloodGlucoseObservation -> {
            val glucose = observation.glucose
        }
        // 30+ typed observation classes available
    }
}

// Disconnect when done
device.disconnect()

Connected Mode

When connectedMode(true) is set during initialization, resolve patients and post observations to the Vitalera backend:

// Resolve a patient by external identifier
val patient = sdk.connected().resolveMonitored("patient-ext-id")

// Post an observation
sdk.connected().postObservation(
    monitoredId = patient.id,
    observation = BaseObservation(
        observationType = "blood-pressure",
        issued = Clock.System.now().toString(),
        components = listOf(
            ObservationComponent(name = "systolic", value = "120", valueUnit = "mmHg"),
            ObservationComponent(name = "diastolic", value = "80", valueUnit = "mmHg"),
        ),
    ),
)

Error Handling

All SDK errors extend the sealed SdkError class:

try {
    device.connect()
    val obs = device.collect().first()
} catch (e: SdkError.ConnectionTimeout) {
    showError("Connection timed out. Move closer to the device.")
} catch (e: SdkError.BluetoothDisabled) {
    showError("Please enable Bluetooth.")
} catch (e: SdkError.BluetoothPermissionDenied) {
    showError("Bluetooth permissions required.")
} catch (e: SdkError) {
    showError("Device error: ${e.message}")
}

Multiple Devices

Connect to multiple devices concurrently using coroutines:

val bpMonitor = sdk.devices.createDevice(bpDescriptor)
val hrMonitor = sdk.devices.createDevice(hrDescriptor)

coroutineScope {
    launch { bpMonitor.connect() }
    launch { hrMonitor.connect() }
}

Health Connect

Read from Google Health Connect (no BLE scanning required):

val descriptor = sdk.devices.discover(
    DiscoveryFilter(providers = setOf("health-connect")),
    timeoutMs = 5_000L,
).first()

val store = sdk.devices.createDevice(descriptor)
store.connect()
val observations = store.collect().toList()
store.disconnect()

Resource Cleanup

Always call close() when the SDK is no longer needed:

sdk.close()  // Cancels heartbeat, closes HTTP client, disposes providers