1대1 음성 통화

1대1 음성 통화를 구현하는 예제 코드입니다.

필수 조건

시작하기 전에 다음 작업을 수행해야 합니다.

• PlanetKit을 초기화하세요.
• 적절한 액세스 토큰을 획득하세요.
• 1대1 통화 흐름에서 전반적인 API 사용 과정을 확인하세요.

1대1 음성 통화 구현 시 고려 사항

착신자 측에서 통화 알림을 받으려면 알림용 시스템을 구현하거나 APNs(Apple Push Notification service) 같은 외부 푸시 알림 시스템을 연동해야 합니다.

또한 착신자에게 어떤 정보를 전달해야 하는지도 알아야 합니다. 앱 서버의 역할에서 애플리케이션이 전달해야 하는 데이터인 cc_param에 관해 볼 수 있습니다.

makeCall() 또는 verifyCall()을 호출한 다음에는 반환된 PlanetKitCallMakeResult 또는 PlanetKitCallVerifyResult에서 reason을 확인해야 합니다.

• reason이 PlanetKitStartFailReason.none인 경우 성공을 의미합니다.
• 그렇지 않으면 실패를 의미하며 reason에 따라 적절한 조치를 취해야 합니다.

이벤트 대리자 구현

통화에서 사용될 이벤트 대리자(delegate)를 구현하세요.

• PlanetKitCallDelegate는 통화 셋업과 관련된 이벤트를 처리하는 데 사용됩니다.
• PlanetKitMyMediaStatusDelegate는 로컬 사용자의 미디어 상태 변경 이벤트를 처리하는 데 사용됩니다. 마이크가 음 소거되거나 음 소거 해제되는 경우 또는 오디오 설명이 업데이트되는 경우 등 이벤트를 기반으로 로컬 사용자의 UI를 업데이트할 수 있습니다.

extension CallDelegateExample : PlanetKitCallDelegate {
    func didWaitConnect(_ call: PlanetKitCall) {

        // This is called after making a call on the caller side.
        // Write your own code here.

    }

    func didVerify(_ call: PlanetKitCall, peerStartMessage: PlanetKitCallStartMessage?, peerUseResponderPreparation: Bool) {

        // This is called after verifying a call on the callee side.
        // Write your own code here.

    }

    func didConnect(_ call: PlanetKitCall, connected: PlanetKitCallConnectedParam) {

        // This is called after the call is connected on both sides.
        // Write your own code here.

    }

    func didDisconnect(_ call: PlanetKitCall, disconnected: PlanetKitDisconnectedParam) {

        // This is called after the call is disconnected on both sides.
        // Write your own code here.

    }

    func didFinishPreparation(_ call: PlanetKitCall) {

        // This is called after making a call on the caller side.
        // Write your own code here.

    }

    ...

    //
    // Also, you should implement other methods defined in the PlanetKitCallDelegate protocol.
    //
    ...
}

extension MyMediaStatusDelegateExample: PlanetKitMyMediaStatusDelegate {
    func didMuteMic(_ myMediaStatus: PlanetKitMyMediaStatus) {

        // This is called when the local user's audio is muted.
        // Write your own code here.

    }

    func didUnmuteMic(_ myMediaStatus: PlanetKitMyMediaStatus) {

        // This is called when the local user's audio is unmuted.
        // Write your own code here.

    }

    func didUpdateAudioDescription(_ myMediaStatus: PlanetKitMyMediaStatus, description: PlanetKitMyAudioDescription) {

        // This is called when the local user's audio description is updated.
        // Write your own code here.

    }
}

통화 생성(발신 측)

통화를 생성하기 위한 절차는 다음과 같습니다.

1. PlanetKitMakeCallSettingBuilder를 통해 설정 정보를 만드세요.
2. PlanetKitCallDelegate를 포함하여 PlanetKitCallParam을 생성하세요.
3. PlanetKitManager.shared.makeCall()를 호출하세요.
4. PlanetKitCallMakeResult를 확인하세요.

Note

PlanetKit 6.0부터 iOS 애플리케이션에서는 통화 설정을 생성할 때 PlanetKitCallKitSetting에 CallKit 유형을 반드시 지정해야 합니다. CallKit 유형 지정에 대한 자세한 내용은 애플리케이션에서 CallKit 유형 설정을 참조하세요.

class CallerExample
{
    var call: PlanetKitCall?
    var myMediaStatusDelegate: MyMediaStatusDelegateExample
}

...

extension CallerExample
{
    func makeCallExample(myId: String, myServiceId: String, peerId: String, peerServiceId: String, accessToken: String, delegate: PlanetKitCallDelegate) {
        let myUserId = PlanetKitUserId(id: myId, serviceId: myServiceId)
        let peerUserId = PlanetKitUserId(id: peerId, serviceId: peerServiceId)

        // Configure CallKitSetting
        let callKitSetting = createCallKitSetting()
        var settingsBuilder = PlanetKitMakeCallSettingBuilder().withCallKitSettingsKey(setting: callKitSetting)
        let settings = try! settingsBuilder.build()
        let param = PlanetKitCallParam(myUserId: myUserId, peerUserId: peerUserId, delegate: delegate, accessToken: accessToken)

        let result = PlanetKitManager.shared.makeCall(param: param, settings: settings)

        guard result.reason == .none else {
            NSLog("Failed reason: result. \(result.reason)")
            return
        }

        // The result.call instance is a call instance for calling other APIs from now on.
        // You must keep this instance in your own context.
        // In this example, the "call" variable holds the instance.
        call = result.call
    }
}

푸시 알림 수신(착신 측)

통화를 수신한 쪽은 푸시 알림 시스템을 통해 새로운 전화가 왔음을 알게 됩니다. 이때 userInfo로부터 cc_param을 파싱해야 합니다.

새로운 전화가 왔음을 알리는 푸시 알림을 받은 다음 사용자가 통화할 수 있도록 그 요청을 수신해야 합니다.

extension YourPushHandler : PKPushRegistryDelegate {

    ...

    var callee: CalleeExample
    var callDelegate: PlanetKitCallDelegate

    func pushRegistry(_ registry: PKPushRegistry, didUpdate pushCredentials: PKPushCredentials, for type: PKPushType) {
        // Update the push token for the application's push server.
    }

    func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {

        let message = payload.dictionaryPayload as NSDictionary as! [String: AnyObject]
        let param = message["cc_param"] as! String
        let ccParam = PlanetKitCCParam(ccParam: param)

        // Now we received a push notification.
        // We should write code here to respond to the new call.
        // For convenience, we assume this is done in verifyCallExample()

        let myUserId = "Callee User ID value"
        let myServiceId = "Callee Service ID value"

        callee.verifyCallExample(myId: myUserId, myServiceId: myServiceId, ccParam: ccParam, delegate: PlanetKitCallDelegate)
    }
}

통화 수신(착신 측)

이제 PlanetKitManager.shared.verifyCall()를 호출해서 통화를 수신해 봅시다.

아래 코드의 verifyCallExample()에서 통화를 수신하는 방법을 볼 수 있습니다. 이때, myId는 착신자의 사용자 ID이고, myServiceId는 착신자의 서비스 ID입니다.

Note

PlanetKit 6.0부터 iOS 애플리케이션에서는 통화 설정을 생성할 때 PlanetKitCallKitSetting에 CallKit 유형을 반드시 지정해야 합니다. CallKit 유형 지정에 대한 자세한 내용은 애플리케이션에서 CallKit 유형 설정을 참조하세요.

class CalleeExample
{
    var verifiedCall: PlanetKitCall?
    var myMediaStatusDelegate: MyMediaStatusDelegateExample
}

...

extension CalleeExample
{
    func verifyCallExample(myId: String, myServiceId: String, ccParam: PlanetKitCCParam, delegate: PlanetKitCallDelegate) {
        // Configure CallKitSetting
        let callKitSetting = createCallKitSetting()
        var settingsBuilder = PlanetKitVerifyCallSettingBuilder().withCallKitSettingsKey(setting: callKitSetting)
        let settings = try! settingsBuilder.build()

        let myUserId = PlanetKitUserId(id: myId, serviceId: myServiceId)

        let result = PlanetKitManager.shared.verifyCall(myUserId: myUserId, ccParam: ccParam, delegate: delegate)

        guard result.reason == .none else {
            NSLog("Failed reason: result. \(result.reason)")
            return
        }

        // The result.call instance is the verified call instance.
        // You have to keep this instance in an application layer to call other APIs provided after call setup.
        // This example keeps the verified call instance in the following verifiedCall variable.
        verifiedCall = result.call
    }
}

통화 응답(착신 측)

일반적으로 통화를 수신한 후 통화를 받을지 결정할 시간이 필요합니다. 통화에 응답하려면 acceptCall()을 호출하세요.

Tip

verifiedCall 변수는 verifyCall()에서 검증을 마친 PlanetKitCall 인스턴스입니다.

extension CalleeExample
{
    func acceptCallExample() {
        verifiedCall.acceptCall(startMessage: nil, useResponderPreparation: false)
    }
}

로컬 사용자에 대한 미디어 상태 이벤트 대리자 설정

통화가 연결되면 로컬 사용자에 대한 미디어 상태 이벤트 대리자를 설정하세요.

// Caller side
extension CallerExample
{
    func addMyMediaStatusHandlerExample() {
        call.myMediaStatus.addHandler(myMediaStatusDelegate) {
            // completion callback
        }
    }
}

// Callee side
extension CalleeExample
{
    func addMyMediaStatusHandlerExample() {
        verifiedCall.myMediaStatus.addHandler(myMediaStatusDelegate) {
            // completion callback
        }
    }
}

통화 종료

통화를 종료하려면 endCall()을 호출하세요.

// Caller side
extension CallerExample
{
    func endCallExample() {
        call.endCall()
    }
}

// Callee side
extension CalleeExample
{
    func endCallExample() {
        verifiedCall.endCall()
    }
}

애플리케이션에서 CallKit 유형 설정

CallKit은 통화 인터페이스를 제공하는 Apple의 프레임워크입니다. PlanetKit SDK는 CallKit 연동을 위해 아래 세 가지 옵션을 지원합니다.

1. 사용자 정의 CallKit 구현
2. PlanetKit 내부 CallKit 구현
3. CallKit 연동하지 않음

PlanetKit SDK를 사용하여 통화를 생성하거나 수신할 때, PlanetKitCallKitSetting에 CallKit 유형을 지정해야 합니다.

PlanetKitCallKitType이 user 또는 planetkit으로 설정된 경우, PlanetKit은 마이크 표시기의 제어를 CallKit에 위임한다는 점을 유의하시기 바랍니다.

PlanetKitCallKitType 설정 예제

func createCallKitSetting() -> PlanetKitCallKitSetting  {
    // Select the appropriate CallKit integration option from the examples below
    // when integrating the user CallKit implementation.
    let callKitSetting = PlanetKitCallKitSetting(type: .user, param: nil)

    // when using PlanetKit internal CallKit implementation.
    let callkitParam = PlanetKitCallKitParam(appName: "Example app", callerName: "caller name", isVideo: true, ringtoneSound: nil, icon: "example icon", addCallToList: true, supportsHolding: true)
    let callKitSetting = PlanetKitCallKitSetting(type: .planetkit, param: callkitParam)

    // when CallKit is not used in the app.
    let callKitSetting = PlanetKitCallKitSetting(type: .none, param: nil)

    return callKitSetting
}

애플리케이션에서 Apple CallKit 구현

다음 예제는 사용자 정의 CallKit 구현을 PlanetKit에 연동하는 방법에 대한 가이드입니다.

사용자 정의 CallKit 구현을 연동할 때, CallKit과 PlanetKit 간에 음 소거 상태와 같은 통화 상태를 동기화하는 것이 중요합니다.

발신 측 구현 예제

1. PlanetKitCallKitSetting 인스턴스를 생성하고 PlanetKitCallKitSetting의 type을 user로 설정하세요.

2. PlanetKitMakeCallSettingBuilder의 withCallKitSettingsKey()에 인스턴스를 전달하고 통화 생성 설정(makeCallSettings)을 만드세요.

   // Code for Step 1 and Step 2
   
   func createMakeCallSettingsWithUserCallKitExample() -> [String: Any]  {
       let callKitSetting = PlanetKitCallKitSetting(type: .user, param: nil)
   
       var settingsBuilder = PlanetKitMakeCallSettingBuilder().withCallKitSettingsKey(setting: callKitSetting)
   
       let makeCallSettings = try! settingsBuilder.build()
   
       return makeCallSettings
   }

착신 측 구현 예제

1. PlanetKitCallKitSetting 인스턴스를 생성하고 PlanetKitCallKitSetting의 type을 user로 설정하세요.

2. PlanetKitVerifyCallSettingBuilder의 withCallKitSettingsKey()에 인스턴스를 전달하고 통화 수신 설정(verifyCallSettings)을 만드세요.

   // Code for Step 1 and Step 2
   
   func createVerifyCallSettingsWithUserCallKitExample() -> [String: Any]  {
       let callKitSetting = PlanetKitCallKitSetting(type: .user, param: nil)
   
       var settingsBuilder = PlanetKitVerifyCallSettingBuilder().withCallKitSettingsKey(setting: callKitSetting)
   
       let verifyCallSettings = try! settingsBuilder.build()
   
       return verifyCallSettings
   }

발신 측/수신 측 공통 구현 예제

1. CallKit 동작을 처리하기 위한 CallKit 핸들러를 구현하세요. call 변수는 통화를 생성하거나 수신할 때 얻은 PlanetKitCall 인스턴스입니다.

   class YourCallKitHandler {
       static let shared = YourCallKitHandler()
   
       private var provider: CXProvider
       private var callController: CXCallController
       private var call: PlanetKitCall
       ...
       // Implement initialization and other features to handle CallKit operations.
   }

2. CXProviderDelegate의 provider(_:didActivate:)에서 PlanetKitCall의 notifyCallKitAudioActivation()을 호출하세요.

   extension YourCallKitHandler : CXProviderDelegate {
   
       ...
   
       func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
           call.notifyCallKitAudioActivation()
       }
   
       // Implement other delegate functions to handle other CXCallActions
       ...
   }

3. CallKit으로 CXCallAction이 수행될 때 관련 PlanetKitCall 함수를 호출하세요.

   extension YourCallKitHandler : CXProviderDelegate {
   
       ...
   
       func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
           call.acceptCall(useResponderPreparation: false, startMessage: nil)
           action.fulfill()
       }
   
       func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
           call.endCall()
           action.fulfill()
       }
   
       func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
           call.muteMyAudio(action.isMuted) { success in
               guard success else {
                   action.fail()
                   return
               }
               action.fulfill()
           }
       }
   
       func provider(_ provider: CXProvider, perform action: CXSetHeldCallAction) {
           if action.isOnHold {
               call.hold(reason: nil) { success in
                   guard success else {
                       action.fail()
                       return
                   }
                   action.fulfill()
               }
           }
           else {
               call.unhold() { success in
                   guard success else {
                       action.fail()
                       return
                   }
                   action.fulfill()
               }
           }
       }
       // Implement other delegate functions to handle other CXCallActions
       ...
   }

4. CallKit과 PlanetKit을 동기화하기 위해 CallKit을 통해 관련 CXCallAction을 요청하세요.

   extension YourCallViewController {
       @IBAction func muteCall(_ sender: UIButton) {
           call.muteMyAudio() { success in
               if success {
                   YourCallKitHandler.shared.muteCall()
               }
           }
       }
       @IBAction func holdCall(_sender: UIButton) {
           call.hold(reason: nil) { success in
               if success {
                   YourCallKitHandler.shared.holdCall()
               }
           }
       }
   }
   
   extension YourCallKitHandler {
       func muteCall() {
           let action = CXSetMutedCallAction(call: call.uuid , muted: true)
           callController.requestTransaction(with: action) { error in
               NSLog("\(error)")
           }
       }
   
       func holdCall() {
           let action = CXSetHeldCallAction(call: call.uuid, onHold: true)
           callController.requestTransaction(with: action) { error in
               NSLog("\(error)")
           }
       }
   }

상세한 정보는 CallKit 문서를 참고하세요.

관련 예제 코드

• PlanetKit 초기화 및 로그 설정
• 1대1 영상 통화

관련 문서

• 액세스 토큰
• 1대1 통화 흐름
• 앱 서버의 역할