Thư viện Core-Telecom đơn giản hoá quy trình tích hợp ứng dụng gọi với nền tảng Android bằng cách cung cấp một bộ API mạnh mẽ và nhất quán
Nếu muốn tìm hiểu cách triển khai thực tế, bạn có thể tìm thấy các ứng dụng mẫu trên GitHub:
- Ứng dụng mẫu gọn nhẹ – Một ví dụ tối thiểu minh hoạ cách sử dụng API
Core-Telecom. Lý tưởng để nhanh chóng hiểu các khái niệm cơ bản. - Ứng dụng mẫu toàn diện (do Nhóm Core-Telecom phát triển) – Một ứng dụng có nhiều tính năng hơn, giới thiệu các chức năng Viễn thông nâng cao và các phương pháp hay nhất. Đây là một tài nguyên tuyệt vời để hiểu các tình huống tích hợp phức tạp.
Thiết lập Core-Telecom
Thêm phần phụ thuộc androidx.core:core-telecom vào tệp build.gradle của ứng dụng:
dependencies {
implementation ("androidx.core:core-telecom:1.0.0")
}
Khai báo quyền MANAGE_OWN_CALLS trong AndroidManifest.xml:
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
Đăng ký ứng dụng của bạn
Đăng ký ứng dụng gọi điện của bạn với Android bằng CallsManager để bắt đầu thêm lệnh gọi vào hệ thống. Khi đăng ký, hãy chỉ định các chức năng của ứng dụng (ví dụ: hỗ trợ âm thanh, video):
val callsManager = CallsManager(context)
val capabilities: @CallsManager.Companion.Capability Int =
(CallsManager.CAPABILITY_BASELINE or
CallsManager.CAPABILITY_SUPPORTS_VIDEO_CALLING)
callsManager.registerAppWithTelecom(capabilities)
Quản lý cuộc gọi
Sử dụng API Core-Telecom để tạo và quản lý vòng đời cuộc gọi.
Tạo lệnh gọi
Đối tượng CallAttributesCompat xác định các thuộc tính của một lệnh gọi duy nhất, lệnh gọi này có thể có các đặc điểm sau:
displayName: tên người gọi.address: Địa chỉ cuộc gọi (ví dụ: số điện thoại, đường liên kết đến cuộc họp).direction: Đến hoặc đi.callType: Âm thanh hoặc video.callCapabilities: Hỗ trợ chuyển và giữ.
Sau đây là ví dụ về cách tạo cuộc gọi đến:
fun createIncomingCallAttributes(
callerName: String,
callerNumber: String,
isVideoCall: Boolean): CallAttributesCompat {
val addressUri = Uri.parse("YourAppScheme:$callerNumber")
// Define capabilities supported by your call.
val callCapabilities = CallAttributesCompat.CallCapability(
supportsSetInactive = CallAttributesCompat.SUPPORTS_SET_INACTIVE // Call can be made inactive (implies hold)
)
return CallAttributesCompat(
displayName = callerName,
address = addressUri,
direction = CallAttributesCompat.DIRECTION_INCOMING,
callType = if (isVideoCall) CallAttributesCompat.CALL_TYPE_VIDEO_CALL else CallAttributesCompat.CALL_TYPE_AUDIO_CALL,
callCapabilitiesCompat = callCapabilities
)
}
Thêm cuộc gọi
Sử dụng callsManager.addCall với CallAttributesCompat và lệnh gọi lại để thêm một lệnh gọi mới vào hệ thống và quản lý các bản cập nhật bề mặt từ xa. callControlScope trong khối addCall chủ yếu cho phép ứng dụng chuyển đổi trạng thái cuộc gọi và nhận thông tin cập nhật về âm thanh:
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.
}
Trả lời cuộc gọi
Trả lời cuộc gọi đến trong CallControlScope:
when (val result = answer(CallAttributesCompat.CALL_TYPE_AUDIO_CALL)) {
is CallControlResult.Success -> { /* Call answered */ }
is CallControlResult.Error -> { /* Handle error */ }
}
Từ chối cuộc gọi
Từ chối cuộc gọi bằng cách sử dụng disconnect() với DisconnectCause.REJECTED trong CallControlScope:
disconnect(DisconnectCause(DisconnectCause.REJECTED))
Đang thực hiện cuộc gọi đi
Đặt cuộc gọi đi thành đang hoạt động sau khi bên từ xa trả lời:
when (val result = setActive()) {
is CallControlResult.Success -> { /* Call active */ }
is CallControlResult.Error -> { /* Handle error */ }
}
Giữ cuộc gọi
Sử dụng setInactive() để giữ cuộc gọi:
when (val result = setInactive()) {
is CallControlResult.Success -> { /* Call on hold */ }
is CallControlResult.Error -> { /* Handle error */ }
}
Ngắt kết nối cuộc gọi
Ngắt kết nối cuộc gọi bằng disconnect() với DisconnectCause:
disconnect(DisconnectCause(DisconnectCause.LOCAL))
Quản lý điểm cuối âm thanh cuộc gọi
Quan sát và quản lý các điểm cuối âm thanh bằng cách sử dụng Flow currentCallEndpoint, availableEndpoints và isMuted trong CallControlScope
fun observeAudioStateChanges(callControlScope: CallControlScope) {
with(callControlScope) {
launch { currentCallEndpoint.collect { /* Update UI */ } }
launch { availableEndpoints.collect { /* Update UI */ } }
launch { isMuted.collect { /* Handle mute state */ } }
}
}
Thay đổi thiết bị âm thanh đang hoạt động bằng requestEndpointChange():
coroutineScope.launch {
callControlScope.requestEndpointChange(callEndpoint)
}
Hỗ trợ trên nền trước
Thư viện này sử dụng ConnectionService (Android 13 API cấp 33 trở xuống) hoặc foregroundtypes (Android 14 API cấp 34 trở lên) để hỗ trợ chế độ nền trước.
Theo yêu cầu về chế độ nền trước, ứng dụng phải đăng thông báo để người dùng biết rằng ứng dụng đang chạy ở chế độ nền trước.
Để đảm bảo ứng dụng của bạn được ưu tiên thực thi trên nền trước, hãy tạo một thông báo sau khi bạn thêm lệnh gọi với nền tảng. Mức độ ưu tiên ở nền trước sẽ bị xoá khi ứng dụng của bạn chấm dứt lệnh gọi hoặc thông báo của bạn không còn hợp lệ.
Tìm hiểu thêm về dịch vụ trên nền trước.
Hỗ trợ Surface từ xa
Các thiết bị từ xa (đồng hồ thông minh, tai nghe Bluetooth, Android Auto) có thể quản lý cuộc gọi mà không cần tương tác trực tiếp với điện thoại. Ứng dụng của bạn phải triển khai các hàm callback lambda (onAnswerCall, onSetCallDisconnected, onSetCallActive, onSetCallInactive) được cung cấp cho CallsManager.addCall để xử lý các thao tác do các thiết bị này khởi tạo.
Khi một thao tác từ xa xảy ra, lambda tương ứng sẽ được gọi.
Hoàn tất thành công các tín hiệu lambda cho biết lệnh đã được xử lý. Nếu không thể tuân theo lệnh, hàm lambda sẽ gửi một ngoại lệ.
Việc triển khai đúng cách đảm bảo tính năng điều khiển cuộc gọi liền mạch trên nhiều thiết bị. Kiểm thử kỹ lưỡng với nhiều bề mặt từ xa.