Essential Reading for Beginners
Key Concepts
Room
- Non-Real-Time Room: 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.
- Real-Time Room: You can directly call the SDK interface joinRoomEx to enter the room and start audio and video interaction.
User
You can enter the room using 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 own audio data separately, or publish both audio and video data simultaneously.
User Guide
Enter and Exit the Room
Call the joinRoom or joinRoomEx interface to join the room. After successfully joining the room, you will receive the event TK.EVENT_TYPE.roomConnected (Room Joined Successfully event), and at the same time, other users in the room will receive the event TK.EVENT_TYPE.roomParticipantJoin (User Joined Room event).
When you need to leave the room, you should call the leaveRoom interface. After successfully leaving the room, you will receive the event TK.EVENT_TYPE.roomLeaveRoom (Leave Room event), and at the same time, other users in the room will receive the event TK.EVENT_TYPE.roomParticipantLeave (User Left Room event).
When encountering abnormal situations such as network disconnections, you will also receive the event TK.EVENT_TYPE.roomDisconnected (Room Connection Disconnected event). In such cases, you need to perform the necessary cleanup operations for your project.
About User
Each client connected to the room is referred to as a user. The identity of a user 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 one you set. If you don't pass in a userId, the SDK will automatically generate a guid as your userId. However, please note that the system does not allow two users with the same userId to exist in the same room. Therefore, when you use a userId that already exists in the room to enter the room, the server will kick out the user who previously used this userId.
In addition to the userId, each user also has some other attributes (both predefined and custom). You can use the changeUserProperty interface to modify any attribute of any user, and you can specify which user(s) (or just yourself) should be notified of this change. Subsequently, the specified user(s) will receive an event TK.EVENT_TYPE.roomUserPropertyChanged (indicating that a user's property has changed), informing that certain attributes of a particular 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 TK.EVENT_TYPE.roomUserAudioStateChanged and TK.EVENT_TYPE.roomUserVideoStateChanged. It is important to note that you do not need to publish the local user's video; you can always call playVideo to view your own video image. If you do not want 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 stops publishing both audio and video, all users in the room will receive the events TK.EVENT_TYPE.roomUserVideoStateChanged and TK.EVENT_TYPE.roomUserAudioStateChanged. At this time, you need to call unplayVideo and unplayAudio to stop viewing other people's videos and listening to their audio.
Custom Signaling
By utilizing the custom signaling interface, you can accomplish a variety of business processes that 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 and name. The name can be duplicated with other messages, but the id must be unique within the room. If messages have the same id, the later one will replace the previous one. In addition to these two attributes, messages also have the following properties:
| Property Name | Description |
|---|---|
| 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 a predefined identity set, see Message Sending Roles |
| data | Data (can store various data structures, including numbers, strings, and JSON) |
| 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 marked for saving are sent consecutively, the server will only save the latter one. When set to false, the server will discard this message immediately after forwarding it |
The specific process is as follows:
1.When you call the pubMsg interface to publish a message, all specified users will receive the event TK.EVENT_TYPE.roomPubmsg (Custom Message Published)
2.If this message is designated to be saved, then subsequently, users who newly enter the room will receive an array of all currently saved and non-deleted messages from the server in the data of the event TK.EVENT_TYPE.roomConnected (Room Connection Successful)
3.After publishing a message, you can call the pubMsg interface again to publish a message with the same id to overwrite it. Then, the specified users will receive the event TK.EVENT_TYPE.roomPubmsg (Room Custom Message Published) once again
4.You can also call the delMsg interface to delete the message. At this time, the specified users will receive the event TK.EVENT_TYPE.roomDelmsg (Custom Message Deleted)
