iOS VoIP Push 구성 — APNs, PushKit, CallKit

[앱 서버] ──→ [Apple APNs] ──→ [사용자 아이폰]

[Apple 데이터센터 (구름 위)]
└─ APNs 서버 ← 실제 푸시를 라우팅하는 서버 인프라

[당신의 아이폰 (손에 든 기기)]
└─ iOS 운영체제
   ├─ APNs 클라이언트 ← APNs 연결을 관리하는 시스템 구성요소
   ├─ UIKit              ← 화면/버튼 그리는 프레임워크
   ├─ Foundation         ← String, Array, Date 등 기본 타입
   ├─ AVFoundation       ← 오디오/비디오
   ├─ PushKit            ← VoIP 푸시 도착 시 앱 코드를 호출해주는 도우미
   ├─ CallKit            ← 통화 UI 그리는 도우미
   └─ ...수백 개의 프레임워크

앱 첫 실행:
  앱 → iOS:    "푸시 받을 거야, 등록해줘"
  iOS → APNs:  "이 앱+이 디바이스+이 환경 토큰 발급해줘"
  APNs → iOS:  "ABC123..."
  iOS → 앱:    "토큰 ABC123 받아"
  앱 → 서버:   "내 토큰 ABC123 저장해놔"

푸시 보낼 때:
  서버 → APNs: "ABC123한테 '새 메시지' 보내줘"
  APNs → 그 디바이스로 라우팅

APNs 푸시 도착 → 알림 배너 표시 → 사용자가 탭 → 그제서야 앱 실행

VoIP 푸시 도착 → 사용자 개입 없이 앱 자동 실행 → 통화 화면 즉시 표시

메시징 앱:
├─ APNs device token: "4a9c..." ← 메시지 알림용
└─ VoIP push token:    "8d2b..." ← 보이스톡 수신용

서버 DB:
┌─────────┬─────────────────┬─────────────────┐
│ user_id │ apns_token      │ voip_token      │
├─────────┼─────────────────┼─────────────────┤
│ vita    │ 4a9c...         │ 8d2b...         │
│ alice   │ 8d2b...         │ 7f1e...         │
└─────────┴─────────────────┴─────────────────┘

notification.topic    = 'com.example.myapp';        // bundle ID 그대로
notification.pushType = 'alert';
notification.payload  = { aps: { alert: '새 메시지' } };
provider.send(notification, apnsToken);             // APNs provider 자격 증명으로 인증

notification.topic    = 'com.example.myapp.voip';   // ← .voip 접미사 필수
notification.pushType = 'voip';                     // ← voip 명시 필수
notification.payload  = { /* 자유 형식 */ };
provider.send(notification, voipToken);             // 동일 키 또는 허용된 인증서로 인증

파일명: VoIPServices.p12
내용:   바이너리 (X.509 인증서 + 개인키)
크기:   약 4~10KB
유효기간: 발급일로부터 1년 (만료 시 갱신 필수)

파일명: AuthKey_ABC123XYZ.p8
내용:   ASCII 텍스트 (PEM 형식)
크기:   약 250바이트
유효기간: 만료 없음

-----BEGIN PRIVATE KEY-----
MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQg...
-----END PRIVATE KEY-----

1. https://developer.apple.com/account 로그인
2. "Certificates, Identifiers & Profiles" 클릭
3. 좌측 메뉴 "Keys" 선택
4. 우측 상단 "+" 버튼
5. Key Name 입력 (예: "MyApp Push Key")
6. "Apple Push Notifications service (APNs)" 체크
7. Continue → Register
8. Download 버튼 클릭 (한 번만 가능)
9. AuthKey_XXXXXXXXXX.p8 파일 받음

final class PushManager: NSObject, PKPushRegistryDelegate {
    private let pushRegistry = PKPushRegistry(queue: .main)

    override init() {
        super.init()
        pushRegistry.delegate = self
        pushRegistry.desiredPushTypes = Set([.voIP])
    }
}

PKPushRegistry (시스템) ── delegate ──→ 내 객체 (PKPushRegistryDelegate 채택)
                                          │
                                  ┌───────┴───────┐
                                  ▼               ▼
                       didUpdate 콜백        didReceiveIncomingPush 콜백
                       (토큰 발급)           (푸시 도착)

func pushRegistry(_ registry: PKPushRegistry,
                  didUpdate pushCredentials: PKPushCredentials,
                  for type: PKPushType) {
    let bytes = [UInt8](pushCredentials.token)
    uploadToServer(bytes)
}

pushRegistry(_:didUpdate:for:)
   │           │           │
[알리는 객체]  [일어난 일]  [부가 정보]

앱 첫 실행:
  앱 → iOS:    "등록해줘"
  iOS → APNs:  "토큰 발급"
  APNs → iOS:  "ABC123..."  ← 새 발급
  iOS → 앱:    didUpdate 콜백

앱 두 번째 실행:
  앱 → iOS:    "등록해줘"
  iOS:         "이미 ABC123 캐시되어 있음"
  iOS → 앱:    didUpdate 콜백으로 같은 값 전달

토큰 변경 시점과 값을 앱이 예측해서는 안 됨

func pushRegistry(_ registry: PKPushRegistry, didUpdate ..., for type: PKPushType) {
    // 전달된 현재 값을 서버에 idempotent upsert
    uploadToServer(token)
}

user_devices 테이블:
┌─────────┬───────────────┬───────────┬──────────┬──────────────┐
│ user_id │ device_id     │ token     │ platform │ token_type   │
├─────────┼───────────────┼───────────┼──────────┼──────────────┤
│ vita    │ iphone-uuid-A │ 4a9c...   │ ios      │ voip         │
│ vita    │ iphone-uuid-A │ 9f8e...   │ ios      │ apns         │
│ vita    │ ipad-uuid-B   │ 7d2b...   │ ios      │ voip         │
│ vita    │ android-id-C  │ 8e1f...   │ android  │ fcm          │
└─────────┴───────────────┴───────────┴──────────┴──────────────┘

func pushRegistry(_ registry: PKPushRegistry,
                  didInvalidatePushTokenFor type: PKPushType) {
    // 토큰이 더 이상 유효하지 않음 → 서버 DB에서 삭제
    deleteFromServer()
}

{
  "aps": {
    "alert": "새 메시지가 도착했습니다",
    "badge": 1,
    "sound": "default"
  }
}

{
  "aps": {},
  "caller_id": "alice",
  "caller_name": "앨리스",
  "call_id": "call_123",
  "call_uuid": "F47AC10B-58CC-4372-A567-0E02B2C3D479"
}

func pushRegistry(_ registry: PKPushRegistry,
                  didReceiveIncomingPushWith payload: PKPushPayload,
                  for type: PKPushType,
                  completion: @escaping () -> Void) {
    
    let dict = payload.dictionaryPayload
    
    let callerName  = dict["caller_name"] as? String ?? "알 수 없음"
    let callId      = dict["call_id"] as? String ?? ""
    let callUuid    = UUID(uuidString: dict["call_uuid"] as? String ?? "") ?? UUID()
    
    // CallKit에 통화 띄우기 — 반드시 이 콜백 안에서!
    let update = CXCallUpdate()
    update.remoteHandle = CXHandle(type: .generic, value: callerName)
    
    provider.reportNewIncomingCall(with: callUuid, update: update) { error in
        // 표시 완료
    }
    
    completion()  // 시스템에 처리 끝났다고 알림 (필수)
}

class CallController: NSObject {
    let controller = CXCallController()
    let provider: CXProvider
    let rtcEngine: AgoraRtcEngineKit
    
    override init() {
        provider = CXProvider(configuration: Self.providerConfiguration)
        super.init()
        provider.setDelegate(self, queue: nil)
    }
    
    private static var providerConfiguration: CXProviderConfiguration {
        let config = CXProviderConfiguration(localizedName: "ExampleCall")
        config.supportsVideo = false
        config.maximumCallsPerCallGroup = 1
        config.maximumCallGroups = 1
        config.supportedHandleTypes = [.generic]
        config.iconTemplateImageData = UIImage(named: "callkit_logo")?.pngData()
        config.ringtoneSound = "ring5.mp3"
        // config.includesCallsInRecents = false  // 시스템 통화기록 노출 여부
        return config
    }
}

extension CallController: CXProviderDelegate {
    
    func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
        // 서버에 수락을 알리고 RTC 연결을 준비한다.
        signaling.accept(callUUID: action.callUUID)
        prepareRtcChannelIfNeeded()
        action.fulfill()
    }
    
    // 시스템이 AVAudioSession 활성화 완료 → RTC 오디오 시작/재개
    func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
        resumeRtcAudio()
    }
    
    // 시스템이 세션 비활성화 → RTC 오디오 중지/일시 정지
    func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
        pauseRtcAudio()
    }
    
    // ⑥ 끊기
    func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
        rtcEngine.leaveChannel(nil)
        
        action.fulfill()
    }
}

[사용자가 앱 안에서 "전화걸기" 탭]
    ↓
① 내 앱 → CallKit: "발신 의도"
   - CXStartCallAction 생성 + CXCallController.request(transaction:)
    ↓
② CallKit → 내 앱: "OK, 발신 진행해"
   - CXProviderDelegate의 perform(CXStartCallAction) 콜백
    ↓
③ 그 안에서 실제 발신 작업
   - Agora 채널 조인
   - 백엔드에 알림 → 서버가 상대 디바이스에 VoIP 푸시 발송
   - reportOutgoingCall(with:startedConnectingAt:) ← "연결 시도 중"
    ↓
④ 상대 폰에서 VoIP 푸시 수신 → reportNewIncomingCall (수신측)
    ↓
⑤ 상대가 받기 누름 → 시그널링 채널로 "answered" 신호 도달
   - reportOutgoingCall(with:connectedAt:)        ← "연결 완료"
   - 여기서부터 CallKit이 통화 시간 카운트 시작
    ↓
⑥ 통화 진행
    ↓
⑦ 끊기 → CXEndCallAction

func startOutgoingCall(to calleeId: String) {
    let callUUID = UUID()
    let handle = CXHandle(type: .generic, value: calleeId)
    
    let startCallAction = CXStartCallAction(call: callUUID, handle: handle)
    startCallAction.isVideo = false
    
    let transaction = CXTransaction(action: startCallAction)
    callController.request(transaction) { error in
        if let error = error {
            print("발신 실패: \(error)")
        }
        // 성공해도 여기서는 할 일 없음 — 실제 처리는 델리게이트에서
    }
}

func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
    // CallKit이 발신을 승인. 이제 실제 발신 작업 수행.
    
    // 앱과 SDK가 합의한 AudioSession 정책 적용
    configureAudioSession()
    
    // Agora 채널 조인
    rtcEngine.joinChannel(byToken: token,
                          channelId: action.handle.value,
                          info: nil, uid: 0)
    
    // 백엔드에 "이 사람한테 통화 시작" 알림
    // → 서버가 상대 디바이스에 VoIP 푸시 발송
    backend.notifyCallStart(callee: action.handle.value,
                            callUUID: action.callUUID)
    
    // CallKit에 "연결 시도 중" 보고
    provider.reportOutgoingCall(with: action.callUUID,
                                startedConnectingAt: nil)
    
    action.fulfill()
}

func onCalleeAnswered(callUUID: UUID) {
    // 시그널링 채널(RTM/RTC 콜백 등)에서 "상대 응답" 알림 도착 시
    provider.reportOutgoingCall(with: callUUID, connectedAt: nil)
    // → CallKit이 통화 시간 카운트 시작
    // → 시스템 통화 화면이 "연결됨" 상태로 전환
}

// Agora Chat SDK가 토큰을 등록받음 (정확한 API)
[[AgoraChatClient sharedClient] bindDeviceToken:deviceToken];

// Swift:
AgoraChatClient.sharedClient().bindDeviceToken(deviceToken)

□ PKPushRegistry를 앱 시작 직후 등록
□ desiredPushTypes = Set([.voIP])
□ delegate = self (PKPushRegistryDelegate 채택)
□ didUpdate 콜백에서 토큰을 매번 서버에 upload (upsert)
□ didInvalidatePushTokenFor에서 서버 DB 정리

□ didReceiveIncomingPushWith 콜백 안에서 즉시 reportNewIncomingCall (iOS 13+ 필수)
□ payload.dictionaryPayload에서 caller_id / channel_id / call_uuid 파싱
□ completion() 반드시 호출
□ reportNewIncomingCall 실패 시에도 completion 호출

□ APNs provider 인증 방식 선택: `.p8` 토큰 또는 TLS 인증서
□ 자격 증명에 VoIP topic 권한이 있는지 확인
□ 서버: topic = "...app.voip" (.voip 접미사)
□ 서버: pushType 헤더 = "voip"
□ 인증서 방식이면 만료 알람, 토큰 방식이면 키 보관·JWT 갱신 정책 설정

□ CXProviderConfiguration의 supportsVideo / handleTypes 서비스에 맞게
□ CXAnswerCallAction에서 서버 수락·RTC 준비 후 fulfill/fail
□ didActivate에서 RTC 오디오 시작 또는 재개
□ CXEndCallAction에서 leaveChannel과 통화 상태 정리
□ 모든 CXAction 콜백에서 timeout 안에 fulfill
□ didDeactivate에서 RTC 오디오 일시 정지 또는 중지

□ 앱이 죽어있는 상태에서 VoIP 푸시 수신 시 정상 동작
□ 통화 중 다른 통화 들어왔을 때 동작 정의
□ 블루투스 헤드셋 / 스피커 / earpiece 라우팅 (#35 §Case 6 참고)
□ 시스템 알람 / 시스템 전화 인터럽션 처리 (#35 §Case 1, 2 참고)
□ 통화 종료 후 ADM 미복구 처리 (#35 §Case 5 참고)

┌─────────────────────────────────────────────────────────┐
│              Apple APNs (서버 인프라)                    │
│     ┌──────────────────┬──────────────────┐             │
│     │   일반 푸시 채널   │   VoIP 푸시 채널  │             │
│     │  (일반 topic)     │  (VoIP topic)    │             │
│     │  topic: bundleId  │ topic: ...voip   │             │
│     │  pushType: alert  │ pushType: voip   │             │
│     └────────┬─────────┴─────────┬────────┘             │
└──────────────┼───────────────────┼──────────────────────┘
               │                   │
               ▼                   ▼
        [APNs 토큰 발급]      [VoIP 토큰 발급]
               │                   │
       ┌───────┴───────┐   ┌───────┴───────┐
       ▼               ▼   ▼               ▼
   [발급 시]       [도착 시]    [발급 시]    [도착 시]
   AppDelegate가   iOS가 알림   PKPushRegistry  PKPushRegistry
   토큰 받음       자동 표시    가 토큰 받음    가 콜백 실행
                  (탭하면 앱)                  (즉시 앱 깸)
                                                   │
                                                   ▼
                                         CallKit reportNewIncomingCall
                                                   │
                                                   ▼
                                         사용자 "받기" → 액션 처리
                                                   │
                                                   ▼
                                         didActivate → RTC 오디오 시작