預設電話應用程式可讓 Android Telecom 架構透過角色管理工具和通話服務,將通話狀態通知應用程式,以便在 Android 裝置上建立預設電話應用程式的替代項目,並實作 InCallService API。導入時必須符合下列規定:
不得具備任何通話功能,且必須僅由通話使用者介面組成。它必須處理 Telecom 架構知道的所有通話,且不對通話性質做出假設。舉例來說,應用程式不得假設通話是 SIM 卡式電話通話,也不得根據任何一個 ConnectionService 實施通話限制,例如對視訊通話強制執行電話限制。
通話應用程式可讓使用者在裝置上接聽或撥打語音/視訊通話。通話應用程式會使用自己的使用者介面進行通話,而非使用預設的「電話」應用程式介面,如下方螢幕截圖所示。

通話應用程式使用自有使用者介面的範例
Android 架構包含 android.telecom 套件,其中包含可協助您根據電信架構建構通話應用程式的類別。根據電信架構建構應用程式,可享有下列優點:
- 應用程式可與裝置中的原生電信子系統正確互通。
- 應用程式可與其他同樣遵循架構的通話應用程式正確互通。
- 這個架構可協助應用程式管理音訊和影片轉送。
- 這個架構可協助應用程式判斷通話是否具有焦點。
資訊清單宣告和權限
在應用程式資訊清單中,宣告應用程式會使用 MANAGE_OWN_CALLS 權限,如以下範例所示:
<manifest … >
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
</manifest>
如要進一步瞭解如何宣告應用程式權限,請參閱「權限」。
您必須宣告一項服務,指定在應用程式中實作 ConnectionService 類別的類別。電信子系統會要求服務宣告 BIND_TELECOM_CONNECTION_SERVICE 權限,才能繫結至該服務。以下範例說明如何在應用程式資訊清單中宣告服務:
<service android:name="com.example.MyConnectionService"
android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
<intent-filter>
<action android:name="android.telecom.ConnectionService" />
</intent-filter>
</service>
如要進一步瞭解如何宣告應用程式元件 (包括服務),請參閱「應用程式元件」。
實作連線服務
通話應用程式必須提供 ConnectionService 類別的實作,讓電信子系統可以繫結。ConnectionService 實作應覆寫下列方法:
onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)電信子系統會呼叫這個方法,回應應用程式呼叫
placeCall(Uri, Bundle)建立新撥出電話。應用程式會傳回Connection類別實作的新例項 (詳情請參閱「實作連線」),代表新的撥出電話。您可以執行下列動作,進一步自訂連出連線:- 應用程式應呼叫
setConnectionProperties(int)方法,並以PROPERTY_SELF_MANAGED常數做為引數,表示連線來自通話應用程式。 - 如果應用程式支援保留通話,請呼叫
setConnectionCapabilities(int)方法,並將引數設為CAPABILITY_HOLD和CAPABILITY_SUPPORT_HOLD常數的位元遮罩值。 - 如要設定來電者名稱,請使用
setCallerDisplayName(String, int)方法,並傳遞PRESENTATION_ALLOWED常數做為int參數,表示應顯示來電者名稱。 - 為確保撥出電話具有適當的視訊狀態,請呼叫
Connection物件的setVideoState(int)方法,並傳送ConnectionRequest物件的getVideoState()方法傳回的值。
- 應用程式應呼叫
onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)當應用程式呼叫
placeCall(Uri, Bundle)方法,且無法撥出電話時,電信子系統會呼叫這個方法。在這種情況下,應用程式應通知使用者 (例如使用快訊方塊或浮動式訊息) 無法撥出電話。如果正在進行緊急電話,或另一個應用程式正在進行通話,且無法在撥打電話前保留通話,應用程式可能無法撥打電話。onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)當應用程式呼叫
addNewIncomingCall(PhoneAccountHandle, Bundle)方法,通知系統有新的來電時,電信子系統會呼叫這個方法。應用程式會傳回Connection實作的新例項 (詳情請參閱「實作連線」),代表新的來電。您可以執行下列動作,進一步自訂傳入連線:- 應用程式應呼叫
setConnectionProperties(int)方法,並以PROPERTY_SELF_MANAGED常數做為引數,表示連線來自通話應用程式。 - 如果應用程式支援保留通話,請呼叫
setConnectionCapabilities(int)方法,並將引數設為CAPABILITY_HOLD和CAPABILITY_SUPPORT_HOLD常數的位元遮罩值。 - 如要設定來電者名稱,請使用
setCallerDisplayName(String, int)方法,並傳遞PRESENTATION_ALLOWED常數做為int參數,表示應顯示來電者名稱。 - 如要指定來電的電話號碼或地址,請使用
Connection物件的setAddress(Uri, int)方法。 - 為確保撥出電話具有適當的視訊狀態,請呼叫
Connection物件的setVideoState(int)方法,並傳送ConnectionRequest物件的getVideoState()方法傳回的值。
- 應用程式應呼叫
onCreateIncomingConnectionFailed(PhoneAccountHandle, ConnectionRequest)當應用程式呼叫
addNewIncomingCall(PhoneAccountHandle, Bundle)方法,通知電信子系統有新的來電,但來電不符合許可條件時,電信子系統就會呼叫這個方法 (詳情請參閱通話限制)。應用程式應在不發出通知的情況下拒絕來電,並可選擇發布通知,告知使用者有未接來電。
建立連線
應用程式應建立 Connection 的子類別,代表應用程式中的通話。您應在實作中覆寫下列方法:
onShowIncomingCallUi()當您新增來電,且應用程式應顯示來電 UI 時,電信子系統會呼叫這個方法。
onCallAudioStateChanged(CallAudioState)電信子系統會呼叫這個方法,通知應用程式目前的音訊路徑或模式已變更。當應用程式使用
setAudioRoute(int)方法變更音訊模式時,系統會呼叫這個方法。如果系統變更音訊路徑 (例如藍牙頭戴式耳機中斷連線),也可能會呼叫這個方法。onHold()電信子系統想保留通話時,會呼叫這個方法。為回應這項要求,應用程式應保留通話,然後叫用
setOnHold()方法,通知系統通話已保留。當通話中服務 (例如 Android Auto) 顯示通話,並想轉達使用者保留通話的要求時,電信子系統可能會呼叫這個方法。如果使用者在其他應用程式中撥打電話,電信子系統也會呼叫這個方法。如要進一步瞭解通話中服務,請參閱InCallService。onUnhold()電信子系統想要恢復保留的通話時,會呼叫這個方法。應用程式恢復通話後,應叫用
setActive()方法,通知系統通話已不再保留。當通話中服務 (例如 Android Auto) 顯示通話,並想轉送恢復通話的要求時,電信子系統可能會呼叫這個方法。如要進一步瞭解通話中服務,請參閱InCallService。onAnswer()電信子系統會呼叫這個方法,通知應用程式應接聽來電。應用程式接聽來電後,應叫用
setActive()方法,通知系統來電已接聽。當應用程式新增來電,且其他應用程式已有無法保留的通話時,電信子系統可能會呼叫這個方法。在這些情況下,電信子系統會代表應用程式顯示來電 UI。這個架構提供超載方法,可指定接聽來電時的視訊狀態。詳情請參閱onAnswer(int)。onReject()電信子系統想拒接來電時,會呼叫這個方法。應用程式拒絕通話後,應呼叫
setDisconnected(DisconnectCause)並指定REJECTED做為參數。接著,應用程式應呼叫destroy()方法,通知系統應用程式已處理通話。當使用者拒絕應用程式的來電時,電信子系統會呼叫這個方法。onDisconnect()電信子系統想中斷通話時,會呼叫這個方法。通話結束後,應用程式應呼叫
setDisconnected(DisconnectCause)方法,並指定LOCAL做為參數,表示通話因使用者要求而中斷。接著,應用程式應呼叫destroy()方法,通知電信子系統應用程式已處理通話。當使用者透過其他通話中服務 (例如 Android Auto) 中斷通話時,系統可能會呼叫此方法。如果必須中斷通話才能撥打其他電話 (例如使用者想撥打緊急電話),系統也會呼叫這個方法。如要進一步瞭解通話中服務,請參閱InCallService。
處理常見通話情境
在通話流程中使用 ConnectionService API 時,會與 android.telecom 套件中的其他類別互動。以下各節說明常見的通話情境,以及應用程式應如何使用 API 處理這些情境。
接聽來電
無論其他應用程式是否有通話,處理來電的流程都會變更。流程之所以不同,是因為其他應用程式有進行中的通話時,電信架構必須建立一些限制,確保裝置上所有通話應用程式的環境穩定。詳情請參閱「呼叫限制」。
其他應用程式沒有進行中的通話
如要在其他應用程式沒有進行中的通話時接聽來電,請按照下列步驟操作:
- 應用程式會使用一般機制接收新來電。
- 使用
addNewIncomingCall(PhoneAccountHandle, Bundle)方法,將新的來電通知電信子系統。 - 電信子系統會繫結至應用程式的
ConnectionService實作,並使用onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)方法要求代表新來電的Connection類別新例項。 - 電信子系統會使用
onShowIncomingCallUi()方法,通知應用程式應顯示來電使用者介面。 - 應用程式會使用通知和相關聯的全螢幕意圖,顯示來電 UI。詳情請參閱
onShowIncomingCallUi()。 - 如果使用者接受來電,請呼叫
setActive()方法;如果使用者拒絕來電,請呼叫setDisconnected(DisconnectCause)並指定REJECTED做為參數,然後呼叫destroy()方法。
其他應用程式中的通話無法保留
如要在其他應用程式有無法保留的通話時接聽來電,請按照下列步驟操作:
- 應用程式會使用一般機制接收新來電。
- 使用
addNewIncomingCall(PhoneAccountHandle, Bundle)方法,將新的來電通知電信子系統。 - 電信子系統會繫結至應用程式的
ConnectionService實作,並使用onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)方法要求代表新來電的Connection物件新例項。 - 電信子系統會顯示來電的使用者介面。
- 如果使用者接聽來電,電信子系統會呼叫
onAnswer()方法。您應呼叫setActive()方法,向電信子系統指出通話已連線。 - 如果使用者拒絕通話,電信子系統會呼叫
onReject()方法。您應呼叫setDisconnected(DisconnectCause)方法,並指定REJECTED做為參數,然後呼叫destroy()方法。
撥出電話
撥出電話的流程涉及處理因電信架構限制而無法撥打電話的可能性。詳情請參閱「呼叫限制」。
如要撥出電話,請按照下列步驟操作:
- 使用者在應用程式中撥出電話。
- 使用
placeCall(Uri, Bundle)方法,將新的撥出電話通知電信子系統。請留意下列方法參數:Uri參數代表通話撥打的地址。如為一般電話號碼,請使用tel:URI 配置。Bundle參數可讓您將應用程式的PhoneAccountHandle物件新增至EXTRA_PHONE_ACCOUNT_HANDLE額外項目,提供通話應用程式的相關資訊。應用程式必須為每通撥出電話提供PhoneAccountHandle物件。Bundle參數也可讓您指定撥出電話是否包含影片,方法是在EXTRA_START_CALL_WITH_VIDEO_STATE額外項目中指定STATE_BIDIRECTIONAL值。請注意,根據預設,電信子系統會將視訊通話轉送至擴音模式。
- 電信子系統會繫結至應用程式的
ConnectionService實作。 - 如果應用程式無法撥出電話,電信子系統會呼叫
onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)方法,通知應用程式目前無法撥出電話。應用程式應告知使用者無法撥打電話。 - 如果應用程式可以撥出電話,電信子系統會呼叫
onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)方法。應用程式應傳回Connection類別的例項,代表新的撥出電話。如要進一步瞭解應在連線中設定的屬性,請參閱「實作連線服務」。 - 撥出電話接通後,請呼叫
setActive()方法,通知電信子系統通話已啟用。
結束通話
如要結束通話,請按照下列步驟操作:
- 如果使用者終止通話,請呼叫
setDisconnected(DisconnectCause),並傳送LOCAL做為參數;如果另一方終止通話,則傳送REMOTE做為參數。 - 呼叫
destroy()方法。
通話限制
為確保使用者享有簡單一致的通話體驗,電信架構會強制執行一些限制,管理裝置上的通話。舉例來說,假設使用者安裝了兩個通話應用程式,分別是 FooTalk 和 BarTalk,這兩個應用程式都實作了自行管理的 ConnectionService API。在這種情況下,適用下列限制:
在搭載 API 級別 27 以下版本的裝置上,一次只能有一個應用程式維持通話。這項限制表示,當使用者透過 FooTalk 應用程式進行通話時,BarTalk 應用程式無法發起或接聽新通話。
在搭載 API 級別 28 以上版本的裝置上,如果 FooTalk 和 BarTalk 都宣告
CAPABILITY_SUPPORT_HOLD和CAPABILITY_HOLD權限,使用者就能在應用程式之間切換,發起或接聽其他通話,同時維持多通進行中的通話。如果使用者正在進行一般受管理通話 (例如使用內建的「電話」或「撥號程式」應用程式),就無法接聽通話應用程式發起的通話。也就是說,如果使用者正在透過行動電信業者進行一般通話,就無法同時進行 FooTalk 或 BarTalk 通話。
如果使用者撥打緊急電話,電信子系統會中斷應用程式的通話。
使用者撥打緊急電話時,應用程式無法接聽或撥打電話。
如果應用程式收到來電時,另一個通話應用程式正在通話,接聽來電會結束其他應用程式中的所有通話。應用程式不應顯示一般的來電使用者介面。電信架構會顯示來電使用者介面,並通知使用者接聽新來電會結束目前的通話。也就是說,如果使用者正在進行 FooTalk 通話,而 BarTalk 應用程式收到來電,電信架構會通知使用者有新的 BarTalk 來電,並告知接聽 BarTalk 來電會結束 FooTalk 通話。
成為預設「電話」應用程式
預設撥號程式/「電話」應用程式會在裝置通話時提供通話使用者介面。此外,使用者也可以透過這項功能在裝置上發起通話及查看通話記錄。裝置會隨附系統提供的預設撥號器/電話應用程式。使用者可以選擇單一應用程式,從系統應用程式接管這個角色。想要履行這個角色的應用程式會使用 RoleManager 要求填寫 RoleManager.ROLE_DIALER 角色。
當裝置處於通話狀態且未進入車用模式 (即 UiModeManager#getCurrentModeType() 不是 Configuration.UI_MODE_TYPE_CAR) 時,預設「電話」應用程式會提供使用者介面。
如要擔任 RoleManager.ROLE_DIALER 角色,應用程式必須符合多項規定:
- 必須處理
Intent#ACTION_DIAL意圖。也就是說,應用程式必須提供撥號鍵盤 UI,讓使用者撥出電話。 - 必須完整實作
InCallServiceAPI,並提供來電 UI 和通話中 UI。
使用者撥打緊急電話時,一律會使用預先載入的撥號器,即使應用程式填入 RoleManager.ROLE_DIALER 角色也一樣。為確保撥打緊急電話時能獲得最佳體驗,預設撥號器應一律使用 TelecomManager.placeCall(Uri, Bundle) 撥打電話 (包括緊急電話)。這可確保平台能夠驗證要求是否來自預設撥號器。如果非預先載入的撥號應用程式使用 Intent#ACTION_CALL 撥打緊急電話,系統會將該應用程式提升為使用 Intent#ACTION_DIAL 進行確認的預先載入撥號應用程式;這並非最佳的使用者體驗。
以下是 InCallService 的資訊清單註冊範例。中繼資料 TelecomManager#METADATA_IN_CALL_SERVICE_UI 表示這個特定的 InCallService 實作項目旨在取代內建的通話中 UI。中繼資料 TelecomManager#METADATA_IN_CALL_SERVICE_RINGING 表示這個 InCallService 會播放來電鈴聲。如要進一步瞭解如何在應用程式中顯示來電 UI 和播放鈴聲,請參閱下文。
<service android:name="your.package.YourInCallServiceImplementation"
android:permission="android.permission.BIND_INCALL_SERVICE"
android:exported="true">
<meta-data android:name="android.telecom.IN_CALL_SERVICE_UI" android:value="true" />
<meta-data android:name="android.telecom.IN_CALL_SERVICE_RINGING"
android:value="true" />
<intent-filter>
<action android:name="android.telecom.InCallService"/>
</intent-filter>
</service>
注意:請勿使用 android:exported="false" 屬性標記 InCallService,否則可能會導致在呼叫期間無法繫結至實作。
除了實作 InCallService API 之外,您還必須在資訊清單中宣告處理 Intent#ACTION_DIAL 意圖的活動。以下範例說明如何執行這項操作:
<activity android:name="your.package.YourDialerActivity"
android:label="@string/yourDialerActivityLabel">
<intent-filter>
<action android:name="android.intent.action.DIAL" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.DIAL" />
<category android:name="android.intent.category.DEFAULT" />
<data android:scheme="tel" />
</intent-filter>
</activity>
使用者安裝並首次執行應用程式時,您應使用 RoleManager 提示使用者,詢問是否要將應用程式設為新的預設電話應用程式。
以下程式碼說明應用程式如何要求成為預設電話/撥號應用程式:
private static final int REQUEST_ID = 1;
public void requestRole() {
RoleManager roleManager = (RoleManager) getSystemService(ROLE_SERVICE);
Intent intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_DIALER);
startActivityForResult(intent, REQUEST_ID);
}
public void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == REQUEST_ID) {
if (resultCode == android.app.Activity.RESULT_OK) {
// Your app is now the default dialer app
} else {
// Your app is not the default dialer app
}
}
}
穿戴式裝置的 InCallService 存取權
如果您的應用程式是第三方隨附應用程式,且想要存取 InCallService API,可以採取下列做法:
- 在資訊清單中宣告 MANAGE_ONGOING_CALLS 權限
- 透過
CompanionDeviceManagerAPI 與實體穿戴式裝置建立關聯,做為隨附應用程式。請參閱「配對裝置配對」。 - 使用 BIND_INCALL_SERVICE 權限實作這個 InCallService
顯示來電通知
當應用程式透過InCallService#onCallAdded(Call) 收到新來電時,必須顯示來電的使用者介面。這項操作應使用 NotificationManager API 發布新的來電通知。
如果應用程式宣告中繼資料 TelecomManager#METADATA_IN_CALL_SERVICE_RINGING,則負責播放來電鈴聲。應用程式應建立 NotificationChannel,指定所需鈴聲。例如:
NotificationChannel channel = new NotificationChannel(YOUR_CHANNEL_ID, "Incoming Calls",
NotificationManager.IMPORTANCE_MAX);
// other channel setup stuff goes here.
// We'll use the default system ringtone for our incoming call notification channel. You can
// use your own audio resource here.
Uri ringtoneUri = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE);
channel.setSound(ringtoneUri, new AudioAttributes.Builder()
// Setting the AudioAttributes is important as it identifies the purpose of your
// notification sound.
.setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
.setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
.build());
NotificationManager mgr = getSystemService(NotificationManager.class);
mgr.createNotificationChannel(channel);
應用程式收到新來電時,會為來電建立 Notification,並與來電通知管道建立關聯。您可以在通知上指定 PendingIntent,啟動全螢幕來電 UI。如果使用者正在使用手機,通知管理員架構會將通知顯示為抬頭通知。如果使用者未使用手機,系統會改用全螢幕來電 UI。例如:
// Create an intent which triggers your fullscreen incoming call user interface.
Intent intent = new Intent(Intent.ACTION_MAIN, null);
intent.setFlags(Intent.FLAG_ACTIVITY_NO_USER_ACTION | Intent.FLAG_ACTIVITY_NEW_TASK);
intent.setClass(context, YourIncomingCallActivity.class);
PendingIntent pendingIntent = PendingIntent.getActivity(context, 1, intent, PendingIntent.FLAG_MUTABLE_UNAUDITED);
// Build the notification as an ongoing high priority item; this ensures it will show as
// a heads up notification which slides down over top of the current content.
final Notification.Builder builder = new Notification.Builder(context);
builder.setOngoing(true);
builder.setPriority(Notification.PRIORITY_HIGH);
// Set notification content intent to take user to the fullscreen UI if user taps on the
// notification body.
builder.setContentIntent(pendingIntent);
// Set full screen intent to trigger display of the fullscreen UI when the notification
// manager deems it appropriate.
builder.setFullScreenIntent(pendingIntent, true);
// Setup notification content.
builder.setSmallIcon( yourIconResourceId );
builder.setContentTitle("Your notification title");
builder.setContentText("Your notification content.");
// Use builder.addAction(..) to add buttons to answer or reject the call.
NotificationManager notificationManager = mContext.getSystemService(
NotificationManager.class);
notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, builder.build());
```