電信架構總覽

Android Telecom 架構 (簡稱「Telecom」) 可管理 Android 裝置上的語音和視訊通話。包括使用電話通訊架構的 SIM 卡通話,以及實作 Core-Telecom Jetpack 程式庫的 VoIP 通話。

Telecom 管理的主要元件為 ConnectionService 和 InCallService。

ConnectionService 實作會以 PSTN 等技術為基礎,將通話連線至其他方。手機上最常見的 ConnectionService 實作是電話通訊 ConnectionService。可接通電信業者通話。

InCallService 實作會為電信服務管理的通話提供使用者介面,並允許使用者控制這些通話及與其互動。InCallService 最常見的實作方式是裝置隨附的「電話」應用程式。

Telecom 的作用就像總機。它會將 ConnectionService 實作提供的呼叫轉送至 InCallService 實作提供的呼叫使用者介面。

您可能基於下列原因,想要導入 Telecom API:

建立替代的「電話」應用程式

如要為 Android 裝置建立預設「電話」應用程式的替代項目,請實作 InCallService API。實作時必須符合下列規定:

  • 不得具備任何通話功能,且必須僅由通話使用者介面組成。
  • 它必須處理 Telecom 架構知道的所有通話,且不對通話性質做出假設。舉例來說,不得假設通話是 SIM 卡式電話通話,也不得根據任何 ConnectionService 實施通話限制,例如對視訊通話強制執行電話限制。

詳情請參閱 InCallService。

整合通話解決方案

如要將通話解決方案整合至 Android,可以選擇下列做法:

  • 導入自行管理的 Core-Telecom Jetpack 程式庫:如果開發人員打造的是獨立通話應用程式,不希望在預設「電話」應用程式中顯示通話,也不想在使用者介面中顯示其他通話,這個選項就很適合。

    整合 Core-Telecom Jetpack 程式庫後,應用程式不僅能與裝置上的系統電話通話互通,還能與其他整合 Telecom 的獨立通話應用程式互通。Core-Telecom 程式庫也會管理音訊轉送和焦點。詳情請參閱「建構通話應用程式」。

  • 實作受管理的 ConnectionService API: 這個選項有助於開發通話解決方案,該解決方案會依賴現有的裝置電話應用程式,提供通話使用者介面。例如第三方實作的 SIP 通話和 VoIP 通話服務。詳情請參閱 getDefaultDialerPackage()。

    ConnectionService 本身僅提供連接通話的方式。沒有相關聯的使用者介面。

  • 同時實作 InCallService 和 ConnectionService API: 如果您想建立自己的 ConnectionService 呼叫解決方案,並提供專屬使用者介面,同時在同一個使用者介面中顯示所有其他 Android 通話,這個選項是理想選擇。使用這個方法時,InCallService 的實作方式不得對顯示的通話來源做出任何假設。此外,即使預設電話應用程式未設為自訂 InCallService,ConnectionService 的實作也必須繼續運作。

過濾電話

在搭載 Android 10 (API 級別 29) 以上版本的裝置上,應用程式可將使用者通訊錄以外號碼的來電,識別為疑似騷擾電話。使用者可以選擇在不發出提示音的情況下拒接騷擾電話。為提高透明度,當使用者有未接來電時,系統會在通話記錄中記錄這些遭封鎖的來電資訊。使用 Android 10 API 時,不必向使用者取得 READ_CALL_LOG 權限,即可提供來電過濾和來電顯示功能。

您可以使用 CallScreeningService 實作來過濾來電。如果號碼不在使用者的聯絡人清單中,請針對任何新的來電或撥出電話呼叫 onScreenCall() 函式。您可以查看 Call.Details 物件,瞭解呼叫相關資訊。具體來說,getCallerNumberVerificationStatus() 函式包含網路供應商提供的其他號碼資訊。如果驗證狀態為失敗,則表示來電可能來自無效號碼或騷擾電話。

class ScreeningService : CallScreeningService() {
    // This function is called when an ingoing or outgoing call
    // is from a number not in the user's contacts list
    override fun onScreenCall(callDetails: Call.Details) {
        // Can check the direction of the call
        val isIncoming = callDetails.callDirection == Call.Details.DIRECTION_INCOMING

        if (isIncoming) {
            // the handle (e.g. phone number) that the Call is currently connected to
            val handle: Uri = callDetails.handle

            // determine if you want to allow or reject the call
            when (callDetails.callerNumberVerificationStatus) {
                Connection.VERIFICATION_STATUS_FAILED -> {
                    // Network verification failed, likely an invalid/spam call.
                }
                Connection.VERIFICATION_STATUS_PASSED -> {
                    // Network verification passed, likely a valid call.
                }
                else -> {
                    // Network could not perform verification.
                    // This branch matches Connection.VERIFICATION_STATUS_NOT_VERIFIED.
                }
            }
        }
    }
}

將 onScreenCall() 函式設為呼叫 respondToCall(),指示系統如何回應新來電。這個函式會採用 CallResponse 參數,您可以使用這個參數指示系統封鎖來電、拒接來電 (就像使用者拒接一樣),或將來電設為靜音。您也可以指示系統完全略過將這筆通話新增至裝置通話記錄的步驟。

// Tell the system how to respond to the incoming call
// and if it should notify the user of the call.
val response = CallResponse.Builder()
    // Sets whether the incoming call should be blocked.
    .setDisallowCall(false)
    // Sets whether the incoming call should be rejected as if the user did so manually.
    .setRejectCall(false)
    // Sets whether ringing should be silenced for the incoming call.
    .setSilenceCall(false)
    // Sets whether the incoming call should not be displayed in the call log.
    .setSkipCallLog(false)
    // Sets whether a missed call notification should not be shown for the incoming call.
    .setSkipNotification(false)
    .build()

// Call this function to provide your screening response.
respondToCall(callDetails, response)

您必須在資訊清單檔案中註冊 CallScreeningService 實作,並設定適當的意圖篩選器和權限,系統才能正確觸發。

<service
    android:name=".ScreeningService"
    android:permission="android.permission.BIND_SCREENING_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallScreeningService" />
    </intent-filter>
</service>

重新導向通話

搭載 Android 10 以上版本的裝置管理通話意圖的方式,與搭載 Android 9 以下版本的裝置不同。在 Android 10 以上版本中,ACTION_NEW_OUTGOING_CALL 廣播已淘汰,並由 CallRedirectionService API 取代。CallRedirectionService 提供介面,可讓您修改 Android 平台撥出的電話。例如,第三方應用程式可能會取消通話,並透過 VoIP 重新路由。

class RedirectionService : CallRedirectionService() {
    override fun onPlaceCall(
        handle: Uri,
        initialPhoneAccount: PhoneAccountHandle,
        allowInteractiveResponse: Boolean
    ) {
        // Determine if the call should proceed, be redirected, or cancelled.
        val callShouldProceed = true
        val callShouldRedirect = false
        when {
            callShouldProceed -> {
                placeCallUnmodified()
            }
            callShouldRedirect -> {
                // Update the URI to point to a different phone number or modify the
                // PhoneAccountHandle and redirect.
                redirectCall(handle, initialPhoneAccount, true)
            }
            else -> {
                cancelCall()
            }
        }
    }
}

您必須在資訊清單中註冊這項服務,系統才能正確啟動。

<service
    android:name=".RedirectionService"
    android:permission="android.permission.BIND_CALL_REDIRECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallRedirectionService"/>
    </intent-filter>
</service>

如要使用重新導向服務,應用程式必須向 RoleManager 要求通話重新導向角色。系統會詢問使用者是否要允許應用程式處理通話重新導向。如果應用程式未獲授予這個角色,系統就不會使用重新導向服務。

當使用者啟動應用程式時,您應檢查應用程式是否具備這個角色,以便視需要提出要求。您會啟動由 RoleManager 建立的意圖,因此請務必覆寫 onActivityResult() 函式,以處理使用者的選項。

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Tell the system that you want your app to handle call redirects. This
        // is done by using the RoleManager to register your app to handle redirects.
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
            val roleManager = getSystemService(Context.ROLE_SERVICE) as RoleManager
            // Check if the app needs to register call redirection role.
            val shouldRequestRole = roleManager.isRoleAvailable(RoleManager.ROLE_CALL_REDIRECTION) &&
                !roleManager.isRoleHeld(RoleManager.ROLE_CALL_REDIRECTION)
            if (shouldRequestRole) {
                val intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_CALL_REDIRECTION)
                startActivityForResult(intent, REDIRECT_ROLE_REQUEST_CODE)
            }
        }
    }

    companion object {
        private const val REDIRECT_ROLE_REQUEST_CODE = 1
    }
}