メッセージング機能

注意

メッセージング機能は実験的機能のため、正式版では仕様が変更される可能性があります

概要

ここでは DataChannel を利用したメッセージング機能について説明します。

DataChannel は、WebRTC の機能の一つでデータの送受信を行える機能です。

注意

  • メッセージング機能を利用するためには、data_channel_siganling が有効になっている必要があります

  • メッセージング機能は DataChannel プロトコル互換性を維持しつつ Sora 独自の仕組みを追加しています

制限

メッセージサイズ制限

注意

1 回のメッセージで送れる値には制限がありますのでご注意ください。

詳しくは DataChannel シグナリングの 推奨メッセージサイズ をご確認ください

SDK 対応状況

  • 安定版 の JavaScript SDK

    • 対応済みです

  • 安定版 の iOS SDK

    • 対応済みです

  • 安定版 のAndroid SDK

    • 対応済みです

  • 安定版 の Unity SDK

    • 対応済みです

DataChannel を利用したメッセージング機能を有効にする

DataChannel を利用したメッセージングを利用する場合、 DataChannel シグナリングが有効になっている必要があります。

その上で sora.conf にて data_channel_messagingtrue に指定してください。

利用する場合は "type": "connect" 時に "data_channels": [{"label": "#spam", "direction": "sendrecv"}, ...] を指定してください。

メッセージング用 DataChannel の作成

重要

DataChannel を利用したメッセージングを利用する場合は、DataChannel シグナリングが有効になっている必要があります

Sora では、Sora がシグナリングで使用する DataChannel 以外にも、メッセージング用の DataChannel を作成できます。

利用する場合は "type": "connect" 時に定義するか、認証成功時の払い出しで定義する必要があります。

Sora のメッセージング用 DataChannel は、DataChannel の属性である Label を定義する際に必ず # から始める必要があります。

data_channels 仕様

警告

現時点では誰から送られたメッセージかを判断する仕組みはありません。

重要

メッセージは 送信者以外 の同一 label 、かつ、 directionsendrecv または recvonly のクライアントに送信されます。

label

メッセージのラベルを指定します。先頭に # が付いている必要があります。

  • label# を含めて 32 文字まで指定可能です

  • label には小文字大文字のアルファベットと - (ハイフン) しか利用できません

    • # の次の文字に - は指定できません

    • ^#[a-zA-Z0-9][a-zA-Z0-9-]{1,30}$

  • 1 接続においてラベルは最大で 1024 まで指定可能です

compress

メッセージを zlib にて圧縮するかどうかを指定します。

  • compresstrue の場合、圧縮/展開に 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 はどちらかしか指定できません。

最大再送時間を指定します。デフォルトでは未指定で、無制限に再送します。

JavaScript SDK 利用時の注意

  • max_retransmitsmaxRetransmits に変更してください

  • max_packet_life_timemaxPacketLifeTime に変更してください

"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

注意

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"
        },
        {
            "label": "#egg",
            "max_retransmits": 0,
            "ordered": false,
            "protocol": "abc",
            "compress": false,
            "direction": "recvonly"
        }
    ]
}

認証成功時の戻り値

{
    "allowed": true,
    "data_channels": [
        {
            "label": "#spam",
            "max_packet_life_time": 5000,
            "ordered": true,
            "protocol": "efg",
            "compress": false,
            "direction": "sendonly"
        },
        {
            "label": "#egg",
            "max_retransmits": 0,
            "ordered": false,
            "protocol": "abc",
            "compress": false,
            "direction": "recvonly"
        }
    ]
}

"type": "offer" 時の "data_channels"

{
    "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"
        },
        {
            "label": "#egg",
            "max_retransmits": 0,
            "ordered": false,
            "protocol": "abc",
            "compress": false
            "direction": "recvonly"
        }
    ]
}

DataChannel を利用したメッセージングのみで接続する

DataChannel を利用したメッセージングのみを有効にするには以下を満たす必要があります。

  • sora.confdefault_data_channel_signalingtrue にする

  • sora.confdata_channel_messaging_onlytrue にする

  • sora.confdata_channel_messagingtrue にする

  • "type": "conenct" 時に rolesendrecv にする

  • "type": "conenct" 時に multistreamtrue にする

  • "type": "connect" 時に audiofalse にする

    • 認証成功時の払い出しでも可

  • "type": "connect" 時に videofalse にする

    • 認証成功時の払い出しでも可

  • "type": "connect" 時に data_channels を指定する

    • 認証成功時の払い出しでも可

  • "type": "conenct" 時に data_channel_signalingtrue にする

    • 認証成功時の払い出しでも可

これで音声や映像を送らず、 DataChannel を利用したメッセージングのみを利用することが可能になります。

シーケンス図

シンプル

  1. クライアント 1 が label: spam, direction: sendrecv と label: egg, direction: sendonly でメッセージング利用開始

    • "type": "connect", "data_channels": [{"label": "spam", "direction": "sendrecv"}, {"label": "egg": "direction": "sendonly"}]

  2. クライアント 2 が label: spam, direction: recvonly でメッセージング利用開始 - "type": "connect", "data_channels": [{"label": "spam", "direction": "recvonly"}]

  3. クライアント 1 が label: spam へメッセージ "abc" を送信

  4. クライアント 2 が Sora から label: spam のメッセージ "abc" を受信

  5. クライアント 1 が label: egg へメッセージ "abc" を送信

    • 誰も受け取る人がいない

  6. クライアント 3 が label: spam, direction: sendrecv でメッセージング利用開始

    • "type": "connect", "data_channels": [{"label": "spam", "direction": "sendrecv"}]

  7. クライアント 1 が Sora へ label: spam のメッセージ "123" を送信

  8. クライアント 2 が Sora から label: spam のメッセージ "123" を受信

  9. クライアント 3 が Sora から label: spam のメッセージ "123" を受信

blockdiag クライアント1 クライアント2 クライアント3 Sora 1. type: connect 2. type: connect 3. label: spam 4. label: spam 5. label: egg 6. type: connect 7. label: spam 8. label: spam 9. label: spam クライアント1 WebRTC 確立 クライアント2 WebRTC 確立 クライアント3 WebRTC 確立
© Copyright 2022, Shiguredo Inc Created using Sphinx 5.0.0b1