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 をします。
切断時のコードと理由の定義¶
新しい WebSocket 関連のコードと理由¶
WebSocket の Close Code と Reason で送られてきます。
この仕組みを利用するには sora.conf の websocket_signaling_close を true にする必要があります。
1000: 正常に切断された
reason:
""
1009: 送られてきたデータが大きすぎた
reason:
""
4000: 不正なメッセージ
reason:
INVALID-MESSAGE
4401: 認証失敗
reason: ウェブフックによる指定
4408: タイムアウト
reason:
TIMEOUT
4500: 内部エラー
reason:
INTERNAL-ERROR
4503: サービス利用不可
reason:
SERVICE-UNAVAILABLE
DataChannel 関連のコードと理由¶
1000: 正常に切断された
4999: クライアント側でのエラー
"type": "disconnect"を送ったが Sora から一定時間経過しても切断されなかったreason:
DISCONNECT-TIMEOUT-ERROR
"type": "disconnect"を送ったが DataChannel のonerrorが上がったreason:
DISCONNECT-DATA-CHANNEL-ERROR
新しい DataChannel 関連のコードと理由¶
異常終了時の切断前にラベル signaling に "type": "error" のエラーメッセージを送信してきます。
この "type": "error" 後に Sora は全ての DataChannel を閉じます。
この仕組みを利用するには sora.conf の data_channel_signaling_error_message を true にする必要があります。
正常終了時にはそのまま DataChannel を全てクローズします。
注釈
API による切断は正常な終了と判断します。
{
"type": "error",
"code": 4000,
"reason": "INVALID-MESSAGE"
}
4000: 不正なメッセージ
reason:
INVALID-MESSAGE
4401: 認証失敗
reason: ウェブフックによる指定
4408: タイムアウト
reason:
TIMEOUT
4500: 内部エラー
reason:
INTERNAL-ERROR
4503: サービス利用不可
reason:
SERVICE-UNAVAILABLE
4999: クライアント側でのエラー
DataChannel の
onerrorが上がったreason:
DATA-CHANNEL-ERROR
"type": "disconnect"を送ったが Sora から一定時間経過しても切断されなかったreason:
DISCONNECT-TIMEOUT-ERROR
"type": "disconnect"を送ったが DataChannel のonerrorが上がったreason:
DISCONNECT-DATA-CHANNEL-ERROR