- Documentation
- Video Call
- Best practices
- Implement a video call for multiple users
Implement a video call for multiple users
Introduction
This document describes how to implement a video call for multiple users, and you can use this document as a best practice for implementing a video scenario that enables multiple users to publish and play video streams simultaneously.
Prerequisites
Before you begin, make sure you complete the following steps:
- ZEGO Express SDK has been integrated into the project to implement basic real-time audio and video functions. For details, please refer to Quick start .
- A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information .
Implementation process
The following diagram shows the basic process of the video call for multiple users:
Create a ZegoExpressEngine
instance
To create a singleton instance of the ZegoExpressEngine class, call the createEngineWithProfile
method with the AppID of your project.
To receive event callbacks, implement an event handler object that conforms to the ZegoEventHandler
protocol (for example, self
), and then pass the implemented event handler object to the createEngineWithProfile
method as the eventHandler
parameter.
Alternatively, you can pass nil
to the createEngineWithProfile
method as the eventHandler
parameter for now, and then call the method setEventHandler
to set up the event handler after creating the engine.
ZegoEngineProfile *profile = [ZegoEngineProfile new];
// The AppID value you get from the ZEGO Admin console.
profile.appID = appID;
// Use the general scenario.
profile.scenario = ZegoScenarioGeneral;
// Create a ZegoExpressEngine instance and set eventHandler to [self]. If eventHandler is set to [nil], no callback will be received. You can set up the event handler later by calling the [-setEventHandler:] method.
[ZegoExpressEngine createEngineWithProfile:profile eventHandler:self];
Enable the event notification
To receive the event notification that other users join or leave the room, you must set the isUserStatusNotify
property of the room configuration parameter ZegoRoomConfig
to true
every time the user logs in to a room.
ZegoRoomConfig *roomConfig = [ZegoRoomConfig defaultConfig];
roomConfig.isUserStatusNotify = YES;
[[ZegoExpressEngine sharedEngine] loginRoom:@"room_id_1" user:[ZegoUser userWithUserID:@"user_id_1"] config:roomConfig];
Listen for and handle the event callbacks
To implement the video call for multiple users feature, you will need to listen for and handle the event callbacks related to room users and streams. To listen for and handle the related event callbacks, call the setEventHandler
method.
To receive the event notification for updates on the status of other users in the room, call the onRoomUserUpdate
method. And when other users join or leave the room, the SDK sends out the event notification through this callback.
The updateType
parameter in the callback onRoomUserUpdate
indicates the type of changes, details are listed below:
Change type | Enumerated values | Description |
---|---|---|
User joins | ZegoUpdateTypeADD | New users join the room. The userList indicates the list of new users. |
User leaves | ZegoUpdateTypeDELETE | Users leave the room. The userList indicates the list of users who have logged out. |
When a user joins a room for the first time, if there are already other users in the room, the new user will receive a user list (the event notification when updateType
is ZegoUpdateTypeADD
) through this callback, which includes the existing users in the room.
- To receive the
onRoomUserUpdate
callback, you must set theisUserStatusNotify
property of the room configuration parameterZegoRoomConfig
totrue
when you call theloginRoom
method to log in to a room. - This callback turns invalid when there are more than 500 users in the room.
//Callback for updates on the status of other users in the room (other users join or leave the room).
- (void)onRoomUserUpdate:(ZegoUpdateType)updateType userList:(NSArray<ZegoUser *> *)userList roomID:(NSString *)roomID {
// Update the UI or implement other operations here.
}
To receive the event notification for updates on the status of the streams in the room, call the onRoomStreamUpdate
callback. And when new streams are published to the room or existing streams in the room stop, the SDK sends out the event notification through this callback.
The updateType
parameter in the callback onRoomStreamUpdate
indicates the type of changes, details are listed below:
Change type | Enumerated values | Description |
---|---|---|
New stream publishes | ZegoUpdateTypeADD | New streams published to the room. The streamList indicates the list of newly published streams. |
Existing stream stops | ZegoUpdateTypeDELETE | Existing streams in the room stop. The streamList indicates the list of stopped streams. |
When a user joins a room for the first time, if there is stream publishing ongoing, the new user will receive a stream list (the event notification when updateType
is ZegoUpdateTypeADD
) through this callback, which includes the newly published streams in the room.
- (void)onRoomStreamUpdate:(ZegoUpdateType)updateType streamList:(NSArray<ZegoStream *> *)streamList extendedData:(NSDictionary *)extendedData roomID:(NSString *)roomID {
//Implement the callback handling logic as needed.
}
Start publishing/playing a stream
To start the stream publishing and playing, see Implement a basic video call.
API call sequence diagram
The following diagram shows the API call sequence of the stream publishing and playing process: