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 = ZMVideoSDK.shared().getSubSessionHelper() {
    // Continue with subsession methods here
}

Configure subsessions

Sessions can be configured only by the host.

Once you have the subsession names, call the following methods as needed to create the committed list of subsessions:

  • 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 ZMVideoSDKSubSessionStatus value and a list of ZMVideoSDKSubSessionKit objects. Each kit contains the subsession's name, ID, user list, and the joinSubSession method.

subsessionHelper.getCommittedSubSessionList()
subsessionHelper.withdrawSubSessionList()
subsessionHelper.commitSubSessionList(["Session 1", "Session 2", "Session 3"])
func onSubSessionStatusChanged(_ status: ZMVideoSDKSubSessionStatus, subSessionKit subSessionKitList: [ZMVideoSDKSubSessionKit]?) {
}
// ZMVideoSDKSubSessionStatus
enum ZMVideoSDKSubSessionStatus {
    ZMVideoSDKSubSessionStatus_None,
    ZMVideoSDKSubSessionStatus_Committed,
    ZMVideoSDKSubSessionStatus_Withdrawn,
    ZMVideoSDKSubSessionStatus_Started,
    ZMVideoSDKSubSessionStatus_Stopping,
    ZMVideoSDKSubSessionStatus_Stopped,
    ZMVideoSDKSubSessionStatus_CommitFailed,
    ZMVideoSDKSubSessionStatus_WithdrawFailed,
    ZMVideoSDKSubSessionStatus_StartFailed,
    ZMVideoSDKSubSessionStatus_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 ZMVideoSDKSubSessionManager or ZMVideoSDKSubSessionParticipant object upon receiving the respective callback, as the local user will be using its dedicated methods later on.

var subsessionUser: ZMVideoSDKSubSessionParticipant?
var subsessionManager: ZMVideoSDKSubSessionManager?
// Subsession manager role
public func onSubSessionManagerHandle(_ manager: ZMVideoSDKSubSessionManager?) {
    guard let manager = manager else {
        print("Warning: onSubSessionManagerHandle received nil manager.")
        return
    }
    subsessionManager = manager
}
// Subsession user role
public func onSubSessionParticipantHandle(_ user: ZMVideoSDKSubSessionParticipant?) {
    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 onSubSessionUserHelpRequest callback. After a manager responds to this request, the subsession user who requested help will receive the onSubSessionUserHelpRequestResult callback.
// Subsession user role
guard let user = subsessionUser else {
    print("Warning: subsessionUser is nil — cannot perform actions.")
    return
}
user.returnToMainSession()
user.requestForHelp()

List users in a subsession

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

func onSubSessionUsersUpdate(_ subSessionKit: ZMVideoSDKSubSessionKit?) {
    subSessionKit?.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 ZMVideoSDKSubSessionStatus_Started status, you can identify which ZMVideoSDKSubSessionKit they can join by calling joinSubSession.

guard status == ZMVideoSDKSubSessionStatus_Started, let subSessionKitList = subSessionKitList else { return }
// From the subSessionKitList, identify which 1 of the subSessionKit to join
for subSessionKit in subSessionKitList {
    // Identify which subSessionKit first then join
    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
func onSubSessionUserHelpRequestResult(_ result: ZMVideoSDKUserHelpRequestResult) {
}
enum ZMVideoSDKUserHelpRequestResult {
    ZMVideoSDKUserHelpRequestResult_Idle,
    ZMVideoSDKUserHelpRequestResult_Busy,
    ZMVideoSDKUserHelpRequestResult_Ignore,
    ZMVideoSDKUserHelpRequestResult_HostAlreadyInSubSession
}

Manager responds to request for help

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

func onSubSessionUserHelpRequest(_ handler: ZMVideoSDKSubSessionUserHelpRequestHandler) {
    handler.requestUserName
    handler.requestSubSessionName
    handler.ignore()
    handler.joinSubSessionByUserRequest()
}

Chat in subsession

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

More details

See the ZMVideoSDKSubsessionHelper.h File Reference for more details.