시그널링 관리
Overview
Signaling APIs are a set of invitation process control APIs based on IM messages. They can be used to implement a variety of real-time features, including:
Mic-on or mic-off management in audio-video chat rooms
Chatting: audio/video calls as those in WeChat
Control of the process for teachers to invite students to "raise hands" and speak in education scenarios
Features
Signaling APIs support the following features:
One-to-one chat invitation
When the API for sending and receiving simple messages or the API for sending and receiving rich media messages is used for a one-to-one chat, the invite signaling API can be used to make a point-to-point call. After receiving the invitation onReceiveNewInvitation, the receiver can accept or reject the invitation, or wait for the invitation to time out.
Group chat invitation
First, you need to manage the group through APIs such as those for creating a group, joining a group, leaving a group, and disbanding a group, as well as group profile and group member APIs, and listen for relevant group callbacks through V2TimGroupListener. Then group members can send a call invitation in the group through inviteInGroup. The invitee will receive the invitation onReceiveNewInvitation and can accept or reject the invitation, or wait for the invitation to time out.
Canceling an invitation
An inviter can call cancel to cancel the invitation, if it is not processed by the invitee before the timeout period. The invitee will receive the cancellation notification onInvitationCancelled, and the invitation process ends.
Accepting an invitation
After receiving the invitation onReceiveNewInvitation, the invitee can call accept to accept the invitation, if it is not canceled by the inviter before the timeout period. The inviter will receive the acceptance notification onInviteeAccepted. After the invitation is processed by the invitee, for example, it is accepted or rejected, or times out, the invitation process ends.
Rejecting an invitation
After receiving the invitation onReceiveNewInvitation, the invitee can call reject to reject the invitation, if it is not canceled by the inviter before the timeout period. The inviter will receive the rejection notification onInviteeRejected. After the invitation is processed by the invitee, for example, it is accepted or rejected, or times out, the invitation process ends.
Invitation timeout
If the timeout period of the invitation API is larger than 0, and the invitee doesn't respond to the invitation within the timeout period, the invitation times out, and both the inviter and the invitee will receive the timeout notification onInvitationTimeout. After the invitation is processed by the invitee, for example, it is accepted or rejected, or times out, the invitation process ends. If the timeout period of the invitation API is 0, there will be no timeout notification.
Use Cases
Audio/Video call
In the open-source project TRTCFlutterScenesDemo, we developed an audio/video call solution suitable for one-to-one and multi-person chatting based on TRTC. You can directly modify the demo for adaptation. The following takes the one-to-one video call process as an example to introduce how signaling APIs work with the TRTC SDK.
One-to-one video call process:
1. The inviter enters the TRTC room based on the room ID generated at the service layer and calls the signaling invitation API invite to initiate an audio/video call request, including the room ID in the custom field of the invitation API.
2. The invitee receives the signaling invitation onReceiveNewInvitation and gets the
roomID
through the custom data. The UI rings.3. The invitee processes the invitation notification:
To accept the invitation, the invitee needs to call the accept signaling API, enter the TRTC room based on the
roomID
, and call the openCamera()
function to enable the local camera. The inviter and the invitee receive the onRemoteUserEnterRoom
callback from the TRTC SDK, and their systems record the start time of the call.To reject the invitation, the invitee needs to call the reject signaling API to end the call.
If the invitee is on the call, the invitee can call the reject signaling API to reject the invitation and notify the inviter through the custom data that the invitation is rejected due to the busy local line.
4. After the invitee answers the call and the audio/video channel between the inviter and invitee is established, both the inviter and invitee will receive the
onUserVideoAvailable
event notification from the TRTC SDK, which indicates that they have received each other's video image. At this point, they can call the startRemoteView
API of the TRTC SDK to display the remote video image, and the remote audio will be automatically played back by default.5. After the call ends (either the inviter or invitee hangs up), the party who hangs up exits the TRTC room. The other party receives the
onRemoteUserLeaveRoom
callback from the TRTC SDK, and its system calculates the total duration of the call and initiates an invitation again. The custom data in the invitation specifies the call end event and call duration to facilitate UI display.Flowchart
Teacher inviting students to raise their hand and speak
In this scenario, the teacher asks students to raise hands and then chooses one of the students to speak. The process is as follows:
1. The teacher calls the inviteInGroup API to invite students to "raise hands", specifying the "hand raising" operation in the custom field
data
. The students receive the onReceiveNewInvitation callback.2. The students check the
inviteeList
and data
fields in onReceiveNewInvitation to determine whether they are invited to raise their hand. Then they call the accept API to raise their hand.3. If a student raises her/his hand, others can receive the onInviteeAccepted callback. The system determines that the
data
field is hand raising and displays the list of students who raise hands.4. The teacher invites one of the students raising their hand to speak and calls the inviteInGroup API. Here, the custom field
data
is specified as "speaking". The students receive the onReceiveNewInvitation callback.5. The students check the
inviteeList
and data
fields in the onReceiveNewInvitation callback to determine whether they are invited to speak. Then they call the accept API to speak.6. If one of the students speaks, all the students will receive the onInviteeAccepted callback, which contains the
data
field specified as "speaking" and displays the list of speaking students.