ECV Video Görüşme iOS SDK

İçindekiler

Giriş

ECV Video Görüşme iOS SDK'sına hoş geldiniz! Bu SDK, gerçek zamanlı video görüşme işlevselliğini iOS uygulamalarınıza sorunsuz bir şekilde entegre etmenizi sağlar. Sinyal iletimi, WebRTC eş bağlantıları, medya akışları ve görüşme durumu yönetimi gibi karmaşık işlemleri halleder, böylece siz uygulamanızın kullanıcı arayüzü ve iş mantığına odaklanabilirsiniz.

Bu depo şunları içerir:

1. SDK: Önceden derlenmiş bir iOS Framework'ü (.framework dosyası) olarak sağlanır. Bunu projenize bir bağımlılık olarak ekleyeceksiniz.

2. Demo Uygulama: SDK özelliklerinin nasıl kullanılacağını gösteren bir gösterim uygulamasının (ECV175_iOS_DEMO) tam kaynak kodu. Bu demo, üretim için hazır UI kodu değil, referans ve örnek olarak tasarlanmıştır.

Temel Özellikler

• ECV backend servislerine bağlantı kurar (v1.75+)

• WebRTC kurulumunu ve eşler arası bağlantıyı yönetir

• Yerel ve uzak video/ses akışlarını yönetir

• Ses ve video için sessize alma/sesi açma kontrollerini sağlar

• Kamera değiştirmeyi destekler

• Görüşme yaşam döngüsü olaylarını yönetir (arama, sırada bekleme, bağlandı, bekletme, sonlandırma)

• Yapılandırılabilir ortamlar ve görüşme parametreleri

Başlangıç

Ön Koşullar

• Xcode (En Son Kararlı Sürüm Önerilir)

• iOS geliştirme temel bilgisi (Swift)

• Minimum iOS Sürümü: 13.0

• Hedef iOS Sürümü: 17.0

1. Gerekli Framework'leri Ekleyin

Uygulamanızın ECV SDK framework'ünü ve gerekli bağımlılıklarını içermesi gerekir: WebRTC. Bunları .framework dosyaları olarak alacaksınız.

1. Gerekli Framework Dosyaları:

   • ECV SDK: (örn., ECV175_iOS_SDK.framework)

   • WebRTC: WebRTC.xcframework

2. Framework'leri projenize ekleyin:

   • Framework dosyalarını Xcode projenize sürükleyip bırakın

   • "Copy items if needed" seçeneğinin işaretli olduğundan emin olun

   • Hedefinizin "Frameworks, Libraries, and Embedded Content" bölümüne ekleyin

   • Her framework için "Embed & Sign" ayarını yapın

3. Projenizin Build Ayarlarında:

   • "Enable Bitcode" ayarını Hayır olarak ayarlayın

   • Framework'leri "Framework Search Paths"e ekleyin

   • "Build Active Architecture Only" ayarının ihtiyaçlarınıza uygun şekilde ayarlandığından emin olun

2. Demo Uygulamayı İnceleyin

Dahil edilen demo uygulama (ECV175_iOS_DEMO), SDK entegrasyonunun pratik bir örneğini sunar.

1. Xcode'da ECV175_iOS.xcworkspace'i açın

2. Demo uygulamayı bir simülatör veya fiziksel cihazda derleyip çalıştırın

3. SDK bileşenlerinin nasıl başlatıldığını ve kullanıldığını anlamak için özellikle UI dizinindeki dosyaları ve AppState.swift dosyasını inceleyin

3. Temel SDK Başlatma (Kavramsal)

// AppDelegate veya merkezi bir yönetim nesnesinde
import ECV175_iOS_SDK

// 1. SDK Yapılandırmasını Tanımlayın
let sdkConfig = ECVSdkConfiguration(
    name: "Environment_Name" // Uygulamanızı veya backend'inizi ifade eden herhangi bir isim verin
    serviceUrl: "YOUR_SERVICE_URL" // Gerçek servis URL'niz ile değiştirin
    // İsteğe bağlı olarak webrtcUrl, signalingUrl vb. değerleri geçersiz kılın
)

// 2. SDK Örneğini Başlatın
// Merkezi olarak yönetilen tek bir örnek olması önerilir
let ecvSdk = ECVSdk(config: sdkConfig)

// Bu örneği uygulamanız genelinde erişim için saklayın (örn., AppDelegate, DI, Singleton)
// Örnek: MyApp.sdkInstance = ecvSdk

Temel Kavramlar

• ECVSdk: SDK ile etkileşim için ana giriş noktası. Görüşmeler oluşturmak ve global ayarlar/modüllere erişmek için kullanılır.

• ECVSdkConfiguration: SDK için backend URL'lerini ve bağlantı parametrelerini tanımlar.

• VideoCall: Tek bir video görüşme oturumunu temsil eder. Görüşme durumunu, olayları ve bağlantı detaylarını yönetir.

• WebRtcConnection: Temel WebRTC eş bağlantısını, medya akışlarını ve renderer'ları yönetir. VideoCall.connect() üzerinden erişilir.

• Olaylar: SDK, uygulamanızı görüşme durumu değişiklikleri, hatalar ve medya olayları (VideoCallEvent) hakkında bilgilendirmek için bir delegate sistemi kullanır.

• Renderer'lar (RTCMTLVideoView): Yerel ve uzak videoyu görüntülemek için kullanılan standart WebRTC görünümleri. Yaşam döngülerini yönetmeniz ve WebRtcConnection kullanarak bunları eklemeniz/çıkarmanız gerekir.

Demo Uygulama Akışı

Demo uygulama şu temel akışı izler:

1. EnvironmentsScreen: Backend bağlantı yapılandırmalarını (Servis URL'si vb.) seçmeye veya tanımlamaya olanak tanır. Bu öncelikle gösterim amaçlıdır; uygulamanız muhtemelen sabit bir yapılandırmaya sahip olacak veya bunu dinamik olarak alacaktır.

2. MainScreen: Gerekli görüşme bilgilerini toplar (örn., arayan adı, öznitelikler), izinleri ister (Kamera, Mikrofon) ve sdk.createCall() kullanarak görüşmeyi başlatır.

3. QueueScreen: Görüşme bir temsilciye bağlanırken bekleme durumunu gösterir. AgentConnected veya Error/Hangup olaylarını dinler.

4. CallScreen: Ana video görüşme arayüzü. Yerel ve uzak video için RTCMTLVideoView'ları yönetir, görüşme kontrollerini gösterir (sessize alma, kamera değiştirme, görüşmeyi sonlandırma) ve UI'ı güncellemek için SDK olaylarına tepki verir.

SDK Kullanım Kılavuzu

Bu belge, ECV Video Görüşme iOS SDK'sını uygulamanızda kullanma hakkında detaylı bilgi sağlar.

SDK Başlatma

Temel Başlatma

import ECV175_iOS_SDK

// SDK yapılandırmasını oluştur
let config = ECVSdkConfiguration(
    name: "Environment_Name" // Uygulamanızı veya backend'inizi ifade eden herhangi bir isim verin
    serviceUrl: "YOUR_SERVICE_URL"
)

// SDK örneğini başlat
let sdk = ECVSdk(config: config)

Yapılandırma Seçenekleri

ECVSdkConfiguration sınıfı çeşitli yapılandırma seçeneklerini destekler:

let config = ECVSdkConfiguration(
    name: "Environment_Name",
    serviceUrl: "YOUR_SERVICE_URL",
    webrtcUrl: "YOUR_WEBRTC_URL", // İsteğe bağlı, varsayılan: serviceUrl
    signalingUrl: "YOUR_SIGNALING_URL" // İsteğe bağlı, varsayılan: serviceUrl
)

Ek Yapılandırmalar

Logger.setLevel(logLevel: .debug) // .debug SDK'daki her şeyin hata ayıklamasını etkinleştirmek için (.debug, .info, .warn, .error) // varsayılan: .info

Görüşme Oluşturma ve Yönetme

Görüşme Oluşturma

// Video görüşmesini oluştur ve başlat
let call = await sdk.createVideoCall() 

Eğer zaten bir rtcId'niz varsa, bunu createVideoCall fonksiyonuna sağlayabilirsiniz, aksi takdirde otomatik olarak backend'den oluşturulacaktır (varsayılan)

let call = await sdk.createVideoCall(rtcId: "your_rtcId")

VideoCall Olayları

Şimdi görüşmeyi başlatmadan önce görüşmeye olay dinleyicisi ekleyebiliriz

sdk.modules.onCallEvent.append { (videoCall: VideoCall, newEvent: VideoCallEvent, lastEvent: VideoCallEvent) in
    if(videoCall.rtcId != call.rtcId){
        return // Sadece mevcut görüşmeyle ilgili olayları yakaladığımızdan emin oluyoruz. // tüm görüşmelerin olaylarını yakalamak için bu kodu yorum satırına alın
    }

    if(newEvent.type == .AgentConnected) {
        Logger.info("From sdk.modules.onCallEvent: \(newEvent.type)")
    }
    else if(newEvent.type == .Error){
        Logger.error("From sdk.modules.onCallEvent: \(newEvent.detail ?? "")")
    }
    else {
        Logger.info("From sdk.modules.onCallEvent: \(newEvent)")
    }
}

VideoCall Parametreleri

Görüşmeyi başlatmak için DialCallParameters nesnesini hazırlamamız gerekir

let dialCallParameters = DialCallParameters(
    callerName: "Caller_Name",      // İsteğe bağlı ama sağlanmalı, aksi takdirde rastgele bir isim oluşturulacak
    attributes: [String: String],   // İsteğe bağlı, Görüşme için veri ekleyin
    queue: String?,                 // İsteğe bağlı, Kuyruk adı, sağlanmazsa sistemin varsayılan kuyruğunu kullanacak
    
    // Gelişmiş İsteğe Bağlı Parametreler
    acdAttributes: [String: String],
    customPayload: [String: String],
    additionalHeaders: [String: String],
)

Örnek:

let dialCallParameters = DialCallParameters(
    callerName: "John Doe",
    attributes: [
        "department": "support",
        "priority": "high"
    ],
    queue: "TechSupport",
)

VideoCall'u Başlatma

ECV 1.75'te bir VideoCall başlatmak istiyorsak, call.start kullanırız

_ = await call.start(dialCallParameters: dialCallParameters)

Not: Sonucu _'ye atadık çünkü call.start queueSocket bağlantısını [String: Any]? verisini döndürür. Şimdilik bunları işlememize gerek yok. (Çok Gelişmiş)

Bir Temsilcinin bağlanmasını beklemek (inQueue)

Bir temsilcinin bağlanmasını beklemek için iki basit yol vardır:

1- Yukarıda zaten uyguladığımız VideoCall olaylarını kullanarak if(newEvent.type == .AgentConnected)

2- Beklenen promise tabanlı görevi kullanarak:

let isAgentConnected = await call.agentConnected?.value
Logger.info("isAgentConnected: \(String(describing: isAgentConnected))")

if(isAgentConnected == true) {
    // Görüşmeyi ayrı bir web tarayıcısında açmak belki? // Geliştirme için faydalı
    if let urlString = call.getUrl(), let url = URL(string: urlString) {
        UIApplication.shared.open(url, options: [:], completionHandler: nil)
    }
    else {
        Logger.error("Failed to open URL: invalid URL string")
    }
}
else {
    Logger.warn("Agent not connected!")
}

VideoCall'u Bağlama

1- videoCall.connect() kullanarak

CallScreen.swift dosyanızda

func setup() {
    Task {
        guard let rtcId = self.rtcId else {
            Logger.error("Setup failed: RtcId is nil")
            return
        }

        // Ekranlar arasında gezinirken ve zaten bir video görüşmesi oluşturduysanız, video görüşmesini sdk içinde rtcId kullanarak bulabilirsiniz.
        if let videoCall = appState.sdk?.getVideoCall(rtcId: rtcId){
            self.videoCall = videoCall
        }
        else {
            // Veya yeni bir videoCall nesnesi oluşturmak istiyorsanız ve rtcId'niz varsa, ve temsilcinin odada beklediğinden eminseniz // geliştirme için faydalı
            self.videoCall = await appState.sdk?.createVideoCall(rtcId: rtcId)
        }

        guard let webRtcConnection = self.videoCall?.connect() else {
            self.callError = "WebRtcConnection failed to connect"
            Logger.error("Setup failed: WebRtcConnection is nil")
            return
        }
        self.webRtcConnection = webRtcConnection

        Logger.debug("Instantiating and assigning renderers...")
        let local = Renderer()
        let remote = Renderer()

        webRtcConnection.localVideoRenderer = local
        webRtcConnection.remoteVideoRenderer = remote

        self.localRenderer = local
        self.remoteRenderer = remote

        Logger.info("Starting WebRTC room...")
        await webRtcConnection.startRoom()
        Logger.info("Call setup complete.")
    }
}

2- Veya arayan web tarayıcısı kullanarak video görüşmesine katılabilir (önerilmez / geliştirme için faydalı)

if let urlString = call.getUrl(), let url = URL(string: urlString) {
    UIApplication.shared.open(url, options: [:], completionHandler: nil)
}
else {
    Logger.error("Failed to open URL: invalid URL string")
}

Video Görüşme Arayüzü

Video Görünümlerini Ayarlama

import Foundation
import SwiftUI
import Combine
import ECV175_iOS_SDK
import WebRTC

struct CallScreen: View {
    let rtcId: String?
    @EnvironmentObject var appState: AppState

    @Binding var path: NavigationPath

    @State private var videoCall: VideoCall?
    @State private var webRtcConnection: WebRtcConnection?

    @State private var localRenderer: Renderer?
    @State private var remoteRenderer: Renderer?

    let localStreamWidth: CGFloat = 80
    let localStreamHeight: CGFloat = 120
    let margin: CGFloat = 10
    let pipBottomPadding: CGFloat = 70
    
    var body: some View {
        ZStack {
            Color.black.ignoresSafeArea()

            WebRtcVideoView(renderer: remoteRenderer).ignoresSafeArea()

            WebRtcVideoView(renderer: localRenderer)
                .frame(width: localStreamWidth, height: localStreamHeight)
                .cornerRadius(8)
                .overlay(
                    RoundedRectangle(cornerRadius: 8)
                        .stroke(Color.white.opacity(0.5), lineWidth: 1)
                )
                .padding(.trailing, margin)
                .padding(.bottom, margin + pipBottomPadding)

            // ... Görüşme Düğmeleri
        }
        .navigationBarHidden(true)
        .statusBar(hidden: true)
        .onAppear(perform: setup)
        .onDisappear {
            hangup(by: "onDisappear")
        }
    }

    // MARK: - Video Renderer SwiftUI Sarmalayıcısı

    struct WebRtcVideoView: UIViewRepresentable {
        let renderer: (any RTCVideoRenderer)?

        func makeUIView(context: Context) -> UIView {
            if let renderer = renderer as? Renderer {
                return renderer.view
            } else if let renderer = renderer as? Renderer {
                return renderer.view
            } else {
                return UIView()
            }
        }

        func updateUIView(_ uiView: UIView, context: Context) {}
    }

    // MARK: - Özel Renderer Sınıfları

    class Renderer: NSObject, RTCVideoRenderer {
        let view: RTCMTLVideoView

        override init() {
            self.view = RTCMTLVideoView()
            self.view.videoContentMode = .scaleAspectFill
            super.init()
            Logger.debug("Renderer created")
        }

        deinit { Logger.debug("Renderer deallocated") }

        func setSize(_ size: CGSize) {
            view.setSize(size)
        }

        func renderFrame(_ frame: RTCVideoFrame?) {
            view.renderFrame(frame)
        }
    }

    func hangup(by: String = "HangUpButton") {
        Logger.debug("Hangup requested by: \(by)")

        videoCall?.hangup()

        videoCall = nil
        webRtcConnection = nil
        localRenderer = nil
        remoteRenderer = nil
    }

    // func setup(){
    // ... buraya yapıştırın
    //}
}

Görüşme Kontrolleri

// Sesi Kapat/Aç
webRtcConnection.setAudioEnabled(state: false) // Sesi kapat
webRtcConnection.setAudioEnabled(state: true)  // Sesi aç

// Videoyu Devre Dışı Bırak/Etkinleştir
webRtcConnection.setVideoEnabled(state: false) // Videoyu devre dışı bırak
webRtcConnection.setVideoEnabled(state: true)  // Videoyu etkinleştir

// Kamerayı Değiştir
try await webRtcConnection.switchCamera()

// Flaşı Etkinleştir/Devre Dışı Bırak
webRtcConnection.setFlashlightEnabled(state: true)
webRtcConnection.setFlashlightEnabled(state: false)

// Görüşmeyi Sonlandır
videoCall.hangup()

Video Görüşme Olay İşleme

sdk.modules.onCallEvent'te bir olay tetiklendiğinde, newEvent VideoCallEvent ve newEvent.type VideoCallEventType'dır

sdk.modules.onCallEvent.append { (videoCall: VideoCall, newEvent: VideoCallEvent, lastEvent: VideoCallEvent) in
    if(videoCall.rtcId != call.rtcId){
        return // Sadece mevcut görüşmeyle ilgili olayları yakaladığımızdan emin oluyoruz. // tüm görüşmelerin olaylarını yakalamak için bu kodu yorum satırına alın
    }

    if(newEvent.type == .DialSuccess){
        Logger.error("From sdk.modules.onCallEvent: \(newEvent.detail ?? "")")
    }
    else if(newEvent.type == .CallEnded){
        // işle
    }
    //else if(){

    //}
}

her tip kendini açıklayıcıdır:

public enum VideoCallEventType {
    case None
    case Init
    case GotRtcId
    case DialSuccess
    case Error
    case OnQueue
    case AgentConnected
    case CallEnded
    case SignalingConnected
    
    case GotLocalStream
    case GotRemoteStream
    
    case JoinedRoom
    case SignalingRegistered
    case RtcPeerConnectionCreated
    
    case GotOffer
    case SentOffer
    case GotAnswer
    case SentAnswer
    
    case AudioMuted
    case AudioUnmuted
    case VideoMuted
    case VideoUnmuted
    
    case RemoteAudioMuted
    case RemoteAudioUnmuted
    case RemoteVideoMuted
    case RemoteVideoUnmuted
    
    case StartHold
    case EndHold
    
    case TakePhotoOn
    case TakePhotoOff
    
    case WebRtcOnDataChannel
    case TextChannelConnected
    case TextChannelMessage
    case ConnectionTimeoutStart
    case ConnectionTimeoutEnd
    case WebRtcConnected
    case WebRtcRenegotiationNeeded

    case WebRtcDisconnected
    case WebRtcFailed
    case Hangup
    
    case TransferPending
    case TransferCanceled
    case TransferredTo
}

Hata Yönetimi

Hataları daha kesin bir şekilde yönetmek için, .onCallEvent altında bir hata oluştuğunda videoCall.lastError'ı kontrol edebiliriz

Yapılandırma Kılavuzu

Bu belge, ECV Video Görüşme iOS SDK'sında mevcut yapılandırma seçeneklerini detaylandırır.

SDK Yapılandırması

Temel Yapılandırma

ECVSdkConfiguration sınıfı video görüşme örneğini yapılandırmak için kullanılır:

let config = ECVSdkConfiguration(
    name: "Environment_Name" 
    serviceUrl: "YOUR_SERVICE_URL",
)

Gerekli Parametreler

İsteğe Bağlı Parametreler

Örnek Kullanımlar:

let configV175 = ECVSdkConfiguration(
    name: "Some ECV 1.75 App" 
    serviceUrl: "https://prod-v175.ecv.example.com"
)

let configSeparateV175 = ECVSdkConfiguration(
    name: "Some custom ECV 1.75 App",
    serviceUrl: "https://api.example.com",
    webrtcUrl: "https://webrtc-v15.example.com", // /join için ayrı endpoint
    signalingUrl: "https://websocket-v15.example.com" // Ayrı WebSocket sunucusu
)

Görüşme Yapılandırması

Temel Görüşme Yapılandırması

DialCallParameters sınıfı bireysel görüşmeleri yapılandırmak için kullanılır:

let dialCallParameters = DialCallParameters() // Gerekli parametre yok

İsteğe Bağlı DialCallParameters Parametreleri

Örnek Kullanımlar:

let dialCallParameters = DialCallParameters(
    callerName: "Jane Doe",
    attributes: [
        "accountNumber" to "ACC9876",
        "lastInteraction" to "2023-10-26"
    ],
    queue: "SupportQueue",
    additionalHeaders: ["X-Auth-Token": "user_session_token"]
)

await call.start(dialCallParameters: dialCallParameters)

WebRTC Bağlantı Parametreleri

Bu parametreler videoCall.connect() çağrıldığında isteğe bağlı olarak sağlanır ve WebRTC eş bağlantı davranışını ince ayar yapar. Çoğu parametrenin makul varsayılanları vardır.

• Bağlantı & Sinyalleşme:

  • connectionTimeout: Int = 10000: Genel WebRTC bağlantı denemesi için zaman aşımı (ms) (WebRtcConnection'da manuel bir zamanlayıcı tarafından kullanılır).

  • joinHttpConnectTimeout: Int = 3000: /join isteği için HTTP bağlantı zaman aşımı (ms).

  • joinHttpReadTimeout: Int = 3000: /join isteği için HTTP okuma zaman aşımı (ms).

  • additionalHeaders: [String: String]: /join isteğine ve WebSocket sinyalleşme bağlantı el sıkışmasına eklenen özel HTTP başlıkları. WebRTC/Sinyalleşme altyapısına ulaşması gereken kimlik doğrulama belirteçleri için faydalıdır.

• Medya Kontrolü & Davranışı:

  • videoCallEnabled: Boolean = true: Video parçalarının kurulup kurulmayacağı. Sadece sesli görüşmeler için false olarak ayarlayın.

  • useSpeakerPhone: Boolean = true: Görüşmeyi hoparlör kullanarak başlat.

  • autoHandleCameraSwitch: Boolean = true: SDK'nın belirli olaylar gerçekleştiğinde (örn., temsilci arka kamera ile fotoğraf istediğinde) otomatik olarak kameraları değiştirmesine izin verir.

  • autoHandleHoldSideEffects: Boolean = true: Temsilci görüşmeyi bekletmeye aldığında veya devam ettirdiğinde yerel ses/videoyu otomatik olarak sessize alır/açar.

• Video Yapılandırması:

  • videoWidth: Int = 480 / videoHeight: Int = 640: İstenen video çözünürlüğü.

  • videoFps: Int = 0 (Varsayılan ~30): İstenen video kare hızı.

  • videoMaxBitrate: Int = 0 (WebRTC varsayılanı): Video kodlama için maksimum bit hızı (kbps).

  • videoCodec: String = "VP8": Tercih edilen video codec'i ("VP8", "VP9", "H264").

  • videoCodecHwAcceleration: Boolean = true: Varsa donanım hızlandırmasını etkinleştir.

• Ses Yapılandırması:

  • audioCodec: String = "OPUS": Tercih edilen ses codec'i ("OPUS", "ISAC").

  • audioStartBitrate: Int = 0 (WebRTC varsayılanı): Başlangıç ses bit hızı (kbps).

  • noAudioProcessing: Boolean = false: Platform ses işlemeyi devre dışı bırak (AEC, AGC, NS).

  • disableBuiltInAEC: Boolean = false / disableBuiltInNS: Boolean = false: Varsa donanım AEC/NS'yi devre dışı bırak.

• Hata Ayıklama:

  • tracing: Boolean = false: WebRTC dahili izlemeyi etkinleştir.

• Veri Kanalı (textChannelConfig):

  • textChannelConfig: DataChannelConfig? = DataChannelConfig(...): FLASH_ON/OFF, HOLD/PICKUP vb. komutlar için kullanılan yerleşik metin veri kanalı yapılandırması. Genellikle varsayılan olarak bırakılır. Detaylar için DataChannelConfig sınıfına bakın.

Örnek Kullanım:

let customConnectParams = ConnectParameters(
    videoWidth: 1280,
    videoHeight: 720,
    videoCodec: "H264",
    additionalHeaders: ["X-WebRTC-Auth": "webrtc_token"]
)

// Özel parametreleri kullanarak WebRtcConnection'ı al
let webRtcConnection = videoCall.connect(parameters: customConnectParams)
webRtcConnection.startRoom()

DataChannelConfig

DataChannelConfig, eşler arası iletişim ortamında bir veri kanalını başlatmak için kullanılan bir yapılandırma modelidir.

Özellikler

Başlatıcı

init(
    enabled: Bool,
    label: String,
    id: Int = -1,
    negotiated: Bool = false,
    protocol: String = "",
    ordered: Bool = true,
    maxRetransmits: Int = -1,
    maxRetransmitTimeMs: Int = -1
)

Demo Uygulama Kılavuzu

Genel Bakış

ECV175_iOS_DEMO uygulaması, ECV Video Görüşme SDK'sının bir iOS uygulamasına nasıl entegre edileceğini ve kullanılacağını gösteren pratik bir örnek olarak hizmet eder. Bu kılavuz, uygulamanın mimarisini, temel bileşenlerini ve nasıl etkili bir şekilde kullanılacağını adım adım açıklar.

Uygulama Mimarisi

Temel Bileşenler

1. Uygulama Yapısı

   • Modern iOS geliştirme uygulamalarıyla SwiftUI framework'ü kullanılarak oluşturulmuştur

   • MVVM (Model-View-ViewModel) mimari desenini takip eder

   • Ekran yönetimi için SwiftUI'nin navigasyon sistemini kullanır

   • NavigationRoute enum'u ile tip güvenli navigasyon uygular

   • Bağımlılık enjeksiyonu için environment object'leri kullanır

2. Durum Yönetimi

   • AppState: Şunları yöneten merkezi durum yönetim sınıfı:

     • UserDefaults kullanarak ortam yapılandırması kalıcılığı

     • SDK örneği yaşam döngüsü yönetimi

     • Ortam seçimi ve depolama

     • @Published özellikleri kullanarak reaktif UI güncellemeleri

   • ConfigurationManager: Ortam yapılandırmalarını yönetir

     • Önceden tanımlanmış ve özel ortamları yönetir

     • Ortam yapılandırmaları için CRUD işlemleri sağlar

     • Ortam ayarlarını kalıcı hale getirir

3. Navigasyon Sistemi

   • Üç ana rota ile NavigationRoute enum'u kullanarak tip güvenli navigasyon:

     • mainScreen: Ortam seçiminden sonra giriş noktası

     • queueScreen(rtcId:name:queue:): Kuyruk yönetim arayüzü

     • callScreen(rtcId:): Video görüşme arayüzü

   • Uygun geri navigasyon ve derin bağlantı desteği uygular

   • Modern navigasyon için SwiftUI'nin NavigationStack'ini kullanır

Temel Özellikler

1. Ortam Seçimi

   • Birden fazla ortam yapılandırmasını destekler:

     • Önceden tanımlanmış ortamlar

     • Yapılandırılabilir ayarlarla özel ortamlar

   • Ortam yapılandırması şunları içerir:

     • Servis URL'si

     • WebRTC URL'si (isteğe bağlı)

     • Sinyal URL'si (isteğe bağlı)

     • Kuyruk soketi yapılandırması

     • Oda aralığı ayarları

   • Seçilen ortamı UserDefaults kullanarak kalıcı hale getirir

   • Seçilen ortamla otomatik SDK başlatma

2. Video Görüşme Entegrasyonu

   • ECV Video Görüşme SDK'sı ile sorunsuz entegrasyon

   • Özellikler şunları içerir:

     • Gerçek zamanlı video akışı

     • Ses kontrolleri (sessize alma/sesi açma)

     • Video kontrolleri (etkinleştirme/devre dışı bırakma)

     • Kamera değiştirme

     • Flaş kontrolü

     • Picture-in-Picture desteği

   • Kuyruk yönetim sistemi:

     • Mevcut kuyruklara katılma

     • Yeni kuyruklar oluşturma

     • Kuyruk durumunu izleme

   • Görüşme olay işleme:

     • Görüşme durumu yönetimi

     • Hata işleme

     • Bağlantı durumu izleme

Başlangıç

Ön Koşullar

• Xcode 14.0 veya üzeri

• iOS 15.0 veya üzeri

• ECV175_iOS_SDK framework'ü

• Kamera ve mikrofon izinleri

• İnternet bağlantısı

Kurulum Süreci

1. Proje Yapılandırması

   • ECV175_iOS.xcworkspace'i açın

   • Demo uygulama ve SDK hedeflerinin doğru yapılandırıldığından emin olun

   • Tüm bağımlılıkların doğru bağlandığını kontrol edin

   • Info.plist'te gerekli izinleri yapılandırın:

     • Kamera kullanım açıklaması

     • Mikrofon kullanım açıklaması

2. Ortam Yapılandırması

   • Uygulamayı başlatın

   • Ortam seçim ekranından istediğiniz ortamı seçin

   • Ortam ayarlarını yapılandırın:

     • Servis URL'si (gerekli)

     • WebRTC URL'si (isteğe bağlı)

     • Sinyal URL'si (isteğe bağlı)

     • Kuyruk soketi ayarları

   • Uygulama, seçilen yapılandırma ile SDK'yı otomatik olarak başlatacaktır

Uygulama Akışı

1. İlk Başlatma

   • Uygulama önceden kaydedilmiş ortam yapılandırmasını kontrol eder

   • Bulunursa, otomatik olarak ana ekrana gider

   • Bulunmazsa, ortam seçim ekranını gösterir

   • Gerekli izinleri ister (kamera, mikrofon)

2. Ana Ekran

   • Video görüşmeleri için mevcut seçenekleri gösterir

   • Mevcut ortam yapılandırmasını gösterir

   • Şunlara erişim sağlar:

     • Kuyruk seçimi

     • Görüşme başlatma

     • Ortam ayarları

   • İzin yönetimini işler

   • Video görüşme örneğini başlatır

3. Kuyruk Yönetimi

   • Mevcut kuyruklara katılma

   • Yeni kuyruklar oluşturma

   • Kuyruk durumunu izleme

   • Kuyruk ayarlarını yapılandırma

   • Kuyruk olaylarını işleme

4. Video Görüşme Arayüzü

   • Gerçek zamanlı video akışı:

     • Yerel video önizleme

     • Uzak video görüntüleme

     • Picture-in-Picture desteği

   • Görüşme kontrolleri:

     • Ses sessize alma/sesi açma

     • Video etkinleştirme/devre dışı bırakma

     • Kamera değiştirme

     • Flaş kontrolü

   • Görüşme yönetimi:

     • Görüşmeyi sonlandırma işlevi

     • Hata işleme

     • Bağlantı durumu izleme

Kod Yapısı

Temel Dosyalar

1. ECV175_iOS_DEMOApp.swift

   • Uygulama giriş noktası

   • Ana navigasyon yapısını kurar

   • Temel durum nesnelerini başlatır:

     • AppState

     • ConfigurationManager

   • Environment object'leri yapılandırır

2. AppState.swift

   • Uygulama durumunu yönetir

   • Ortam kalıcılığını işler

   • SDK yaşam döngüsünü kontrol eder

   • Durum geri yüklemeyi uygular

   • SDK örneğini yönetir

3. Views Dizini

   • Screens/:

     • EnvironmentsScreen.swift: Ortam seçimi ve yapılandırması

     • MainScreen.swift: Ana arayüz ve görüşme başlatma

     • CallScreen.swift: Video görüşme arayüzü

     • QueueScreen.swift: Kuyruk yönetimi

   • Components/: Yeniden kullanılabilir UI bileşenleri

   • Uygun durum yönetimi ile SwiftUI görünümlerini uygular

En İyi Uygulamalar

1. Durum Yönetimi

   • Bağımlılık enjeksiyonu için @EnvironmentObject kullanın

   • Temiz endişe ayrımını koruyun

   • Uygun hata işlemeyi uygulayın

   • Reaktif güncellemeler için @Published özelliklerini kullanın

   • Durum kalıcılığını uygun şekilde işleyin

2. Navigasyon

   • Tip güvenli navigasyon rotalarını kullanın

   • Uygun geri navigasyonu uygulayın

   • Derin bağlantı senaryolarını işleyin

   • Navigasyon durumunu yönetin

   • Navigasyon hatalarını işleyin

3. SDK Entegrasyonu

   • SDK'yı sadece gerektiğinde başlatın

   • SDK yaşam döngüsünü düzgün şekilde işleyin

   • SDK işlemleri için hata işlemeyi uygulayın

   • Kaynakları verimli şekilde yönetin

   • SDK olaylarını düzgün şekilde işleyin

Sorun Giderme

1. Yaygın Sorunlar

   • SDK başlatma hataları:

     • Ortam yapılandırmasını kontrol edin

     • Ağ bağlantısını doğrulayın

     • Uygun izinlerin olduğundan emin olun

   • Navigasyon durumu tutarsızlıkları:

     • Navigasyon rotalarını doğrulayın

     • Durum yönetimini kontrol edin

     • Navigasyon hatalarını işleyin

   • Ortam yapılandırma sorunları:

     • Yapılandırma ayarlarını doğrulayın

     • URL formatlarını kontrol edin

     • Gerekli alanları doğrulayın

2. Hata Ayıklama İpuçları

   • Detaylı hata mesajları için konsol günlüklerini kontrol edin

   • Ortam yapılandırmasını doğrulayın

   • Uygun SDK başlatmayı sağlayın

   • Ağ bağlantısını izleyin

   • İzin durumunu kontrol edin

   • Xcode hata ayıklama araçlarını kullanın

SDK Entegrasyonu ve Teknik Detaylar

Temel Yapılandırma ve Derleme Sistemi

1. Build.swift

   • Farklı derleme çeşitlerini ve ortamları yönetir

   • Birden fazla bundle tanımlayıcısını destekler:

     • ccr.ECV175-iOS-DEMO.CORE: Core bundle

   • Her ortam yapılandırması şunları içerir:

     • Servis URL'si

     • Kuyruk yapılandırmaları

     • Önceden tanımlanmış ayarlar

2. AppState.swift

   • SDK entegrasyonu için merkezi durum yönetimi

   • Temel sorumluluklar:

     • SDK örneği yaşam döngüsü yönetimi

     • Ortam yapılandırması kalıcılığı

     • Durum geri yükleme

     • Olay işleme koordinasyonu

   • Reaktif güncellemeler için @Published özelliklerini kullanır

   • Ortam seçimi için UserDefaults kalıcılığını uygular

Ekran Bazlı SDK Entegrasyonu

1. EnvironmentsScreen

   • Ortam seçimi ve yapılandırması

   • SDK Entegrasyonu:

     • Ortam yapılandırmalarını yönetir

     • Önceden tanımlanmış ve özel ortamları işler

     • Ortam seçimini kalıcı hale getirir

     • Seçilen yapılandırma ile SDK'yı başlatır

2. MainScreen

   • Görüşme başlatma için birincil arayüz

   • SDK Entegrasyonu:

     • Video görüşme örneğini başlatır

     • İzinleri yönetir (kamera, mikrofon)

     • Kuyruk seçimini işler

     • Görüşme olay dinleyicilerini kurar

     • Temel özellikler:

       // SDK başlatma
       let call = await appState.sdk?.createVideoCall()
       
       // Olay işleme
       ECVModules?.onCallEvent.append { (videoCall, newEvent, lastEvent) in
           // Görüşme olaylarını işle
       }
       

3. QueueScreen

   • Kuyruk yönetimi ve temsilci bağlantısı

   • SDK Entegrasyonu:

     • Kuyruk katılmayı işler

     • Temsilci bağlantısını yönetir

     • Temel özellikler:

       // Kuyruğa katılma
       let dialCallParameters = DialCallParameters(
           callerName: name,
           queue: queue,
           attributes: [queueKey: queueValue]
       )
       
       // Temsilci bağlantı işleme
       let isAgentConnected = await call.agentConnected?.value

4. CallScreen

   • Video görüşme arayüzü

   • SDK Entegrasyonu:

     • WebRTC bağlantısını yönetir

     • Video/ses akışlarını işler

     • Görüşme özelliklerini kontrol eder

     • Temel özellikler:

       // WebRTC kurulumu
       let webRtcConnection = videoCall?.connect()
       
       // Akış yönetimi
       localRenderer = webRtcConnection?.localStream
       remoteRenderer = webRtcConnection?.remoteStream
       
       // Görüşme kontrolleri
       func toggleLocalAudio()
       func toggleLocalVideo()
       func toggleFlashlight()
       func switchCamera()
       func switchViewRenderers()
       

5. TestScreen

   • Geliştirme ve test arayüzü

   • SDK Entegrasyonu:

     • Temel SDK kullanımını gösterir

     • Farklı SDK sürümlerini test eder

     • Olay işlemeyi gösterir

     • Temel özellikler:

       // SDK başlatma
       let sdk = ECVSdk(config: ECVSdkConfiguration(
           name: "Test",
           serviceUrl: "https://srv12.ccr.group:41743"
       ))
       
       // Görüşme oluşturma ve olay işleme
       let call = await sdk.createVideoCall()
       ECVModules.onCallEvent.append { /* olay işleme */ }
       

SDK Sürüm Uyumluluğu

1. ECV 1.75 Özellikleri

   • Kuyruk soketi desteği

   • Gelişmiş olay işleme

   • İyileştirilmiş temsilci bağlantı yönetimi

   • Daha iyi durum yönetimi

Olay İşleme Sistemi

1. Görüşme Olayları

   • Olay türleri:

     • AgentConnected

     • CallEnded

     • Error

   • Olay işleme:

     ECVModules?.onCallEvent.append { (videoCall, newEvent, lastEvent) in
         switch newEvent.type {
         case .AgentConnected:
             // Temsilci bağlantısını işle
         case .CallEnded:
             // Görüşme sonunu işle
         case .Error:
             // Hataları işle
         }
     }
     

2. Durum Yönetimi

   • Görüşme durumu takibi

   • Bağlantı durumu izleme

   • Hata durumu işleme

   • Kuyruk durumu yönetimi

SDK Entegrasyonu için En İyi Uygulamalar

1. Başlatma

   • SDK'yı sadece gerektiğinde başlatın

   • Yapılandırmayı düzgün şekilde işleyin

   • SDK yaşam döngüsünü yönetin

   • Başlatma hatalarını işleyin

2. Olay İşleme

   • Uygun olay filtrelemeyi kullanın

   • Tüm olay türlerini işleyin

   • Hata işlemeyi uygulayın

   • Olay dinleyicilerini temizleyin

3. Kaynak Yönetimi

   • Kaynakları düzgün şekilde temizleyin

   • Uygulama sonlandırmasında temizliği işleyin

   • Belleği verimli şekilde yönetin

   • Arka plan/ön plan geçişlerini işleyin

4. Hata İşleme

   • Kapsamlı hata işlemeyi uygulayın

   • Kullanıcı geri bildirimi sağlayın

   • Ağ sorunlarını işleyin

   • SDK'ya özgü hataları yönetin

Sonuç

ECV175_iOS_DEMO uygulaması, ECV Video Görüşme SDK'sını kullanarak video görüşme işlevselliğini uygulamak için sağlam bir temel sağlar. Bu kılavuzu takip ederek ve uygulamanın mimarisini anlayarak, kendi iOS uygulamalarınıza video görüşme özelliklerini etkili bir şekilde entegre edebilirsiniz.

Belirli özellikler veya uygulama detayları hakkında daha ayrıntılı bilgi için lütfen SDK dokümantasyonuna ve API referansına bakın.

Olaylar ve Durum Yönetimi

Giriş

ECV iOS SDK asenkron olarak çalışır. Durum değişikliklerini, hataları ve diğer önemli olayları uygulamanıza iletmek için olay tabanlı bir mimari kullanır. Bu olayları anlamak, duyarlı ve sağlam bir kullanıcı arayüzü oluşturmak için çok önemlidir.

Bu kılavuz, SDK olaylarının yapısını detaylandırır, temel olay türlerini listeler ve ilgili durum özelliklerini belirtir.

Olaylara Abone Olma

Olayları sdk.modules.onCallEvent örneği üzerinde dinlersiniz:

sdk.modules.onCallEvent.append { (videoCall: VideoCall, newEvent: VideoCallEvent, lastEvent: VideoCallEvent) in
    if(videoCall.rtcId != call?.rtcId){
        return // Sadece mevcut görüşmeyle ilgili olayları yakaladığımızdan emin oluyoruz. // tüm görüşmelerin olaylarını yakalamak için bu kodu yorum satırı yapın
    }
    
    if(newEvent.type == .Error){
        // Hata olayını işle
    }
    else if(newEvent.type == .AgentConnected) {
        // AgentConnected olayını işle
    }
    else {
        print("ECVModules?.onCallEvent'ten: \(newEvent)")
    }
}

Her iki abonelik yöntemi için detaylı kod örnekleri için "Video Görüşme Olay İşleme" bölümüne bakın.

Olay Yapısı (VideoCallEvent)

Temel Alanlar:

• type: VideoCallEventType: (Gerekli) Olayın türünü belirten bir enum değeri. Nasıl tepki vereceğinizi belirlemek için kontrol edeceğiniz birincil alan budur.

• detail: String?: (İsteğe bağlı) Olaya özel ek string bilgisi sağlar (örn. GotRtcId için rtcId, DialSuccess için bir etkileşim ID'si, CallEnded için bir neden).

• objData: Any?: (İsteğe bağlı) SignalingConnected sırasında WebRtcConnection veya belirli hatalarda bir HTTP yanıt nesnesi gibi ilgili nesneleri içerebilir. Bu veriye erişirken tip kontrolü (is veya instanceof) kullanın.

• data: [String: String]: (İsteğe bağlı, genellikle boş) Olayla ilişkili potansiyel anahtar-değer verileri için genel bir harita.

• createdAt: Date: Olayın SDK içinde oluşturulduğu tarih.

Olay Türü Referansı (VideoCallEventType)

İşte yaygın olay türlerinin, bir görüşmenin tipik aşamalarına göre gruplandırılmış bir dökümü:

Aşama 1: Başlatma ve Arama

• GotRtcId

  • Ne Zaman: sdkInstance.createVideoCall() başarıyla backend'den benzersiz bir görüşme tanımlayıcısı aldıktan sonra tetiklenir.

  • Veri: event.detail rtcId'yi (String) içerir.

  • Yanıt: rtcId'yi saklayın. Daha sonra VideoCall örneğini almak ve aramayı başlatmak (call.start()) için buna ihtiyacınız olacak.

• DialSuccess

  • Ne Zaman: call.start() başarıyla arama isteğini backend'e gönderdikten ve onay aldıktan sonra tetiklenir (genellikle bir Etkileşim ID'si içerir).

  • Veri: event.detail Etkileşim ID'sini içerebilir. event.objData ham JSON yanıtını tutabilir.

  • Yanıt: Genellikle bekleme/kuyruk durumuna geçebileceğinizi gösterir.

• Error (Başlatma/Arama Sırasında)

  • Ne Zaman: rtcId alınamazsa, call.start() parametreleri geçersizse, backend arama isteğini reddederse veya ağ sorunları oluşursa meydana gelebilir.

  • Veri: event.error ECVError'ı içerir. event.detail daha fazla bağlam içerebilir. event.objData bir HTTP yanıtı tutabilir. CALL_NOT_INITIALIZED, DIAL_FAILED gibi belirli ErrorTypes için error.error'ı kontrol edin.

  • Yanıt: Kullanıcıya bir hata mesajı gösterin. Görüşmenin devam etmesini engelleyin. Kullanılamaz durumdaysa VideoCall örneğini temizleyin.

Aşama 2: Kuyruk ve Temsilci Bağlantısı

• OnQueue

  • Ne Zaman: Başarılı bir aramadan sonra tetiklenir, arayanın artık bir temsilci beklediğini gösterir.

  • Veri: Genellikle özel veri gerekmez.

  • Yanıt: Bekleme arayüzünü gösterin (örn. QueueScreen).

• AgentConnected

  • Ne Zaman: Bir temsilci görüşmeyi kabul ettiğinde tetiklenir. Bu, eşler arası medya bağlantısını kurmak için tetikleyicidir.

  • Veri: Özel veri yok.

  • Yanıt: WebRTC bağlantısını başlatın:

    1. WebRtcConnection'ı almak için videoCall.connect()'i çağırın.

    2. WebRTC kurulumunu başlatmak için webRtcConnection.startRoom()'u çağırın.

    3. Ana görüşme ekranına (CallScreen) gidin.

• Error (Kuyruk Sırasında)

  • Ne Zaman: Kuyruk zaman aşımı, kuyruk mekanizmasıyla ilgili ağ sorunları (QUEUE_SOCKET_ERROR) veya backend sorunları nedeniyle oluşabilir.

  • Veri: event.error ECVError'ı içerir.

  • Yanıt: Kullanıcıya görüşmenin bağlanamadığını bildirin. Kuyruk ekranından geri dönün. SDK otomatik olarak CallEnded'i tetiklemezse temizliği sağlamak için videoCall.hangup()'ı çağırın.

• Hangup / CallEnded (Kuyruk Sırasında)

  • Ne Zaman: Kullanıcı açıkça görüşmeyi sonlandırırsa (videoCall.hangup()) veya görüşme bir temsilci bağlanmadan önce backend tarafından sonlandırılırsa.

  • Veri: event.detail bir neden içerebilir ("LOCAL_HANGUP" vb.).

  • Yanıt: Kuyruk ekranından geri dönün. Arayüzün temizlendiğinden emin olun.

Aşama 3: WebRTC Bağlantı Kurulumu

Bu olaylar genellikle WebRtcConnection tarafından dahili olarak işlenir ancak hata ayıklama veya gelişmiş kullanım durumları için gözlemlenebilir. Başarıyı işaret eden temel olay WebRtcConnected'dır.

• SignalingConnected: Sinyal sunucusuna WebSocket bağlantısı kuruldu.

• SignalingRegistered: İstemci, oda (rtcId) için sinyal sunucusuna başarıyla kaydedildi.

• JoinedRoom: HTTP /join isteği başarılı, başlangıç parametreleri alındı (ICE sunucuları, başlatıcı durumu gibi). event.objData JoinRoomResponse'u içerir.

• RtcPeerConnectionCreated: Temel WebRTC PeerConnection nesnesi oluşturuldu. event.objData PeerConnectionClient'ı tutar.

• GotOffer / SentOffer: Eşten alınan / eşe gönderilen SDP Teklifi. event.objData JSON mesajını içerir.

• GotAnswer / SentAnswer: Eşten alınan / eşe gönderilen SDP Yanıtı. event.objData JSON mesajını içerir.

• WebRtcConnected

  • Ne Zaman: WebRTC PeerConnection (ICE ve DTLS) tamamen kuruldu ve medya akışı başlayabilir.

  • Veri: Özel veri yok.

  • Yanıt: Genellikle medya yolunun hazır olduğunu bilmek için bir tetikleyici olarak kullanılır. CallScreen'deki başlangıç yükleme göstergelerini gizleyebilirsiniz.

• TextChannelConnected: Metin komutları (bekletme, flaş vb.) için kullanılan özel veri kanalı açık. event.objData DataChannel'ı tutar.

• WebRtcDisconnected / WebRtcFailed: WebRTC bağlantısı beklenmedik şekilde kesildi veya başarısız oldu. Genellikle kısa süre sonra bir CallEnded olayına yol açar.

Aşama 4: Aktif Görüşme ve Medya

• GotLocalStream: Yerel kamera yakalama başladı. event.objData VideoCapturer'ı içerebilir.

• GotRemoteStream: Uzak medya akışı mevcut (genellikle WebRtcConnected civarında tetiklenir).

  • Yanıt: Uzak SurfaceViewRenderer'ın bağlı olduğundan emin olun.

• AudioMuted / AudioUnmuted: Yerel ses gönderme durumu değişti (setAudioEnabled tarafından tetiklendi).

  • Yanıt: Sessiz düğmesi arayüz durumunu güncelleyin.

• VideoMuted / VideoUnmuted: Yerel video gönderme durumu değişti (setVideoEnabled tarafından tetiklendi).

  • Yanıt: Video sessiz düğmesi arayüz durumunu güncelleyin. Potansiyel olarak yerel video önizleme katmanını gösterin/gizleyin.

• RemoteAudioMuted / RemoteAudioUnmuted: Uzak katılımcı sesini sessize aldı/sesi açtı.

  • Yanıt: İsteğe bağlı olarak uzak tarafın sessiz olduğunu gösteren bir gösterge gösterin.

• RemoteVideoMuted / RemoteVideoUnmuted: Uzak katılımcı videosunu sessize aldı/sesi açtı.

  • Yanıt: Uzak video renderer'ında bir katman veya gösterge gösterin/gizleyin.

• StartHold / EndHold: Görüşme temsilci tarafından bekletildi veya bekletme kaldırıldı (genellikle metin veri kanalı üzerinden tetiklenir).

  • Yanıt: "Görüşme Bekletildi" katmanını gösterin/gizleyin. SDK (autoHandleHoldSideEffects true ise) yanıt olarak yerel medyayı otomatik olarak sessize alabilir/sesi açabilir.

• TakePhotoOn / TakePhotoOff: Temsilci tarafından başlatılan fotoğraf yakalama özellikleriyle ilgili sinyaller.

  • Yanıt: Gerekirse arayüzü ayarlayın (örn. potansiyel olarak yerel videoyu tam ekran yapın). autoHandleCameraSwitch true ise SDK otomatik olarak kameraları değiştirebilir.

• TextChannelMessage: Metin veri kanalı üzerinden alınan bir komut veya mesaj.

  • Veri: event.detail ham mesaj dizesini içerir (örn. "FLASH_ON", "STATUS|VIDEO|MUTED|rtcId").

  • Yanıt: SDK birçok standart mesajı dahili olarak işler (HOLD, PICKUP, MUTE durumları, FLASH komutları gibi). Uygulamanıza özel özel mesajlara tepki verebilirsiniz.

Aşama 5: Görüşme Sonlandırma

• Hangup

  • Ne Zaman: Yerel olarak videoCall.hangup() çağrıldığında hemen tetiklenir.

  • Veri: Özel veri yok.

  • Yanıt: Backend görüşme sonunu onaylamadan önce arayüz temizliğini başlatmak için kullanılabilir. CallEnded'in kesin son olay olduğunu unutmayın.

• CallEnded

  • Ne Zaman: Görüşme oturumunun tamamen sonlandığını gösteren son olay, yerel olarak (hangup() tamamlandığında), uzaktan (temsilci/eş görüşmeyi sonlandırdığında) veya kurtarılamaz bir hata nedeniyle.

  • Veri: event.detail genellikle bir neden içerir (örn. "LOCAL_HANGUP", "REMOTE_HANGUP", "PEER_DISCONNECTED", "CONNECTION_TIMEOUT", hata açıklaması).

  • Yanıt: Bu, şunları yapmak için kesin sinyaldir:

    1. Tüm görüşme ile ilgili arayüzü temizleyin (renderer'lar, kontroller).

    2. Görüşme ekranından ayrılın.

    3. Belirli VideoCall'a bağlı tüm kaynakları serbest bırakın. SDK genellikle bu olaydan sonra VideoCall örneğine olan dahili referansını kaldırır.

Durum Özellikleri

Olaylar değişiklikleri sinyal ederken, bazı mevcut durum özelliklerini de kontrol edebilirsiniz:

• VideoCall Üzerinde:

  • rtcId: String: Benzersiz görüşme tanımlayıcısı (GotRtcId'den sonra mevcut).

  • dialResponse: [String: Any]?: DialSuccess olayı gerçekleştiğinde, bu özellik ham arama yanıtını içerir.

  • agentConnected: Boolean: AgentConnected olayı gerçekleştiyse true.

  • webRtcConnection: WebRtcConnection?: İlişkili WebRTC bağlantısı (connect() çağrıldıktan sonra mevcut).

Genellikle ara yüz durumunuzu güncellemek için olaylara tepki vermek, bu özellikleri sürekli kontrol etmekten daha iyi bir uygulamadır. Bu özellikleri başlangıç durumu kontrolleri veya gerektiğinde kararlar için kullanın (örn. connect()'i çağırmadan önce AgentConnected'ı kontrol etmek).

Özelleştirme Kılavuzu

Giriş

Sağlanan Demo Uygulama (ECV175_iOS_DEMO), ECV SDK'nın temel işlevlerini gösterir. Ancak, üretim uygulamanızın kesinlikle farklı UI/UX gereksinimleri, yapılandırma yöntemleri ve veri ihtiyaçları olacaktır. Bu kılavuz, SDK ve demo kavramlarını kendi uygulamanıza uyarlamak için tavsiyeler sağlar.

1. UI Uygulaması

Demo SwiftUI kullanır, ancak SDK'nın kendisi UI'dan bağımsızdır. Bunu şunlarla oluşturulmuş uygulamalara entegre edebilirsiniz:

• SwiftUI

• UIKit

• Bunların herhangi bir kombinasyonu.

UI için Temel Hususlar:

• Kendi UI'ınızı Oluşturun: Demo UI ekranlarını basitçe kopyalamayın. Uygulamanızın görünümüne, hissine ve kullanıcı akışına uygun ekranlar tasarlayın.

• Temel SDK Etkileşimleri Aynı Kalır: UI araç setinizden bağımsız olarak, SDK ile temel etkileşimler devam eder:

  • İzinler: Bir görüşme başlatmadan önce Kamera, Mikrofon (ve S+ için Bluetooth Bağlantı) izinlerini istemeli ve işlemelisiniz.

  • Video Renderer'ları: Video göstermek için düzeninizde RTCMTLVideoView örnekleri sağlamanız gerekir.

  • Renderer Yaşam Döngüsü: Bu kritik öneme sahiptir. RTCVideoRenderer'ların yaşam döngüsünü doğru şekilde yönetmelisiniz:

    • Bunları UIView kullanarak başlatın.

    • Bunları webRtcConnection.localVideoRenderer/remoteVideoRenderer kullanarak yerel/uzak akışlara bağlayın.

  • Görüşme Durumu Gösterimi: UI'ınız, SDK olaylarına dayalı olarak mevcut görüşme durumunu yansıtmalıdır (örn. "Bağlanıyor...", "Temsilci bekleniyor...", "Bağlandı", "Bekletildi").

  • Görüşme Kontrolleri: Şunlar için UI öğeleri (Düğmeler, Simgeler) uygulayın:

    • Sesi Sessize Alma/Açma (webRtcConnection.setAudioEnabled(...))

    • Videoyu Açma/Kapatma (webRtcConnection.setVideoEnabled(...))

    • Kamerayı Değiştirme (webRtcConnection.switchCamera(...))

    • Görüşmeyi Sonlandırma (videoCall.hangup())

  • Olay İşleme: UI katmanınız, durumunu güncellemek, ekranlar arasında gezinmek ve hataları işlemek için SDK olaylarını dinlemelidir.

2. Yapılandırma (ECVSdkConfiguration)

Demo'nun EnvironmentsScreen.swift'i, farklı backend ortamlarını kolayca test etmek için tasarlanmıştır. Üretim uygulamanızda muhtemelen bu ekrana ihtiyacınız olmayacaktır.

Üretim Yapılandırma Stratejileri:

1. Sabit Yapılandırma: Uygulamanız yalnızca bir backend ortamına bağlanıyorsa (örn. üretim), ECVSdk'yı başlatırken ECVSdkConfiguration değerlerini sabit kodlayabilirsiniz.

   // Örnek: Application.onCreate veya DI modülü içinde
   let prodConfig = ECVSdkConfiguration(
       name: "My App Prod"
       serviceUrl = "https://your-prod.ecv.example.com"
       // ... gerekirse diğer parametreler ...
   )
   
   let sdkInstance = ECVSdk("MyAppProdInstance", prodConfig)
   

2. Dinamik Yapılandırma: ECVSdk'yı başlatmadan önce yapılandırma detaylarını (serviceUrl, webrtcUrl gibi) kendi uygulama backend'inizden alın. Bu, uygulama güncellemeleri gerektirmeden endpoint'leri merkezi olarak yönetmenizi sağlar.

   • Uygulamanız yapılandırmayı sunucunuzdan alır.

   • Alınan URL'leri kullanarak ECVSdkConfiguration'ı oluşturur.

   • ECVSdk'yı başlatır.

3. Görüşme Verisi (DialCallParameters)

Demo, seçilen ortama göre görüşme verisi için açılır listeleri (kuyruk seçimi) dinamik olarak eklemek üzere Build.swift'te selectableQueues kullanır. Bu, demo'nun çoklu ortam kurulumuna özeldir.

Uygulamanızda, videoCall.start()'ı çağırmadan hemen önce DialCallParameters'ı ilgili bağlamsal verilerle doldurmalısınız.

Örnek:

// Kullanıcı profil verisi
val userId = "user123"
val accountType = "Premium"
val intent = "Fatura Sorgusu"

// Hedef kuyruk/beceri
val targetQueue = "BillingSupport"

// SDK örneğini al ve görüşme oluştur
val videoCall = sdkInstance.createVideoCall()
// ... GotRtcId için bekle ...

// Uygulamaya özel verilerle parametreleri oluştur
val dialParams = DialCallParameters(
    callerName = "User $userId", // Veya gerçek kullanıcı adı
    attributes = [
        "userId": userId,
        "accountType": accountType,
        "callIntent": intent
    ],
    acdAttributes = [
        "skill": "Billing" // Örnek ACD özelliği
    ],
    queue = targetQueue, // Hedef kuyruğu açıkça ayarla
    additionalHeaders = ["Authorization": "Bearer \(getUserAuthToken())"] // Örnek kimlik doğrulama
)

// Görüşmeyi başlat
videoCall.start(dialParams)

// Kuyruk/Bekleme ekranına git

4. Olay İşleme Mantığı

Demo olaylara nasıl abone olunacağını gösterirken, yanıt olarak ne yaptığınız uygulamaya özeldir. Uygulamanızın şu temel olayları doğru şekilde işlediğinden emin olun:

• Navigasyon: AgentConnected, CallEnded, Error üzerinde ekran değişikliklerini tetikleyin.

• UI Güncellemeleri: Sessiz durumu, bekletme durumu, bağlantı durumu değişikliklerini görsel olarak yansıtın.

• Hata Gösterimi: Error olayları oluştuğunda kullanıcı dostu mesajlar gösterin.

• Kaynak Temizliği: UI'ı temizlemek ve potansiyel olarak görüşmeye özel kaynakları serbest bırakmak için CallEnded'i kesin sinyal olarak kullanın.

5. Gelişmiş Özelleştirme (İsteğe Bağlı)

• Özel Veri Kanalı Mesajları: Backend'iniz metin veri kanalı üzerinden özel komutlar gönderiyorsa (HOLD, FLASH vb. ötesinde), TextChannelMessage olayını dinleyebilir ve özel uygulama davranışını uygulamak için event.detail'i ayrıştırabilirsiniz.

• ConnectParameters Ayarı: Belirli ağ ortamları veya kalite gereksinimleri için, videoMaxBitrate, codec'ler veya ICE filtreleme modları gibi ConnectParameters'daki parametreleri ayarlamayı deneyebilirsiniz. Bu gelişmiş seçenekler hakkında detaylar için WebRTC dokümantasyonuna bakın.

• Ses Yönetimi: ConnectParameters'da varsayılanlar (useSpeakerPhone vb.) sağlanırken, daha karmaşık ses yönlendirmesi temel SDK kullanımının kapsamı ötesinde daha derin entegrasyon veya özelleştirme gerektirebilir.

6. İzinler

Her zaman iOS'un izin isteme en iyi uygulamalarını takip edin:

• İzinleri yalnızca gerektiğinde isteyin (görüşmeyi başlatmadan hemen önce).

• İzinlerin (Kamera, Mikrofon) neden gerekli olduğunu açıkça açıklayın.

• Kullanıcının izinleri reddettiği durumları zarif bir şekilde işleyin (örn. arama işlevselliğini devre dışı bırakın, ayarlardan nasıl etkinleştirileceği konusunda talimatlar sağlayın).

Sorun Giderme Kılavuzu

Bu kılavuz, ECV iOS SDK'sını entegre ederken veya kullanırken karşılaşılan yaygın sorunlar için çözümler ve hata ayıklama adımları sağlar.

Yaygın Sorunlar ve Çözümleri

Derleme ve Bağımlılık Hataları

1. Hata: "Could not find module 'ECV175_iOS_SDK'"

   • Neden: Xcode gerekli framework dosyalarını bulamıyor.

   • Çözüm:

     • ECV SDK framework'ünün projenize düzgün şekilde gömüldüğünden emin olun.

     • Framework'ün hedefinizin "Frameworks, Libraries, and Embedded Content" bölümünde listelendiğini doğrulayın.

     • Proje ayarlarınızdaki framework arama yollarının doğru konumu içerdiğini kontrol edin.

     • Derleme klasörünü temizleyin (Cmd + Shift + K) ve projeyi yeniden derleyin.

2. Hata: "Undefined symbols for architecture"

   • Neden: Gerekli bağımlılıkların eksik olması veya mimari uyumsuzlukları.

   • Çözüm:

     • Tüm gerekli framework'lerin projenizde düzgün şekilde bağlandığından emin olun.

     • Dağıtım hedefinin ve mimarilerin uygulamanız ile SDK arasında eşleştiğini doğrulayın.

     • Uyumlu bağımlılık sürümlerini kullandığınızı kontrol edin.

     • Projeyi temizleyin ve yeniden derleyin.

3. Hata: "Code signing failed"

   • Neden: Kod imzalama veya sağlama profilleriyle ilgili sorunlar.

   • Çözüm:

     • Apple Developer hesabınızın aktif olduğunu doğrulayın.

     • Sağlama profilinizin gerekli yetkileri içerdiğini kontrol edin.

     • İmzalama sertifikanızın geçerli ve düzgün şekilde yüklendiğinden emin olun.

     • Gerekirse sağlama profillerinizi güncelleyin.

Çalışma Zamanı Çökmeleri

1. Çökme: "Thread 1: EXC_BAD_ACCESS"

   • Neden: Bellek erişim sorunları, genellikle WebRTC veya yerel kodla ilgili.

   • Çözüm:

     • SDK'nın kullanımdan önce düzgün şekilde başlatıldığından emin olun.

     • Uygulamanızda düzgün bellek yönetimini kontrol edin.

     • Tüm gerekli izinlerin verildiğini doğrulayın.

     • Çökmenin tam noktasını belirlemek için hata ayıklayıcıyı kullanın.

2. Çökme: "Fatal error: Unexpectedly found nil while unwrapping an Optional value"

   • Neden: SDK nesnesine başlatılmadan önce veya temizlendikten sonra erişmeye çalışma.

   • Çözüm:

     • SDK Başlatılmamış: Herhangi bir SDK işlevselliğine erişmeden önce ECVSdk.shared.initialize(...)'ın çağrıldığından emin olun.

     • VideoCall Nil: rtcId'nin geçerli olduğunu ve görüşmenin sonlanmadığını doğrulayın.

     • WebRTC Bağlantısı Nil: AgentConnected olayından sonra videoCall.connect()'in başarıyla çağrıldığından emin olun.

     • View Controller'lar: Düzgün view controller yaşam döngüsü yönetimini sağlayın.

3. Çökme: WebRTC veya Medya İşleme ile İlgili

   • Neden: WebRTC bileşenlerinin yaşam döngüsünün düzgün yönetilmemesi.

   • Çözüm:

     • WebRTC kaynaklarının deinit veya viewWillDisappear'da düzgün şekilde temizlendiğinden emin olun.

     • Kamera ve mikrofon izinlerinin verildiğini doğrulayın.

     • Arka plan/ön plan geçişlerinin düzgün işlenmesini kontrol edin.

     • WebRTC işlemleri için düzgün thread yönetimini sağlayın.

4. Çökme: "Permission Denial"

   • Neden: Uygun izinler olmadan kamera veya mikrofona erişmeye çalışma.

   • Çözüm:

     • AVCaptureDevice.requestAccess kullanarak düzgün izin isteme akışını uygulayın.

     • Arama işlevselliğini etkinleştirmeden önce izin durumunu kontrol edin.

     • İzin reddini UI'da zarif bir şekilde işleyin.

     • Info.plist'in gerekli izin açıklamalarını içerdiğini doğrulayın.

Medya Kalitesi Sorunları

1. Düşük Video/Ses Kalitesi (Gecikme, Donma, Pikselleşme, Bozuk Ses)

   • Hata Ayıklama:

     • Ağ: Ağ bant genişliğini, gecikmeyi ve paket kaybını kontrol edin. Farklı ağlarda test edin (Wi-Fi vs Hücresel).

     • Cihaz Performansı: Eski cihazlar daha yüksek çözünürlüklerde kodlama/çözümleme konusunda zorlanabilir.

     • Yapılandırma: Video çözünürlüğü, kare hızı veya bit hızı ayarlarını ayarlamayı düşünün.

     • WebRTC İstatistikleri: Detaylı performans metrikleri için WebRTC istatistik toplamayı etkinleştirin.

Belirli Özellik Sorunları

1. Kamera Değiştirme Çalışmıyor

   • Hata Ayıklama:

     • webRTCConnection.switchCamera()'nın çağrıldığından emin olun.

     • Değiştirme denemesi sırasındaki hatalar için günlükleri kontrol edin.

     • Cihazın birden fazla kamera kullanılabilir olduğunu doğrulayın.

     • Düzgün kamera başlatmayı sağlayın.

2. Bekletme/Devam Etme Otomatik Olarak Sessize Almıyor/Sesi Açmıyor

   • Hata Ayıklama:

     • Yapılandırmada autoHandleHoldSideEffects'in etkin olduğunu doğrulayın.

     • Bekletme/devam etme olaylarının doğru şekilde alınıp alınmadığını kontrol edin.

     • Metin kanalı bağlantı durumunu doğrulayın.

     • Olay işleme uygulamasını kontrol edin.

Genel Hata Ayıklama Adımları

1. Konsol Günlüklerini Kontrol Edin: SDK günlüklerini izlemek için Xcode'un konsolunu kullanın. İlgili etiketlere göre filtreleme yapın ve uyarıları ve hataları arayın.

2. Yapılandırmayı Doğrulayın: ECVSdkConfiguration, DialCallParameters ve herhangi bir özel parametreyi ortam gereksinimlerinize göre çift kontrol edin.

3. Ağ Bağlantısını Kontrol Edin: Cihazın gerekli endpoint'lere ulaşabildiğini doğrulayın. Farklı ağlarda test edin ve herhangi bir güvenlik duvarı sorunu olup olmadığını kontrol edin.

4. Uygulamayı Basitleştirin: Temel yapılandırma ile başlayın ve sorunları izole etmek için kademeli olarak karmaşıklık ekleyin.

5. Aşamayı İzole Edin: Hatasının ne zaman oluştuğunu belirleyin: SDK başlatma, arama, kuyruk, WebRTC bağlantısı veya medya işleme.

6. Demo Uygulamasına Başvurun: Uygulamanızı, özellikle olay işleme ve view controller yaşam döngüsü yönetimi etrafında sağlanan demo kaynak koduyla karşılaştırın.

7. Tüm Olayları Günlüğe Kaydedin: Arama akışını izlemek ve eksik veya beklenmeyen olayları belirlemek için olay işlemenize günlük kaydı ekleyin.

Destek ile İletişim

Destek ile iletişime geçerken lütfen şunları sağlayın:

• SDK Sürümü: (örn. ECV-175-iOS-SDK-v1.2.3)

• Test Edilen Cihaz(lar): iPhone/iPad modeli, iOS sürümü

• Backend Sürümü: ECV v1.75+

• Yapılandırma: ECVSdkConfiguration'ınız, ilgili DialCallParameters ve herhangi bir özel parametre

• Detaylı Sorun Açıklaması: Belirtiler, yeniden üretme adımları, beklenen vs gerçek davranış

• İlgili Konsol Günlükleri: Sorun sırasında SDK ve uygulama günlükleri dahil günlükleri yakalayın

• Ekran Görüntüleri/Videolar: Sorunu göstermek için yardımcı olacaksa