Core-Telecom

Core-Telecom 程式庫提供可靠且一致的 API 組合，簡化將呼叫應用程式與 Android 平台整合的程序

如要瞭解實際實作方式，您可以在 GitHub 上找到應用程式範例：

設定 Core-Telecom

將 androidx.core:core-telecom 依附元件新增至應用程式的 build.gradle 檔案：

dependencies {
    implementation ("androidx.core:core-telecom:1.0.0")
}

在 AndroidManifest.xml 中宣告 MANAGE_OWN_CALLS 權限：

<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />

註冊應用程式

使用 CallsManager 將通話應用程式註冊至 Android，即可開始向系統新增通話。註冊時，請指定應用程式的功能 (例如音訊、視訊支援)：

val callsManager = CallsManager(context)

val capabilities: @CallsManager.Companion.Capability Int =
    (CallsManager.CAPABILITY_BASELINE or
          CallsManager.CAPABILITY_SUPPORTS_VIDEO_CALLING)

callsManager.registerAppWithTelecom(capabilities)

通話管理

使用 Core-Telecom API 建立及管理通話生命週期。

建立通話

CallAttributesCompat 物件會定義專屬通話的屬性，這些屬性可具有下列特性：

  • displayName：來電者名稱。
  • address：通話地址 (例如電話號碼、會議連結)。
  • direction：傳入或傳出。
  • callType：音訊或視訊。
  • callCapabilities：支援轉移和保留。

以下範例說明如何建立來電：

fun createIncomingCallAttributes(
    callerName: String,
    callerNumber: String,
    isVideoCall: Boolean): CallAttributesCompat {
    val addressUri = Uri.parse("YourAppScheme:$callerNumber")

    // Define capabilities supported by your call.
    val callCapabilities = CallAttributesCompat.CallCapability(
        supportsSetInactive = CallAttributesCompat.SUPPORTS_SET_INACTIVE // Call can be made inactive (implies hold)
    )

    return CallAttributesCompat(
        displayName = callerName,
        address = addressUri,
        direction = CallAttributesCompat.DIRECTION_INCOMING,
        callType = if (isVideoCall) CallAttributesCompat.CALL_TYPE_VIDEO_CALL else CallAttributesCompat.CALL_TYPE_AUDIO_CALL,
        callCapabilitiesCompat = callCapabilities
    )
}

新增通話

請將 callsManager.addCall 與 CallAttributesCompat 和回呼搭配使用，為系統新增呼叫並管理遠端途徑更新。addCall 區塊中的 callControlScope 主要可讓應用程式轉換通話狀態，並接收音訊更新：

try {
    callsManager.addCall(
        INCOMING_CALL_ATTRIBUTES,
        onAnswerCall, // Watch needs to know if it can answer the call.
        onSetCallDisconnected,
        onSetCallActive,
        onSetCallInactive
    ) {
        // The call was successfully added once this scope runs.
        callControlScope = this
    }
}
catch(addCallException: Exception){
   // Handle the addCall failure.
}

接聽來電

在 CallControlScope 中接聽來電：

when (val result = answer(CallAttributesCompat.CALL_TYPE_AUDIO_CALL)) {
    is CallControlResult.Success -> { /* Call answered */ }
    is CallControlResult.Error -> { /* Handle error */ }
}

拒接來電

在 CallControlScope 中使用 disconnect() 搭配 DisconnectCause.REJECTED 拒接來電：

disconnect(DisconnectCause(DisconnectCause.REJECTED))

讓外撥通話處於活動狀態

在對方接聽後，將外撥通話設為啟用狀態：

when (val result = setActive()) {
    is CallControlResult.Success -> { /* Call active */ }
    is CallControlResult.Error -> { /* Handle error */ }
}

保留通話

使用 setInactive() 保留通話：

when (val result = setInactive()) {
    is CallControlResult.Success -> { /* Call on hold */ }
    is CallControlResult.Error -> { /* Handle error */ }
}

中斷通話

使用 disconnect() 與 DisconnectCause 中斷通話：

disconnect(DisconnectCause(DisconnectCause.LOCAL))

管理通話音訊端點

使用 CallControlScope 中的 currentCallEndpoint、availableEndpoints 和 isMuted Flow 觀察及管理音訊端點

fun observeAudioStateChanges(callControlScope: CallControlScope) {
    with(callControlScope) {
        launch { currentCallEndpoint.collect { /* Update UI */ } }
        launch { availableEndpoints.collect { /* Update UI */ } }
        launch { isMuted.collect { /* Handle mute state */ } }
    }
}

使用 requestEndpointChange() 變更有效音訊裝置：

coroutineScope.launch {
     callControlScope.requestEndpointChange(callEndpoint)
}

前景支援

程式庫會使用 ConnectionService (Android 13 API 級別 33 以下) 或 foregroundtypes (Android 14 API 級別 34 以上) 提供前景支援。

根據前景服務規定，應用程式必須發布通知，讓使用者知道應用程式正在前景執行。

為確保應用程式獲得前景執行優先順序，請在新增與平台的呼叫後建立通知。當應用程式終止呼叫或通知不再有效時，前景優先順序就會移除。

進一步瞭解前景服務。

遠端 Surface 支援

遠端裝置 (智慧手錶、藍牙耳機、Android Auto) 可在不直接與手機互動下管理通話。您的應用程式必須實作回呼 lambda (onAnswerCall、onSetCallDisconnected、onSetCallActive、onSetCallInactive)，並提供給 CallsManager.addCall，以便處理這些裝置啟動的動作。

發生遠端動作時，系統會叫用相應的 lambda。

成功完成 lambda 信號，表示指令已處理。如果無法遵循指令，lambda 應擲回例外狀況。

正確實作可確保在不同裝置上流暢控制通話。使用各種遠端表面進行徹底測試。