Supporting Third-Party Calling Apps

Android 9 provides APIs to better support third-party (3P) calling apps. 3P calling apps typically rely on Telephony APIs such as the PHONE_STATE broadcast to co-exist alongside carrier phone calls. As a consequence, 3P calling apps must give carrier calls priority and often resort to silently rejecting incoming calls in the app, or terminating an ongoing call to make way for a carrier call.

The APIs in Android 9 support concurrent calling scenarios between 3P apps and carrier calls. This makes it possible, for example, to receive an incoming 3P call while engaged in a carrier call. The framework assumes responsibility for ensuring the carrier call is held when the user engages in the 3P call.

In Android 9, 3P calling apps are encouraged to implement the self-managed ConnectionService API. For more information on how to build a calling app using this API, see Build a calling app.

The self-managed ConnectionService API also gives developers the opportunity to opt-in to having calls in their app logged in the system call log (see EXTRA_LOG_SELF_MANAGED_CALLS). Per the requirements in the Android Compatibility Definition Document (CDD) (section 7.4.1.2), you should ensure your dialer/phone app displays these call log entries and shows the name of the 3P calling app where the call originated (for an example of how the AOSP dialer app meets this requirement, see Call log entries from 3P calling apps).

Apps are responsible for setting CAPABILITY_SUPPORT_HOLD and CAPABILITY_HOLD on their apps' connections. However, it is possible that an app cannot hold a call in some circumstances. The framework includes provisions for resolving these types of cases.

Scenarios

You should modify your dialer app to handle the following scenarios.

Handling incoming calls which disconnect an ongoing call

In a scenario where there is an ongoing 3P call (e.g. in a SuperCaller call) that does not support hold, and the user receives a mobile call (e.g. via their carrier FooCom), your Dialer/Phone app should indicate to the user that answering the mobile network call will end the ongoing 3P call.

This user experience is important as a 3P calling app may have an ongoing call that cannot be held by the framework. Answering a new mobile call causes the ongoing 3P call to be disconnected.

See the user interface below for an example:

Incoming call disconnecting an ongoing 3P call
Figure 1. Incoming call which disconnects an ongoing 3P call

Your dialer app can check if an incoming call causes another call to be disconnected by checking the call extras. Make sure that EXTRA_ANSWERING_DROPS_FG_CALL is set to TRUE, and EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME is set to the name of the app whose call is disconnected upon answering the incoming mobile call.

Call log entries from 3P calling apps

Developers of 3P calling apps can opt-in to having calls in their app logged in the system call log (see EXTRA_LOG_SELF_MANAGED_CALLS). This means that it is possible to have entries in the call log that are not for mobile network calls.

When the AOSP dialer app displays call log entries related to a 3P calling app, the name of the app where the call took place is displayed in the call log, as illustrated below:

Call log entry with 3P calling app
Figure 2. Call log entry with name of 3P calling app on dialer app

To determine the name of an app associated with a call log entry, use the PHONE_ACCOUNT_COMPONENT_NAME and PHONE_ACCOUNT_ID columns in the call log provider to create an instance of PhoneAccountHandle, which identifies the source of a call log entry. Query TelecomManager to get the details for the PhoneAccount.
To determine if a call log entry is from a 3P calling app, check PhoneAccount capabilities to see if CAPABILITY_SELF_MANAGED is set.

The getLabel method of the returned PhoneAccount returns the name of the app associated with a call log entry from the 3P calling app.

Validation

To test that your device supports 3P calling apps, use the Telecomm test application, which implements the self-managed ConnectionService API. The application is located in /packages/services/Telecomm/testapps/.

  1. Build the test app from the root of your Android source repository using:

    mmma packages/services/Telecomm/testapps/

  2. Install the build apk using adb install -g -r <apk path>. A Self-Managed Sample icon is then added to your launcher.

  3. Tap the icon to open the test application.

Handling incoming calls which disconnect an ongoing call

Follow these steps to verify that an incoming call disconnects an ongoing 3P call.

Test application for 3P calling apps
Figure 3. Test application with sample implementations of the self-managed ConnectionService API
  1. Uncheck the Holdable option.
  2. Tap OUTGOING to start a new sample outgoing call.
  3. Tap the ACTIVE button to make the call go active.
  4. Call the phone number of the device under test with another phone. This invokes the scenario where your dialer is provided with the name of an app, which will have its call disconnected.
  5. When you are finished, tap the DISCONNECT button in the test app.

Call log entries from 3P calling apps

After completing the steps above, the test app should have logged a call to the system call log. To confirm the device logs calls from 3P calling apps, open your dialer app and confirm the call appears in the system call log.