Core-Telecom

Библиотека Core-Telecom упрощает интеграцию приложения для звонков с платформой Android, предоставляя надежный и согласованный набор API.

Если вы хотите изучить практические реализации, вы можете найти примеры приложений на GitHub:

  • Lightweight Sample App — минимальный пример приложения, демонстрирующий использование Core-Telecom API. Идеально подходит для быстрого понимания фундаментальных концепций.
  • Полнофункциональное пример приложения (разработано командой Core-Telecom). Приложение с расширенным набором функций, демонстрирующее продвинутые возможности Telecom и рекомендации по их использованию. Это отличный ресурс для понимания сложных сценариев интеграции.

Как настроить Core-Telecom

Добавьте зависимость androidx.core:core-telecom в файл build.gradle своего приложения.

dependencies {
    implementation ("androidx.core:core-telecom:1.0.0")
}

Объявите разрешение MANAGE_OWN_CALLS в файле AndroidManifest.xml:

<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />

Регистрация приложения

Зарегистрируйте приложение для звонков в Android с помощью CallsManager, чтобы начать добавлять звонки в систему. При регистрации укажите возможности приложения (например, поддержку аудио и видео):

val callsManager = CallsManager(context)

val capabilities: @CallsManager.Companion.Capability Int =
    (CallsManager.CAPABILITY_BASELINE or
          CallsManager.CAPABILITY_SUPPORTS_VIDEO_CALLING)

callsManager.registerAppWithTelecom(capabilities)

Управление звонками

Используйте Core-Telecom API, чтобы создавать жизненный цикл вызова и управлять им.

Как создать звонок

Объект CallAttributesCompat определяет свойства уникального звонка, который может иметь следующие характеристики:

  • displayName – имя звонящего.
  • address – адрес вызова (например, номер телефона или ссылка на встречу).
  • direction: входящий или исходящий.
  • callType: аудио или видео.
  • callCapabilities: поддерживает перенос и удержание.

Вот пример того, как создать входящий вызов:

fun createIncomingCallAttributes(
    callerName: String,
    callerNumber: String,
    isVideoCall: Boolean): CallAttributesCompat {
    val addressUri = Uri.parse("YourAppScheme:$callerNumber")

    return CallAttributesCompat(
        displayName = callerName,
        address = addressUri,
        direction = CallAttributesCompat.DIRECTION_INCOMING,
        callType = if (isVideoCall) {
            CallAttributesCompat.CALL_TYPE_VIDEO_CALL
        } else {
            CallAttributesCompat.CALL_TYPE_AUDIO_CALL
        },
        callCapabilities = CallAttributesCompat.SUPPORTS_SET_INACTIVE
    )
}

Добавить вызов

Используйте callsManager.addCall с CallAttributesCompat и обратными вызовами, чтобы добавить новый вызов в систему и управлять обновлениями удаленного интерфейса. Элемент callControlScope в блоке addCall в основном позволяет приложению переключать состояние вызова и получать обновления аудио.

try {
    callsManager.addCall(
        INCOMING_CALL_ATTRIBUTES,
        onAnswerCall, // Watch needs to know if it can answer the call.
        onSetCallDisconnected,
        onSetCallActive,
        onSetCallInactive
    ) {
        // The call was successfully added once this scope runs.
        callControlScope = this
    }
}
catch(addCallException: Exception){
   // Handle the addCall failure.
}

Как ответить на звонок

Чтобы ответить на входящий вызов в CallControlScope:

when (val result = answer(CallAttributesCompat.CALL_TYPE_AUDIO_CALL)) {
    is CallControlResult.Success -> { /* Call answered */ }
    is CallControlResult.Error -> { /* Handle error */ }
}

Отклонить вызов

Отклонение вызова с помощью disconnect() с DisconnectCause.REJECTED в CallControlScope.

disconnect(DisconnectCause(DisconnectCause.REJECTED))

Как сделать исходящий вызов активным

Чтобы сделать исходящий вызов активным после ответа удаленной стороны, выполните следующие действия:

when (val result = setActive()) {
    is CallControlResult.Success -> { /* Call active */ }
    is CallControlResult.Error -> { /* Handle error */ }
}

Удержание вызова

Чтобы поставить вызов на удержание, используйте setInactive():

when (val result = setInactive()) {
    is CallControlResult.Success -> { /* Call on hold */ }
    is CallControlResult.Error -> { /* Handle error */ }
}

Как завершить вызов

Чтобы завершить вызов с помощью disconnect() и DisconnectCause:

disconnect(DisconnectCause(DisconnectCause.LOCAL))

Управление конечными точками аудиовызовов

Отслеживайте конечные точки аудио и управляйте ими с помощью currentCallEndpoint, availableEndpoints и isMuted Flow в CallControlScope. Не используйте API AudioManager#setCommunicationDevice или AudioManager#startBluetoothSco для управления маршрутами аудио при работе с Telecom, иначе во время звонка возникнут проблемы со звуком.

fun observeAudioStateChanges(callControlScope: CallControlScope) {
    with(callControlScope) {
        launch { currentCallEndpoint.collect { /* Update UI */ } }
        launch { availableEndpoints.collect { /* Update UI */ } }
        launch { isMuted.collect { /* Handle mute state */ } }
    }
}

Чтобы изменить активное аудиоустройство, используйте requestEndpointChange():

coroutineScope.launch {
     callControlScope.requestEndpointChange(callEndpoint)
}

Поддержка активных служб

Для поддержки активных служб библиотека использует ConnectionService на устройствах с Android 13 (уровень API 33) и более ранними версиями или типы активных служб на устройствах с Android 14 (уровень API 34) и более поздними версиями.

Чтобы звонки не прерывались, когда приложение работает в фоновом режиме, разместите CallsManager в активной службе Service (например, LifecycleService) и объявите тип активной службы phoneCall в файле AndroidManifest.xml:

<service
    android:name=".TelecomVoipService"
    android:foregroundServiceType="phoneCall" />

Согласно требованиям к активным службам, ваше приложение должно отправлять уведомление NotificationCompat.CallStyle, чтобы пользователи знали, что звонок активен. Чтобы приложение получило приоритет выполнения в активном режиме, после добавления вызова с платформой переведите службу в активный режим с помощью startForeground.

startForeground(
    notificationId,
    notification,
    ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL
)

Подробнее об активных службах…

Поддержка удаленных поверхностей

Удаленные устройства (умные часы, Bluetooth-гарнитуры, Android Auto) могут управлять звонками без прямого взаимодействия с телефоном. Чтобы обрабатывать действия, инициированные этими устройствами, в приложении должны быть реализованы лямбда-выражения обратного вызова (onAnswerCall, onSetCallDisconnected, onSetCallActive, onSetCallInactive), передаваемые в CallsManager.addCall.

При удаленном действии вызывается соответствующая лямбда-функция.

Успешное завершение лямбда-функции означает, что команда была обработана. Если команда не может быть выполнена, лямбда-функция должна выдать исключение.

Правильная реализация обеспечивает бесперебойное управление вызовами на разных устройствах. Тщательно протестируйте пульт на разных поверхностях.

Номера телефонов

Помимо управления статусом вызова и маршрутизацией аудио, библиотека также поддерживает расширения вызовов – дополнительные функции, которые ваше приложение может использовать для улучшения качества звонков на удаленных устройствах, например Android Auto. К ним относятся переговорные комнаты, отключение звука и дополнительные значки вызовов. Когда вы реализуете расширение в приложении, информация, которую оно предоставляет, будет синхронизироваться со всеми подключенными устройствами, которые также поддерживают показ этих расширений в своем интерфейсе. Это означает, что эти функции также будут доступны на удаленных устройствах для взаимодействия с пользователями.

Как создать кампанию с номером телефона и расширениями

При создании вызова вместо CallsManager.addCall можно использовать CallsManager.addCallWithExtensions. Это предоставит приложению доступ к другой области действия – ExtensionInitializationScope. Эта область действия позволяет приложению инициализировать набор поддерживаемых им дополнительных расширений. Кроме того, эта область действия предоставляет дополнительный метод onCall, который возвращает CallControlScope в приложение после завершения обмена возможностями расширения и инициализации.

scope.launch {
    mCallsManager.addCallWithExtensions(
        attributes,
        onAnswer,
        onDisconnect,
        onSetActive,
        onSetInactive
    ) {
        // Initialize extension-specific code...

        // After the call has been initialized, perform in-call actions
        onCall {
            // Example: process call state updates
            callStateFlow.onEach { newState ->
                // handle call state updates and notify telecom
            }.launchIn(this)

            // Use initialized extensions...
        }
    }
}

Поддержка участников звонков

Если ваше приложение поддерживает участников встреч или групповых звонков, используйте addParticipantExtension, чтобы заявить о поддержке этого расширения, и связанные API, чтобы обновлять удаленные поверхности при изменении участников.

mCallsManager.addCallWithExtensions(...) {
        // Initialize extensions...

        // Notifies Jetpack that this app supports the participant
        // extension and provides the initial participants state in the call.
        val participantExtension = addParticipantExtension(
            initialParticipants,
            initialActiveParticipant
        )

        // After the call has been initialized, perform in-call control actions
        onCall {
            // other in-call control and extension actions...

            // Example: update remote surfaces when the call participants change
            participantsFlow.onEach { newParticipants ->
                participantExtension.updateParticipants(newParticipants)
            }.launchIn(this)
        }
    }

Помимо уведомления удаленных устройств о том, какие участники находятся на звонке, активного участника также можно обновить с помощью ParticipantExtension#updateActiveParticipant.

Также поддерживаются дополнительные действия, связанные с участниками звонка. Приложение может использовать ParticipantExtension#addRaiseHandSupport, чтобы поддерживать функцию поднятия руки во время звонка и видеть, кто ещё из участников поднял руку.

mCallsManager.addCallWithExtensions(...) {
        // Initialize extensions...

        // Notifies Jetpack that this app supports the participant
        // extension and provides the initial list of participants in the call.
        val participantExtension = addParticipantExtension(initialParticipants)
        // Notifies Jetpack that this app supports the notion of participants
        // being able to raise and lower their hands.
        val raiseHandState = participantExtension.addRaiseHandSupport(
                initialRaisedHands
            ) { onHandRaisedStateChanged ->
                // handle this user's raised hand state changed updates from
                // remote surfaces.
            }

        // After the call has been initialized, perform in-call control actions
        onCall {
            // other in-call control and extension actions...

            // Example: update remote surfaces when the call participants change
            participantsFlow.onEach { newParticipants ->
                participantExtension.updateParticipants(newParticipants)
            }.launchIn(this)
            // notify remote surfaces of which of the participants have their
            // hands raised
            raisedHandsFlow.onEach { newRaisedHands ->
                raiseHandState.updateRaisedHands(newRaisedHands)
            }.launchIn(this)
        }
    }

Поддержка отключения звука звонка

Отключение звука позволяет пользователю запросить, чтобы приложение отключило исходящий звук вызова без физического отключения микрофона устройства. Эта функция управляется для каждого вызова, поэтому Jetpack справляется со сложностью управления глобальным состоянием отключения звука текущих сотовых вызовов, пока активен вызов VOIP. Это снижает вероятность ошибок при отключении исходящего аудио в сценариях с многократными вызовами, а также позволяет использовать полезные функции, такие как индикация «вы говорите», когда пользователь говорит, не понимая, что звук вызова отключен.

mCallsManager.addCallWithExtensions(...) {
        // Initialize extensions...

        // Add support for locally silencing the call's outgoing audio and
        // register a handler for when the user changes the call silence state
        // from a remote surface.
        val callSilenceExtension = addLocalCallSilenceExtension(
            initialCallSilenceState = false
        ) { newCallSilenceStateRequest ->
            // handle the user's request to enable/disable call silence from
            // a remote surface
        }

        // After the call has been initialized, perform in-call control actions
        onCall {
            // other in-call control and extension actions...

            // When the call's call silence state changes, update remote
            // surfaces of the new state.
            callSilenceState.onEach { isSilenced ->
                callSilenceExtension.updateIsLocallySilenced(isSilenced)
            }.launchIn(this)
        }
    }

Значки звонка в службу поддержки

Значок вызова позволяет приложению указать собственный значок, представляющий вызов, который будет отображаться на удаленных поверхностях во время вызова. Этот значок также может обновляться в течение всего времени вызова.

mCallsManager.addCallWithExtensions(...) {
        // Initialize extensions...

        // Add support for a custom call icon to be displayed during the
        // lifetime of the call.
        val callIconExtension = addCallIconExtension(
            initialCallIconUri = initialUri
        )

        // After the call has been initialized, perform in-call control actions
        onCall {
            // other in-call control and extension actions...

            // When the call's icon changes, update remote surfaces by providing
            // the new URI.
            callIconUri.onEach { newIconUri ->
                callIconExtension.updateCallIconUri(newIconUri)
            }.launchIn(this)
        }
    }

Добавление в системный список вызовов

Вы можете добавить VoIP-вызовы из приложения в системный список вызовов, чтобы они отображались в системном номеронабирателе и пользователи могли перезванивать из него. Подробнее о едином журнале звонков…