データセッション
LINE Planetは、アプリケーションがデータをやり取りするためのデータセッションを提供します。グループ通話（カンファレンス）中にテキストメッセージを送ったり、受信したりするのがその例です。
このとき、データ通信プロトコルはアプリケーション側で定義する必要があることにご注意ください。LINE Planetが提供するデータセッションは、アプリケーションが定義したデータ通信プロトコルのための通信チャネルとしてのみ機能します。
| 対応する通話タイプ | SDKの最低バージョン |
|---|---|
| 1対1通話、グループ通話 | 1.2 |
- LINE Planetは、リアルタイム通信プラットフォームです。インターネットでは、ネットワークの状態によってパケットが失われたり、遅延したりすることがあり、リアルタイム通信を保証しません。ネットワークの障害は、リアルタイム通信の品質に影響を与え、深刻な場合通話が中断されることもあります。また、トラフィックが多い場合、各種ネットワーク障害が発生する可能性もあります。アプリケーションがデータセッションを使用する場合、データ通信が音声通話またはビデオ通話の品質を低下させる可能性があることにご注意ください。
- データセッションは、コールセットアップ（call setup）が完了した後、またはグループ通話に参加した後のみ使用できます。
データセッションの仕様
データセッションAPIには送信側と受信側があります。両者のアプリケーションは、事前に定義した ストリームIDでデータセッションをリクエストする必要があります。「事前に定義した」とは、実装段階に入る前に両者がストリームIDの値について協議していることを意味します。
ストリームID
ストリームIDは、各アプリケーションが設計段階で定義したデータ通信識別子です。ストリームIDの特長は次のとおりです。
- ストリームIDは動的に生成されません。ストリームIDは、アプリケーションの設計段階で割り当てられ、サービス運営全般に渡って一定に維持されます。これは、受信者が特定のストリームIDを処理できない場合に、アプリケーションがそのストリームIDの使用を中止しなければならないことを意味します。
- ストリームIDは100から999までの整数から選択する必要があります。
- 1つのストリームIDを送信側と受信側で使用できます。これは、双方向通信で同じ識別子を使用して双方向にデータが流れることを意味します。
データセッションのライフタイム
通話タイプによるデータセッションのライフタイムは次のとおりです。
- 1対1通話
- データセッションを作成すると、通話が終了するまで有効な状態を維持します。
- グループ通話
- データセッションを作成すると、グループ通話が終了するまで有効な状態を維持します。
データセッションのタイプ
データセッションのタイプは以下のとおりです。アプリケーションは、データの特性によって使用するタイプを決定する必要があります。
| データセッションのタイプ | 説明 |
|---|---|
| Reliable message | 損失されたパケットを再送します。 各メッセージが再組み立て時に、 onReceive コールバックが呼び出されるため、このコールバックはsend()が呼び出された回数分だけ呼び出されます。 |
| Unreliable message | 損失されたパケットを再送しません。 各メッセージの再組み立て時に、 onReceiveコールバックが呼び出されます。パケット損失がなければ、このコールバックがsend()と同じ回数で呼び出されますが、パケット損失が発生した場合はコールバックの呼び出し回数はsend()の呼び出し回数よりも少なくなる可能性があります。 |
| Reliable bytes | 損失されたパケットを再送します。 PlanetKitは、アプリケーションデータが大きい場合、それを分解します。ただし、受信側ではパケットの再組み立てをしないため、アプリケーションが分解されたパケットを組み立て直す必要があります。 |
| Unreliable bytes | 損失されたパケットを再送しません。 PlanetKitは、アプリケーションデータが大きい場合、それを分解します。ただし、受信側ではパケットの再組み立てをしないため、アプリケーションが分解されたパケットを組み立て直す必要があります。 |
データセッションの最大転送帯域幅
データセッションは、2Mbps以上のデータを送信できません。データセッションの帯域幅がオーディオまたはビデオの品質を低下させる可能性があるためです。そのため、PlanetKitはデータ送信速度（data rate）を制御します。アプリケーションが過剰なトラフィックを送る場合、PlanetKitはアプリケーションに対してデータの転送を遅らせることを知らせるために例外（exception）イベントを生成します。
送信側
送信側のAPIと操作について説明します。
送信側API
送信側では以下のAPIを使用します。
| API | 説明 |
|---|---|
makeOutboundDataSession() | ストリームIDを使用してアウトバウンドデータセッションを作成する |
getOutboundDataSession() | 以前作成されたアウトバウンドデータセッションをインポートする |
send() | アウトバウンドデータセッションを使用してデータを送信する |
target | アウトバウンドデータセッションの現在の送信先を取得する |
changeDestination() | データの送信先を変更する |
アウトバウンドデータセッションの作成
アウトバウンドデータセッションを作成するには、makeOutboundDataSession()を使用します。
Future<PlanetKitMakeOutboundDataSessionResult> makeOutboundDataSession(
PlanetKitDataSessionStreamId streamId,
PlanetKitDataSessionType type,
PlanetKitOutboundDataSessionHandler handler,
)
| パラメーター | 説明 |
|---|---|
streamId | アプリケーションで定義したストリーム識別子。詳しくは、ストリームIDを参照してください。 |
type | データセッションタイプ。詳しくは、データセッションタイプを参照してください。 |
handler | アウトバウンドデータセッションに関連するイベントを処理するためのハンドラー |
結果はPlanetKitMakeOutboundDataSessionResultオブジェクトとして返されます。
- アウトバウンドデータセッションの作成に成功すると、
result.dataSessionはnullではなく、result.reasonはPlanetKitDataSessionFailReason.noneです。 - アウトバウンドデータセッションを作成できなかった場合は、
result.dataSessionはnullになり、result.reasonが失敗の理由を示します。詳しくは、データセッションの失敗理由を参照してください。
アウトバウンドセッションが作成された後、onTooLongQueuedDataは、データトラフィックの状態を知らせます。下表の内容を参考に、アプリケーションで必要な処理を行ってください。
| イベント | 説明 | アプリケーションに必要な処理 |
|---|---|---|
onTooLongQueuedData (enabled=true) | データ使用量が多すぎます。 | データ送信を中断するか、ビットレートを下げて送信してください。 |
onTooLongQueuedData (enabled=false) | ネットワーク状態が改善されました。 | もっと多くのデータを送信してください。 |
onTooLongQueuedDataイベントが継続的に発生すると、音声および映像の通信品質に悪影響を及ぼす可能性があります。これを緩和するには、データ送信ビットレートを下げる必要があります。
アウトバウンドデータセッションのインポート
既存のアウトバウンドデータセッションをインポートするには、getOutboundDataSession()を使用します。
Future<PlanetKitOutboundDataSession?> getOutboundDataSession(
PlanetKitDataSessionStreamId streamId,
)
| パラメーター | 説明 |
|---|---|
streamId | ストリームID。詳しくは、ストリームIDを参照してください。 |
データを送信する
アウトバウンドデータセッションを使用してデータを送信するには、PlanetKitOutboundDataSessionのsend()を使用します。
Future<bool> send(Uint8List data, int timestamp)
| パラメーター | 説明 |
|---|---|
data | 送信するデータ。「Message」タイプの最大サイズは128KB、その他のタイプの最大サイズは4MBです。 |
timestamp | データを識別するためのユーザー定義のタイムスタンプ |
現在の送信先を取得する
アウトバウンドデータセッションの現在の送信先を取得するには、PlanetKitOutboundDataSessionのtargetを使用します。
PlanetKitUserId? get target
現在送信先として設定されているピアのPlanetKitUserIdを返します。すべてのピアにデータを送信している場合はnullを返します。
データの送信先を変更する
データの送信先を変更するには、PlanetKitOutboundDataSessionのchangeDestination()を使用します。
このメソッドは、グループ通話でのみ有効です。
Future<bool> changeDestination(PlanetKitUserId? target) async
| パラメーター | 説明 |
|---|---|
target | データを受信するピア。nullに設定すると、ルーム内のすべてのピアにデータを送信します。 |
受信側
このセクションでは、受信側のAPIと操作について説明します。
受信側 API
受信側では以下のAPIを使用します。
| API | 説明 |
|---|---|
onDataSessionIncoming | 送信側で新たにアウトバウンドデータセッションを作成したときに呼び出される |
makeInboundDataSession() | データを受信するためのインバウンドデータセッションを作成する |
getInboundDataSession() | 以前作成されたインバウンドデータセッションをインポートする |
unsupportInboundDataSession() | アプリケーションがストリームIDをサポートしていないことを送信側に通知する |
新しいデータセッションについての通知を受信する
送信側で新しいデータセッションを作成すると、PlanetKitCallEventHandler（1対1通話）またはPlanetKitConferenceEventHandler（グループ通話）のonDataSessionIncomingコールバックを通じて受信側にイベントが通知されます。
// For 1-to-1 calls — PlanetKitCallEventHandler
void Function(
PlanetKitCall call,
PlanetKitDataSessionStreamId streamId,
PlanetKitDataSessionType type,
)? onDataSessionIncoming
// For group calls — PlanetKitConferenceEventHandler
void Function(
PlanetKitConference conference,
PlanetKitDataSessionStreamId streamId,
PlanetKitDataSessionType type,
)? onDataSessionIncoming
| パラメーター | 説明 |
|---|---|
streamId | 発信者が設定したストリームIDです。詳しくは、ストリームIDを参照してください。 |
type | データセッションタイプ。詳しくは、データセッションタイプを参照してください。 |
グループ通話で誰かがデータセッションを使用してデータストリーミングを開始した後の参加者は、参加フローが完了してデータを受信するときにonDataSessionIncomingも受信します。
インバウンドデータセッションの作成
インバウンドデータセッションを作成するには、makeInboundDataSession()を使用します。
Future<PlanetKitMakeInboundDataSessionResult> makeInboundDataSession(
PlanetKitDataSessionStreamId streamId,
PlanetKitInboundDataSessionHandler handler,
)
| パラメーター | 説明 |
|---|---|
streamId | アプリケーションで定義したストリーム識別子。詳しくは、ストリームIDを参照してください。 |
handler | インバウンドデータセッションに関連するイベントを処理するためのハンドラー |
結果はPlanetKitMakeInboundDataSessionResultオブジェクトとして返されます。
- インバウンドデータセッションの作成に成功すると、
result.dataSessionはnullではなく、result.reasonはPlanetKitDataSessionFailReason.noneです。 - インバウンドデータセッションを作成できない場合は、
result.dataSessionはnullになり、result.reasonが失敗の理由を示します。詳しくは、データセッションの失敗理由を参照してください。
onReceiveでデータ受信イベント通知を受け取ることができます。
インバウンドデータセッションのインポート
既存のインバウンドデータセッションをインポートするには、getInboundDataSession()を使用します。
Future<PlanetKitInboundDataSession?> getInboundDataSession(
PlanetKitDataSessionStreamId streamId,
)
| パラメーター | 説明 |
|---|---|
streamId | ストリームID。詳しくは、ストリームIDを参照してください。 |
サポートされていないデータセッションを通知する
アプリケーションがストリームIDをサポートしていないことを送信側に通知するには、unsupportInboundDataSession()を使用します。
Future<bool> unsupportInboundDataSession(
PlanetKitDataSessionStreamId streamId,
)
| パラメーター | 説明 |
|---|---|
streamId | ストリームID。詳しくは、ストリームIDを参照してください。 |
onDataSessionIncomingイベントで受信したストリームIDをアプリケーションが処理できない場合（つまり、ストリームIDが受信者に知られていない場合）、このメソッドを呼び出します。
- 1対1通話
- 送信者は、データセッションの失敗理由「Unsupported」を通じてこのメソッドが呼び出されたことが分かります。その後送信者は、このストリームからデータの送信ができなくなります。
- グループ通話
- 送信者は、複数の受信者がいるため、このメソッドが呼び出されたことが分かりません。
- このメソッドを呼び出したアプリケーションのユーザーは、このストリームを通じてデータを受信しませんが、送信者はこのストリームを通じてデータを送り続けることができます。
データセッションの終了
データセッションが終了されると、onClose（送信側）またはonClose（受信側）イベントが発生します。
終了コールバックはPlanetKitDataSessionClosedReason値を使用してデータセッションの終了理由を提供します。データセッションの終了理由は次のとおりです。
| 列挙値 | 説明 |
|---|---|
sessionEnd | データセッションは正常に終了しました。 |
internal | 内部で予期しないエラーが発生しました。 |
unsupported | データセッションIDはピアでサポートされていません。 |
データセッションの失敗理由
データセッションの失敗理由（data session fail reason）を通じて、データセッションの作成結果と作成に失敗した理由が分かります。PlanetKitDataSessionFailReason列挙型で定義されているデータセッションの失敗理由は次のとおりです。
| 列挙値 | 説明 |
|---|---|
none | データセッションの作成に成功しました。 |
internal | 内部で予期しないエラーが発生しました。 |
notIncoming | データ受信イベント（onDataSessionIncoming）なしではインバウンドデータセッションを作成できません。 |
alreadyExist | すでにデータセッションストリームIDが存在します。 |
invalidId | データセッションストリームIDが正しくありません。 |
invalidType | データセッションタイプが正しくありません。 |
データセッションの互換性
通話タイプによって次のようにデータセッションの互換性を確認できます。
- 1対1通話
PlanetKitCallのisDataSessionSupportedの値は通話の接続時に決定され、PlanetKitCallEventHandler.onConnected以降から有効です。
- グループ通話
PlanetKitConferencePeerのisDataSessionSupported値からピアがデータセッションをサポートしているかどうかを確認できます。
ピアがデータセッション機能をサポートしていても、特定のストリームIDを処理することは互換性の問題です。この問題は、ストリームIDの処理が実装されていない古いバージョンのクライアントで特定のストリームIDを処理することに関係があります。
以下のいずれかの方法で、特定のストリームIDの互換性問題を解決できます。
- 旧バージョンのクライアントでは、未知のストリームIDは
unsupportInboundDataSession()を呼び出してリジェクトする - 旧バージョンのクライアントを開発する時点で、特定のストリームIDをreliableタイプの、互換性を検査するためのものとして割り当て、互換性検査のためのプロトコルを設計します。以降のバージョンのクライアントでは、これを活用して互換性の問題を希望する方法で解決します。
関連API
データセッション機能に関連するAPIは、以下のとおりです。
共通
-
PlanetKitOutboundDataSessionのsend() -
PlanetKitOutboundDataSessionのtarget -
PlanetKitOutboundDataSessionのchangeDestination() -
PlanetKitOutboundDataSessionHandlerのonTooLongQueuedData -
PlanetKitOutboundDataSessionHandlerのonClose -
PlanetKitInboundDataSessionHandlerのonReceive -
PlanetKitInboundDataSessionHandlerのonClose -
PlanetKitDataSessionClosedReason -
PlanetKitDataSessionFailReason
1対1通話
-
PlanetKitCallのmakeOutboundDataSession() -
PlanetKitCallのgetOutboundDataSession() -
PlanetKitCallのmakeInboundDataSession() -
PlanetKitCallのgetInboundDataSession() -
PlanetKitCallのunsupportInboundDataSession() -
PlanetKitCallEventHandlerのonDataSessionIncoming