Data session

LINE Planet provides a data session that allows applications to send and receive application data. For example, an application can send or receive text messages to enable text chatting during a group call (conference).

Keep in mind that the data communication protocol must be defined by the application. The data session provided by LINE Planet serves only as a communication channel for application-defined data communication protocols.

Supported call type	Minimum SDK version
1-to-1 call, group call	1.2

Note

• LINE Planet is a real-time communication platform. On the internet, real-time communication is not guaranteed because packets may be lost or delayed depending on network conditions. These network impairments affect real-time communication quality, and in severe cases, calls can be interrupted. Heavy traffic can also cause various network impairments. If your application uses a data session, note that data communication might degrade the quality of voice or video calls.
• A data session is available only after a call is set up or participants join a group call.

Data session specifications

Data session APIs are directional, so there are sender and receiver. For each side, applications should request a data session with a pre-defined stream ID. Here, "pre-defined" means that the stream ID value must be defined between both sides before the implementation stage.

Stream ID

A stream ID is an identifier for data communication. The characteristics of stream IDs are as follows:

• Stream IDs are not dynamically generated. They are assigned during the design stage of the application and remain constant throughout the service operation. This means that if a receiver is unable to handle a particular stream ID, applications must stop using that specific stream ID.
• Stream IDs must be chosen from a specific range of integers, from 100 through 999.
• A single stream ID can be used by both the sender and the receiver. This means that the same identifier is used for communication in both directions, allowing for a bidirectional flow of data.

Lifetime of a data session

The lifetime of a data session by call type is as follows:

• 1-to-1 call
  • Once a data session is created, it remains active until the call is ended.
• Group call
  • Once a data session is created, it remains active until the group call is ended.

Data session type

Data sessions have four types. Applications should choose which type to use, depending on application data characteristics.

Data session type	Description
Reliable message	Lost packets are retransmitted. The onReceive callback is called when each message is aggregated, so the callback is called as many times as send() is called.
Unreliable message	Lost packets are not retransmitted. The onReceive callback is called when each message is aggregated. When there is no packet loss, the callback is called as many times as send() is called. When there is packet loss, however, the callback can be called fewer times than send().
Reliable bytes	Lost packets are retransmitted. PlanetKit fragments data if the application data is large. However, packets are not aggregated on the receiver side, so applications should aggregate the fragmented packets.
Unreliable bytes	Lost packets are not retransmitted. PlanetKit fragments data if the application data is large. However, packets are not aggregated on the receiver side, so applications should aggregate the fragmented packets.

Maximum transmission bandwidth

Data sessions cannot transmit data at more than 2 Mbps. This is because data session bandwidth can degrade voice or video quality. For this reason, PlanetKit controls the data rate. If your application is sending excessive traffic, PlanetKit generates an exception event to notify your application that the data transmission should be slowed down.

Sender side

This section describes APIs and tasks for the sender side.

Sender side APIs

The following APIs are used by the sender side.

API	Description
makeOutboundDataSession()	Creates an outbound data session with a stream ID
getOutboundDataSession()	Retrieves a previously created outbound data session
send()	Sends data using the outbound data session
target	Gets the current destination of the outbound data session
changeDestination()	Changes the destination of data

Create an outbound data session

To create an outbound data session, use makeOutboundDataSession().

Future<PlanetKitMakeOutboundDataSessionResult> makeOutboundDataSession(
    PlanetKitDataSessionStreamId streamId,
    PlanetKitDataSessionType type,
    PlanetKitOutboundDataSessionHandler handler,
)

Parameter	Description
streamId	Stream identifier defined by the application. For more information, see Stream ID.
type	Data session type. For more information, see Data session type.
handler	Handler for receiving events related to the outbound data session

The result is returned as a PlanetKitMakeOutboundDataSessionResult object:

• If an outbound data session is created successfully, result.dataSession is non-null and result.reason is PlanetKitDataSessionFailReason.none.
• If an outbound data session could not be created, result.dataSession is null and result.reason indicates the failure reason. For more information, see Data session fail reason.

After the outbound session is created, onTooLongQueuedData reports the status of data traffic. Refer to the following table and take necessary action in your application.

Event	Description	Action required by an application
onTooLongQueuedData (enabled=true)	Data traffic is too heavy.	Stop sending data or reduce the transmission bitrate.
onTooLongQueuedData (enabled=false)	Network conditions become better.	Send more data.

Note

If onTooLongQueuedData events continue to occur, it can negatively impact the quality of voice and video communication. To mitigate this, you should reduce the data transmission bitrate.

Retrieve an outbound data session

To retrieve an existing outbound data session, use getOutboundDataSession().

Future<PlanetKitOutboundDataSession?> getOutboundDataSession(
    PlanetKitDataSessionStreamId streamId,
)

Parameter	Description
streamId	Stream ID. For more information, see Stream ID.

Send data

To send data using an outbound data session, use send() of PlanetKitOutboundDataSession.

Future<bool> send(Uint8List data, int timestamp)

Parameter	Description
data	Data to send. The maximum size for "Message" type is 128 kBytes, and the maximum size for other types is 4 MBytes.
timestamp	User-defined timestamp to identify the data

Get the current destination

To get the current destination of an outbound data session, use target of PlanetKitOutboundDataSession.

PlanetKitUserId? get target

Returns the PlanetKitUserId of the peer currently set as the destination, or null if data is being sent to all peers.

Change the destination of data

To change the destination of data, use changeDestination() of PlanetKitOutboundDataSession.

Note

This method is effective for group calls only.

Future<bool> changeDestination(PlanetKitUserId? target) async

Parameter	Description
target	Peer who will receive the data. Setting to null sends data to all peers in the room.

Receiver side

This section describes APIs and tasks for the receiver side.

Receiver side APIs

The following APIs are used by the receiver side.

API	Description
onDataSessionIncoming	Called when the sender newly created an outbound data session
makeInboundDataSession()	Creates an inbound data session to receive data
getInboundDataSession()	Retrieves a previously created inbound data session
unsupportInboundDataSession()	Informs the sender that the application does not support the stream ID

Get notified of an incoming data session

When the sender creates a new data session, the receiver side is notified of the event through the onDataSessionIncoming callback of PlanetKitCallEventHandler (for 1-to-1 calls) or PlanetKitConferenceEventHandler (for group calls).

// 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

Parameter	Description
streamId	Stream ID set by the sender. For more information, see Stream ID.
type	Data session type. For more information, see Data session type.

In a group call, a participant who joined after someone started data streaming using the data session will also receive onDataSessionIncoming when receiving data upon completion of the join flow.

Create an inbound data session

To create an inbound data session, use makeInboundDataSession().

Future<PlanetKitMakeInboundDataSessionResult> makeInboundDataSession(
    PlanetKitDataSessionStreamId streamId,
    PlanetKitInboundDataSessionHandler handler,
)

Parameter	Description
streamId	Stream identifier defined by the application. For more information, see Stream ID.
handler	Handler for receiving events related to the inbound data session

The result is returned as a PlanetKitMakeInboundDataSessionResult object:

• If an inbound data session is created successfully, result.dataSession is non-null and result.reason is PlanetKitDataSessionFailReason.none.
• If an inbound data session could not be created, result.dataSession is null and result.reason indicates the failure reason. For more information, see Data session fail reason.

You can get notified of the data reception event through onReceive.

Retrieve an inbound data session

To retrieve an existing inbound data session, use getInboundDataSession().

Future<PlanetKitInboundDataSession?> getInboundDataSession(
    PlanetKitDataSessionStreamId streamId,
)

Parameter	Description
streamId	Stream ID. For more information, see Stream ID.

Report an unsupported data session

To inform the sender that the application does not support the stream ID, use unsupportInboundDataSession().

Future<bool> unsupportInboundDataSession(
    PlanetKitDataSessionStreamId streamId,
)

Parameter	Description
streamId	Stream ID. For more information, see Stream ID.

Call this method if the stream ID received through the onDataSessionIncoming event cannot be processed by the application (that is, unknown to the receiver).

• 1-to-1 call
  • The sender becomes aware that this method has been called through the data session fail reason Unsupported. The sender cannot send data through this stream anymore.
• Group call
  • The sender does not know that this method has been called because there are multiple receivers.
  • The user of the application that called this method will not receive data through this stream, but the sender can continue to send data through this stream.

Closure of a data session

When a data session is closed, the onClose event (for the sender) or onClose event (for the receiver) occurs.

The closure callback delivers the reason through a PlanetKitDataSessionClosedReason value. The data session closure reasons are as follows:

Enum value	Description
sessionEnd	The data session has ended normally.
internal	An unexpected error occurred internally.
unsupported	The data session ID is unsupported by the peer.

Data session fail reason

A data session fail reason lets you determine the result of data session creation and its failure reason. The data session fail reasons defined in the PlanetKitDataSessionFailReason enum are as follows:

Enum value	Description
none	Successfully created a data session.
internal	Unexpected error occurred internally.
notIncoming	Cannot make an inbound data session without an incoming event (onDataSessionIncoming).
alreadyExist	Data session stream ID already exists.
invalidId	Data session stream ID is invalid.
invalidType	Data session type is invalid.

Data session compatibility

Based on the call type, you can determine the data session compatibility as follows:

• 1-to-1 call
  • The value of isDataSessionSupported of PlanetKitCall is determined when the call connects and is valid from PlanetKitCallEventHandler.onConnected onward.
• Group call
  • The value of isDataSessionSupported of PlanetKitConferencePeer describes whether the participant supports a data session or not.

Even if peers have data session capabilities, handling a specific stream ID is another compatibility issue. This issue is related to handling of a specific stream ID by older versions of clients where handling of the stream ID is not implemented.

You can solve the compatibility issue of a specific stream ID by one of the following methods:

• In older versions of clients, reject unknown stream IDs by calling unsupportInboundDataSession().
• When developing older versions of clients, assign a specific stream ID as a reliable type for compatibility check, and design a protocol for compatibility check. In subsequent versions of clients, use the protocol to solve the compatibility issue in the way you want.

Related API

APIs related to the data session function are as follows.

Common

• send() of PlanetKitOutboundDataSession
• target of PlanetKitOutboundDataSession
• changeDestination() of PlanetKitOutboundDataSession
• onTooLongQueuedData of PlanetKitOutboundDataSessionHandler
• onClose of PlanetKitOutboundDataSessionHandler
• onReceive of PlanetKitInboundDataSessionHandler
• onClose of PlanetKitInboundDataSessionHandler
• PlanetKitDataSessionClosedReason
• PlanetKitDataSessionFailReason

1-to-1 call

• makeOutboundDataSession() of PlanetKitCall
• getOutboundDataSession() of PlanetKitCall
• makeInboundDataSession() of PlanetKitCall
• getInboundDataSession() of PlanetKitCall
• unsupportInboundDataSession() of PlanetKitCall
• onDataSessionIncoming of PlanetKitCallEventHandler

Group call

• makeOutboundDataSession() of PlanetKitConference
• getOutboundDataSession() of PlanetKitConference
• makeInboundDataSession() of PlanetKitConference
• getInboundDataSession() of PlanetKitConference
• unsupportInboundDataSession() of PlanetKitConference
• onDataSessionIncoming of PlanetKitConferenceEventHandler