Sora クライアント要求仕様¶
概要¶
Sora SDK や Sora クライアントの開発者に向けた資料です。
クライアント側の終了処理条件¶
RTCPeerConnectionState が failed になる¶
すべての接続において RTCPeerConnectionState が failed になったタイミングで "type": "disconnect" は送らず、
クライアント側で終了処理をしてください。
WebSocket のみ¶
RTCPeerConnectionState が failed になった
終了処理に入る
WebSocket onclose が上がった
終了処理に入る
WebSocket onerror が上がった
終了処理に入る
WebSocket と DataChannel¶
RTCPeerConnectionState が failed になった
終了処理に入る
WebSocket onclose が上がった
"type": "switched"が送られてきていない終了処理に入る
"type": "switched", "ignore_disconnect_websocket": trueが送られてきていた何もしない
"type": "switched", "ignore_disconnect_websocket": falseが送られてきていて、 RTCPeerConnectionState が failed になっている終了処理に入る
"type": "switched", "ignore_disconnect_websocket": falseが送られてきていて、 RTCPeerConnectionState が failed になっていないDataChanel で
"type": "disconnect", reason: "WEBSOCKET-ONCLOSE"を送ることを試みる終了処理に入る
WebSocket onerror が上がった
"type": "switched"が送られてきていない終了処理に入る
"type": "switched", "ignore_disconnect_websocket": trueが送られてきていた何もしない
"type": "switched", "ignore_disconnect_websocket": falseが送られてきていて、 RTCPeerConnectionState が failed になっている終了処理に入る
"type": "switched", "ignore_disconnect_websocket": falseが送られてきていて、 RTCPeerConnectionState が failed になっていないDataChanel で
"type": "disconnect", reason: "WEBSOCKET-ONERROR"を送ることを試みる終了処理に入る
DataChannel のみ¶
RTCPeerConnectionState が failed になった
終了処理に入る
DataChannel の終了¶
Sora SDK の切断タイムアウトのデフォルト値は 3000 ミリ秒です。
RTCDataChannel onclose が上がった
RTCDataChannel onerror にコールバックをセットしている場合
終了処理に入る、または切断タイマーを開始し、すべての RTCDataChannel の readyState がすべて closed にならずタイムアウトした場合は終了処理にはいる
RTCDataChannel onerror にコールバックをセットしていない場合
終了処理に入る
RTCDataChannel onerror が上がった
終了処理に入る
アプリケーション経由の "type": "disconnect" 送信後の終了処理¶
Sora SDK の切断タイムアウトのデフォルト値は 3000 ミリ秒です。
WebSocket のみ¶
data_channel_signaling: false の場合。
WebSocket 経由で
"type": "disconnect", reason: "NO-ERROR"を送る終了処理に入る、または切断タイマーを開始し、WebSocket onclose が上がらずタイムアウトした場合は終了処理に入る
WebSocket と DataChannel¶
data_channel_signaling: true で ignore_disconnect_websocket: false の場合。
"type": "switched"が送られて来ていないWebSocket 経由で
"type": "disconnect", reason: "NO-ERROR"を送る終了処理にはいる、または切断タイマーを開始し、WebSocket onclose が上がらずタイムアウトした場合は終了処理にはいる
"type": "switched", "ignore_disconnect_websocket": falseが送られてきていて、 WebSocket は切断していないDataChannel 経由で
"type": "disconnect", reason: "NO-ERROR"を送るRTCDataChannel onerror にコールバックをセットしている場合
終了処理に入る、または切断タイマーを開始し、WebSocket の onclose かつ、すべての RTCDataChannel の readyState がすべて closed にならずタイムアウトした場合は終了処理にはいる
RTCDataChannel onerror にコールバックをセットしていない場合
終了処理に入る
DataChannel のみ¶
data_channel_signaling: true で ignore_disconnect_websocket: true の場合。
"type": "switched"が送られて来ていないWebSocket 経由で
"type": "disconnect", reason: "NO-ERROR"を送る切断タイマーを開始する
WebSocket onclose が上がらずタイムアウトした場合は終了処理に入る
"type": "switched", "ignore_disconnect_websocket": trueが送られてきていて、 WebSocket も切断しているDataChannel 経由で
"type": "disconnect", reason: "NO-ERROR"を送るRTCDataChannel onerror にコールバックをセットしている場合
終了処理に入る、または切断タイマーを開始し、すべての RTCDataChannel の readyState がすべて closed にならずタイムアウトした場合は終了処理にはいる
RTCDataChannel onerror にコールバックをセットしていない場合
終了処理に入る
異常発生による終了¶
シグナリングの異常¶
終了処理に入ってください。
シグナリング以外の異常¶
"type": "disconnect", reason: "INTERNAL-ERROR" を送り、終了処理に入って下さい。
ライセンスエラーによる終了¶
"type": "connect" を送った際、ライセンスの期限が過ぎていたり、最大同時接続数を超えた場合、
Sora はエラーメッセージ EXCEED-MAX-CONNECTIONS を送信し、 WebSocket を切断し終了します。
RTCPeerConnectionState が定義されていない場合¶
注釈
ブラウザでは Firefox が RTCPeerConnectionState が定義されていません
RTCDtlsTransprot が実装されていない場合 RTCPeerConnectionState が正常に動作しないため、 RTCIceConnectionState を利用してください。
RTCIceConnectionState が disconnect になった場合、切断タイマーを開始し、 タイムアウトした場合 disconnect から変化がなければ切断してください。
Sora SDK の RTCIceConnectionState 用の切断タイマーはデフォルトで 10 秒です。
クライアントの状態¶
認証失敗¶
接続を試みて、認証ウェブフックが接続を許可しなかった状態です。
Sora は認証失敗理由を WebSocket で送信後に、WebSocket を切断します。
認証成功¶
接続を試みて、認証ウェブフックが接続を許可した状態です。
この時点ではまだ WebRTC での接続に成功していません。そのため、同時接続数としてもカウントされません 認証は成功しているが、WebRTC での接続に失敗するということがありえるためです。
セッション参加¶
認証が許可されると、そのチャネル ID のセッションが存在していれば セッションへの参加 が行われます。 もしセッションが存在していなければ セッションの生成 が行われます。
この時点ではまだ WebRTC での接続に成功していません。そのため、同時接続数としてもカウントされません 認証は成功しているが、WebRTC での接続に失敗するということがありえるためです。
認証が成功したタイミングで、 Sora はクライアントをセッションに参加させます。
この後、クライアントは Sora からの "type": "offer" を受け取り、WebRTC の確立を試みます。
セッション離脱¶
セッションからの離脱は、コネクションが破棄された後に発生します。
セッションが API で破棄されたり、セッションのライフタイムが終了した場合、 そのセッションに参加しているクライアントのコネクションを破棄し、セッションから離脱します。
コネクション生成¶
認証が成功し、セッションへ参加後、WebRTC のコネクションが確立された状態です。
つまり connection.created ウェブフックが送信されたタイミングになります。
このタイミングで Sora は初めて同時接続数に +1 をします。
コネクション破棄¶
何かしらの理由で、WebRTC のコネクションが破棄された状態です。
このタイミングで Sora は同時接続数から -1 をします。
クライアントからの "type": "disconnect" による切断¶
WebSocket シグナリングを利用している場合は、 WebSocket の Close フレームの Reason に "TYPE-DISCONNECT" が入るようになりました。
DataChannel シグナリングのみを利用している場合は、 DataChannel を閉じて終了します。
WebSocket シグナリング利用時に Sora から正常切断¶
切断系 API やライフタイム期限などのSora からの正常切断時に、 WebSocket シグナリングを利用している場合、 WebSocket Close フレームの Code に 1000 、 Reason に切断理由が入ります。
正常な場合の切断理由は以下の 3 つです。
LIFETIME-EXPIREDライフタイムによるコネクションの破棄
SESSION-DESTROYEDAPI やライフタイムなどによるセッションの破棄
DISCONNECTED-APIAPI によるコネクションの破棄
DataChannel シグナリングのみ利用時に Sora から切断が発生した際の "type": "close" メッセージの送信¶
DataChannel シグナリングのみ利用時に Sora から切断が発生した際、
DataChannel を閉じる前に "type": "close" メッセージを送信します。
sora.conf の data_channel_signaling_close_message を true に設定することで有効になります。
デフォルトは false です。
DataChannel が閉じられたのが正常な処理なのか、それとも何か問題が発生したのかを明確にするための仕組みです。
正常な場合の切断理由は以下の 3 つです。
LIFETIME-EXPIREDライフタイムによるコネクションの破棄
SESSION-DESTROYEDAPI やライフタイムなどによるセッションの破棄
DISCONNECTED-APIAPI によるコネクションの破棄