建構預設手機應用程式

預設電話應用程式可讓 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 類別實作的新例項 (詳情請參閱「實作連線」),代表新的撥出電話。您可以執行下列動作,進一步自訂連出連線:

onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)

當應用程式呼叫 placeCall(Uri, Bundle) 方法,且無法撥出電話時,電信子系統會呼叫這個方法。在這種情況下,應用程式應通知使用者 (例如使用快訊方塊或浮動式訊息) 無法撥出電話。如果正在進行緊急電話,或另一個應用程式正在進行通話,且無法在撥打電話前保留通話,應用程式可能無法撥打電話。

onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)

當應用程式呼叫 addNewIncomingCall(PhoneAccountHandle, Bundle) 方法,通知系統有新的來電時,電信子系統會呼叫這個方法。應用程式會傳回 Connection 實作的新例項 (詳情請參閱「實作連線」),代表新的來電。您可以執行下列動作,進一步自訂傳入連線:

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 處理這些情境。

接聽來電

無論其他應用程式是否有通話,處理來電的流程都會變更。流程之所以不同,是因為其他應用程式有進行中的通話時,電信架構必須建立一些限制,確保裝置上所有通話應用程式的環境穩定。詳情請參閱「呼叫限制」。

其他應用程式沒有進行中的通話

如要在其他應用程式沒有進行中的通話時接聽來電,請按照下列步驟操作:

  1. 應用程式會使用一般機制接收新來電。
  2. 使用 addNewIncomingCall(PhoneAccountHandle, Bundle) 方法,將新的來電通知電信子系統。
  3. 電信子系統會繫結至應用程式的 ConnectionService 實作,並使用 onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest) 方法要求代表新來電的 Connection 類別新例項。
  4. 電信子系統會使用 onShowIncomingCallUi() 方法,通知應用程式應顯示來電使用者介面。
  5. 應用程式會使用通知和相關聯的全螢幕意圖,顯示來電 UI。詳情請參閱 onShowIncomingCallUi()。
  6. 如果使用者接受來電,請呼叫 setActive() 方法;如果使用者拒絕來電,請呼叫 setDisconnected(DisconnectCause) 並指定 REJECTED 做為參數,然後呼叫 destroy() 方法。

其他應用程式中的通話無法保留

如要在其他應用程式有無法保留的通話時接聽來電,請按照下列步驟操作:

  1. 應用程式會使用一般機制接收新來電。
  2. 使用 addNewIncomingCall(PhoneAccountHandle, Bundle) 方法,將新的來電通知電信子系統。
  3. 電信子系統會繫結至應用程式的 ConnectionService 實作,並使用 onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest) 方法要求代表新來電的 Connection 物件新例項。
  4. 電信子系統會顯示來電的使用者介面。
  5. 如果使用者接聽來電,電信子系統會呼叫 onAnswer() 方法。您應呼叫 setActive() 方法,向電信子系統指出通話已連線。
  6. 如果使用者拒絕通話,電信子系統會呼叫 onReject() 方法。您應呼叫 setDisconnected(DisconnectCause) 方法,並指定 REJECTED 做為參數,然後呼叫 destroy() 方法。

撥出電話

撥出電話的流程涉及處理因電信架構限制而無法撥打電話的可能性。詳情請參閱「呼叫限制」。

如要撥出電話,請按照下列步驟操作:

  1. 使用者在應用程式中撥出電話。
  2. 使用 placeCall(Uri, Bundle) 方法,將新的撥出電話通知電信子系統。請留意下列方法參數:
    • Uri 參數代表通話撥打的地址。如為一般電話號碼,請使用 tel: URI 配置。
    • Bundle 參數可讓您將應用程式的 PhoneAccountHandle 物件新增至 EXTRA_PHONE_ACCOUNT_HANDLE 額外項目,提供通話應用程式的相關資訊。應用程式必須為每通撥出電話提供 PhoneAccountHandle 物件。
    • Bundle 參數也可讓您指定撥出電話是否包含影片,方法是在 EXTRA_START_CALL_WITH_VIDEO_STATE 額外項目中指定 STATE_BIDIRECTIONAL 值。請注意,根據預設,電信子系統會將視訊通話轉送至擴音模式。
  3. 電信子系統會繫結至應用程式的 ConnectionService 實作。
  4. 如果應用程式無法撥出電話,電信子系統會呼叫 onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest) 方法,通知應用程式目前無法撥出電話。應用程式應告知使用者無法撥打電話。
  5. 如果應用程式可以撥出電話,電信子系統會呼叫 onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest) 方法。應用程式應傳回 Connection 類別的例項,代表新的撥出電話。如要進一步瞭解應在連線中設定的屬性,請參閱「實作連線服務」。
  6. 撥出電話接通後,請呼叫 setActive() 方法,通知電信子系統通話已啟用。

結束通話

如要結束通話,請按照下列步驟操作:

  1. 如果使用者終止通話,請呼叫 setDisconnected(DisconnectCause),並傳送 LOCAL 做為參數;如果另一方終止通話,則傳送 REMOTE 做為參數。
  2. 呼叫 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,讓使用者撥出電話。
  • 必須完整實作 InCallService API,並提供來電 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,可以採取下列做法:

  1. 在資訊清單中宣告 MANAGE_ONGOING_CALLS 權限
  2. 透過 CompanionDeviceManager API 與實體穿戴式裝置建立關聯,做為隨附應用程式。請參閱「配對裝置配對」。
  3. 使用 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());
```