コールバック¶

Sora iOS SDK には WebRTC API イベントや Sora 固有の機能のイベントをハンドリングするためのコールバックを MediaChannelHandlers で提供しています。

ここではそのコールバックの利用方法について説明します。

onConnect¶

Sora との接続時に呼ばれるコールバックです。

error が nil ではない場合は接続に失敗しています。

let config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

config.mediaChannelHandlers.onConnect = { [weak self] error in
    guard let self = self else { return }

    // error が nil でない場合は接続に失敗しているのでエラーハンドリングを行ってください
    if let error = error {
        // エラー処理
    }

}

onDisconnect¶

Sora との接続を解除したときに呼ばれるコールバックです。

event は SoraCloseEvent という enum で、以下の 2 つのケースがあります。

ok: Sora から正常に切断された場合
error: Sora との接続に異常が発生した結果切断された場合

ok の例

クライアントから切断した場合
Sora の API を利用して切断された場合
認証エラーで Sora から切断された場合

error の例

接続中にネットワークエラーが起こった場合
WebSocket 切断時に異常が起こった場合

let config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

config.mediaChannelHandlers.onDisconnect = { [weak self] event in
    guard let self = self else { return }
    switch event {
    case .ok(let code, let reason):
        // 正常に切断された場合の処理
        print("切断コード: \(code)")
        print("切断理由: \(reason)")
    case .error(let error):
        // エラー内容を表示
        print("エラー内容: \(error.localizedDescription)")
    }
}

SoraCloseEvent の定義は以下のようになっています。

enum SoraCloseEvent {
    // 正常系
    case ok(code: Int, reason: String)
    // 異常系
    case error(Error)
}

onAddStream¶

ストリームが追加されたときに呼ばれるコールバックです。

自分自身のストリームも入ってくるため、Configuration.publisherStreamId を控えておくことでリモートのストリームを判別することができます。

let config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

let publisherStreamId = config.publisherStreamId

config.mediaChannelHandlers.onAddStream = { [weak self] stream in
    guard let self = self else { return }

    // 例: リモートストリームの videoRenderer に receiverVideoView をセットする
    if stream.streamId != publisherStreamId {
        stream.videoRenderer = self.receiverVideoView
    }
}

onRemoveStream¶

ストリームが削除されたときに呼ばれるコールバックです。

let config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

let publisherStreamId = config.publisherStreamId

config.mediaChannelHandlers.onRemoveStream = { [weak self] stream in
    guard let self = self else { return }

    // 例: リモートストリーム用の videoRenderer をクリアする
    if stream.streamId != publisherStreamId {
        self.receiverVideoView.stop()
        self.receiverVideoView.clear()
    }
}

onReceiveSignaling¶

Sora からシグナリングメッセージを受信したときに呼ばれるコールバックです。

Sora から受信する type: notify メッセージなどをアプリケーションで利用したい場合にこのコールバックを利用します。

  let config = Configuration(url: url,
                             channelId: channelId,
                             role: .sendrecv)

  mediaChannel.handlers.onReceiveSignaling = { signaling in
      switch signaling {

      // type: notify
      case .notify(let notify):
          switch notify.eventType {
          case "connection.created":
              // メタデータに含まれる JSON 値 (Any) を任意の型にキャストする
              if let metadata = notify.metadata as? [String: Any] {
                  print("metadata => \(metadata)")
              }
              if let authnMetadata = notify.authnMetadata as? [String: Any] {
                  print("authn => \(authnMetadata)")
              }
              if let authzMetadata = notify.authzMetadata as? [String: Any] {
                  print("authz => \(authzMetadata)")
              }
              ...

          // 他のイベント種別でも同様に処理する
          case "connection.created":
              ...

          default:
              ...
          }

      // type: push
      case .push(let push):
          if let data = push.data as? [String: Any] {
              print("data => \(data)")
          }
          ...

      default:
          ...
      }
}

onDataChannel¶

DataChannel シグナリングに切り替わったタイミングで呼ばれるコールバックです。

let config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

config.mediaChannelHandlers.onDataChannel = { [weak self] mediaChannel in
    // ここに DataChannel が利用可能になった際の処理を書いてください
}

onDataChannelMessage¶

DataChannel のメッセージ受信時に呼ばれるコールバックです。

詳しい使い方はリアルタイムメッセージング機能を参照してください。