Contents sharing

The contents sharing API allows a user to share time-dependent data with peers. Shared data can be of any type, but it must be limited to a maximum size of 1 kilobyte.

Supported call type	Minimum SDK version
1-to-1 call, group call (conference)	PlanetKit 3.2 (Room-scoped sharing: PlanetKit 3.6.15)

Tip

In both 1-to-1 calls and group calls, contents sharing APIs are available only after the call setup is completed.

Types of contents sharing

LINE Planet provides the following types of contents sharing.

Contents sharing type	Description	Note
Normal sharing	Each user shares their own data.
Exclusive sharing	Everyone in a room needs the same shared data. For more information, see Exclusive sharing.
Room-scoped sharing	The lifetime of the shared data is scoped to the room. For more information, see Room-scoped sharing.	Available in group calls only

Note

Since the three types of contents sharing are independent, they can be operated simultaneously within a room.

Related APIs

This sections describes the APIs related to contents sharing by call type.

1-to-1 call

To share contents in 1-to-1 calls, use the following methods of PlanetKitCall.

Type	Method	Description	Related event callback
Normal sharing	setSharedContents() iOS, macOS	Sets shared data to be shared with all peers	peerDidSetSharedContents iOS, macOS
-	unsetSharedContents() iOS, macOS	Clears previously set shared data	peerDidUnsetSharedContents iOS, macOS
Exclusive sharing	setExclusivelySharedContents() iOS, macOS	Sets exclusively shared data to be shared with all peers	peerDidSetExclusivelySharedContents iOS, macOS
-	unsetExclusivelySharedContents() iOS, macOS	Clears previously set exclusively shared data	peerDidUnsetExclusivelySharedContents iOS, macOS

Group call

To share contents in group calls, use the following methods of PlanetKitConference.

Type	Method	Description	Related event callback
Normal sharing	setSharedContents() iOS, macOS	Sets shared data to be shared with all peers	peersDidSetSharedContents iOS, macOS
-	unsetSharedContents() iOS, macOS	Clears previously set shared data	peersDidUnsetSharedContents iOS, macOS
Exclusive sharing	setExclusivelySharedContents() iOS, macOS	Sets exclusively shared data to be shared with all peers	peerDidSetExclusivelySharedContents iOS, macOS
-	unsetExclusivelySharedContents() iOS, macOS	Clears previously set exclusively shared data	peerDidUnsetExclusivelySharedContents iOS, macOS
Room-scoped sharing	setRoomSharedContents() iOS, macOS	Sets room shared data to be shared with all peers in the room	peerDidSetRoomSharedContents iOS, macOS
-	unsetRoomSharedContents() iOS, macOS	Clears previously set room shared data	peerDidUnsetRoomSharedContents iOS, macOS

Information delivered to peers

Once a user starts to share data using one of the methods for setting shared contents, other users are notified by the corresponding event callback, which delivers the following information:

Field	Description
peer	Information of the peer who set the shared data
data	Shared data
elapsed	Elapsed time since the shared data was last modified (in milliseconds)

The elapsed time lets you calculate how much time has passed since the last modification of the shared data.

Exclusive sharing

The term "exclusive sharing" means that there is only one instance of the shared data for the room (or the call).

Use setExclusivelySharedContents() and unsetExclusivelySharedContents() if everyone in a room needs the same shared data.

Note

In case of exclusively shared contents, only the participant who called setExclusivelySharedContents() can modify the shared data.

Room-scoped sharing

PlanetKit provides setRoomSharedContents() and unsetRoomSharedContents() for room-scoped content sharing. This feature is available in group calls only and has the following characteristics:

• Data lifetime
  • In room-scoped content sharing, unless you call unsetRoomSharedContents(), the lifetime of the data and the lifetime of the room are the same.
  • On the other hand, the lifetime of data shared by setSharedContents() and setExclusivelySharedContents() depends on the participant who called the API. Therefore, when the participant leaves, the data is also invalidated.
  • However, data shared by setRoomSharedContents() is maintained until all participants leave or someone calls unsetRoomSharedContents().
• Multi-setter and one instance
  • In room-scoped content sharing, data shared by setRoomSharedContents() can be changed by all participants. Therefore, the value of the data will be the one set by the last called setRoomSharedContents().
  • Room-scoped content sharing assumes that there can be multiple setters, so even if the last setter leaves, the remaining participants will receive the related event.

Example: Raise hands before speaking

Let's look at a simple example that shows you how to use the contents sharing APIs. This example illustrates what exclusive sharing is and how to design the structure of shared data.

Suppose you plan to implement a feature that allows a participant to "raise hands" before speaking, using the contents sharing API. In addition, let's assume that the "raise hands" flag is valid only for 3 seconds (3000 msec).

The first case assumes the participants can raise hands at the same time, so multiple participants can raise hands.

1. The structure of shared data is flag.
2. Anyone who wants to speak calls setSharedContents() with the flag=true.
3. All participants become aware of who wants to speak through the user ID in peersDidSetSharedContents.
4. Only participants who meet the condition of "elapsed time < 3000 msec" can raise hands. Consequently, when a new participant joins after 4000 msec, the participant will be notified of who raised hands by peersDidSetSharedContents but will not be eligible for raising hands.

The second case assumes that only one speaker can raise hands at one time, so only one participant can raise hands. This case requires a master participant. Let's assume that user-m is the user ID of the master.

1. The structure of shared data is flag.
2. The master calls setExclusivelySharedContents() with h-user-id=NULL, flag=false. From this moment on, calling of setExclusivelySharedContents() by other participants are ignored.
3. Anyone who wants to speak calls sendShortData() to user-m.
4. The master picks only one participant (assume user-a).
5. The master calls setExclusivelySharedContents() with (h-user-id=user-a, flag=true).
6. All participants become aware that user-a (h-user-id) wants to speak (flag=true) through peerDidSetExclusivelySharedContents.