Essential Reading for Beginners
Key Concepts
- Room
Non-Instant Rooms: Before using this SDK, you need to create a room using the WebAPI or by accessing the management system page. Once you have obtained the room number, you can exchange audio, video, and other data with other users in the same room.
Instant Rooms: You can directly call the SDK interface to create an instant room and then enter the room to interact with audio and video.
- User
You can enter the room via a web page, client application, or mobile app. Each client instance that connects to the room is referred to as a user.
- Audio and Video
Each user with available audio and video capture devices can publish their audio data separately, or publish both audio and video data simultaneously.
User Guide
- Enter and Exit the Room
Call the joinRoomWithHost: or joinRoomEx: interface to join the room. After successfully joining the room, you will receive the event roomManagerRoomJoined: (event for successful room join), and other users in the room will receive the event roomManagerUserJoined: (event for a user joining the room).
When you need to leave the room, you should call the leaveRoom: interface. After successfully leaving the room, you will receive the event roomManagerRoomLeft: (event for leaving the room), and other users in the room will receive the event roomManagerUserLeft: (event for a user leaving the room).
When encountering abnormal situations such as momentary network disconnections, you will also receive the event roomManagerOnConnectionLost (event for room connection interruption) or roomManagerDidOccurWarning (event for room connection interruption with reconnection). In such cases, you need to properly handle the relevant cleanup work for your project.
About User
Each client connected to the room is referred to as a user. The user's identity is uniquely identified by the userId. When you call the joinRoom interface, if you pass in a userId, the local user's userId will be the ID you set. If you do not pass one, the SDK will automatically generate a GUID as your userId. However, please note that in either case, the system does not allow two users with the same userId to exist in the same room. Therefore, when you enter the room using a userId that already exists in the room, the server will kick out the user who previously used this ID.
In addition to the userId, each user has some other properties (both predefined and custom). You can use the changeUserProperty interface to modify any property of any user and can specify which user(s) (or just yourself) to notify about this change. Subsequently, the specified user(s) will receive an event roomManagerUserPropertyChanged (user property changed), informing that some properties of a certain user have been modified.
- Audio and Video
You can call the publishVideo and publishAudio interfaces to publish your own audio and video. Once a user starts publishing audio and video data, all users in the room will receive the events roomManagerOnUserVideoStatus and roomManagerOnUserAudioStatus. It is important to note that even if you do not publish your own video, you can always call playVideo to view your own video image. If you do not want to watch a certain user's video, you can call unPlayVideo to stop viewing it.
You can call the unPublishAudio and unPublishVideo interfaces to unpublish your own audio or video. Once a user unpublishes both their audio and video, all users in the room will receive the events roomManagerOnUserVideoStatus and roomManagerOnUserAudioStatus. At this point, you need to call unPlayVideo and unPlayAudio to stop watching other people's videos and listening to their audio.
- Custom Signaling
By using the custom signaling interface, you can implement various business processes you have designed and create exciting user experiences. We have abstracted all types of signaling into messages. Similar to users, messages have their own ID (msgId) and nickname (msgName). The nickname can be the same as other messages, but the ID must be unique within the room. If two messages have the same ID, the later one will replace the previous one. In addition to these two properties, messages also have the following attributes:
• toId: Who will receive the notification of this message. You can fill in the target user's peerID (which can be yourself), or you can use one of the following four macro definitions:
• TKRoomPubMsgTellAllExceptSender: Notify everyone except the caller.
• TKRoomPubMsgTellAllExceptAuditor: Notify everyone except the auditor.
• TKRoomPubMsgTellNone: Do not notify anyone.
• TKRoomPubMsgTellAll: Notify everyone.
• data: Data (can be NSNumber, NSString, NSDictionary, or NSArray).
• save: Whether to save. When set to true, the server will save this message in the room, and new users entering the room will receive this message. If two messages with the same ID and the need to be saved are sent consecutively, the server will only save the latter one. When set to false, the server will discard the message after forwarding it.
The specific process is as follows:
When you call the pubMsg interface to publish a message, all specified users will receive the event roomManagerOnRemotePubMsgWithMsgID (pubMsg message event).
If this message is specified to be saved, then users who enter the room later will receive an array of all saved and undeleted messages currently on the server. After publishing a message, you can call the pubMsg interface again to publish a message with the same ID to overwrite it, and the specified users will receive the event (pubMsg message publication event) once more. You can also call the delMsg interface to delete this message, at which point the specified users will receive the event (delMsg message deletion event).
