Subsessions

Subsessions allow you to create separate sessions that users can choose to join. This is similar to the breakout room feature in Zoom Meetings. A Video SDK session can have up to 50 subsessions.

Call the subsession helper

After joining a session, call getsubSessionHelper to get the subsession helper. This method can be called only by the session's host and manager.

if let subsessionHelper = ZoomVideoSDK.shareInstance()?.getsubSessionHelper() {
	// Continue with subsession methods here
}

Configure subsessions

Sessions can be configured only by the host.

To prepare the subsession list, call the following methods as needed:

  • addSubSession(toPreList: "Array of subsession names") - Add subsessions to the prepared list and pass in an array of your subsession names.
  • getSubSessionPreList - Get the added subsession prepared list.
  • removeSubSession(fromPreList: "Array of subsession names") - Remove any subsessions from the added prepared list.
  • clearSubSessionPreList - Remove all subsessions from the added prepared list.
subsessionHelper.addSubSession(toPreList: ["Subsession 1", "Subsession 2", "Subsession 3"])
subsessionHelper.getSubSessionPreList()
subsessionHelper.removeSubSession(fromPreList: ["Subsession 3"])
subsessionHelper.clearSubSessionPreList()

Once you are satisfied with the prepared list and ready to create the committed list, call the following methods as needed:

  • commitSubSessionList - Withdraw all committed subsession lists and commit the prepared list.
  • getCommittedSubSessionList - Get the committed subsession list. Calling this right after commitSubSessionList will not work, as you will have to wait for the onSubSessionStatusChanged callback to get successful creation.
  • withdrawSubSessionList - Withdraw the committed subsession list.

The SDK calls onSubSessionStatusChanged whenever the committed subsession lists change. The callback returns a ZoomVideoSDKSubSessionStatus value and a list of ZoomVideoSDKSubSessionKit objects. Each kit provides the subsession's name, ID, user list, and joinSubSession method.

subsessionHelper.commitSubSessionList()
subsessionHelper.getCommittedSubSessionList()
subsessionHelper.withdrawSubSessionList()
public func onSubSessionStatusChanged(_ status: ZoomVideoSDKSubSessionStatus, subSession pSubSessionKitList: [ZoomVideoSDKSubSessionKit]) {
}
// ZoomVideoSDKSubSessionStatus
enum ZoomVideoSDKSubSessionStatus {
    case ZoomVideoSDKSubSessionStatus_None,
    case ZoomVideoSDKSubSessionStatus_Committed,
    case ZoomVideoSDKSubSessionStatus_Withdrawn,
    case ZoomVideoSDKSubSessionStatus_Started,
    case ZoomVideoSDKSubSessionStatus_Stopping,
    case ZoomVideoSDKSubSessionStatus_Stopped,
    case ZoomVideoSDKSubSessionStatus_CommitFailed,
    case ZoomVideoSDKSubSessionStatus_WithdrawFailed,
    case ZoomVideoSDKSubSessionStatus_StartFailed,
    case ZoomVideoSDKSubSessionStatus_StopFailed,
}

Manage subsessions

The host and managers can manage subsessions from the main session. The SDK calls these callbacks based on the following scenarios:

  • onSubSessionManagerHandle - The local user has the subsession manager role.
  • onSubSessionParticipantHandle - The local user has the subsession user role.

We recommended that you save an instance of the ZoomVideoSDKSubSessionManager or ZoomVideoSDKSubSessionParticipant object upon receiving the respective callback, as the local user will be using its dedicated methods later on.

var subsessionUser: ZoomVideoSDKSubSessionParticipant?
var subsessionManager: ZoomVideoSDKSubSessionManager?
// Subsession manager role
public func onSubSessionManagerHandle(_ manager: ZoomVideoSDKSubSessionManager?) {
    guard let manager = manager else {
        print("Warning: onSubSessionManagerHandle received nil manager.")
        return
    }
    subsessionManager = manager
}
// Subsession user role
public func onSubSessionParticipantHandle(_ user: ZoomVideoSDKSubSessionParticipant?) {
    guard let user = user else {
        print("Warning: onSubSessionParticipantHandle received nil user.")
        return
    }
    subsessionUser = user
}

Subsession manager

Both the main session's host and managers hold the subsession manager role. The subsession manager role can call the following methods:

  • startSubSession - Start subsessions.
  • stopSubSession - Stop subsessions.
  • isSubSessionStarted - Determine if subsessions have started.
  • broadcastMessage(message: String) - Broadcast a message from the main session to all subsessions. Upon a successful broadcast, the SDK calls the onBroadcastMessage callback.
// Subsession manager role
guard let subsessionManager = subsessionManager else { return }
subsessionManager.startSubSession()
subsessionManager.stopSubSession()
subsessionManager.isSubSessionStarted()
subsessionManager.broadcastMessage("Hello World")

Subsession user

The user role can call the following methods:

  • returnToMainSession - Leave subsession and return to the main session.
  • requestForHelp - Request the manager's help. This can be used to notify and request that a manager come into the subsession. The manager will receive the onSubSessionUserHelpRequestHandler callback. After a manager responds to this request, the subsession user who requested help will receive the onSubSessionUserHelpRequestResult callback.
// Subsession user role
guard let subsessionUser = subsessionUser else { return }
subsessionUser.returnToMainSession()
subsessionUser.requestForHelp()

List users in a subsession

To list users in a specific subsession, call getSubSessionUserList. Each ZoomVideoSDKSubSessionUser object contains the local subsession user's username and GUID. When subsession users are changed, the SDK calls onSubSessionUsersUpdate and returns an updated ZoomVideoSDKSubSessionKit object.

public func onSubSessionUsersUpdate(_ pSubSessionKit: ZoomVideoSDKSubSessionKit) {
    pSubSessionKit.getSubSessionUserList()
}

Navigate subsessions

Users can navigate across different subsessions.

Join subsession

Hosts and managers can't assign users to subsessions, but users can join a subsession once it has started. You can offer them a choice of which subsession to join. Upon receiving the onSubSessionStatusChanged callback with the ZoomVideoSDKSubSessionStatus_Started status, you can identify which ZoomVideoSDKSubSessionKit they can join by calling joinSubSession.

// subSessionKit is an instance of ZoomVideoSDKSubSessionKit
subSessionKit.joinSubSession()

Leave subsession

To leave a subsession and return to the main session, call the returnToMainSession method from the previously saved subsessionUser object.

subsessionUser?.returnToMainSession()

Request help

All users in subsessions can request that the manager come into their subsession. The manager will be notified of these help requests and can take a follow-up action, which will also be sent back to the requester.

Subsession user request for help

To request help, the user in a subsession can send a requestForHelp call to notify and request that the manager come into the subsession. After the manager responds to the request, the user who requested help will receive the onSubSessionUserHelpRequestResult callback.

// User requested help
subsessionUser?.requestForHelp()
// User received back the result
public func onSubSessionUserHelpRequestResult(_ result: ZoomVideoSDKUserHelpRequestResult) {
}
enum ZoomVideoSDKUserHelpRequestResult {
    ZoomVideoSDKUserHelpRequestResult_Idle = 0,
    ZoomVideoSDKUserHelpRequestResult_Busy,
    ZoomVideoSDKUserHelpRequestResult_Ignore,
    ZoomVideoSDKUserHelpRequestResult_HostAlreadyInSubSession
}

Manager responds to request for help

Whenever a user in a subsession requests help, the manager receives the onSubSessionUserHelpRequestHandler callback. The manager can decide what to do with the received ZoomVideoSDKSubSessionUserHelpRequestHandler, which contains the user information and the subsession name.

public func onSubSessionUserHelpRequestHandler(_ pHandler: ZoomVideoSDKSubSessionUserHelpRequestHandler) {
    pHandler.getRequestUserName()
    pHandler.getRequestSubSessionName()
    pHandler.ignore()
    pHandler.joinSubSessionByUserRequest()
}

Chat in subsession

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

More details

See the ZoomVideoSDKSubSessionHelper Class Reference for more details.