ספריית Core-Telecom מייעלת את תהליך השילוב של אפליקציית השיחות עם פלטפורמת Android, באמצעות קבוצה עקבית ויציבה של ממשקי API.
אם אתם רוצים לבחון הטמעות מעשיות, תוכלו למצוא אפליקציות לדוגמה ב-GitHub:
- אפליקציה לדוגמה קלה – דוגמה מינימלית שממחישה את השימוש ב-API של
Core-Telecom. הוא אידיאלי להבנה מהירה של מושגים בסיסיים. - אפליקציה מקיפה לדוגמה (שפותחה על ידי צוות 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: כתובת השיחה (לדוגמה, מספר טלפון, קישור לפגישה ב-Meet). -
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 וקריאות חוזרות (callbacks) כדי להוסיף שיחה חדשה למערכת ולנהל עדכונים של תצוגה מרחוק. ההרשאה 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))
ניהול נקודות הקצה (endpoints) של האודיו בשיחות
צפייה בנקודות הקצה של האודיו וניהול שלהן באמצעות 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
מכשירים שמחוברים לרשת אחרת (שעונים חכמים, אוזניות Bluetooth, Android Auto) יכולים לנהל שיחות בלי אינטראקציה ישירה עם הטלפון. האפליקציה צריכה להטמיע פונקציות למבדה של קריאה חוזרת (onAnswerCall, onSetCallDisconnected, onSetCallActive, onSetCallInactive) שסופקו ל-CallsManager.addCall כדי לטפל בפעולות שהמכשירים האלה יזמו.
כשמתרחשת פעולה מרחוק, מופעלת פונקציית הלמבדה המתאימה.
השלמה מוצלחת של פונקציית הלמבדה מציינת שהפקודה עובדה. אם אי אפשר לבצע את הפקודה, ה-lambda אמורה להקפיץ חריגה.
הטמעה נכונה מאפשרת שליטה חלקה בשיחות במכשירים שונים. חשוב לבדוק את האפליקציה ביסודיות עם משטחים מרוחקים שונים.
תוספי שיחה
בנוסף לניהול מצב השיחה וניתוב האודיו של השיחות, הספרייה תומכת גם בתוספים לשיחות – תכונות אופציונליות שאפשר להטמיע באפליקציה כדי לשפר את חוויית השיחה בממשקים מרוחקים, כמו 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 של האפליקציה ליומן השיחות של המערכת, כדי שהן יופיעו בחייגן של המערכת והמשתמשים יוכלו להתקשר בחזרה משם. פרטים נוספים זמינים במאמר היסטוריית שיחות מאוחדת.