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 통합 환경에서는 setActive(true)를 직접 호출하지 않음
    // CallKit이 활성화 타이밍을 가져가므로, didActivate에서 수신
} 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()
    }
    
    // 수신 수락 — 여기서 joinChannel 호출하면 안 됨!
    func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
        // 채널 정보만 보관, 실제 join은 didActivate에서
        pendingChannelId = action.callUUID.uuidString
        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 활성화 완료 — 여기서 joinChannel
    func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
        agoraKit.setEnableSpeakerphone(true)
        agoraKit.joinChannel(byToken: token, channelId: channel, info: nil, uid: 0)
    }
    
    // ✅ 시스템이 세션 비활성화 — Agora 정리 + ADM 강제 재시작 준비
    func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
        agoraKit.disableAudio()
        agoraKit.enableAudio()
    }
}

[잘못된 순서 — 처음 3초 무음]

t=0   사용자 "수락"
t=0+  performAnswerCallAction 콜백
t=0+  agoraKit.joinChannel ← ❌ 너무 빠름. AVAudioSession 아직 비활성
t=1   ADM이 stale AudioUnit으로 캡처 시도 → 0 sample
t=2   시스템이 didActivate 콜백
t=2~5 ADM 워치독이 0 sample 감지 → AudioUnit 재할당
t=5   드디어 음성 흐름

[올바른 순서]

t=0   사용자 "수락"
t=0+  performAnswerCallAction → action.fulfill()만
t=1   시스템이 didActivate 콜백
t=1+  agoraKit.joinChannel ← ✅ 깨끗한 AudioUnit 위에서 시작
t=1+  즉시 음성 흐름

agoraKit.setParameters("{\"che.audio.restartWhenInterrupted\":true}")
agoraKit.joinChannel(byToken: nil, channelId: session, info: nil, uid: 0)

if #available(iOS 14.5, *) {
    try? AVAudioSession.sharedInstance().setCategory(
        .playAndRecord,
        mode: .default,
        options: [
            .allowAirPlay,
            .allowBluetooth,
            .allowBluetoothA2DP,
            .defaultToSpeaker,
            .interruptSpokenAudioAndMixWithOthers,
            .overrideMutedMicrophoneInterruption   // ← 핵심 1
        ]
    )
    try? AVAudioSession.sharedInstance()
        .setPrefersNoInterruptionsFromSystemAlerts(true)  // ← 핵심 2
}

// 옵션 A: 세션 deactivate만 막기 (권장)
agoraKit.setAudioSessionOperationRestriction(.deactivateSession)

// 옵션 B: SDK가 AVAudioSession을 일절 건드리지 않게 (강력)
agoraKit.setAudioSessionOperationRestriction(.all)

// joinChannel 직전: SDK 권한 복구 (캡처/재생 정상 시작 보장)
agoraKit.setAudioSessionOperationRestriction(.none)
agoraKit.joinChannel(byToken: token, channelId: ch, info: nil, uid: 0)

// leaveChannel 직전: SDK 제한 (호스트 앱이 세션 회수)
agoraKit.setAudioSessionOperationRestriction(.all)
agoraKit.leaveChannel(nil)

// 동일 효과의 private parameter (공식 KB에 언급)
agoraKit.setParameters("{\"che.audio.keep.audiosession\":true}")

agoraKit.setParameters("{\"che.audio.specify.category\": 3}")
// 1=SoloAmbient, 2=Ambient, 3=Playback, default=PlayAndRecord

1. Talkito(Agora 기반) 통화 진행 중
2. ChatMoa로 전화 옴 → 사용자 수락
3. ChatMoa 활성, Talkito는 백그라운드
4. 사용자가 ChatMoa를 백그라운드로 보내고 Talkito 복귀
5. Agora 룸에서 원격 사용자가 → 로컬 사용자 음성 + ChatMoa 음성 양쪽을 모두 들음

agoraKit.setParameters("{\"che.audio.nonmixable.option\":true}")
agoraKit.joinChannel(byToken: nil, channelId: session, info: nil, uid: 0)

// 옵션 A: 공개 API
func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
    agoraKit.disableAudio()
    agoraKit.enableAudio()
}

// 옵션 B: private parameter (Case 1과 동일)
agoraKit.setParameters("{\"che.audio.restartWhenInterrupted\":true}")

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

func joinChannel() {
    // ① 앱이 직접 카테고리 설정 (.allowBluetoothA2DP가 핵심)
    try? AVAudioSession.sharedInstance().setCategory(
        .playAndRecord,
        mode: .voiceChat,
        options: [.mixWithOthers, .allowBluetoothA2DP]
    )
    
    // ② SDK가 위 설정을 덮어쓰지 못하도록 제한
    agoraKit.setAudioSessionOperationRestriction(.configureSession)
    
    // ③ 그 뒤에 채널 조인 — 순서가 바뀌면 효과 없음
    agoraKit.joinChannel(byToken: nil, channelId: session, info: nil, uid: 0)
}

t=0  ChatMoa 통화로 인터럽트 시작
     → AVAudioSession이 비활성화됨
     → 그 시점 Agora가 잡고 있던 AudioUnit 인스턴스가 invalidated

t=N  ChatMoa 통화 종료
     → 시스템이 우리 앱의 세션을 다시 활성화
     → didActivate 콜백 도착

t=N+ 만약 Agora ADM이 여전히 invalidated AudioUnit 참조를 잡고 있으면
     → 캡처 콜백에서 0 sample 반환 (실제로 데이터가 안 들어옴)
     → 송신측 Opus 인코더에 무음만 흘러감

t=N+ 몇 초 후
     → ADM의 헬스체크가 "왜 sample이 안 들어오지?" 감지
     → 새 AudioUnit 할당 + 재시작
     → 음성 정상화

func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
    // 시스템이 세션을 거둘 때 ADM도 명시적으로 정리
    agoraKit.disableAudio()
    agoraKit.enableAudio()
}

            발신측                    수신측
              │                         │
   ① 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에서 joinChannel 부르지 않기
   □ didActivate 콜백에서 joinChannel 부르기
   □ didDeactivate에서 disableAudio() → enableAudio()

□ AVAudioSession
   □ category: .playAndRecord, mode: .voiceChat
   □ defaultToSpeaker는 영상 통화에만
   □ CallKit 환경에선 setActive(true) 직접 호출 금지

□ Agora 트러블 처방 (필요 시)
   □ che.audio.restartWhenInterrupted (시스템 알람 인터럽트)
   □ setAudioSessionOperationRestriction(.deactivateSession 또는 .all) (3rd party 오디오 보존)
   □ che.audio.nonmixable.option (멀티앱 오디오 누수 방지)
   □ setCategory + .allowBluetoothA2DP + .configureSession (CallKit 스피커 버튼 풀림)
   □ overrideMutedMicrophoneInterruption + setPrefersNoInterruptionsFromSystemAlerts (iOS 14.5+)

□ Agora 권장 토글 패턴
   □ joinChannel 직전: setAudioSessionOperationRestriction(.none) — SDK 권한 복구
   □ leaveChannel 직전: setAudioSessionOperationRestriction(.all) — SDK 권한 제한

                [VoIP 통합 이슈 보고]
                         │
                         ▼
              [언제 일어나나?]
            ┌────────────┼────────────┬────────────┐
        통화 시작     통화 도중      통화 종료     멀티앱 동시
            │            │             │            │
       3초 무음       알람/전화      3rd party     ChatMoa 누수
            │       인터럽트       오디오 죽음        │
            ▼            ▼             ▼            ▼
      didActivate     restart       keep.       nonmixable
      에서 join      WhenInterrupt   audiosession    .option
            │            │             │            │
            │       (Case 1, 2)    (Case 3)      (Case 4)
            ▼
       (3초 무음 §8)