iOS VoIP 통합의 4-레이어 모델 — CallKit · PushKit · AVAudioSession · Agora ADM

┌───────────────────────────────────────────────────────┐
│  ① PushKit          (iOS 시스템 → 앱 깨우기)          │
│     "전화 왔다는 신호 배달"                            │
├───────────────────────────────────────────────────────┤
│  ② CallKit          (시스템 통화 UI + 세션 권한 점유)   │
│     "사용자에게 보여주고 AVAudioSession 활성화 결정"    │
├───────────────────────────────────────────────────────┤
│  ③ AVAudioSession   (오디오 라우팅 / 카테고리 / 모드)   │
│     "마이크·스피커·블루투스 누가 쓸지 시스템이 중재"    │
├───────────────────────────────────────────────────────┤
│  ④ Agora SDK ADM    (실제 캡처/재생 + RTP 송수신)       │
│     "PCM 가져와서 Opus로 인코딩 → SD-RTN 송출"          │
└───────────────────────────────────────────────────────┘

let config = CXProviderConfiguration(localizedName: "Talkito")
config.supportsVideo = true
config.maximumCallGroups = 1
config.maximumCallsPerCallGroup = 1
config.supportedHandleTypes = [.generic]

let provider = CXProvider(configuration: config)
provider.setDelegate(self, queue: nil)   // nil → main queue

let update = CXCallUpdate()
update.localizedCallerName = "김철수"          // 표시명
update.hasVideo = true                         // 영상 통화 여부
update.supportsHolding = true                  // 보류 가능
update.supportsDTMF = false                    // 키패드 톤
update.supportsGrouping = false
update.supportsUngrouping = false
update.remoteHandle = CXHandle(type: .generic, value: "user_42")

let callUUID = UUID()
provider.reportNewIncomingCall(with: callUUID, update: update) { error in
    if let error = error {
        // 시스템 UI를 표시하지 못했으므로 PushKit completion 호출
        print("CallKit reject: \(error)")
    } else {
        // 시스템 통화 UI 표시 성공
    }
    completion()  // PushKit completion 필수
}

[VoIP 푸시 도착] ──► [didReceiveIncomingPushWith 콜백]
                            │
                            ▼
                    [reportNewIncomingCall 호출?]
                       │            │
                      예           아니오
                       │            │
                  [통화 UI 표시]  [시스템이 앱 강제 종료]
                                       │
                                       ▼
                              [반복 위반 시 VoIP 푸시 차단]

let session = AVAudioSession.sharedInstance()

do {
    try session.setCategory(
        .playAndRecord,
        mode: .voiceChat,
        options: [.allowBluetooth, .defaultToSpeaker]
    )
    // CallKit과 합의한 세션 수명 주기에 따라 활성화 상태를 처리
} catch {
    print("AVAudioSession setup failed: \(error)")
}

<key>NSMicrophoneUsageDescription</key>
<string>음성 통화를 위해 마이크 권한이 필요합니다</string>

<key>NSCameraUsageDescription</key>
<string>영상 통화를 위해 카메라 권한이 필요합니다</string>

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
    <string>voip</string>
</array>

extension CallController: CXProviderDelegate {
    
    func providerDidReset(_ provider: CXProvider) { /* 정리 */ }
    
    // 발신 시작
    func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
        action.fulfill()
    }
    
    // 수신 수락 — 서버 수락 처리와 채널 준비
    func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
        signaling.accept(callUUID: action.callUUID)
        prepareRtcChannelIfNeeded()
        action.fulfill()
    }
    
    // 종료
    func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
        agoraKit.leaveChannel(nil)
        action.fulfill()
    }
    
    // Mute
    func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
        agoraKit.muteLocalAudioStream(action.isMuted)
        action.fulfill()
    }
    
    // 시스템이 AVAudioSession 활성화 완료 — 오디오 장치 시작/재개
    func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
        resumeRtcAudio()
    }
    
    // 시스템이 세션 비활성화 — 오디오 장치 일시 정지/중지
    func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
        pauseRtcAudio()
    }
}

[수락 액션] → 서버 수락/채널 준비 → action.fulfill()
                           │
[didActivate] ─────────────┴→ RTC 오디오 장치 시작 또는 재개

[didDeactivate] ────────────→ RTC 오디오 장치 일시 정지 또는 중지

if #available(iOS 14.0, *) {
    try? AVAudioSession.sharedInstance()
        .setPrefersNoInterruptionsFromSystemAlerts(true)
}

// 예: 호스트 앱이 통화 뒤에도 세션을 유지해야 하는 경우
agoraKit.setAudioSessionOperationRestriction(.deactivateSession)

1. RTC 통화 진행 중
2. 다른 통화 앱의 수신 전화를 받음
3. 기존 앱으로 돌아왔을 때 입력·출력 route 또는 mute 상태가 예상과 다름

func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
    pauseRtcAudio()
}

func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
    resumeRtcAudio()
}

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CallKit   │ ◄►  │ AVAudioSess │ ◄►  │  Agora SDK  │
│ (시스템 UI)  │     │   (공용자원)  │     │  (RTC ADM)  │
└─────────────┘     └─────────────┘     └─────────────┘

func joinChannel() {
    // 앱이 AVAudioSession 구성을 맡는 설계라면
    try? AVAudioSession.sharedInstance().setCategory(
        .playAndRecord,
        mode: .voiceChat,
        options: [.allowBluetooth, .defaultToSpeaker]
    )

    // SDK 버전에서 지원하는 공개 제한 API로 책임 경계를 고정
    agoraKit.setAudioSessionOperationRestriction(.configureSession)
    agoraKit.joinChannel(byToken: nil, channelId: session, info: nil, uid: 0)
}

            발신측                    수신측
              │                         │
   ① CXStartCallAction request          │
              │                         │
   ② perform CXStartCallAction          │
              │                         │
   ③ reportOutgoingCall.connecting   ④ VoIP push 도착
              │                         │
   ⑤ reportOutgoingCall.connected    ⑥ reportNewIncomingCall
              │                         │
              │              ┌──────────┴──────────┐
              │              │                     │
              │       ⑦ perform Answer       ⑧ perform End (거절)
              │              │                     │
              │              ▼                     │
              │         CallKit didActivate        │
              │         on both sides              │
              │              │                     │
              └──────────────┴─────────┐           │
                                       ▼           │
                            joinChannel + RTP      │
                                       │           │
                                       ▼           │
                            ⑨ end / endCallAction  │
                                       │           │
                                       ▼           ▼
                              perform CXEndCallAction

□ Info.plist
   □ NSMicrophoneUsageDescription (빈 문자열 금지)
   □ NSCameraUsageDescription (영상 통화면)
   □ UIBackgroundModes: audio, voip

□ PushKit
   □ didReceiveIncomingPushWith 핸들러에서 즉시 reportNewIncomingCall
   □ completion handler 누락 없음

□ CallKit
   □ CXProvider 단일 인스턴스 유지
   □ CXProviderConfiguration의 supportsVideo / maximumCallGroups 설정
   □ performAnswerCallAction에서 서버 수락·채널 준비 후 fulfill
   □ didActivate에서 RTC 오디오 장치 시작 또는 재개
   □ didDeactivate에서 RTC 오디오 장치 일시 정지 또는 중지

□ AVAudioSession
   □ category: .playAndRecord, mode: .voiceChat
   □ defaultToSpeaker는 제품의 기본 출력 정책에 맞춰 선택
   □ CallKit과 SDK 중 AVAudioSession 구성 책임자를 명확히 지정
   □ interruption·routeChange·currentRoute 로그 수집

□ Agora 통합
   □ 현재 SDK의 공개 API 레퍼런스와 릴리스 노트 확인
   □ 필요한 범위에서만 setAudioSessionOperationRestriction 사용
   □ 비공개 setParameters 키는 제품 코드에 고정하지 않음
   □ join·first local frame·first remote frame 시각 기록

                [VoIP 통합 이슈 보고]
                         │
                         ▼
              [언제 일어나나?]
            ┌────────────┼────────────┬────────────┐
        통화 시작     통화 도중      통화 종료     라우트 변경
            │            │             │            │
       수락 직후 무음   알람/전화      호스트 오디오   스피커/BT
            │       인터럽션       미복구            │
            ▼            ▼             ▼            ▼
      이벤트 시각      began/ended    세션 책임자     routeChange
      4종 비교       shouldResume    설정 비교       currentRoute