Core-Telecom kitaplığı, güçlü ve tutarlı bir API grubu sunarak arama uygulamanızı Android platformuyla entegre etme sürecini kolaylaştırır.
Pratik uygulamaları incelemek isterseniz GitHub'da örnek uygulamalar bulabilirsiniz:
- Hafif Örnek Uygulama:
Core-TelecomAPI kullanımını gösteren basit bir örnek. Temel kavramları hızlıca anlamak için idealdir. - Kapsamlı Örnek Uygulama (Core-Telecom Ekibi Tarafından Geliştirilmiştir): Gelişmiş Telecom işlevlerini ve en iyi uygulamaları gösteren, daha fazla özellik içeren bir uygulama. Karmaşık entegrasyon senaryolarını anlamak için bu kaynaktan yararlanabilirsiniz.
Core-Telecom'u ayarlama
Uygulamanızın build.gradle dosyasına androidx.core:core-telecom bağımlılığını ekleyin:
dependencies {
implementation ("androidx.core:core-telecom:1.0.0")
}
AndroidManifest.xml dosyanızda MANAGE_OWN_CALLS iznini beyan edin:
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
Uygulamanızı kaydettirme
Sisteme arama eklemeye başlamak için CallsManager kullanarak arama uygulamanızı Android'e kaydedin. Kayıt sırasında uygulamanızın özelliklerini (ör. ses, video desteği) belirtin:
val callsManager = CallsManager(context) val capabilities: @CallsManager.Companion.Capability Int = (CallsManager.CAPABILITY_BASELINE or CallsManager.CAPABILITY_SUPPORTS_VIDEO_CALLING) callsManager.registerAppWithTelecom(capabilities)
Çağrı Yönetimi
Arama yaşam döngüsü oluşturmak ve yönetmek için Core-Telecom API'lerini kullanın.
Telefon araması oluşturma
CallAttributesCompat nesnesi, benzersiz bir aramanın özelliklerini tanımlar. Bu özellikler şunlar olabilir:
displayName: arayanın adı.address: Görüşme adresi (ör. telefon numarası, toplantı bağlantısı).direction: Gelen veya giden.callType: Ses veya video.callCapabilities: Aktarma ve bekletme işlemlerini destekler.
Aşağıda, gelen aramanın nasıl oluşturulacağına dair bir örnek verilmiştir:
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 ) }
Görüşme ekle
Sisteme yeni bir arama eklemek ve uzak yüzey güncellemelerini yönetmek için CallAttributesCompat ve geri çağırmalarla callsManager.addCall kullanın. addCall bloğundaki callControlScope, uygulamanızın arama durumunu değiştirmesine ve ses güncellemelerini almasına olanak tanır:
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. }
Çağrı yanıtlama
CallControlScope içinde gelen aramayı yanıtlama:
when (val result = answer(CallAttributesCompat.CALL_TYPE_AUDIO_CALL)) { is CallControlResult.Success -> { /* Call answered */ } is CallControlResult.Error -> { /* Handle error */ } }
Aramayı reddetme
CallControlScope içinde DisconnectCause.REJECTED ile disconnect() kullanarak bir aramayı reddetme:
disconnect(DisconnectCause(DisconnectCause.REJECTED))
Giden aramayı etkinleştirme
Karşı taraf yanıt verdiğinde giden aramayı etkin olarak ayarlama:
when (val result = setActive()) { is CallControlResult.Success -> { /* Call active */ } is CallControlResult.Error -> { /* Handle error */ } }
Çağrıyı beklemeye alma
Aramayı beklemeye almak için setInactive() uygulamasını kullanın:
when (val result = setInactive()) { is CallControlResult.Success -> { /* Call on hold */ } is CallControlResult.Error -> { /* Handle error */ } }
Aramayı sonlandırma
DisconnectCause ile disconnect() kullanarak aramayı sonlandırma:
disconnect(DisconnectCause(DisconnectCause.LOCAL))
Görüşme ses uç noktalarını yönetme
CallControlScope içinde currentCallEndpoint, availableEndpoints ve isMuted Flow kullanarak ses uç noktalarını gözlemleyin ve yönetin. Telecom'u kullanırken ses rotalarını yönetmek için AudioManager#setCommunicationDevice veya AudioManager#startBluetoothSco API'lerini kullanmayın. Aksi takdirde aramanızda ses sorunları yaşanır.
fun observeAudioStateChanges(callControlScope: CallControlScope) { with(callControlScope) { launch { currentCallEndpoint.collect { /* Update UI */ } } launch { availableEndpoints.collect { /* Update UI */ } } launch { isMuted.collect { /* Handle mute state */ } } } }
requestEndpointChange() kullanarak etkin ses sistemini değiştirme:
coroutineScope.launch { callControlScope.requestEndpointChange(callEndpoint) }
Ön plan desteği
Kitaplık, ön plan desteği için Android 13 (API düzeyi 33) ve önceki sürümlerde ConnectionService, Android 14 (API düzeyi 34) ve sonraki sürümlerde ise ön plan hizmet türlerini kullanır.
Uygulamanız arka plandayken aramaları etkin tutmak için CallsManager öğesini ön plandaki bir Service (ör. LifecycleService) içinde barındırın ve AndroidManifest.xml dosyanızda phoneCall ön plan hizmet türünü bildirin:
<service
android:name=".TelecomVoipService"
android:foregroundServiceType="phoneCall" />
Ön plan şartları kapsamında uygulamanızın, kullanıcıların ön planda etkin bir arama olduğunu bilmesi için NotificationCompat.CallStyle bildirimi yayınlaması gerekir. Uygulamanızın ön planda yürütme önceliği almasını sağlamak için platformla çağrıyı ekledikten sonra startForeground kullanarak hizmetinizi ön plana çıkarın:
startForeground( notificationId, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL )
Ön plan hizmetleri hakkında daha fazla bilgi edinin.
Uzaktan Surface desteği
Uzak cihazlar (akıllı saatler, Bluetooth mikrofonlu kulaklıklar, Android Auto), doğrudan telefon etkileşimi olmadan aramaları yönetebilir. Uygulamanız, bu cihazlar tarafından başlatılan işlemleri gerçekleştirmek için CallsManager.addCall öğesine sağlanan geri çağırma lambda'larını (onAnswerCall, onSetCallDisconnected, onSetCallActive, onSetCallInactive) uygulamalıdır.
Uzaktan işlem gerçekleştiğinde ilgili lambda çağrılır.
Lambda'nın başarıyla tamamlanması, komutun işlendiğini gösterir. Komut yerine getirilemiyorsa lambda bir istisna oluşturmalıdır.
Doğru uygulama, farklı cihazlarda sorunsuz görüşme kontrolü sağlar. Çeşitli uzaktan kumanda yüzeyleriyle kapsamlı bir şekilde test edin.
Telefon Uzantıları
Aramalarınızın arama durumunu ve ses rotasını yönetmenin yanı sıra kitaplık, arama uzantılarını da destekler. Bunlar, uygulamanızın Android Auto gibi uzak yüzeylerde daha zengin bir arama deneyimi için uygulayabileceği isteğe bağlı özelliklerdir. Bu özellikler arasında toplantı odaları, aramayı sessize alma ve ek arama simgeleri yer alır. Uygulamanız bir uzantı uyguladığında, uygulamanın sağladığı bilgiler, kullanıcı arayüzlerinde bu uzantıların görüntülenmesini de destekleyen tüm bağlı cihazlarla senkronize edilir. Bu sayede kullanıcılar, uzaktan kumandalı cihazlarda da bu özelliklerden yararlanabilecek.
Uzantılarla arama oluşturma
Görüşme oluştururken görüşmeyi oluşturmak için CallsManager.addCall kullanmak yerine CallsManager.addCallWithExtensions kullanabilirsiniz. Bu, uygulamaya ExtensionInitializationScope adlı farklı bir kapsama erişim izni verir. Bu kapsam, uygulamanın desteklediği isteğe bağlı uzantı grubunu başlatmasına olanak tanır. Ayrıca bu kapsam, uzantı özelliği değişimi ve başlatma işlemi tamamlandıktan sonra uygulamaya CallControlScope döndüren ek bir yöntem (onCall) sağlar.
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... } } }
Destek Görüşmesi Katılımcıları
Uygulamanız toplantılar veya grup görüşmeleri için görüşme katılımcılarını destekliyorsa bu uzantının desteklendiğini bildirmek için addParticipantExtension kullanın ve katılımcılar değiştiğinde uzak yüzeyleri güncellemek için ilgili API'leri kullanın.
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)
}
}
Uzak yüzeylere görüşmedeki katılımcıları bildirmekle birlikte, etkin katılımcı ParticipantExtension#updateActiveParticipant kullanılarak da güncellenebilir.
Görüşme katılımcılarıyla ilgili isteğe bağlı işlemler de desteklenir.
Uygulama, görüşmede söz isteyen katılımcıları desteklemek ve söz isteyen diğer katılımcıları görmek için ParticipantExtension#addRaiseHandSupport kullanabilir.
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)
}
}
Aramaları sessize alma desteği
Arama sessize alma özelliği, kullanıcının cihazın mikrofonunu fiziksel olarak sessize almadan uygulamanın giden sesini sessize almasını istemesine olanak tanır. Bu özellik, her arama için ayrı ayrı yönetilir. Bu sayede Jetpack, VoIP araması etkinken devam eden hücresel aramaların genel ses kapatma durumunu yönetme karmaşıklığını ortadan kaldırır. Bu sayede, çoklu arama senaryolarında giden sesin kapatılması daha az hataya açık hale gelirken, kullanıcının arama sessizliğinin etkin olduğunu fark etmeden konuştuğu durumlarda "konuşuyor musunuz" göstergeleri gibi faydalı özellikler de kullanılabilir.
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)
}
}
Destek Araması Simgeleri
Arama simgesi, uygulamanın, arama sırasında uzak yüzeylerde gösterilecek aramayı temsil eden özel bir simge belirtmesine olanak tanır. Bu simge, görüşme süresince de güncellenebilir.
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)
}
}
Sistem arama kaydına ekleme
Uygulamanızın VoIP aramalarını sistem arama kaydına ekleyerek sistem çeviricisinde görünmesini ve kullanıcıların buradan geri arama yapabilmesini sağlayabilirsiniz. Ayrıntılar için Birleştirilmiş arama geçmişi başlıklı makaleyi inceleyin.