グループビデオ通話

グループビデオ通話を実装するサンプルコードです。

前提条件

開始する前に、次の作業が必要です。

• PlanetKitを初期化してください。
• 適切なアクセストークンを取得してください。
• グループ通話フローにて、APIを使用するための全般的なプロセスを確認してください。

グループビデオ通話実装時の考慮事項

joinConference()を呼び出した後、返却されたPlanetKitConferenceJoinResultのreasonプロパティを確認する必要があります。

• reasonがPlanetKitStartFailReason.noneの場合、成功を意味します。
• それ以外は失敗を意味し、reasonに応じて適切に処理する必要があります。

イベントデリゲートの実装

通話で使用されるイベントデリゲート（delegate）を実装します。

• PlanetKitConferenceDelegateは、グループ通話のステータス変更イベントを処理するのに使用されます。
• PlanetKitMyMediaStatusDelegateは、ローカルユーザーのメディアステータス変更イベントを処理するのに使用されます。マイクがミュートもしくはミュート解除された場合やオーディオの説明がアップデートされた場合、またはビデオのステータスがアップデートされた場合など、イベントに基づいてローカルユーザーのUIをアップデートできます。

extension ConferenceDelegateExample : PlanetKitConferenceDelegate {
    func didConnect(_ conference: PlanetKitConference, connected: PlanetKitConferenceConnectedParam) {

        // This is called when the call is connected.
        // Write your own code here.

    }

    func didDisconnect(_ conference: PlanetKitConference, disconnected: PlanetKitDisconnectedParam) {

        // This is called when the call is disconnected.
        // Write your own code here.

    }

    func peerListDidUpdate(_ conference: PlanetKitConference, updated: PlanetKitConferencePeerListUpdateParam) {

        // This is called when the list of peers is updated.
        // Write your own code here.

    }


    func peersVideoDidUpdate(_ conference: PlanetKitConference, updated: PlanetKitConferenceVideoUpdateParam) {

        // This is called when the video of one or more peers is updated.
        // Write your own code here.

    }

    //
    // Also, you should implement other methods defined in the PlanetKitConferenceDelegate 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.

    }


    func didUpdateVideoStatus(_ myMediaStatus: PlanetKitMyMediaStatus, status: PlanetKitVideoStatus) {

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

    }

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

ローカルユーザーのビデオプレビュー

プレビュー機能を使用すると、ローカルユーザーがグループ通話セッションに関係なく、自分のビデオをプレビューできます。

ローカルユーザーのビデオプレビューを開始するには、PlanetKitCameraManagerのをstartPreview()呼び出します。

func startPreviewExample(delegate: PlanetKitVideoOutputDelegate)
{
    PlanetKitCameraManager.shared.startPreview(delegate)
}

ローカルユーザーのビデオプレビューを中止するには、PlanetKitCameraManagerのをstopPreview()呼び出します。

func stopPreviewExample(delegate: PlanetKitVideoOutputDelegate)
{
    PlanetKitCameraManager.shared.stopPreview(delegate)
}

通話に参加

グループ通話に参加するための手順は次のとおりです。

1. PlanetKitJoinConferenceSettingBuilderを通じて設定情報を作成します。
2. PlanetKitConferenceDelegateを含めてPlanetKitConferenceParamを作成し、mediaTypeプロパティを.audiovideoに設定します。
3. PlanetKitManager.shared.joinConference()を呼び出します。
4. PlanetKitConferenceJoinResultを確認してください。

ローカルユーザーのビデオの初期状態は、PlanetKitConferenceParamのinitialMyVideoStateプロパティに設定できます。

• initialMyVideoStateプロパティのデフォルト値は、PlanetKitInitialMyVideoState.resumeです。
• initialMyVideoStateプロパティをPlanetKitInitialMyVideoState.pauseに設定してローカルユーザーのビデオの初期状態が一時停止に設定された場合、ローカルユーザーのビデオは送信されません。この場合、ローカルユーザーのビデオは通話が接続された後、resumeMyVideo()を呼び出して送信できます。

Note

PlanetKit 6.0からiOSアプリケーションでは、通話設定を作成する時にPlanetKitCallKitSettingにCallKitタイプを必ず指定する必要があるため、グループ通話に参加するためのコードがiOSとmacOSの間で異なります。CallKitタイプの指定に関する詳細は、アプリケーションでCallKitタイプ設定を参照してください。

class ParticipantExample
{
    var conference: PlanetKitConference?
    var myMediaStatusDelegate: MyMediaStatusDelegateExample
}

...

extension ParticipantExample
{
    func joinConferenceExample(myId: String, myServiceId: String, roomId: String, roomServiceId: String, accessToken: String, delegate: PlanetKitConferenceDelegate, initialMyVideoState: PlanetKitInitialMyVideoState) {
        let myUserId = PlanetKitUserId(id: myId, serviceId: myServiceId)

        // Configure CallKitSetting
        let callKitSetting = createCallKitSetting()
        var settingsBuilder = PlanetKitJoinConferenceSettingBuilder().withCallKitSettingsKey(setting: callKitSetting)
        let settings = try! settingsBuilder.build()
        let param = PlanetKitConferenceParam(myUserId: myUserId, roomId: roomId, roomServiceId: roomServiceId, displayName: nil, delegate: delegate, accessToken: accessToken)
        param.mediaType = .audiovideo
        param.initialMyVideoState = initialMyVideoState

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

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

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

ローカルユーザーに対するメディアステータスのイベントデリゲート設定

通話が接続されると、ローカルユーザーに対するメディアステータスのイベントデリゲートを設定します。

extension ParticipantExample
{
    func addMyMediaStatusHandlerExample() {
        conference.myMediaStatus.addHandler(myMediaStatusDelegate) {
            // completion callback
        }
    }
}

ローカルユーザーのためのビデオビュー追加

ローカルユーザーのためのビデオビューを追加するには、PlanetKitMTKViewインスタンス（myVideoView）を作成し、ローカルビューにサブビューとして追加した後、PlanetKitVideoStreamのaddReceiver()でローカルユーザーのビデオストリームを受信するように設定します。

ビデオのレンダリングは、ローカルユーザーのビデオ状態によって、開始または中止されます。

#if os(macOS)
typealias UIView = NSView
#endif

extension YourConferenceViewController {

    @IBOutlet weak var localView: UIView!

    var conference: PlanetKitConference!

    ...

    func addMyVideoViewExample()
    {
        let myVideoView = PlanetKitMTKView(frame: localView.bounds, device: nil)
        localView.addSubview(myVideoView)

        conference.myVideoStream.addReceiver(myVideoView)
    }
}

ピアのためのビデオビュー追加

ピアのためのビデオビューを追加するには、PlanetKitMTKViewインスタンス（peerVideoView）を作成し、ピアビューにサブビューとして追加します。

#if os(macOS)
typealias UIView = NSView
#endif

class YourPeerView: UIView {

    @IBOutlet weak var peerView: UIView!

    var peerVideoView: PlanetKitMTKView!

    ...

    override public func awakeFromNib() {
        super.awakeFromNib()

        peerVideoView = PlanetKitMTKView(frame: peerView.bounds, device: nil)
        peerVideoView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        peerView.addSubview(peerVideoView)
    }
}

各ピアに対するピアコントロールの作成

ピアリストが更新されたら、新たに追加されたピアに対してPlanetKitPeerControlを作成し、PlanetKitPeerControlDelegateオブジェクトを登録してください。PlanetKitPeerControlDelegateを使用して各ピアのステータス変更を処理できます。

#if os(macOS)
typealias UIView = NSView
#endif

class YourPeerView: UIView {

    ...

    var peerControl: PlanetKitPeerControl?
    var peerVideoView: PlanetKitMTKView!

    ...

    func setupPeerControl(for peer: PlanetKitConferencePeer, in conference: PlanetKitConference) {
        guard let peerControl = conference.createPeerControl(peer: peer) else {
            return
        }

        peerControl.register(self) { success in
            // Write your own code here.
        }
        self.peerControl = peerControl
    }

    func setVideoEnabled(_ enable: Bool) {
        if enable {
            peerControl.startVideo(maxResolution: .recommended, delegate: peerVideoView) { success in
                // Write your own code here.
            }
        }
        else {
            peerControl.stopVideo() { success in
                // Write your own code here.
            }
        }
    }
}

extension YourPeerView: PlanetKitPeerControlDelegate {

    func didMuteMic(_ peerControl: PlanetKitPeerControl) {

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

    }

    func didUnmuteMic(_ peerControl: PlanetKitPeerControl) {

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

    }

    func didUpdateVideo(_ peerControl: PlanetKitPeerControl, subgroup: PlanetKitSubgroup, status: PlanetKitVideoStatus) {
        DispatchQueue.main.async {
            self.setVideoEnabled(status.isEnabled)

            // This is called when the local user's video status is changed.
            // Write your own code here.
        }
    }

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

グループ通話退出

グループ通話から退出するには、leaveConference()を呼び出します。

extension ParticipantExample
{
    func leaveConferenceExample() {
        conference?.leaveConference()
    }
}

アプリケーションでCallKitタイプ設定

CallKitは、通話インスタンスを提供するAppleのフレームワークです。PlanetKit SDKはCallKit連動のために以下3つのオプションを提供します。

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. PlanetKitJoinConferenceSettingBuilderのwithCallKitSettingsKey()にインスタンスを引き渡し、設定情報を作成してください。

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

3. CallKit動作を処理するためのCallKitハンドラーを実装します。conference変数はグループ通話に参加する時に取得したPlanetKitConferenceインスタンスです。

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

4. CXProviderDelegateのprovider(_:didActivate:)でPlanetKitConferenceのnotifyCallKitAudioActivation()を呼び出します。

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

5. CallKitでCXCallActionが実行される時に関連PlanetKitConference関数を呼び出します。

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

6. CallKitとPlanetKitを同期化するためにCallKitを通じて関連CXCallActionを呼び出します。

   extension YourCallViewController {
       @IBAction func muteCall(_ sender: UIButton) {
           conference.muteMyAudio() { success in
               if success {
                   YourCallKitHandler.shared.muteCall()
               }
           }
       }
       @IBAction func holdCall(_sender: UIButton) {
           conference.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の初期化およびログ設定
• グループ音声通話

関連ドキュメント

• アクセストークン
• グループ通話フロー