Create, Join, and Leave a Session

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

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 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.

  • 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 participants 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 ZMVideoSDKSessionContext and provide the userName, sessionName, and JWT as shown below.

Create a SessionContext Object

ZMVideoSDKSessionContext *sessionContext = [[ZMVideoSDKSessionContext alloc] init];
// Ensure that you do not hard code JWT or any other confidential credentials in your production app.
sessionContext.token = @"Your jwt";
sessionContext.sessionName = @"Your session name";
sessionContext.userName = @"Your name";
sessionContext.sessionPassword = @"Your session password";
ZMVideoSDKSession *session = [[ZMVideoSDK sharedZMVideoSDK] joinSession:sessionContext];
if (session) {
// Session joined successfully.
}
let sessionContext = ZMVideoSDKSessionContext()
// Ensure that you do not hard code JWT or any other confidential credentials in your production app.
sessionContext.token = "Your jwt"
sessionContext.sessionName = "Your session name"
sessionContext.userName = "Your name"
sessionContext.sessionPassword = "Your session password"
if let session = ZMVideoSDK.shared()?.joinSession(sessionContext) {
// Session joined successfully.
}

The following table describes all the properties of the sessionContext object:

NameRequiredNote
sessionNameYesName and unique identifier of the session. A user will be able to join the session by entering the session name. Should be alphanumeric with a max-length of 150 characters. It can include symbols and the space character. See the tpc value in the JWT payload in Authentication for details.
userNameYesDisplay name of the user shown in the session. If empty, this display name will be shown as null. It does not have any length limits.
tokenYesJWT token generated from your SDK credentials, for more details, refer to the Authentication guide.
sessionPasswordNoPassword for session. If set, the session will be private and can only be joined if the user provides a valid password. If not set, the session will be public for anyone in your account. To join, they must use sessionName only. The field has a max-length limit of 10 characters.
audioOptionNoConfigure audio settings by storing values in ZMVideoSDKAudioOptions.
videoOptionNoConfigure video settings by storing values in ZMVideoSDKVideoOptions.

Prior to joining a session, ensure that you have set up a delegate for callback events by conforming your class to the ZMVideoSDKDelegate protocol and using ZMVideoSDK.shared()?addListener(self) or [[ZMVideoSDK sharedZMVideoSDK] addListener:self];. To successfully monitor events related to a session, you will need to use some important callback functions.

Once you have your context and delegate set up, call the joinSession() method to join a session.

ZMVideoSDKSession *session = [[ZMVideoSDK sharedZMVideoSDK] joinSession:sessionContext];
if (session) {
// Session joined successfully.
}
if let session = ZMVideoSDK.shared()?.joinSession(sessionContext) {
// Session joined successfully.
}

Note that the return value of the joinSession() method will return the session you are attempting to join.

To retrieve further information about the joinSession attempt, you must listen for specific callbacks, some of which may require user interaction.

Important callbacks

All of these callbacks can be found within your ZMVideoSDKDelegate implementation. For information on how to implement this and add it to the SDK, refer to the Listen for callback events guide.

  • onSessionJoin() — This is called when the current user has joined the session.
  • onSessionLeave() — This is called when the current user has left the session.
  • onError(_ ErrorType: ZMVideoSDKErrors, detail details: Int) — This is called when the ZMVideoSDK encounters an error (for example, failure to join a session, network timeouts, etc.). The value ZMVideoSDKErrors_Success (rawValue: 0) represents a successful callback without errors.
  • onUserJoin(_ userHelper: ZMVideoSDKUserHelper!, userList userArray: [ZMVideoSDKUser]!) — This is called when any user joins the session. The helper is provided to provide user-related functionality. The userArray represents the updated array of user IDs of users who have joined the session.
  • onUserLeave(_ userHelper: ZMVideoSDKUserHelper!, userList userArray: [ZMVideoSDKUser]!) — This is called when any user leaves the session. The helper is provided to provide user-related functionality. The userArray represents the updated array of user IDs of users who have left the session.
  • onSessionNeedPassword(_ handle: ZMVideoSDKpasswordHandler!) — This is called when attempting to join a session that requires a password, but no password was provided. A ZMVideoSDKPasswordHandler is provided to allow the user to retry joining the session.
  • onSessionPasswordWrong(_ handle: ZMVideoSDKPasswordHandler!) — This is called when attempting to join a session that requires a password, but the provided password was incorrect. A ZMVideoSDKPasswordHandler is provided to allow the user to retry the password.

Leave a session

When you are ready to leave the session, you must call the leaveSession() method and indicate whether or not you would like to end the session for everyone if you are the host.

// A value of true will end the session, if you are the host.
[[ZMVideoSDK sharedZMVideoSDK] leaveSession:shouldEndSession];
// A value of true will end the session, if you are the host.
ZMVideoSDK.shared()?.leaveSession(shouldEndSession)

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.