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 interface. With the obtained room number, you can exchange audio, video, and other data with users in the same room.
• Instant Rooms: Directly call the SDK interface to create an instant room, and you can enter the room for audio and video interaction.

User

You can enter the room using a web page, client, or mobile app. Each client instance that joins the room is referred to as a user.

A/V

Every user with available audio and video capture devices can publish their own audio data individually, and can also publish audio and video data simultaneously.

User Guide

Entering and Leaving a Room

Call the joinRoom or joinRoomEx interface to join a room. After successfully joining the room, you will receive the event onRoomJoined (event indicating successful room entry), and other users in the room will receive the event onUserJoined (event indicating that a user has joined the room).

When you need to leave the room, you must call the leaveRoom interface. After successfully leaving the room, you will receive the event onRoomLeaved (event for leaving the room), and other users in the room will receive the event onUserLeft (event indicating that a user has left the room)

When encountering network flickering or other abnormal situations, you will also receive the event onConnectionLost (room connection lost event). In such cases, you need to perform the relevant cleanup work for your project.

About User

Each client connected to a room is referred to as a user. The identity of a user is uniquely identified by userId. When you call the joinRoom interface, if you pass a userId, the local user’s userId will be the one 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 a room using a userId that already exists in the room, the server will remove the previous user who used this ID from the room.

In addition to userId, each user has other attributes (both predefined and custom). You can use the changeUserProperty interface to modify any attribute of any user and specify which user(s) to notify of this change (or just yourself). Subsequently, the specified users will receive an event onUserPropertyChanged (user property changed), informing them that certain attributes of a user have been modified.

A/V

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 onUserVideoStatus and onUserAudioStatus. It is important to note that you do not need to publish the local user’s video to be able to call playVideo at any time to watch your own video image. If you do not wish to watch a particular user’s video, you can call unPlayVideo to stop viewing it.

You can call the unPublishAudio and unPublishVideo interfaces to stop publishing your own audio or video. Once a user has stopped publishing both their audio and video, all users in the room will receive the events onUserVideoStatus and onUserAudioStatus. At this point, you need to call unPlayVideo and unPlayAudio to cancel watching other people’s videos and listening to other people’s audio.

Custom Signaling

Using the custom signaling interface, you can complete various business processes you design and create exciting user experiences. We have abstracted all signaling into messages, similar to users, messages have their own ID (msgId) and nickname (msgName). Nicknames can be the same as other messages, but the ID must be unique within the room; messages with the same ID will have the latter replacing the former. In addition to these two attributes, messages also have these properties:

• 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 fill in the following 4 definitions:
• ALL_EXCEPT_SENDER: Notify everyone except the caller.
• ALL_EXCEPT_AUDITOR: Notify everyone except the auditor users.
• NONE: Do not notify anyone.
• ALL: Notify everyone.
• data: The data content of the message.
• save: Whether to save the message. When set to true, the server will save the message within the room, and new users entering the room will receive this message. If two messages with the same ID that need to be saved are sent consecutively, the server will only save the latter one. When set to false, the server will discard this 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 onRemotePubMsg (pubMsg message event).If this message is designated to be saved, then new users entering the room later will receive an array of all saved and undeleted messages from the current server. After publishing the 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 again (pubMsg message published event). Alternatively, you can call the delMsg interface to delete this message, at which point the specified users will receive the event (delMsg message deleted event).