Dragon Copilot web app for mobile - Android API reference

Dragon Copilot web app for mobile offers a set of public APIs that clients can use to integrate with the SDK. This document provides a comprehensive overview of the public classes and methods available in the SDK, along with code examples to help you get started.

Tips and best practices

• For optimum functionality, provide all optional fields when available.

• Use the traceId for logging and troubleshooting; if you don't provide it, the SDK generates it automatically.

• Use the correlationId in VisitInfo to link related visits and events; don't use PHI in this identifier.

• Events are delivered through Kotlin Flow, which supports reactive programming patterns.

• Dragon Copilot web app for mobile automatically handles security checks for external clients.

• Call openSession() for each patient encounter without reinitializing the SDK.

Required Android permissions

Add these permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

Your app must request these runtime permissions before calling openSession(). The SDK uses the checkPermission callback to request these permissions when needed.

Public classes and methods

The following public APIs are available:

• ApplicationConfig class

• ApplicationConfigProvider class

ApplicationConfig class

The ApplicationConfig class is your main entry point for embedding Dragon Copilot in your Android app. It provides methods to initialize the SDK and manage sessions.

Methods

Event flow properties

The ApplicationConfig class provides the following flow properties for reactive event handling:

Initialization procedure

1. Call getInstance to initialize the SDK with app-level configuration.

2. Call openSession to display the Dragon Copilot UI with patient and visit context. You can call this method multiple times to open different patient sessions for the same user, without reinitializing the SDK.

3. Call closeSession to properly close an active patient session, cleaning up temporary data and stopping any active recordings.

4. Call clearInstance to completely release all resources associated with the SDK. Use this when the SDK isn't needed anymore.

Data classes

ApplicationConfigProvider class

The ApplicationConfigProvider data class provides configuration data to the getInstance() call to initialize the SDK.

data class ApplicationConfigProvider( 
    val clientAppInfo: ClientAppInfo, 
    val serverInfo: ServerInfo, 
    var customerId: String? = null, 
    var partnerId: String? = null, 
    var providerName: String, 
    var ehrInstanceId: String? = null, 
    val productId: String? = BuildConfig.DEFAULT_PRODUCT_ID, 
    val authType: AuthType = AuthType.ENTRA_ID, 
    val traceId: String = UUID.randomUUID().toString(), 
    val userInfo: UserInfo? = null
)

AppUiComponent class

The AppUiComponent interface provides the UI context for the SDK. Your app must implement this interface and pass it to getInstance().

interface AppUiComponent {
    val activity: ComponentActivity
    val lifecycleOwner: LifecycleOwner
}

ClientAppInfo class

Information about the app integrating the SDK:

data class ClientAppInfo(
    val appId: String? = null,
    val appVersion: String? = null,
    val deviceId: String? = null
) 

ServerInfo class

Server environment configuration:

data class ServerInfo( 
    val environment: Environment, 
    val geography: String, 
    val cloudInstance: String = "public_global" 
) 

UserInfo class

User details. This class is optional in ApplicationConfigProvider. If you don't provide the id, the SDK automatically creates it from the authentication response. It's recommended to provide additional user details such as name and FHIR ID, for better context.

data class UserInfo(
    val id: String? = null,  // Note: Internally mutable, can be set by SDK
    val fhirId: String? = null,
    val firstName: String? = null,
    val lastName: String? = null,
    val middleName: String? = null,
    val ehrUserId: String? = null
)

PatientInfo class

This class provides patient details to the openSession() call. This parameter is optional, but EHR flows (PARTNER_TOKEN or SMART_ON_FHIR authentication) and ambient recording sessions require the patient context provided here.

data class PatientInfo(
    val id: String?,
    val fhirId: String?,
    val firstName: String?,
    val middleName: String?,
    val lastName: String?,
    val medicalRecordNumber: String?,
    val birthDate: String?,
    val gender: String?
)

VisitInfo class

This class provides patient details to the openSession() call. This parameter is optional, but for ambient recording sessions, it's recommended to provide the visit or encounter context and reason for visit.

data class VisitInfo( 
    val id: String? = null, 
    val fhirId: String? = null, 
    val reasonForVisit: String? = null, 
    val correlationId: String? = null 
) 

Event handling

You can find all event classes in com.microsoft.dragoncopilot.turnkey.model.

Subscribe to the Flow properties on ApplicationConfig to receive events. For the complete list, see Event Flow properties.

AppSettingsUiEvent

Settings-related events:

sealed class AppSettingsUiEvent { 
    data class AppearanceChanged(val theme: String) : AppSettingsUiEvent() 
    data class ApplicationLanguageChanged(val locale: String) : AppSettingsUiEvent() 
    data class KeepScreenOnChanged(val isScreenOn: Boolean) : AppSettingsUiEvent() 
} 

AppRecordingUiEvent

Events related to ambient recording:

sealed class AppRecordingUiEvent {
    data object RecordingStarted : AppRecordingUiEvent()
    data class RecordingStopped(val reason: RecordingStopReason) : AppRecordingUiEvent()
    data object RecordingFailed : AppRecordingUiEvent()
    data object RecordingUploading : AppRecordingUiEvent()
    data object RecordingUploaded : AppRecordingUiEvent()
    data class RecordingInProgress(val notification: RecordingProgressNotification) : AppRecordingUiEvent()
}
 
enum class RecordingStopReason {
    USER,                      // User manually stopped recording
    SYSTEM_ERROR,              // System error occurred
    MAX_LIMIT_REACHED,         // Maximum recording duration was reached
    AUDIO_INTERRUPTED,         // Recording stopped due to audio interruption
    INCOMPATIBLE_AUDIO_DEVICE_DETECTED, // Incompatible input device
    AUDIO_DEVICE_CHANGED,      // Recording stopped due to device change
}
 
enum class RecordingProgressNotification {
    WARN_LIMIT_REACHED,
    AUDIO_SILENCE_DETECTED,
    EXTERNAL_AUDIO_DEVICE_DETECTED
}

AppDictationUiEvent

Events related to dictation:

sealed class AppDictationUiEvent {
    data object DictationStarted : AppDictationUiEvent()
    data object DictationStopped : AppDictationUiEvent()
}

AppUiEvent

General UI events from the SDK.

sealed class AppUiEvent {
    data object OnLoadingBackPress : AppUiEvent()
    data class SignOut(val reason: SignOutReason) : AppUiEvent()
    data object WebViewLoaded : AppUiEvent()
}

Event subscription example

// Subscribe to settings events
lifecycleScope.launch {
    applicationConfig.event.collect { event ->
        when (event) {
            is AppSettingsUiEvent.AppearanceChanged -> {
                // Handle theme change, apply event.theme
            }
            is AppSettingsUiEvent.ApplicationLanguageChanged -> {
                // Handle language change, apply event.locale
            }
            is AppSettingsUiEvent.KeepScreenOnChanged -> {
                // Handle screen keep-on setting change
                if (event.isScreenOn) {
                    window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON) 
                } else {
                    window.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON) 
                }
            }
        }
    }
}

// Subscribe to UI events
lifecycleScope.launch {
    applicationConfig.uiEvent.collect { event ->
        when (event) {
            is AppUiEvent.OnLoadingBackPress -> {
                // handle back button pressed while Dragon Embedded UI loading
            }
            is AppUiEvent.SignOut -> {
                // Handle signout
            }
            is AppUiEvent.WebViewLoaded -> {
                // WebView finished loading
            }
        }
    }
}

// Subscribe to dictation events
lifecycleScope.launch {
    applicationConfig.dictationEvent.collect { event ->
        when (event) {
            is AppDictationUiEvent.DictationStarted -> {
                // Dictation started for correlationId: event.correlationId
            }
            is AppDictationUiEvent.DictationStopped -> {
                // Dictation stopped for correlationId: event.correlationId
            }
        }
    }
}

// Subscribe to recording events
lifecycleScope.launch {
    applicationConfig.recordingEvent.collect { event ->
        when (event) {
            is AppRecordingUiEvent.RecordingStarted -> {
                // Recording started for correlationId: event.correlationId
            }
            is AppRecordingUiEvent.RecordingStopped -> {
                // Recording stopped, reason: event.reason
                when (event.reason) {
                    RecordingStopReason.USER -> { }
                    RecordingStopReason.MAX_LIMIT_REACHED -> { }
                    RecordingStopReason.AUDIO_INTERRUPTED -> { }
                    // ... handle other reasons
                }
            }
            is AppRecordingUiEvent.RecordingProgress -> {
                when (event.notification) {
                    RecordingProgressNotification.WARN_LIMIT_REACHED -> {  }
                    RecordingProgressNotification.EXTERNAL_AUDIO_DEVICE_DETECTED -> { }
                    // ... handle other notifications
                }
            }
            is AppRecordingUiEvent.RecordingFailed -> {
                // Recording failed with error: event.error
                // Perform actions when recording fails
            }
            is AppRecordingUiEvent.RecordingUploading -> {
                // Recording is uploading
            }
            is AppRecordingUiEvent.RecordingUploaded -> {
                // Recording uploaded successfully
            }
        }
    }
}

Authentication

ClientTokenProvider sealed class

Base class for authentication token providers:

package com.microsoft.dragoncopilot.turnkey.model 
 
sealed class ClientTokenProvider { 
    data class ClientToken( 
        val token: String? 
    ) : ClientTokenProvider() 
     
    data class ClientSoFToken( 
        val issuer: String?, 
        val launch: String? 
    ) : ClientTokenProvider() 
} 

Callbacks

AcquireNewTokenListener

Callback interface for token acquisition:

fun interface AcquireNewTokenListener { 
    fun acquireNewToken( 
        scopes: List<String>?, 
        forceRefresh: Boolean, 
        onSuccess: (ClientTokenProvider) -> Unit, 
        onFailure: (Exception) -> Unit 
    ) 
} 

CheckPermissionCallback

Callback interface for runtime permission requests:

fun interface CheckPermissionCallback { 
    fun checkPermission( 
        permissionsToRequest: Set<String>, 
        onPermissionResult: (Map<String, Boolean>) -> Unit 
    ) 
}