メッセージング機能¶
概要¶
ここでは DataChannel を利用したメッセージング機能について説明します。
DataChannel は、WebRTC の機能の一つでデータの送受信を行える機能です。
注意¶
メッセージング機能を利用するためには、
data_channel_signalingが有効になっている必要がありますメッセージング機能は DataChannel プロトコル互換性を維持しつつ Sora 独自の仕組みを追加しています
制限¶
メッセージサイズ制限¶
注意
1 回のメッセージで送れる値には制限がありますのでご注意ください。
詳しくは DataChannel シグナリングの 推奨メッセージサイズ をご確認ください
SDK 対応状況¶
最新版の JavaScript SDK
対応済みです
最新版の iOS SDK
対応済みです
最新版の Android SDK
対応済みです
最新版の Unity SDK
対応済みです
最新版の C++ SDK
対応済みです
最新版の Python SDK
対応済みです
最新版の C SDK
対応済みです
DataChannel を利用したメッセージング機能を有効にする¶
DataChannel を利用したメッセージングを利用する場合、 DataChannel シグナリングが有効になっている必要があります。
その上で sora.conf にて data_channel_messaging を true に指定してください。
利用する場合は "type": "connect" 時に data_channels を指定してください。
メッセージング用 DataChannel の作成¶
重要
DataChannel を利用したメッセージングを利用する場合は、DataChannel シグナリングが有効になっている必要があります
Sora では、Sora がシグナリングで使用する DataChannel 以外にも、メッセージング用の DataChannel を作成できます。
利用する場合は "type": "connect" 時に定義するか、認証成功時の払い出しで定義する必要があります。
Sora のメッセージング用 DataChannel は、DataChannel の属性である label を定義する際に # から始める必要があります。
data_channels 仕様¶
警告
現時点では誰から送られたメッセージかを判断する仕組みはありません。
重要
メッセージは 送信者以外 の同一 label 、かつ、 direction が sendrecv
または recvonly のクライアントに送信されます。
label¶
メッセージのラベルを指定します。先頭に # が付いている必要があります。
labelは#を含めて 32 文字まで指定できますlabelには小文字大文字のアルファベットと-(ハイフン) しか利用できません#の次の文字に-は指定できません^#[a-zA-Z0-9][a-zA-Z0-9-]{1,30}$
1 接続においてラベルは最大で 1024 まで指定できます
compress¶
メッセージを zlib にて圧縮するかどうかを指定します。
compressがtrueの場合、圧縮/展開にzlib.deflateを利用します圧縮方式を変更することはできません
direction¶
メッセージの方向を指定します。
directionにはsendrecv/sendonly/recvonlyが設定できますsendrecv時に 自分が送ったメッセージ は自分には送られてきません
クライアントからみた方向になります。
sendrecvが設定されたラベルは送受信で利用できますsendonlyが設定されたラベルは送信のみが利用できますrecvonlyが設定されたラベルは受信のみが利用できます
ordered¶
順序保証を行うかどうか指定します。デフォルトでは true に設定され、順序保証を行います。
max_retransmits¶
注意
max_retransmits と max_packet_life_time はどちらかしか指定できません。
最大再送回数を指定します。デフォルトでは未指定で、無制限に再送します。
max_packet_life_time¶
注意
max_retransmits と max_packet_life_time はどちらかしか指定できません。
最大再送時間をミリ秒で指定します。デフォルトでは未指定で、無制限に再送します。
header¶
メッセージングにヘッダーを追加します。ヘッダーは Sora 側で付与します。
headerはdirectionがsendrecvまたはrecvonlyの場合に指定できますheaderを指定したメッセージの受信者にヘッダーが付与されるようになりますheaderはオプションですheaderのデフォルトは[]ですheaderには{"type": "sender_connection_id"}を指定できますsender_connection_idはメッセージングの送信元のconnection_idです先頭 26 バイトが
sender_connection_idになります
クライアントから Sora が受信するメッセージ
[message (variable length)]
Sora から
headerを指定したクライアントへ送信するメッセージ[sender_connection_id (26 bytes)][message (variable length)]
"data_channels": [
{
"label": "#spam",
"max_packet_life_time": 5000,
"ordered": true,
"protocol": "efg",
"compress": false,
"direction": "sendonly",
"header": [{"type": "sender_connection_id"}]
},
{
"label": "#egg",
"max_retransmits": 0,
"ordered": false,
"protocol": "abc",
"compress": false,
"direction": "recvonly"
}
]
JavaScript SDK 利用時の注意¶
max_retransmitsはmaxRetransmitsに変更してくださいmax_packet_life_timeはmaxPacketLifeTimeに変更してください
"type": "connect" 時の "data_channels"¶
注釈
protocol は特に指定する必要はありません。
項目名 |
型 |
必須 / オプション |
デフォルト |
備考 |
|---|---|---|---|---|
label |
string |
必須 |
^#[a-zA-Z0-9][a-zA-Z0-9-]{1,30}$ |
|
direction |
string |
必須 |
"sendrecv" / "sendonly" / "recvonly" |
|
ordered |
boolean |
オプション |
true |
|
max_packet_life_time |
integer |
オプション |
未指定 |
|
max_retransmits |
integer |
オプション |
未指定 |
|
protocol |
string |
オプション |
"" |
|
compress |
boolean |
オプション |
false |
|
header |
array[object] |
オプション |
[] |
"sender_connection_id" |
注意
Sora JS SDK や Sora DevTools で max_packet_life_time と max_retransmits を指定する場合は
maxPacketLifeTime と maxRetransmits となります。
{
"type": "connect",
"data_channels": [
{
"label": "#spam",
"max_packet_life_time": 5000,
"ordered": true,
"protocol": "efg",
"compress": false,
"direction": "sendonly",
"header": [{"type": "sender_connection_id"}]
},
{
"label": "#egg",
"max_retransmits": 0,
"ordered": false,
"protocol": "abc",
"compress": false,
"direction": "recvonly"
}
]
}
認証成功時の戻り値¶
認証ウェブフックの認証成功時に data_channels を指定できます。
{
"allowed": true,
"data_channels": [
{
"label": "#spam",
"max_packet_life_time": 5000,
"ordered": true,
"protocol": "efg",
"compress": false,
"direction": "sendonly",
"header": [{"type": "sender_connection_id"}]
},
{
"label": "#egg",
"max_retransmits": 0,
"ordered": false,
"protocol": "abc",
"compress": false,
"direction": "recvonly"
}
]
}
"type": "offer" 時の "data_channels"¶
注釈
Sora SDK を利用する場合はこれを意識する必要はありません。
接続時か認証成功時に指定された data_channels は {"type": "offer"} に含まれます。
{
"type": "offer",
"data_channels": [
{
"label": "signaling",
"ordered": true,
"protocol": "signaling",
"compress": true,
"direction": "sendrecv"
},
{
"label": "notify",
"ordered": true,
"protocol": "notify",
"compress": true,
"direction": "recvonly"
},
{
"label": "push",
"ordered": true,
"protocol": "push",
"compress": true,
"direction": "recvonly"
},
{
"label": "stats",
"ordered": true,
"max_retransmits": 1,
"protocol": "stats",
"compress": true,
"direction": "sendrecv"
},
{
"label": "#spam",
"max_packet_life_time": 5000,
"ordered": true,
"protocol": "efg",
"compress": false,
"direction": "sendrecv",
// header の長さが type: offer 時の data_channels には含まれるようになります
"header": [{"type": "sender_connection_id", "length": 26}]
},
{
"label": "#egg",
"max_retransmits": 0,
"ordered": false,
"protocol": "abc",
"compress": false,
"direction": "recvonly"
}
]
}
DataChannel を利用したメッセージングのみで接続する¶
DataChannel を利用したメッセージングのみを有効にするには以下を満たす必要があります。
注釈
role は sendrecv / sendonly / recvonly のどれでも問題ありませんが、 sendrecv / recvonly の場合、相手から送られてきた音声や映像を受信しますので、sendonly で接続することをお勧めします。
sora.confの default_data_channel_signaling をtrueにするsora.confの data_channel_messaging_only をtrueにするsora.confの data_channel_messaging をtrueにする"type": "connect"時にaudioをfalseにする認証成功時の払い出しでも可
"type": "connect"時にvideoをfalseにする認証成功時の払い出しでも可
"type": "connect"時にdata_channelsを指定する認証成功時の払い出しでも可
"type": "connect"時にdata_channel_signalingをtrueにする認証成功時の払い出しでも可
これで 音声や映像を送らず DataChannel を利用したメッセージングのみを利用できるようになります。
シーケンス図¶
シンプル¶
クライアント 1 が
label:spam,direction:sendrecvと、label:#egg,direction:sendonlyでメッセージング利用開始{ "type": "connect", "data_channels": [ {"label": "#spam", "direction": "sendrecv"}, {"label": "#egg": "direction": "sendonly"} ] }
クライアント 2 が
label:#spam,direction:recvonlyでメッセージング利用開始{ "type": "connect", "data_channels": [ {"label": "#spam", "direction": "recvonly"} ] }
クライアント 1 が
label:#spamへメッセージ"abc"を送信クライアント 2 が Sora から
label:#spamへのメッセージ"abc"を受信クライアント 1 が
label:#eggへメッセージ"xyz"を送信誰も受け取る人がいない
クライアント 3 が
label:#spam,direction:sendrecvでメッセージング利用開始{ "type": "connect", "data_channels": [ {"label": "#spam", "direction": "sendrecv"} ] }
クライアント 1 が Sora へ
label:#spamのメッセージ"123"を送信クライアント 2 が Sora から
label:#spamのメッセージ"123"を受信クライアント 3 が Sora から
label:#spamのメッセージ"123"を受信
sequenceDiagram
autonumber
participant C1 as クライアント1
participant C2 as クライアント2
participant C3 as クライアント3
participant S as Sora
C1->>S: "type": "connect"
note over C1,S: クライアント1 WebRTC 確立
C2->>S: "type": "connect"
note over C2,S: クライアント2 WebRTC 確立
C1-)S: label: #35;spam "abc" send
S-)C2: label: #35;spam "abc" send
C3->>S: "type": "connect"
note over C3,S: クライアント3 WebRTC 確立
C1-)S: label: #35;spam "xyz" send
S-)C2: label: #35;spam "xyz" send
S-)C3: label: #35;spam "xyz" send