ไลบรารี Core-Telecom ช่วยปรับปรุงกระบวนการผสานรวมแอปพลิเคชันการโทรกับแพลตฟอร์ม Android โดยการจัดเตรียมชุด API ที่มีประสิทธิภาพและสอดคล้องกัน
หากต้องการสำรวจการใช้งานจริง คุณสามารถดูแอปพลิเคชันตัวอย่างได้ใน GitHub ดังนี้
- แอปตัวอย่างแบบ Lightweight - ตัวอย่างขั้นต่ำที่สาธิตการใช้งาน API ของ
Core-Telecomเหมาะสำหรับการทำความเข้าใจแนวคิดพื้นฐานอย่างรวดเร็ว - แอปตัวอย่างที่ครอบคลุม (พัฒนาโดยทีม Core-Telecom) - แอปพลิเคชันที่มีฟีเจอร์หลากหลายมากขึ้นซึ่งแสดงฟังก์ชันการทำงานขั้นสูงของ Telecom และแนวทางปฏิบัติแนะนำ ซึ่งเป็นแหล่งข้อมูลที่ยอดเยี่ยมสำหรับการทำความเข้าใจสถานการณ์การผสานรวมที่ซับซ้อน
ตั้งค่า Core-Telecom
เพิ่มทรัพยากร Dependency 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 และ Callback เพื่อเพิ่มการโทรใหม่ไปยังระบบและจัดการการอัปเดตแพลตฟอร์มระยะไกล 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 )
ดูข้อมูลเพิ่มเติมเกี่ยวกับบริการที่ทำงานอยู่เบื้องหน้า
การสนับสนุนระยะไกลสำหรับ Surface
อุปกรณ์ระยะไกล (สมาร์ทวอทช์, ชุดหูฟังบลูทูธ, Android Auto) สามารถจัดการการโทรได้โดยไม่ต้องโต้ตอบกับโทรศัพท์โดยตรง แอปของคุณต้องใช้ Callback Lambda (onAnswerCall, onSetCallDisconnected, onSetCallActive, onSetCallInactive) ที่ส่งไปยัง CallsManager.addCall เพื่อจัดการการดำเนินการที่อุปกรณ์เหล่านี้เริ่มต้น
เมื่อมีการดำเนินการระยะไกล ระบบจะเรียกใช้ Lambda ที่เกี่ยวข้อง
การดำเนินการ Lambda สำเร็จจะส่งสัญญาณว่าคำสั่งได้รับการประมวลผลแล้ว หากไม่สามารถปฏิบัติตามคำสั่งได้ แลมบ์ดาควรแสดงข้อยกเว้น
การติดตั้งใช้งานที่เหมาะสมจะช่วยให้ควบคุมการโทรในอุปกรณ์ต่างๆ ได้อย่างราบรื่น ทดสอบอย่างละเอียดด้วยแพลตฟอร์มระยะไกลต่างๆ
ชิ้นงานการโทร
นอกจากการจัดการสถานะการโทรและเส้นทางเสียงของการโทรแล้ว ไลบรารียังรองรับส่วนขยายการโทร ซึ่งเป็นฟีเจอร์เสริมที่แอปของคุณสามารถใช้เพื่อประสบการณ์การโทรที่สมบูรณ์ยิ่งขึ้นบนแพลตฟอร์มระยะไกล เช่น Android Auto ฟีเจอร์เหล่านี้รวมถึงห้องประชุม การปิดเสียงการโทร และไอคอนการโทรเพิ่มเติม เมื่อแอปใช้ส่วนขยาย ข้อมูลที่แอปให้ไว้จะซิงค์กับอุปกรณ์ที่เชื่อมต่อทั้งหมดซึ่งรองรับการแสดงส่วนขยายเหล่านี้ใน UI ด้วย ซึ่งหมายความว่าฟีเจอร์เหล่านี้จะพร้อมใช้งานในอุปกรณ์ระยะไกลเพื่อให้ผู้ใช้โต้ตอบด้วย
สร้างการโทรด้วยส่วนขยาย
เมื่อสร้างการเรียก แทนที่จะใช้ 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 ของแอปลงในบันทึกการโทรของระบบเพื่อให้ปรากฏในแป้นโทรศัพท์ของระบบ และผู้ใช้สามารถโทรกลับจากที่นั่นได้ โปรดดูรายละเอียดที่หัวข้อประวัติการโทรแบบรวม