Subsessions

Subsessions allow you to breakout users in a session into separate "subsessions" evenly or manually by userId. A Video SDK session can have up to 50 subsessions.

Init subsessions

After joining a session, call client.getSubsessionClient() to get the subsession client.

const subsession = client.getSubsessionClient();

Configure subsessions

Sessions can be configured by the host.

Create subsessions

To create a subsession, call the subsession.createSubsessions() function. For the first parameter, pass in an array of your subsession names. You can also pass in a number instead of an array, to specify the amount of subsessions you want created and the name will generate automatically.

The second parameter is if you want to assign users to the subsessions automatically or manually. The default is Manually.

• Passing in 1 will distribute users evenly to each subsession.
• Passing in 2 will allow you to assign users to a subsession manually.

subsession.createSubsessions(["subsessionName1", "subsessionName2"], 1);

Manually assign users to a subsession

Retrieve the subsession status using subsession.getSubsessionStatus(). Depending on the current status, there are two approaches to assigning users:

1. Subsessions not started (SubsessionStatus.NotStarted or SubsessionStatus.Closed). You can pre-assign users to subsessions by passing a subsessionList when calling subsession.openSubsessions(). Each item in the list can include not only the subsessionId and subsessionName, but also a userList. This allows users to be assigned to their respective subsessions at the time the subsessions are opened.

   const subsessionList = subsession.getSubsessionList();
   function assignUserToSubsessionBeforeStarted(
       userId,
       subsessionId,
       subsessionList,
   ) {
       const session = subsessionList.find(
           (item) => item.subsessionId === subsessionId,
       );
       if (session) {
           const { userList } = session;
           if (!userList.find((user) => user.userId == userId)) {
               userList.push({ userId });
           }
       }
   }
   

2. Subsessions already started (SubsessionStatus.InProgress). In this case, use the subsession.assignUserToSubsession(userId,subsessionId) method to dynamically assign users to the active subsessions.

Open subsessions

After configuring your subsessions, call the subsession.openSubsessions() function to start the subsessions. You can pass in an option object to specify a timer, and if the users can leave the subsession.

subsession.openSubsessions(subsession.getSubsessionList(), {
    isTimerEnabled: true,
    timerDuration: 1800,
});

See the corresponding event listener.

Manage subsessions

Subsessions can be managed by the host. Users can interact with sessions and the host.

Broadcast to subsessions

To broadcast a string to all subsessions, call the subsession.broadcast() function. This is only available to the host.

subsession.broadcast("Hello World");

See the corresponding event listener.

Chat in subsession

Users can chat in a subsession. The SDK scopes the chat to the subsession the user is in.

Ask for help

To have users notify the host in a subsession that their attention is needed, call the subsession.askForHelp() function.

subsession.askForHelp();

See the corresponding event listener.

Postpone response to help

To have the host respond to the user who requested help that they are on the way, call the subsession.postponeHelping() function.

subsession.postponeHelping(userId);

See the corresponding event listener.

List Users in a subsession

To list subsessions including users in the subsession, call the subsession.getSubsessionList() function. If the host calls this function they will get all the subsessions. If a user calls the function, they will get their current subsession.

subsession.getSubsessionList();

List Users not in a subsession

To list users who are not in a subsession, call the subsession.getUnassignedUserList() function.

subsession.getUnassignedUserList();

Navigate subsessions

Users can navigate and be navigated to subsessions.

Join Subsession

To join a subsession, call the subsession.joinSubsession() function. This function is useful to place a user who joins the session after the subsessions have been opened.

subsession.joinSubsession(subsessionId);

Leave subsession

To leave a subsession, call the subsession.leaveSubsession() function.

subsession.leaveSubsession();

Move User to Subsession

To have the host move a user to a subsession, call the subsession.moveUserToSubsession() function.

subsession.moveUserToSubsession(userId, subsessionId);

Close subsessions

To close all subsessions, call the subsession.closeAllSubsessions() function.

subsession.closeAllSubsessions();

Event listeners

Event listeners are available to keep track of state within subsessions.

Open subsessions event listener

If you opened your subsessions with a timer configured, you can use the subsession-countdown event listener to display a countdown timer.

client.on("subsession-countdown", (payload) => {
    console.log(payload);
});

Broadcast to subsessions event listener

Use the subsession-broadcast-message event listener to receive the broadcasted string.

client.on("subsession-broadcast-message", (payload) => {
    console.log(payload);
});

Ask for help event listener

Use the subsession-ask-for-help event listener to receive the user's request for help.

client.on("subsession-ask-for-help", (payload) => {
    console.log(payload);
});

Postpone response to help event listener

Use the subsession-ask-for-help-response event listener to receive the hosts response for help. There are four possible response types:

• The response type of 0 (Received) indicates the host received the ask for help event.
• The response type of 1 (Busy) indicates the host is already in a different subsession.
• The response type of 2 (Ignore) indicates the host responded with the subsession.postponeHelping() function.
• The response type of 3 (AlreadyInRoom) indicates the host is already in the same subsession.

client.on("subsession-ask-for-help-response", (payload) => {
    console.log(payload);
});

More subsession features

For the full set of subsession features, see SubsessionClient in the Video SDK Reference.