默认电话应用可让 Android Telecom 框架通过角色管理器和通话中服务将通话状态告知您的应用,从而在 Android 设备上创建默认电话应用的替代应用,实现 InCallService API。您的实现必须满足以下要求:
它不得具有任何通话功能,并且必须仅包含通话界面。 它必须处理 Telecom 框架已知的所有通话,并且不得对通话的性质做出假设。例如,它不得假定通话是基于 SIM 卡的电话通话,也不得实现基于任何一个 ConnectionService 的通话限制,例如对视频通话强制执行电话限制。
借助通话应用,用户可以在自己的设备上接听或拨打语音或视频通话。通话应用使用自己的界面(而不是默认的“电话”应用界面)显示通话,如以下屏幕截图所示。

使用自己界面的通话应用示例
Android 框架包含 android.telecom 软件包,其中包含可帮助您根据 Telecom 框架构建通话应用的类。根据 Telecom 框架构建应用具有以下优势:
- 您的应用可以与设备中的原生 Telecom 子系统正常进行互操作。
- 您的应用可以与其他同样遵循该框架的通话应用正常进行互操作。
- 该框架有助于您的应用管理音频和视频转接。
- 该框架有助于您的应用确定其通话是否具有焦点。
清单声明和权限
在应用清单中,声明您的应用使用 MANAGE_OWN_CALLS 权限,如以下示例所示:
<manifest … >
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
</manifest>
如需详细了解如何声明应用权限,请参阅权限。
您必须声明一项服务,该服务指定用于在您的应用中实现 ConnectionService 类的类。Telecom 子系统要求该服务声明 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)Telecom 子系统调用此方法以响应您的应用对
placeCall(Uri, Bundle)的调用,从而创建新的去电。您的应用会返回Connection类实现的新实例(如需了解详情,请参阅实现连接)以表示新的去电。您可以通过执行以下操作进一步自定义去电连接:- 您的应用应使用
PROPERTY_SELF_MANAGED常量作为参数以调用setConnectionProperties(int)方法,从而指示连接来自通话应用。 - 如果您的应用支持将通话置于保持状态,请调用
setConnectionCapabilities(int)方法,并将该参数设置为CAPABILITY_HOLD和CAPABILITY_SUPPORT_HOLD常量的位掩码值。 - 如需设置来电者的姓名,请使用
setCallerDisplayName(String, int)方法并将PRESENTATION_ALLOWED常量作为int参数传递,以指示系统应显示来电者的姓名。 - 为了确保去电具有适当的视频状态,请调用
Connection对象的setVideoState(int)方法,并发送由ConnectionRequest对象的getVideoState()方法返回的值。
- 您的应用应使用
onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)Telecom 子系统会在您的应用调用
placeCall(Uri, Bundle)方法且无法拨出电话时调用此方法。为了应对这种情况,您的应用应告知用户(例如,使用提醒框或消息框)无法拨出电话。如果有正在进行的紧急呼叫或者在您拨打电话之前另一个应用中正在进行的通话无法置于保持状态,您的应用可能无法拨打电话。onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)Telecom 子系统会在您的应用调用
addNewIncomingCall(PhoneAccountHandle, Bundle)方法时调用此方法,以告知系统您的应用中有新的来电。您的应用会返回Connection实现的新实例(如需了解详情,请参阅实现连接)以表示新的来电。您可以通过执行以下操作进一步自定义来电连接:- 您的应用应使用
PROPERTY_SELF_MANAGED常量作为参数以调用setConnectionProperties(int)方法,从而指示连接来自通话应用。 - 如果您的应用支持将通话置于保持状态,请调用
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)Telecom 子系统会在您的应用调用
addNewIncomingCall(PhoneAccountHandle, Bundle)方法时调用此方法,以告知 Telecom 有新的来电,但此来电不受允许(如需了解详情,请参阅通话限制)。您的应用应拒绝来电且不发出提示音,可以选择发布通知以告知用户有未接电话。
实现连接
您的应用应创建 Connection 的子类以表示应用中的来电。您应在实现中替换以下方法:
onShowIncomingCallUi()Telecom 子系统会在您添加新的来电时调用此方法,并且您的应用应显示其来电界面。
onCallAudioStateChanged(CallAudioState)Telecom 子系统调用此方法来告知您的应用当前音频路径或模式已发生更改。这样做是为了响应您的应用使用
setAudioRoute(int)方法对音频模式做出的更改。如果系统更改了音频路径(例如,蓝牙耳机断开连接时),也可以调用此方法。onHold()当 Telecom 子系统想要将通话置于保持状态时,就会调用此方法。 为了响应此请求,您的应用应保持通话,然后调用
setOnHold()方法以告知系统通话正置于保持状态。Telecom 子系统可能会在显示通话的通话服务(例如 Android Auto)想要中继用户将通话置于保持状态的请求时调用此方法。如果用户在另一个应用中进行通话,Telecom 子系统也会调用此方法。如需详细了解通话服务,请参阅InCallService。onUnhold()当 Telecom 子系统想要恢复已置于保持状态的通话时,就会调用此方法。您的应用恢复通话后,应调用
setActive()方法以告知系统该通话已不再置于保持状态。当显示通话的通话服务(例如 Android Auto)想要中继恢复通话的请求时,Telecom 子系统可能会调用此方法。如需详细了解通话服务,请参阅InCallService。onAnswer()Telecom 子系统调用此方法以告知您的应用应该接听来电。当应用接听来电后,应调用
setActive()方法以告知系统已接听来电。如果您的应用添加了新的来电,并且另一个应用中已经有一个无法置于保持状态的正在进行的通话,Telecom 子系统可能会调用此方法。在这些情况下,Telecom 子系统会代表您的应用显示来电界面。该框架提供了一种过载方法,支持指定接听来电的视频状态。如需了解详情,请参阅onAnswer(int)。onReject()Telecom 子系统会在想要拒接来电时调用此方法。您的应用拒接来电后,应调用
setDisconnected(DisconnectCause)并指定REJECTED作为参数。然后,您的应用应调用destroy()方法以告知系统应用已对来电进行处理。当用户拒接了来自您应用的来电时,Telecom 子系统会调用此方法。onDisconnect()Telecom 子系统会在它要断开通话连接时调用此方法。 通话结束后,您的应用应调用
setDisconnected(DisconnectCause)方法并指定LOCAL作为参数,以指明通话是因用户请求而断开的。然后,您的应用应调用destroy()方法以告知 Telecom 子系统应用已对来电进行处理。当用户通过其他通话服务(例如 Android Auto)断开通话连接时,系统可能会调用此方法。当您必须断开通话连接以允许拨打其他电话时(例如,如果用户想要进行紧急呼叫),系统也会调用此方法。如需详细了解通话服务,请参阅InCallService。
处理常见的通话场景
在调用流程中使用 ConnectionService API 涉及与 android.telecom 软件包中的其他类进行互动。以下部分介绍了常见的通话场景以及应用应如何使用 API 来处理这些场景。
接听来电
无论其他应用中是否存在来电,处理来电的流程都会发生变化。流程之所以会出现差异,是因为当其他应用中有正在进行的通话时,Telecom 框架必须建立一些限制条件,以确保设备上的所有通话应用都能有一个稳定的环境。如需了解详情,请参阅通话限制。
其他应用中没有正在进行的通话
如需在其他应用中没有正在进行的通话时接听来电,请按以下步骤操作:
- 您的应用会根据常规机制接收新来电。
- 使用
addNewIncomingCall(PhoneAccountHandle, Bundle)方法在有新来电时告知 Telecom 子系统。 - Telecom 子系统绑定到您应用的
ConnectionService实现,并使用onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)方法请求表示新来电的Connection类的新实例。 - Telecom 子系统会使用
onShowIncomingCallUi()方法告知您的应用应显示其来电界面。 - 您的应用会通过具有相关联的全屏 Intent 的通知来显示其来电界面。如需了解详情,请参阅
onShowIncomingCallUi()。 - 如果用户接听来电,则调用
setActive()方法;如果用户拒接来电,则调用setDisconnected(DisconnectCause),以将REJECTED指定为参数,然后调用destroy()方法。
其他应用中无法置于保持状态的正在进行的通话
如需在其他应用中有无法置于保持状态的正在进行的通话时接听来电,请按以下步骤操作:
- 您的应用会根据常规机制接收新来电。
- 使用
addNewIncomingCall(PhoneAccountHandle, Bundle)方法在有新来电时告知 Telecom 子系统。 - Telecom 子系统绑定到您应用的
ConnectionService实现,并使用onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)方法请求表示新来电的Connection对象的新实例。 - Telecom 子系统会为您的来电显示来电界面。
- 如果用户接听该来电,Telecom 子系统会调用
onAnswer()方法。您应调用setActive()方法,以告知 Telecom 子系统来电现已连接。 - 如果用户拒接该来电,Telecom 子系统会调用
onReject()方法。您应调用setDisconnected(DisconnectCause)方法,以将REJECTED指定为参数,然后调用destroy()方法。
拨出电话
拨出电话流程涉及处理以下情况:由于 Telecom 框架施加的限制而导致可能无法拨打电话。如需了解详情,请参阅通话限制。
如需拨出电话,请按以下步骤操作:
- 用户在您的应用内发起去电。
- 使用
placeCall(Uri, Bundle)方法告知 Telecom 子系统要新拨出电话。考虑以下关于方法参数的注意事项:Uri参数表示拨出电话的地址。对于普通电话号码,请使用tel:URI 架构。- 通过
Bundle参数,您可以将应用的PhoneAccountHandle对象添加到EXTRA_PHONE_ACCOUNT_HANDLEextra,以提供有关通话应用的信息。您的应用必须为每个去电提供PhoneAccountHandle对象。 - 通过
Bundle参数,您还可以在EXTRA_START_CALL_WITH_VIDEO_STATEextra 中指定STATE_BIDIRECTIONAL值,从而指定去电是否包含视频。请注意,默认情况下,Telecom 子系统会将视频通话转接到扬声器。
- Telecom 子系统绑定到您应用的
ConnectionService实现。 - 如果您的应用无法拨出电话,Telecom 子系统会调用
onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)方法以告知您的应用目前无法拨打电话。您的应用应告知用户无法拨打电话。 - 如果您的应用能够拨出电话,Telecom 子系统会调用
onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)方法。您的应用应返回Connection类的实例以表示新去电。如需详细了解应在连接中设置的属性,请参阅实现连接服务。 - 去电连接后,调用
setActive()方法,以告知 Telecom 子系统通话正在进行中。
结束通话
如需结束通话,请按以下步骤操作:
- 如果用户终止了通话,则调用
setDisconnected(DisconnectCause)并发送LOCAL作为参数;如果对方终止了通话,则发送REMOTE作为参数。 - 调用
destroy()方法。
通话限制
为了确保为用户提供一致且简单的通话体验,Telecom 框架针对管理设备上的通话施加了一些限制。例如,假设用户安装了两个通话应用,并且这两个应用实现了自行管理的 ConnectionService API:FooTalk 和 BarTalk。在这种情况下,应遵循以下限制条件:
在搭载 API 级别 27 或更低版本的设备上,任何时候都只有一个应用可以保持当前通话。这种限制意味着,当用户使用 FooTalk 应用进行通话时,BarTalk 应用无法发起或接听新的通话。
在搭载 API 级别 28 或更高版本的设备上,如果 FooTalk 和 BarTalk 都声明了
CAPABILITY_SUPPORT_HOLD和CAPABILITY_HOLD权限,用户就可以通过在两个应用之间进行切换发起或接收另一个通话,从而保持多个正在进行的通话。如果用户正在进行常规的受管理通话(例如,使用内置的电话或拨号器应用),用户无法进行来自通话应用的通话。也就是说,如果用户使用移动运营商正常通话,则无法同时进行 FooTalk 或 BarTalk 通话。
如果用户拨打紧急呼叫,Telecom 子系统会断开应用的通话连接。
当用户进行紧急呼叫时,您的应用无法接听或拨出电话。
如果在应用收到来电时,另一个通话应用中有正在进行的通话,接听来电会结束另一个应用中的当前通话。您的应用不应显示其正常的来电界面。Telecom 框架会显示来电界面,并告知用户接听新来电会结束当前通话。也就是说,如果用户正在进行 FooTalk 通话,而 BarTalk 应用收到来电,Telecom 框架会告知用户有新的 BarTalk 来电,并且接听 BarTalk 通话会结束 FooTalk 通话。
成为默认电话应用
默认拨号器/电话应用是指在设备进行通话时提供通话中界面的应用。它还为用户提供在设备上拨打电话和查看通话记录的途径。设备会与系统提供的默认拨号器/电话应用捆绑在一起。用户可以选择一个应用来接管系统应用的这一角色。希望履行此角色的应用会使用 RoleManager 请求履行 RoleManager.ROLE_DIALER 角色。
当设备处于通话状态且未处于车载模式(即 UiModeManager#getCurrentModeType() 不是 Configuration.UI_MODE_TYPE_CAR)时,默认电话应用会提供界面。
为了担任 RoleManager.ROLE_DIALER 角色,应用必须满足多项要求:
- 它必须处理
Intent#ACTION_DIALintent。这意味着应用必须提供拨号键盘界面,以便用户发起去电。 - 它必须完整实现
InCallServiceAPI,并提供来电界面和通话中界面。
当用户拨打紧急呼叫时,系统始终会使用预装的拨号器,即使您的应用填充了 RoleManager.ROLE_DIALER 角色也是如此。为确保在拨打紧急电话时获得最佳体验,默认拨号器应始终使用 TelecomManager.placeCall(Uri, Bundle) 拨打电话(包括紧急电话)。这样可以确保平台能够验证请求是否来自默认拨号器。如果非预加载的拨号器应用使用 Intent#ACTION_CALL 拨打紧急呼叫,系统会将其提升到使用 Intent#ACTION_DIAL 的预加载拨号器应用进行确认;这是一种欠佳的用户体验。
以下是 InCallService 的清单注册示例。元数据 TelecomManager#METADATA_IN_CALL_SERVICE_UI 表示此特定 InCallService 实现旨在替换内置的通话界面。
元数据 TelecomManager#METADATA_IN_CALL_SERVICE_RINGING 表示此 InCallService 将在有来电时播放铃声。如需详细了解如何在应用中显示来电界面和播放铃声,请参阅下文。
<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 intent 的 activity。以下示例说明了如何执行此操作:
<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,用于启动全屏来电界面。如果用户正在使用手机,通知管理器框架会将您的通知显示为浮动通知。当用户未使用手机时,系统会改用您的全屏来电界面。
例如:
// 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());
```