EthioConnect Android SDK

Native Android SDK for the EthioConnect platform. Built with Kotlin coroutines, the SDK orchestrates REST API access, WebSocket signaling, LiveKit media, and QoS telemetry into a unified RoomHandle interface with Kotlin Flow-based events.

Requirements

• Android API 26+ (Android 8.0)
• Kotlin 1.9+
• Java 17+

Installation

Gradle (Kotlin DSL)

dependencies {
    implementation("com.commbaas:sdk:0.1.0")
}

The SDK depends on io.livekit:livekit-android which is resolved automatically.

Quick Start

Initialize the client

import com.commbaas.sdk.CommBaasClient
import com.commbaas.sdk.CommBaasClientOptions

val client = CommBaasClient(
    CommBaasClientOptions(
        baseUrl = "https://api.comm-baas.example.com/v1",
        tokenProvider = { authRepository.getAccessToken() },
    )
)

Join a room

val room = client.joinRoom("room-uuid")

The joinRoom method orchestrates the full flow:

1. POST /rooms/{id}/join to obtain tokens
2. Opens the signaling WebSocket and waits for the hello handshake
3. Connects the LiveKit media session
4. Starts QoS telemetry (unless disabled)
5. Returns a RoomHandle

Collect events

room.events.collect { event ->
    when (event) {
        is RoomEvent.ParticipantJoined -> {
            Log.d("Room", "${event.participant.displayName} joined")
        }
        is RoomEvent.ParticipantLeft -> {
            Log.d("Room", "${event.participant.displayName} left")
        }
        is RoomEvent.Disconnected -> {
            Log.d("Room", "Disconnected")
        }
        else -> {}
    }
}

Leave the room

room.leave()

Architecture

The SDK is organized into four layers:

Layer	Package	Responsibility
HTTP	com.commbaas.sdk.http	Authenticated REST client with retry and error mapping.
Signaling	com.commbaas.sdk.signaling	WebSocket connection with session resume and heartbeat.
Media	com.commbaas.sdk.media	LiveKit Room wrapper and QoS telemetry reporter.
Model	com.commbaas.sdk.model	Data classes for API requests/responses and signaling messages.

Key Types

Type	Description
CommBaasClient	Top-level entry point. Provides joinRoom() and http for direct API access.
RoomHandle	Room-scoped handle exposing a SharedFlow<RoomEvent> and moderation actions.
SignalingConnection	WebSocket signaling with auto-reconnect and session resume.
RoomSession	LiveKit media session wrapper.
QoSReporter	Periodic QoS telemetry reporter.
HttpClient	OkHttp-based authenticated client with exponential backoff.
CommBaasException	Typed exception hierarchy.

Configuration

Parameter	Type	Description
baseUrl	String	Base URL of the API (no trailing slash).
tokenProvider	suspend () -> String	Suspend function returning the current bearer token.

Join Options

val room = client.joinRoom(
    roomId = "room-uuid",
    options = JoinOptions(audio = true, telemetry = true),
)

Option	Type	Default	Description
audio	Boolean	true	Enable microphone on join.
telemetry	Boolean	true	Start QoS telemetry reporting.

Error Handling

All errors are thrown as CommBaasException subclasses:

try {
    val room = client.joinRoom("room-uuid")
} catch (e: CommBaasException.Authentication) {
    // Token expired — refresh and retry
} catch (e: CommBaasException.NotFound) {
    // Room does not exist
} catch (e: CommBaasException.Network) {
    // Network failure
}

Lifecycle Integration

The SDK is coroutine-based and does not manage Android lifecycle directly. Use viewModelScope or lifecycleScope to scope room sessions:

class RoomViewModel(private val client: CommBaasClient) : ViewModel() {
    private var roomHandle: RoomHandle? = null

    fun joinRoom(roomId: String) {
        viewModelScope.launch {
            roomHandle = client.joinRoom(roomId)
            roomHandle!!.events.collect { /* handle events */ }
        }
    }

    override fun onCleared() {
        viewModelScope.launch { roomHandle?.leave() }
    }
}

Related

• ADR 0017 -- Mobile SDK Architecture
• Client SDK (JavaScript) — Browser equivalent