Sessions

A session is the most fundamental building block of the Video SDK. A session is similar to but not limited to a virtual meeting where two or more users can communicate with each other over video and audio. You can also include other features in a session, such as chat and screen sharing.

Create and join a session

To create a session, you must provide a session name to uniquely identify it.

The process of creating and joining a session requires the developer's SDK JWT. When you create and join a session through the Video SDK, you must provide a string value representing the session name. The name determines whether the SDK joins an existing session or creates a new one. See Authorization for details.

• If you call joinSession() with a session name and there is no session currently active with that name, the SDK creates the session for you.
• If a session with that name is currently active, the SDK lets you join the active session if you provide all the required parameters, for example, a password if one has been set for the session.

Sessions become inactive and available for reuse after you call leaveSession() to end a session or the backend closes the session when there are no longer any users in that session.

The session name only needs to be unique to your app at the developer account level. For instance, developers with separate developer accounts (separate SDK credentials) can use the same session name for their separate apps (for example, App A and App B). While the names are the same, Zoom creates different unique sessions for both of these apps. Two different apps built with the Video SDK cannot join sessions created by the other. Each app can only join a session that it created.

To create a session through the SDK, create an instance of ZoomVideoSDKSessionContext and provide the userName, sessionName, and JWT as shown below.

Create SDKSessionContext

val params = ZoomVideoSDKSessionContext().apply {
    sessionName = "My Session"
    userName = "My Name"
    token = "" // TODO: Pass in your JWT. In a production app, ensure that you do not hard code JWT or any confidential credentials.
}

ZoomVideoSDKSessionContext params = new ZoomVideoSDKSessionContext();
params.sessionName = "My Session";
params.userName = "My Name";
params.token = ""; // TODO: Pass in your JWT

Prior to joining a session, ensure that you have implemented an instance of the ZoomVideoSDKDelegate. To successfully monitor events related to a session, you will need to use some important callback functions provided by the delegate.

Once you have your params and listener setup, call the joinSession() method to join a session.

Join a session

val session = ZoomVideoSDK.getInstance().joinSession(params)

ZoomVideoSDKSession session = ZoomVideoSDK.getInstance().joinSession(params);

Note that the return value of the joinSession() method will only indicate that an attempt will be made to join a session. A successful result here does not mean you are in the session already.

To determine the status after calling joinSession(), you must listen for specific callbacks, some of which may require user interaction.

Once you have obtained the session object, you may also use it to display your video preview. More information on how to do this can be found in the Render User Video section.

Obtain session information

Upon joining a session, you may need to obtain various pieces of information about the session itself. To do this, retrieve an instance of the ZoomVideoSDKSession object through the SDK.

Join a session

val session = ZoomVideoSDK.getInstance().session
session.sessionName
session.sessionPassword
session.sessionHost
session.sessionHostName

ZoomVideoSDKSession session = ZoomVideoSDK.getInstance().getSession();
session.getSessionName();
session.getSessionPassword();
session.getSessionHost();
session.getSessionHostName();

For a full list of available information on the session object, refer to the ZoomVideoSDKSession reference documentation.

Leave a session

To leave a session, you must call leaveSession() and indicate whether or not you would like to end the session if you are the host of the session.

// A value of true will end the session if you are the host
ZoomVideoSDK.getInstance().leaveSession(shouldEndSession)

// A value of true will end the session if you are the host
ZoomVideoSDK.getInstance().leaveSession(shouldEndSession);

Configure audio and video

When creating or joining a session, you may also choose to configure the audio and video options of the session. This can be done through ZoomVideoSDKAudioOption and ZoomVideoSDKVideoOption respectively.

Configure audio and video options

// Setup audio options
val audioOptions = ZoomVideoSDKAudioOption().apply {
    connect = true // Auto connect to audio upon joining
    mute = true // Auto mute audio upon joining
}
// Setup video options
val videoOptions = ZoomVideoSDKVideoOption().apply {
    localVideoOn = true // Turn on local/self video upon joining
}
// Pass options into session
val params = ZoomVideoSDKSessionContext().apply {
    audioOption = audioOptions
    videoOption = videoOptions
}

// Setup audio options
ZoomVideoSDKAudioOption audioOptions = new ZoomVideoSDKAudioOption();
audioOptions.connect = true; // Auto connect to audio upon joining
audioOptions.mute = true; // Auto mute audio upon joining
// Setup video options
ZoomVideoSDKVideoOption videoOptions = new ZoomVideoSDKVideoOption();
videoOptions.localVideoOn = true; // Turn on local/self video upon joining
// Pass options into session
ZoomVideoSDKSessionContext params = new ZoomVideoSDKSessionContext();
params.audioOption = audioOptions;
params.videoOption = videoOptions;

See Video and Audio for details.

Get user information

Each user joining a session is represented by an instance of the ZoomVideoSDKUser object. Within this object lives an ID which uniquely identifies the user within the current session.

User information

While in a session, you can retrieve the following information of a user:

• User
• Display name
• Video status
• Audio status
• Share status
• Video Statistic Information
• Share Statistic Information
• Custom Identity (set on JWT payload)

You can retrieve this information by using the ZoomVideoSDKUser.

Get all users

To get the information of users, call the getRemoteUsers method in ZoomVideoSDKSession to get an array of all users:

val userList = session.remoteUsers

List<ZoomVideoSDKUser> userList = session.getRemoteUsers();

User roles and actions

People in a session can hold one of the following roles: host, manager, or participant.

Host

The user with the host role_type is the host of the session.

A host of the session has the following privileges.

• View information of users in the session.
• Change the display name of a user in the session.
• Mute or unmute a user's audio.
• Transfer the host role to someone else in the session.
• Promote another user to be a manager of the session.
• Remove participants from the session.
• Revoke manager privilege from a user.
• Start a live stream.
• Prevent other users from sharing their screen (lock screen).
• End the session.

Manager

The manager or co-host role can be assigned to a participant by the host to help the host to manage the session participants.

A manager of the session is assigned the following subset of the host privileges.

• Remove participants from a session.
• Change the display name of a user in the session.
• Mute or unmute a user's audio.
• Prevent other users from sharing their screen (lock screen).

Participant

A regular user who joins the session without host or manager permission. A participant has privileges to view their own information as well as the information of other users.

Manage users

See below for details on how to manage users.

Change display name

If you are the host, you can change your display name while in the session using the changeName method. If you are the host or manager, you may also change the display name of other users:

userHelper.changeName("MyName", user)

userHelper.changeName("MyName", user);

Transfer host privilege to another user

If you are the host of a session, you may transfer your host role to another user.

userHelper.makeHost(user)

userHelper.makeHost(user);

Assign manager privilege to another user

Managers can help the session host to manage the users. If the host would like to promote a user to be a manager, the following interface must be used to assign a user to be a manager:

Please note that if a user is already a host or a manager, re-assigning will have no impact.

userHelper.makeManager(user)

userHelper.makeManager(user);

Revoke manager privilege

The host can revoke the manager role from a user by using the following method:

userHelper.revokeManager(user)

userHelper.revokeManager(user);

Remove user from a session

Users with either host or manager privilege can remove users from a session.

userHelper.removeUser(user)

userHelper.removeUser(user);

Callbacks

All of these callbacks can be found within your ZoomVideoSDKDelegate implementation. See Integrate for details.

• onSessionNeedPassword - Called when a user is trying to join a session which requires a password. The handler.inputSessionPassword method will allow the user to attempt to join this session with the password provided into this method. After calling this method, you will still need to listen for additional callbacks related to joining the session such as onSessionJoin to determine whether or not the user joined the session.
• onSessionJoin - Called when you have successfully joined the session.
• onSessionPasswordWrong - Called if the last password entered was incorrect. The user may attempt to enter the password again through the same method described in onSessionNeedPassword. Alternatively, the user may stop trying to enter the session by calling handler.leaveSessionIgnorePassword() method.
• onError - Called when an error has occurred. See Integrate for a list of errors.

The following are some examples of callbacks you can use for session events.

Get notified when users join a session

override fun onUserJoin(userHelper: ZoomVideoSDKUserHelper?, userList: MutableList<ZoomVideoSDKUser>) {
    userList.forEach {
        // Access user info for each user that has joined
    }
}

@Override
public void onUserJoin(ZoomVideoSDKUserHelper userHelper, List<ZoomVideoSDKUser> userList) {
    for (ZoomVideoSDKUser user : userList) {
        // Access user info for each user that has joined
    }
}

Get notified when users leave a session

override fun onUserLeave(userHelper: ZoomVideoSDKUserHelper?, userList: MutableList<ZoomVideoSDKUser>) {
    userList.forEach {
        // Access user info for each user that has left
    }
}

@Override
public void onUserLeave(ZoomVideoSDKUserHelper userHelper, List<ZoomVideoSDKUser> userList) {
    for (ZoomVideoSDKUser user : list) {
        // Access user info for each user that has left
    }
}

Get notified when the host of the session is changed

override fun onUserHostChanged(userHelper: ZoomVideoSDKUserHelper?, userInfo: ZoomVideoSDKUser?) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

@Override
public void onUserHostChanged(ZoomVideoSDKUserHelper userHelper, ZoomVideoSDKUser userInfo) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

Get notified when a user attempts to join a session without entering a required password

override fun onSessionNeedPassword(handler: ZoomVideoSDKPasswordHandler?) {
    // Try entering password again
    handler?.inputSessionPassword("anotherPassword")
    // Leave the session without trying
    handler?.leaveSessionIgnorePassword()
}

@Override
public void onSessionNeedPassword(ZoomVideoSDKPasswordHandler handler) {
    // Try entering the password again
    handler.inputSessionPassword("anotherPassword");
    // Leave the session without trying
    handler.leaveSessionIgnorePassword();
}

Get notified when a user enters an incorrect password while attempting to join a session

override fun onSessionPasswordWrong(handler: ZoomVideoSDKPasswordHandler?) {
    // Try entering password again
    handler?.inputSessionPassword("anotherPassword")
    // Leave the session without trying
    handler?.leaveSessionIgnorePassword()
}

@Override
public void onSessionPasswordWrong(ZoomVideoSDKPasswordHandler handler) {
    // Try entering the password again
    handler.inputSessionPassword("anotherPassword");
    // Leave the session without trying
    handler.leaveSessionIgnorePassword();
}

Get notified when you have successfully joined the session

override fun onSessionJoin() {
    // You have successfully joined the session
}

@Override
public void onSessionJoin() {
    // You have successfully joined the session
}

Get notified when you have successfully left the session

override fun onSessionLeave() {
    // You have successfully left the session
}

@Override
public void onSessionLeave() {
    // You have successfully left the session
}

Get notified when the current user is the new host

override fun onUserManagerChanged(user: ZoomVideoSDKUser) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

@Override
public void onUserManagerChanged(ZoomVideoSDKUser zoomVideoSDKUser) {
    // Recommended action: check if current user is the new host and update UI if applicable
}

Get notified when the user name changed

override fun onUserNameChanged(user: ZoomVideoSDKUser) {
    // Recommended action: get new username and update UI if applicable
}

@Override
public void onUserNameChanged(ZoomVideoSDKUser zoomVideoSDKUser) {
    // Recommended action: get new username and update UI if applicable
}