📞 Mastering CallKit

Make VoIP apps feel native! Integrate call UI with the system using CallKit.

⭐ Difficulty: ⭐⭐⭐ ⏱️ Est. Time: 2-3h 📂 System & Network

✨ CallKit is?

CallKit is a framework that integrates VoIP (Voice over IP) apps into the iPhone's native phone system. It displays calls with the same UI as FaceTime and Phone, and allows answering calls from the lock screen. Apps like Slack, WhatsApp, and Zoom use CallKit.

📦 Key Features

Feature Overview

✅ 시스템 통화 UI 통합
✅ 잠금 화면 통화 알림
✅ 통화 기록 (최근 통화)
✅ 차단 및 식별 (Caller ID)
✅ PushKit 연동 (백그라운드 알림)
✅ 통화 대기, 통화 전환
✅ 음소거, 스피커 제어

📞 Basic Structure: CXProvider and CXCallController

CallManager.swift

import CallKit
import AVFoundation

class CallManager: NSObject {
    static let shared = CallManager()

    // CXProvider: 시스템에서 앱으로 들어오는 이벤트 처리
    private let provider: CXProvider

    // CXCallController: 앱에서 시스템으로 액션 요청
    private let callController = CXCallController()

    private override init() {
        // Provider 설정
        let config = CXProviderConfiguration()
        config.localizedName = "MyVoIP"
        config.supportsVideo = true
        config.maximumCallGroups = 1
        config.maximumCallsPerCallGroup = 1
        config.supportedHandleTypes = [.phoneNumber, .generic]

        // 벨소리 설정
        config.ringtoneSound = "ringtone.caf"

        provider = CXProvider(configuration: config)

        super.init()

        provider.setDelegate(self, queue: nil)
    }
}

// MARK: - Provider Delegate
extension CallManager: CXProviderDelegate {
    // Audio Session setup (필수)
    func providerDidReset(_ provider: CXProvider) {
        // all End call
        print("Provider reset")
    }

    // Call 시작
    func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
        // Call 시작 로직
        configureAudioSession()
        action.fulfill()
    }

    // Call 응답
    func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
        // Call 응답 로직
        configureAudioSession()
        action.fulfill()
    }

    // Call 종료
    func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
        // Call 종료 로직
        action.fulfill()
    }

    // 음소거
    func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
        action.fulfill()
    }

    // 대기 (Hold)
    func provider(_ provider: CXProvider, perform action: CXSetHeldCallAction) {
        action.fulfill()
    }

    // Audio 세션 활성화
    func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
        // VoIP 오디오 시작
        print("Audio session activated")
    }

    func configureAudioSession() {
        let session = AVAudioSession.sharedInstance()
        do {
            try session.setCategory(.playAndRecord, mode: .voiceChat)
            try session.setActive(true)
        } catch {
            print("Audio session error: \(error)")
        }
    }
}

📲 Displaying Incoming Calls

IncomingCall.swift

import CallKit

extension CallManager {
    // Incoming call 알림
    func reportIncomingCall(
        uuid: UUID,
        handle: String,
        hasVideo: Bool = false,
        completion: ((Error?) -> Void)? = nil
    ) {
        // CXCallUpdate로 통화 정보 설정
        let update = CXCallUpdate()
        update.remoteHandle = CXHandle(type: .phoneNumber, value: handle)
        update.hasVideo = hasVideo
        update.localizedCallerName = handle

        // 시스템에 통화 알림
        provider.reportNewIncomingCall(with: uuid, update: update) { error in
            if let error = error {
                print("Failed to report call: \(error.localizedDescription)")
            } else {
                print("Incoming call reported")
            }
            completion?(error)
        }
    }
}

// Usage Example
let callUUID = UUID()
CallManager.shared.reportIncomingCall(
    uuid: callUUID,
    handle: "010-1234-5678",
    hasVideo: false
)

📤 Starting Outgoing Calls

OutgoingCall.swift

import CallKit

extension CallManager {
    // Outgoing call 시작
    func startCall(handle: String, videoEnabled: Bool = false) {
        let uuid = UUID()

        // Handle 생성
        let handle = CXHandle(type: .phoneNumber, value: handle)

        // Start Call Action
        let startCallAction = CXStartCallAction(call: uuid, handle: handle)
        startCallAction.isVideo = videoEnabled

        // Transaction 생성 및 요청
        let transaction = CXTransaction(action: startCallAction)

        callController.request(transaction) { error in
            if let error = error {
                print("Start call failed: \(error.localizedDescription)")
            } else {
                print("Start call succeeded")
            }
        }
    }

    // Call 종료
    func endCall(uuid: UUID) {
        let endCallAction = CXEndCallAction(call: uuid)
        let transaction = CXTransaction(action: endCallAction)

        callController.request(transaction) { error in
            if let error = error {
                print("End call failed: \(error.localizedDescription)")
            } else {
                print("Call ended")
            }
        }
    }
}

// Usage Example
CallManager.shared.startCall(handle: "010-9876-5432", videoEnabled: false)

📱 SwiftUI Integration

CallView.swift

import SwiftUI
import CallKit

struct CallView: View {
    @State private var phoneNumber = ""
    @State private var isCallActive = false
    @State private var currentCallUUID: UUID?

    var body: some View {
        VStack(spacing: 20) {
            Text("VoIP 통화")
                .font(.largeTitle)
                .bold()

            if isCallActive {
                // Call 중 UI
                VStack(spacing: 20) {
                    Image(systemName: "phone.fill")
                        .font(.system(size: 60))
                        .foregroundStyle(.green)

                    Text("In call...")
                        .font(.title2)

                    Text(phoneNumber)
                        .font(.title3)
                        .foregroundStyle(.secondary)

                    Button(action: endCall) {
                        HStack {
                            Image(systemName: "phone.down.fill")
                            Text("End call")
                        }
                        .frame(maxWidth: .infinity)
                    }
                    .buttonStyle(.borderedProminent)
                    .tint(.red)
                }
            } else {
                // 다이얼 UI
                TextField("Phone number", text: $phoneNumber)
                    .textFieldStyle(.roundedBorder)
                    .keyboardType(.phonePad)

                Button(action: makeCall) {
                    HStack {
                        Image(systemName: "phone.fill")
                        Text("전화 걸기")
                    }
                    .frame(maxWidth: .infinity)
                }
                .buttonStyle(.borderedProminent)
                .disabled(phoneNumber.isEmpty)

                Button("수신 테스트") {
                    simulateIncomingCall()
                }
                .buttonStyle(.bordered)
            }
        }
        .padding()
    }

    func makeCall() {
        currentCallUUID = UUID()
        CallManager.shared.startCall(handle: phoneNumber)
        isCallActive = true
    }

    func endCall() {
        if let uuid = currentCallUUID {
            CallManager.shared.endCall(uuid: uuid)
        }
        isCallActive = false
        currentCallUUID = nil
    }

    func simulateIncomingCall() {
        let uuid = UUID()
        CallManager.shared.reportIncomingCall(
            uuid: uuid,
            handle: "010-1234-5678"
        )
    }
}

🔔 PushKit Integration (Background Notifications)

PushKitManager.swift

import PushKit
import CallKit

class PushKitManager: NSObject, PKPushRegistryDelegate {
    static let shared = PushKitManager()

    private let pushRegistry = PKPushRegistry(queue: .main)

    func registerForVoIPPushes() {
        pushRegistry.delegate = self
        pushRegistry.desiredPushTypes = [.voIP]
    }

    // Push Token 받음
    func pushRegistry(
        _ registry: PKPushRegistry,
        didUpdate credentials: PKPushCredentials,
        for type: PKPushType
    ) {
        let token = credentials.token.map { String(format: "%02x", $0) }.joined()
        print("VoIP Push Token: \(token)")

        // Server로 토큰 전송
        sendTokenToServer(token)
    }

    // Push 수신 (통화 알림)
    func pushRegistry(
        _ registry: PKPushRegistry,
        didReceiveIncomingPushWith payload: PKPushPayload,
        for type: PKPushType,
        completion: @escaping () -> Void
    ) {
        guard type == .voIP else { return }

        // Payload에서 통화 정보 추출
        let callerID = payload.dictionaryPayload["caller_id"] as? String ?? "Unknown"
        let hasVideo = payload.dictionaryPayload["has_video"] as? Bool ?? false

        // CallKit으로 Incoming call 표시
        let callUUID = UUID()
        CallManager.shared.reportIncomingCall(
            uuid: callUUID,
            handle: callerID,
            hasVideo: hasVideo
        ) { error in
            completion()
        }
    }

    func sendTokenToServer(_ token: String) {
        // API 호출하여 서버에 저장
    }
}

🎯 Practical Example: Complete VoIP App

VoIPApp.swift

import SwiftUI

@main
struct VoIPApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            CallView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        // PushKit 등록
        PushKitManager.shared.registerForVoIPPushes()

        // CallManager 초기화
        _ = CallManager.shared

        return true
    }
}

🔧 Call Status Updates

CallUpdate.swift

import CallKit

extension CallManager {
    // Call Connected
    func reportCallConnected(uuid: UUID) {
        provider.reportOutgoingCall(with: uuid, connectedAt: Date())
    }

    // Call Start failed
    func reportCallFailed(uuid: UUID) {
        provider.reportCall(with: uuid, endedAt: Date(), reason: .failed)
    }

    // 상대방이 거부
    func reportCallRemoteEnded(uuid: UUID) {
        provider.reportCall(with: uuid, endedAt: Date(), reason: .remoteEnded)
    }

    // Call 정보 업데이트
    func updateCall(uuid: UUID, localizedName: String) {
        let update = CXCallUpdate()
        update.localizedCallerName = localizedName
        provider.reportCall(with: uuid, updated: update)
    }
}

// Usage Example
let callUUID = UUID()

// Call Connection successful
CallManager.shared.reportCallConnected(uuid: callUUID)

// 5초 후 End call
DispatchQueue.main.asyncAfter(deadline: .now() + 5) {
    CallManager.shared.reportCallRemoteEnded(uuid: callUUID)
}

📋 Caller ID & Call Blocking Extension

CallDirectoryExtension.swift

import CallKit

// Call Directory Extension (별도 타겟)
class CallDirectoryHandler: CXCallDirectoryProvider {
    // 차단 번호 추가
    override func beginRequest(with context: CXCallDirectoryExtensionContext) {
        do {
            // 차단할 번호 목록
            let blockedNumbers: [CXCallDirectoryPhoneNumber] = [
                82101234567,  // 국가코드 포함
                82109876543
            ]

            for number in blockedNumbers.sorted() {
                context.addBlockingEntry(withNextSequentialPhoneNumber: number)
            }

            // 발신자 표시 정보
            let identifications: [(CXCallDirectoryPhoneNumber, String)] = [
                (82101111111, "홍길동"),
                (82102222222, "배달 서비스")
            ]

            for (number, label) in identifications.sorted(by: { $0.0 < $1.0 }) {
                context.addIdentificationEntry(
                    withNextSequentialPhoneNumber: number,
                    label: label
                )
            }

            context.completeRequest()
        } catch {
            context.cancelRequest(withError: error)
        }
    }
}

💡 HIG Guidelines

HIG Recommendations

✅ DO
1. 정확한 발신자 정보 표시
   - 이름, 번호를 명확하게
   - localizedCallerName 사용

2. 오디오 세션 올바르게 설정
   - .playAndRecord + .voiceChat
   - provider didActivate 에서 오디오 시작

3. 통화 상태 즉시 업데이트
   - 연결, 종료 상태를 정확하게 보고
   - reportCallConnected, reportCallEnded

4. PushKit 필수 사용
   - In background도 통화 수신
   - VoIP Push만 사용

❌ DON'T
1. 일반 Push Notification 사용 금지
2. CallKit 없이 VoIP 앱 제작 불가
3. 통화 아닌 용도로 PushKit 사용
4. 통화 상태 보고 누락

🔧 Practical Tips

Real-World Patterns

import CallKit

// 1. 통화 관찰자 (Observer)
class CallObserver {
    let callObserver = CXCallObserver()

    init() {
        callObserver.setDelegate(self, queue: .main)
    }
}

extension CallObserver: CXCallObserverDelegate {
    func callObserver(_ callObserver: CXCallObserver, callChanged call: CXCall) {
        print("Call changed: \(call.uuid)")

        if call.isOnHold {
            print("통화 대기 중")
        }

        if call.hasEnded {
            print("End call됨")
        }
    }
}

// 2. 음소거 상태 토글
func toggleMute(callUUID: UUID, isMuted: Bool) {
    let muteAction = CXSetMutedCallAction(call: callUUID, muted: isMuted)
    let transaction = CXTransaction(action: muteAction)

    CXCallController().request(transaction) { error in
        if let error = error {
            print("Mute failed: \(error)")
        }
    }
}

// 3. 다중 액션 (통화 전환)
func swapCalls(currentUUID: UUID, incomingUUID: UUID) {
    let holdAction = CXSetHeldCallAction(call: currentUUID, onHold: true)
    let answerAction = CXAnswerCallAction(call: incomingUUID)

    let transaction = CXTransaction(actions: [holdAction, answerAction])

    CXCallController().request(transaction) { error in
        if let error = error {
            print("Swap failed: \(error)")
        }
    }
}

🔐 Info.plist & Entitlements Configuration

Info.plist

<!-- 백그라운드 모드 -->
<key>UIBackgroundModes</key>
<array>
    <string>voip</string>
</array>

<!-- Entitlements에서 설정 필요 -->
- Push Notifications 활성화
- Background Modes > Voice over IP 체크

💡 CallKit 핵심
✅ 시스템 통화 UI와 완벽 통합
✅ PushKit으로 백그라운드 수신
✅ 잠금 화면에서도 통화 가능
✅ 통화 기록 auto save
✅ FaceTime과 동일한 UX

📦 Learning Resources

📎 Apple Official Resources

📘 Documentation 💻 Sample Code 🎬 WWDC Sessions