VoIP 푸시 인프라 완전 가이드 — APNs · PushKit · CallKit · Agora 통합 구현

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

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

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

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

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

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

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

ChatMoa 앱:
├─ 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 인증서로 서명

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

파일명: 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 파일 받음

func registerPushKit() {
    let pushRegistry = PKPushRegistry(queue: .main)
    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 콜백으로 같은 값 전달

토큰이 바뀌는 트리거:
  - 앱 삭제 후 재설치
  - iOS 메이저 업데이트
  - 백업 복원
  - 키체인 변경

func pushRegistry(_ registry: PKPushRegistry, didUpdate ..., for type: PKPushType) {
    // 매번 호출됨. 같은 토큰이어도 무조건 서버에 업로드 → 서버는 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": "앨리스",
  "channel_id": "room_xyz",
  "agora_token": "006a1b2c...",
  "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 channelId   = dict["channel_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: "Talkito")
        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) {
        // ① CallKit 컨텍스트에서 SDK가 AVAudioSession 못 건드리게 잠금
        rtcEngine.setAudioSessionOperationRestriction(.all)
        
        // ② Agora SDK는 채널 정보만 보관 — 실제 join은 didActivate에서
        pendingChannelId = action.callUUID.uuidString
        
        // ③ 즉시 fulfill — CallKit은 액션이 빨리 끝나길 기대 (timeout 있음)
        action.fulfill()
    }
    
    // ④ 시스템이 AVAudioSession 활성화 완료 → 여기서 채널 조인
    func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
        rtcEngine.joinChannel(byToken: token, channelId: channel, info: nil, uid: 0)
    }
    
    // ⑤ 시스템이 세션 비활성화 → ADM 강제 재시작 준비
    func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
        rtcEngine.disableAudio()
        rtcEngine.enableAudio()
    }
    
    // ⑥ 끊기
    func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
        rtcEngine.leaveChannel(nil)
        
        // ⑦ SDK 권한 복구 — 이후 일반(non-CallKit) 채널 조인 시를 위해
        rtcEngine.setAudioSessionOperationRestriction([])
        
        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 설정
    rtcEngine.setAudioSessionOperationRestriction(.all)
    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 인증서 (.p8 권장)
□ VoIP Services 인증서 (별도 발급)
□ 서버: topic = "...app.voip" (.voip 접미사)
□ 서버: pushType 헤더 = "voip"
□ 서버: VoIP Services 인증서로 서명
□ 만료 알람 설정 (1년)

□ CXProviderConfiguration의 supportsVideo / handleTypes 서비스에 맞게
□ CXAnswerCallAction에서 setAudioSessionOperationRestriction(.all) → fulfill만
□ didActivate에서 joinChannel
□ CXEndCallAction에서 leaveChannel → setAudioSessionOperationRestriction([])
□ 모든 CXAction 콜백에서 timeout 안에 fulfill
□ didDeactivate에서 disableAudio() → enableAudio() (다음 통화 대비)

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

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