Обзор фреймворка Telecom

Фреймворк Android Telecom (также известный как Telecom) управляет аудио- и видеовызовами на устройствах Android. К ним относятся звонки по SIM-карте, например вызовы, в которых используется фреймворк телефонии, и VoIP-звонки, в которых реализована библиотека Jetpack Core-Telecom.

Основные компоненты, которыми управляет Telecom, – это ConnectionService и InCallService.

Реализация ConnectionService основана на таких технологиях, как PSTN, для подключения вызовов к другим абонентам. Наиболее распространенная реализация ConnectionService на телефоне – это ConnectionService для телефонии. Оно соединяет звонки оператора.

Реализация InCallService предоставляет пользовательский интерфейс для звонков, управляемых Telecom, и позволяет пользователю контролировать эти звонки и взаимодействовать с ними. Самый распространенный пример InCallService – приложение "Телефон", которое поставляется вместе с устройством.

Telecom действует как коммутатор. Он направляет вызовы, которые предоставляют реализации ConnectionService, в пользовательские интерфейсы вызовов, которые предоставляют реализации InCallService.

Вот почему стоит внедрить Telecom API:

Создание приложения "Телефон" для замены существующего

Чтобы создать замену приложению "Телефон" по умолчанию на устройстве Android, реализуйте API InCallService. Реализация должна соответствовать следующим требованиям:

  • Оно не должно иметь никаких функций вызова и должно состоять исключительно из пользовательского интерфейса для вызова.
  • Оно должно обрабатывать все вызовы, известные фреймворку Telecom, и не делать предположений о характере вызовов. Например, не следует предполагать, что вызовы осуществляются через SIM-карту, или применять ограничения, связанные с определенным классом ConnectionService (например, ограничения для телефонных звонков не должны распространяться на видеовызовы).

Дополнительную информацию вы найдете в статье InCallService.

Интегрируйте решение для звонков

Чтобы интегрировать решение для звонков в Android, вы можете:

  • Используйте библиотеку Core-Telecom Jetpack с самостоятельным управлением. Этот вариант идеально подходит для разработчиков отдельных приложений для звонков, которые не хотят, чтобы их звонки показывались в приложении "Телефон" по умолчанию, а другие звонки – в их пользовательском интерфейсе.

    Интеграция с библиотекой Core-Telecom Jetpack позволяет приложению взаимодействовать не только с системной телефонией на устройстве, но и с другими отдельными приложениями для звонков, интегрированными с Telecom. Библиотека Core-Telecom также управляет маршрутизацией и фокусом аудио. Подробнее о том, как создать приложение для звонков…

  • Реализовать управляемый ConnectionService API. Этот вариант упрощает разработку решения для звонков, которое использует существующее приложение для телефона на устройстве, чтобы предоставить пользовательский интерфейс для звонков. Примеры: сторонние реализации SIP-телефонии и сервисы VoIP-телефонии. Подробная информация приведена в статье getDefaultDialerPackage().

    ConnectionService – это лишь средство связи. У него нет пользовательского интерфейса.

  • Реализовать API InCallService и ConnectionService. Этот вариант подходит, если вы хотите создать собственное решение для звонков на основе ConnectionService с собственным пользовательским интерфейсом, в котором также будут показываться все остальные звонки Android. При таком подходе реализация InCallService не должна делать никаких предположений об источниках вызовов, которые она отображает. Кроме того, ваша реализация ConnectionService должна работать, даже если приложение "Телефон" по умолчанию не выбрано в качестве вашего пользовательского InCallService.

Информация о входящих вызовах

На устройствах с Android 10 (уровень API 29) или более поздней версией ОС приложение может определять звонки с номеров, которых нет в адресной книге пользователя, как потенциальный спам. Пользователи могут включить автоматическое отклонение спам-звонков. Чтобы обеспечить пользователям большую прозрачность в отношении пропущенных вызовов, информация об этих заблокированных вызовах регистрируется в списке вызовов. При использовании API Android 10 не требуется получать от пользователя разрешение 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 устарела и заменена на API CallRedirectionService. 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
    }
}