콘텐츠 공유
콘텐츠 공유 API는 시간 흐름에 따라 달라지는 데이터를 피어와 공유하게 해 줍니다. 공유하는 데이터는 어떤 유형이든 상관없지만 최대 1 킬로바이트여야 합니다.
| 지원 통화 유형 | 최소 SDK 버전 |
|---|---|
| 1대1 통화, 그룹 통화(컨퍼런스) | WebPlanetKit 5.2 |
1대1 통화와 그룹 통화 모두 콜 셋업(call setup)이 완료된 후에만 콘텐츠 공유 API를 사용할 수 있습니다.
콘텐츠 공유 유형
LINE Planet에서 제공하는 콘텐츠 공유 방식에는 다음과 같은 유형이 있습니다.
| 콘텐츠 공유 유형 | 설명 | 비고 |
|---|---|---|
| 일반 공유 | 각 사용자가 자신의 데이터를 공유합니다. | |
| 독점적(exclusive) 공유 | 방에 있는 모든 사람에게 동일한 공유 데이터가 필요한 경우에 사용합니다. 자세한 내용은 독점적 공유를 참조하세요. | |
| 방 범위(room-scoped) 공유 | 공유 데이터의 수명이 방 범위로 지정됩니다. 자세한 내용은 방 범위 공유를 참조하세요. | 그룹 통화에서만 사용 가능 |
세 가지 유형의 콘텐츠 공유는 독립적이기 때문에 한 방 내에서 동시에 사용할 수 있습니다.
관련 API
통화 유형별로 콘텐츠 공유와 관련된 API를 설명합니다.
1대1 통화
1대1 통화에서 콘텐츠를 공유하려면 다음 메서드를 사용하세요.
그룹 통화
그룹 통화에서 콘텐츠를 공유하려면 다음 메서드를 사용하세요.
| 유형 | 메서드 | 설명 | 관련 이벤트 콜백 |
|---|---|---|---|
| 일반 공유 | setSharedContents() | 모든 피어와 공유할 공유 데이터 설정 | evtPeersSharedContentsSet |
| - | unsetSharedContents() | 이전에 설정한 공유 데이터 해제 | evtPeersSharedContentsUnset |
| 독점적 공유 | setExclusivelySharedContents() | 모든 피어와 공유할 독점적 공유 데이터를 설정 | evtPeerExclusivelySharedContentsSet |
| - | unsetExclusivelySharedContents() | 이전에 설정한 독점적 공유 데이터 해제 | evtPeerExclusivelySharedContentsUnset |
| 방 범위 공유 | setRoomSharedContents() | 방 안의 모든 피어와 공유할 방 범위 공유 데이터 설정 | evtPeerRoomSharedContentsSet |
| - | unsetRoomSharedContents() | 이전에 설정한 방 범위 공유 데이터 해제 | evtPeerRoomSharedContentsUnset |
피어에게 전달되는 정보
어떤 사용자가 공유 콘텐츠 설정 메서드 중 하나를 사용하여 데이터 공유를 시작하면 각각 해당하는 이벤트 콜백이 다른 사용자에게 호출되며, 이 콜백은 다음과 같은 정보를 전달합니다.
| 필드 | 설명 |
|---|---|
userId | 공유 콘텐츠를 설정한 사용자의 사용자 ID |
data | 공유 데이터 |
elapsedTimeAfterSetMs | 공유 데이터가 마지막으로 수정된 이후 경과된 시간(밀리초 단위) |
경과 시간 정보를 이용하여 공유 데이터를 마지막으로 수정한 이후 경과한 시간을 계산할 수 있습니다.
독점적 공유
'독점적 공유'라는 용어는 공유 데이터가 방(또는 통화) 내에 단 하나만 존재한다는 것을 의미합니다.
방에 있는 모든 사용자에게 동일한 공유 데이터가 필요하다면 setExclusivelySharedContents() 및 unsetExclusivelySharedContents()를 사용하세요.
독점적 공유 콘텐츠의 경우 setExclusivelySharedContents()를 호출한 참여자만이 공유 데이터를 수정할 수 있습니다.
방 범위 공유
PlanetKit은 방 범위 콘텐츠 공유를 위해 setRoomSharedContents() 및 unsetRoomSharedContents()를 제공합니다. 이 기능은 그룹 통화에서만 사용할 수 있으며 다음과 같은 특징이 있습니다.
- 데이터 수명
- 방 범위 콘텐츠 공유에서는
unsetRoomSharedContents()를 호출하지 않는다면 데이터의 수명과 방의 수명이 같습니다. - 반면,
setSharedContents()와setExclusivelySharedContents()로 공유한 데이터의 수명은 해당 API를 호출한 참여자에 따라 좌우됩니다. 즉 해당 참여자가 퇴장하면 데이터도 무효화됩니다. - 그와 달리
setRoomSharedContents()로 공유한 데이터는 모든 참여자가 퇴장하거나 누군가unsetRoomSharedContents()를 호출하지 않는 한 유지됩니다.
- 방 범위 콘텐츠 공유에서는
- 여러 명의 설정자와 하나의 인스턴스
- 방 범위 콘텐츠 공유에서
setRoomSharedContents()로 공유한 데이터는 모든 참여자가 변경할 수 있습니다. 따라서 공유 데이터의 값은 마지막으로 호출한setRoomSharedContents()에서 설정한 데이터가 됩니다. - 방 범위 콘텐츠 공유는 설정하는 사람이 여럿일 수 있다고 가정하므로 마지막 설정자가 떠나더라도 남은 참여자들은 관련 이벤트를 수신합니다.
- 방 범위 콘텐츠 공유에서
예제 - 발언하기 전에 손 들기
콘텐츠 공유 API 사용법을 알려주는 간단한 예제를 살펴보겠습니다. 이 예제는 독점적 공유가 무엇인지, 공유 데이터 구조를 어떻게 설계할 것인지 보여줍니다.
통화 참여자가 발언하기 전에 '손 들기'하는 기능을 콘텐츠 공유 API로 구현한다고 해 보겠습니다. 또한 '손 들기' 플래그는 단 3초(3,000 밀리초) 동안만 유효하다고 가정합니다.
첫 번째로, 참여자가 동시에 손을 들 수 있다고 가정합시다. 즉 여러 참여자가 손을 들 수 있습니다.
- 공유 데이터 구조: flag
- 발언하려는 사람은 누구든
flag=true로setSharedContents()를 호출합니다. evtPeersSharedContentsSet에 포함된 사용자 ID 정보를 통해 누가 발언하고자 하는지를 모든 참여자가 알게 됩니다.- '경과 시간 3,000 밀리초 미만' 조건을 만족하는 참여자만 손을 들 수 있습니다. 누군가 손을 든지 4,000 밀리초 이후에 입장한 새 참여자는
evtPeersSharedContentsSet를 받아서 누가 손을 들었는지 알 수는 있지만, 그 시점에 손을 들 수는 없습니다.
두 번째는 한 번에 한 발언자만 손을 들 수 있다고 가정합시다. 즉 오직 한 참여자만 손을 들 수 있습니다. 이 경우에는 마스터가 필요합니다. 마스터의 사용자 ID를 user-m이라고 가정합시다.
- 공유 데이터 구조: flag
- 마스터가
h-user-id=NULL, flag=false과 함께setExclusivelySharedContents()를 호출합니다. 이제부터 다른 참여자가setExclusivelySharedContents()를 호출하더라도 무시됩니다. - 발언하려는 사람은 누구든
user-m에게 sendShortData()를 호출합니다. - 마스터가 그중 단 한 명을 고릅니다. 이 사람을
user-a라고 가정합시다. - 마스터가
h-user-id=user-a, flag=true와 함께setExclusivelySharedContents()를 호출합니다. - 모든 참여자는
evtPeerExclusivelySharedContentsSet를 통해user-a(h-user-id)가 발언을 원한다(flag=true)는 것을 알게 됩니다.