데이터 세션

LINE Planet은 애플리케이션이 데이터를 주고받을 수 있는 데이터 세션을 제공합니다. 그룹 통화(컨퍼런스) 도중에 텍스트 메시지를 보내거나 받는 것이 사용 예입니다.

이때 데이터 통신 프로토콜은 애플리케이션이 정의해야 한다는 것을 명심하세요. LINE Planet이 제공하는 데이터 세션은 애플리케이션이 정의한 데이터 통신 프로토콜을 위한 통신 채널 역할만 합니다.

지원 통화 유형	최소 SDK 버전
1대1 통화, 그룹 통화	PlanetKit 3.2

Note

• LINE Planet은 실시간 통신 플랫폼입니다. 인터넷에서는 네트워크 상태에 따라 패킷이 손실 또는 지연될 수 있어 실시간 통신을 보장하지 않습니다. 네트워크의 장애는 실시간 통신 품질에 영향을 주며, 심각하면 통화가 중단되기도 합니다. 트래픽이 많으면 각종 네트워크 장애가 발생할 수 있습니다. 애플리케이션이 데이터 세션을 사용할 경우 데이터 통신이 음성 또는 영상 통화의 품질을 떨어뜨릴 수 있음에 주의하세요.
• 데이터 세션은 콜 셋업(call setup)이 끝났거나 그룹 통화에 참여한 후에만 사용할 수 있습니다.

데이터 세션 사양

데이터 세션 API에는 송신 측과 수신 측이 있습니다. 양측 애플리케이션은 미리 정의한 스트림 ID로 데이터 세션을 요청해야 합니다. "미리 정의했다"는 말은 구현 단계 전에 양측에서 스트림 ID 값을 논의했다는 뜻입니다.

스트림 ID

스트림 ID는 각 애플리케이션이 설계 단계에서 정의한 데이터 통신 식별자입니다. 스트림 ID의 특징은 다음과 같습니다.

• 스트림 ID는 동적으로 생성되지 않습니다. 스트림 ID는 애플리케이션의 설계 단계에서 할당되며 서비스 운영 전반에 걸쳐 일정하게 유지됩니다. 이는 수신자가 특정 스트림 ID를 처리할 수 없는 경우 애플리케이션이 해당 스트림 ID 사용을 중지해야 함을 의미합니다.
• 스트림 ID는 100에서 999까지의 정수 중에서 선택해야 합니다.
• 하나의 스트림 ID를 송신 및 수신 측 모두 사용할 수 있습니다. 이는 양방향 통신에 동일한 식별자를 사용하여 양방향 데이터 흐름이 가능함을 의미합니다.

서브그룹 지원

서브그룹에 속한 데이터 세션은 서브그룹 멤버 간에 데이터를 주고받고자 사용할 수 있습니다. 같은 스트림 ID를 사용하더라도 서브그룹이 다르면 다른 데이터 세션을 정의해서 사용하게 됩니다.

서브그룹은 서브그룹 이름으로 구분됩니다. 서브그룹 이름이 null이면 기본 방(main room)이라는 의미입니다.

Note

• 애플리케이션에서 서브그룹 내 데이터 세션을 사용하려면, 서브그룹 속성 dataSession의 값을 반드시 true로 설정해야 합니다.
• 서브그룹 내 데이터 세션 사용은 PlanetKit 4.1 이상에서 지원합니다.

서브그룹에 관해 상세히 알고 싶으면 서브그룹 카테고리 이하 문서를 참고하세요.

데이터 세션 수명

통화 유형별로 데이터 세션의 수명은 다음과 같습니다.

• 1대1 통화
  • 데이터 세션을 생성하면 통화가 끝날 때까지 활성화된 상태를 유지합니다.
• 그룹 통화 - 기본 방 데이터 세션
  • 데이터 세션을 생성하면 그룹 통화가 끝날 때까지 활성화된 상태를 유지합니다.
• 그룹 통화 - 서브그룹 데이터 세션
  • 특정 서브그룹용 데이터 세션을 생성하면 데이터 세션을 생성한 참여자가 서브그룹에 가입해 있는 동안 활성화된 상태를 유지합니다. 해당 참여자가 서브그룹에서 탈퇴하면 이 데이터 세션은 비활성화됩니다.

데이터 세션 유형

데이터 세션에는 다음과 같은 유형이 있습니다. 애플리케이션은 데이터 특성에 따라 어떤 유형을 사용할지 결정해야 합니다.

데이터 세션 유형	설명
Reliable message	손실된 패킷을 재전송합니다. 각 메시지가 재조립될 때 onDataReceived 콜백이 호출되므로 이 콜백은 send()가 호출되는 횟수만큼 호출됩니다.
Unreliable message	손실된 패킷을 재전송하지 않습니다. 각 메시지가 재조립될 때 onDataReceived 콜백이 호출됩니다. 패킷 손실이 없으면 이 콜백이 send()와 같은 횟수로 호출되지만, 패킷 손실이 발생하면 콜백의 호출 횟수가 send()의 호출 횟수보다 적을 수 있습니다.
Reliable bytes	손실된 패킷을 재전송합니다. PlanetKit은 애플리케이션 데이터가 크면 이를 조각냅니다. 단, 수신 측에서 패킷을 재조립하지 않으므로, 애플리케이션이 조각난 패킷을 재조립해야 합니다.
Unreliable bytes	손실된 패킷을 재전송하지 않습니다. PlanetKit은 애플리케이션 데이터가 크면 이를 조각냅니다. 단, 수신 측에서 패킷을 재조립하지 않으므로, 애플리케이션이 조각난 패킷을 재조립해야 합니다.

데이터 세션 최대 전송 대역폭

데이터 세션은 2 Mbps 이상으로 데이터를 전송할 수 없습니다. 데이터 세션 대역폭이 오디오 또는 비디오 품질을 떨어뜨릴 수 있기 때문입니다. 이 때문에 PlanetKit은 데이터 전송 속도(data rate)를 제어합니다. 애플리케이션이 트래픽을 과도하게 보내면 PlanetKit이 애플리케이션에 데이터 전송을 늦추라고 알리기 위해 예외(exception) 이벤트를 생성합니다.

송신 측

이 섹션에서는 송신 측의 API와 작업을 설명합니다.

송신 측 API

송신 측에서는 다음 API를 사용합니다.

API	설명
makeOutboundDataSession()	스트림 ID를 사용하여 아웃바운드 데이터 세션 생성
getOutboundDataSession()	이전에 생성된 아웃바운드 데이터 세션 가져오기
send()	아웃바운드 데이터 세션을 사용하여 데이터 전송
changeDestination()	데이터의 목적지를 변경

아웃바운드 데이터 세션 생성

아웃바운드 데이터 세션을 생성하려면 makeOutboundDataSession()을 사용하세요.

fun makeOutboundDataSession(
    IntRange(from = 100, to = 999) streamId: Int,
    type: PlanetKitDataSessionType,
    listener: OutboundDataSessionListener
)

파라미터	설명
streamId	애플리케이션에서 정의한 스트림 식별자. 자세한 내용은 스트림 ID를 참조하세요.
type	데이터 세션 유형. 자세한 내용은 데이터 세션 유형을 참조하세요.
listener	아웃바운드 데이터 세션과 관련된 이벤트를 처리하기 위한 리스너

아웃바운드 데이터 세션 생성 결과는 listener의 콜백으로 확인할 수 있습니다.

• 아웃바운드 데이터 세션이 성공적으로 생성되면 onSessionMade가 호출됩니다.
• 아웃바운드 데이터 세션을 생성할 수 없는 경우 실패 이유와 함께 onError가 호출됩니다. 자세한 내용은 데이터 세션 실패 이유를 참조하세요.

아웃바운드 세션이 생성된 후 onTooLongQueueData는 데이터 트래픽 상태를 알려줍니다. 다음 표를 참조하여 애플리케이션에서 필요한 조치를 취하세요.

이벤트	설명	애플리케이션에 필요한 조치
onTooLongQueueData (isTriggered=true)	데이터 트래픽이 너무 많습니다.	데이터 전송을 중지하거나 전송 비트레이트를 줄이세요.
onTooLongQueueData (isTriggered=false)	네트워크 상태가 좋아졌습니다.	더 많은 데이터를 보내세요.

Note

onTooLongQueueData 이벤트가 계속 발생하면 음성 및 영상 통신 품질에 부정적인 영향을 미칠 수 있습니다. 이를 완화하려면 데이터 전송 비트레이트를 줄여야 합니다.

아웃바운드 데이터 세션 가져오기

기존 아웃바운드 데이터 세션을 가져오려면 getOutboundDataSession()을 사용하세요.

fun getOutboundDataSession(streamId: Int): PlanetKitOutboundDataSession?

파라미터	설명
streamId	스트림 ID. 자세한 내용은 스트림 ID를 참조하세요.

데이터 보내기

아웃바운드 데이터 세션을 사용하여 데이터를 전송하려면 PlanetKitOutboundDataSession의 send()를 사용하세요.

fun send(data: ByteBuffer, timestamp: Long): Boolean

파라미터	설명
data	전송할 데이터. "Message" 유형의 최대 크기는 128KB이고, 다른 유형의 최대 크기는 4MB입니다.
timestamp	데이터를 식별하기 위한 사용자 정의 타임스탬프

데이터 목적지 변경

데이터의 목적지를 변경하려면 PlanetKitOutboundDataSession의 changeDestination()을 사용하세요.

Note

이 메서드는 그룹 통화에만 유효합니다.

fun changeDestination(peer: PlanetKitUser?, userData: Any?, callback: PlanetKitRequestCallback?): Boolean

파라미터	설명
peer	데이터를 받을 피어. null로 설정하면 다음과 같은 효과가 있습니다. - 기본 방 데이터 세션의 경우 방에 있는 모든 피어에게 데이터를 보냅니다. - 서브그룹 데이터 세션의 경우 모든 서브그룹 멤버에게 데이터를 보냅니다.
userData	콜백을 위한 사용자 데이터
callback	요청 결과를 수신하기 위한 선택적 콜백

수신 측

이 섹션에서는 수신 측의 API와 작업을 설명합니다.

수신 측 API

수신 측에서는 다음 API를 사용합니다.

API	설명
onDataSessionIncoming	송신 측에서 아웃바운드 데이터 세션을 새로 생성했을 때 호출됨
makeInboundDataSession()	데이터를 수신하기 위한 인바운드 데이터 세션 생성
getInboundDataSession()	이전에 생성된 인바운드 데이터 세션 가져오기
unsupportInboundDataSession()	애플리케이션이 스트림 ID를 지원하지 않는다는 것을 송신 측에 알리기

새로운 데이터 세션에 대한 알림 받기

송신 측에서 새로운 데이터 세션을 생성하면 onDataSessionIncoming을 통해 수신 측에 이벤트가 통보됩니다.

// For 1-to-1 calls
fun onDataSessionIncoming(call: PlanetKitCall, streamId: Int, type: PlanetKitDataSessionType)

// For group calls
fun onDataSessionIncoming(conference: PlanetKitConference, subgroupName: String?, streamId: Int, type: PlanetKitDataSessionType)

파라미터	설명
call 또는 conference	1대1 통화 또는 그룹 통화의 인스턴스
subgroupName	(그룹 통화만 해당) 서브그룹 이름. null은 기본 방을 의미합니다.
streamId	발신자가 설정한 스트림 ID입니다. 자세한 내용은 스트림 ID를 참조하세요.
type	데이터 세션 유형. 자세한 내용은 데이터 세션 유형을 참조하세요.

그룹 통화에서 누군가 기본 방 데이터 세션을 사용하여 데이터 스트리밍을 시작한 후 참여한 참가자는 참여 흐름이 완료되면 데이터를 수신할 때 onDataSessionIncoming도 받게 됩니다. 이 경우 데이터 세션은 기본 방을 위한 것이기 때문에 서브그룹 이름은 null입니다.

서브그룹의 경우, 누군가가 서브그룹 데이터 세션을 사용하여 데이터 스트리밍을 시작한 후 가입하는 멤버는 가입 흐름 완료 시 데이터를 수신할 때 적절한 서브그룹 이름과 함께 onDataSessionIncoming도 수신하게 됩니다.

인바운드 데이터 세션 생성

인바운드 데이터 세션을 생성하려면 makeInboundDataSession()을 사용하세요.

fun makeInboundDataSession(
    @IntRange(from = 100, to = 999) streamId: Int,
    listener: InboundDataSessionListener
)

파라미터	설명
streamId	애플리케이션에서 정의한 스트림 식별자. 자세한 내용은 스트림 ID를 참조하세요.
listener	인바운드 데이터 세션과 관련된 이벤트를 처리하기 위한 리스너

인바운드 데이터 세션 생성 결과는 listener의 콜백으로 확인할 수 있습니다.

• 인바운드 데이터 세션이 성공적으로 생성되면 onSessionMade가 호출됩니다.
• 인바운드 데이터 세션을 생성할 수 없는 경우 실패 이유와 함께 onError가 호출됩니다. 자세한 내용은 데이터 세션 실패 이유를 참조하세요.

listener의 onDataReceived를 통해 데이터 수신 이벤트 알림을 받을 수 있습니다.

인바운드 데이터 세션 가져오기

기존 인바운드 데이터 세션을 가져오려면 getInboundDataSession()을 사용하세요.

fun getInboundDataSession(streamId: Int): PlanetKitInboundDataSession?

파라미터	설명
streamId	스트림 ID. 자세한 내용은 스트림 ID를 참조하세요.

지원되지 않는 데이터 세션 알리기

애플리케이션이 스트림 ID를 지원하지 않는다는 것을 송신 측에 알리려면 unsupportInboundDataSession()을 사용하세요.

fun unsupportInboundDataSession(streamId: Int): Boolean

파라미터	설명
streamId	스트림 ID. 자세한 내용은 스트림 ID를 참조하세요.

onDataSessionIncoming 이벤트를 통해 수신한 스트림 ID를 애플리케이션에서 처리할 수 없는 경우(즉, 스트림 ID가 수신자에게 알려지지 않은 경우) 이 메서드를 호출합니다.

• 1대1 통화
  • 송신자는 데이터 세션 실패 이유 "Unsupported"를 통해 이 메서드가 호출되었음을 알게 됩니다. 송신자는 더 이상 이 스트림을 통해 데이터를 보낼 수 없습니다.
• 그룹 통화
  • 송신자는 수신자가 여러 명이므로 이 메서드가 호출되었음을 알 수 없습니다.
  • 이 메서드를 호출한 애플리케이션의 사용자는 이 스트림을 통해 데이터를 수신하지 않지만, 송신자는 이 스트림을 통해 계속 데이터를 보낼 수 있습니다.

데이터 세션 종료

데이터 세션이 종료되면 OutboundDataSessionListener(송신 측) 또는 InboundDataSessionListener(수신 측)의 onClosed 이벤트가 발생합니다.

onClosed 이벤트는 데이터 세션이 종료된 이유를 closedReason 파라미터로 전달합니다. PlanetKitDataSessionClosedReason 열거형에 정의된 데이터 세션 종료 이유는 다음과 같습니다.

열거형 값	설명
SESSION_END	데이터 세션이 정상적으로 종료되었습니다.
INTERNAL	내부적으로 예기치 않은 오류가 발생했습니다.
UNSUPPORTED	피어가 데이터 세션 ID를 지원하지 않습니다.

데이터 세션 실패 이유

데이터 세션 실패 이유(data session fail reason)를 통해 데이터 세션 생성 결과와 생성 실패 이유를 알 수 있습니다. PlanetKitDataSessionFailReason 열거형에 정의된 데이터 세션 실패 이유는 다음과 같습니다.

열거형 값	설명
NONE	데이터 세션을 성공적으로 생성했습니다.
INTERNAL	내부적으로 예기치 않은 오류가 발생했습니다.
NOT_INCOMING	데이터 수신 이벤트(onDataSessionIncoming) 없이 인바운드 데이터 세션을 만들 수 없습니다.
ALREADY_EXIST	데이터 세션 스트림 ID가 이미 존재합니다.
INVALID_ID	데이터 세션 스트림 ID가 잘못되었습니다.
INVALID_TYPE	데이터 세션 유형이 잘못되었습니다.

Tip

데이터 세션 실패 이유는 PlanetKit 5.1부터 사용할 수 있습니다.

데이터 세션 호환성

통화 유형에 따라 다음과 같이 데이터 세션 호환성을 확인할 수 있습니다.

• 1대1 통화
  • onConnected가 전달하는 PlanetKitCallConnectedParam의 isDataSessionSupported 값을 통해 피어가 데이터 세션을 지원하는지 확인할 수 있습니다.
• 그룹 통화
  • PlanetKitConferencePeer의 isDataSessionSupported 값을 통해 피어가 데이터 세션을 지원하는지 확인할 수 있습니다.

피어가 데이터 세션 기능을 지원하더라도, 특정 스트림 ID를 처리하는 것은 별개의 호환성 문제입니다. 이 문제는 스트림 ID 처리가 구현되지 않은 구 버전의 클라이언트에서 특정 스트림 ID를 처리하는 것과 관계가 있습니다.

다음 중 하나의 방법으로 특정 스트림 ID의 호환성 문제를 해결할 수 있습니다.

• 구 버전의 클라이언트에서는 알려지지 않은 스트림 ID는 unsupportInboundDataSession()을 호출하여 거부합니다.
• 구 버전의 클라이언트를 개발할 때부터 특정 스트림 ID를 reliable 유형으로 호환성 검사를 위한 것으로 할당하고, 호환성 검사를 위한 프로토콜을 설계합니다. 이후 버전의 클라이언트에서는 이를 활용하여 호환성 문제를 원하는 방식으로 해결합니다.

관련 API

데이터 세션 기능과 관련된 API는 다음과 같습니다.

공통

• PlanetKitOutboundDataSession의 send()
• PlanetKitOutboundDataSession의 changeDestination()
• OutboundDataSessionListener의 onTooLongQueueData
• OutboundDataSessionListener의 onClosed
• InboundDataSessionListener의 onDataReceived
• InboundDataSessionListener의 onClosed
• PlanetKitDataSessionClosedReason
• PlanetKitDataSessionFailReason

1대1 통화

• PlanetKitCall의 makeOutboundDataSession()
• PlanetKitCall의 getOutboundDataSession()
• PlanetKitCall의 makeInboundDataSession()
• PlanetKitCall의 getInboundDataSession()
• PlanetKitCall의 unsupportInboundDataSession()
• CallListener의 onDataSessionIncoming

그룹 통화

• PlanetKitConference의 makeOutboundDataSession()
• PlanetKitConference의 getOutboundDataSession()
• PlanetKitConference의 makeInboundDataSession()
• PlanetKitConference의 getInboundDataSession()
• PlanetKitConference의 unsupportInboundDataSession()
• PlanetKitSubgroup의 makeOutboundDataSession()
• PlanetKitSubgroup의 getOutboundDataSession()
• PlanetKitSubgroup의 makeInboundDataSession()
• PlanetKitSubgroup의 getInboundDataSession()
• PlanetKitSubgroup의 unsupportInboundDataSession()
• ConferenceListener의 onDataSessionIncoming