Signaling Management (iOS)

Last updated: 2020-07-31 11:40:00

    Overview

    Signaling APIs are a set of invitation process control APIs that are provided based on IM messages to implement various real-time scenarios, such as:

    • Mic-on and mic-off management in live streaming chat rooms.
    • Voice and video call feature in chat scenarios, similar to the voice and video call feature of WeChat.
    • Process control for teachers to invite students to raise their hands and speak in turn in education scenarios.

    Features

    Signaling APIs support the following features:

    One-to-one chat invitation

    While using the Simple Message APIs or Rich Media Message APIs for a one-to-one chat, you can use the invite signaling API to make a one-to-one call, and when receiving the invitation notification onReceiveNewInvitation, the other party can choose to accept or reject the call or wait until it times out.

    Group chat invitation

    First, complete group management by using the APIs for creating a group, joining a group, quitting a group, disbanding a group, group profile and group members. Listen for relevant event callback in the group via V2TIMGroupListener. Then, group members can initiate a group call invitation inviteInGroup in the group, and when receiving the invitation notification onReceiveNewInvitation, the invited group member can choose to accept or reject the call or wait until it times out.

    Canceling an invitation

    Before an invitation times out or is processed by the callee, the caller can cancel the invitation. The invitee will receive the cancellation notification onInvitationCancelled, and the invitation process ends.

    Canceling an invitation

    Accepting an invitation

    When receiving an invitation notification onReceiveNewInvitation, the callee can accept the invitation before the invitation times out or is canceled by the caller. If the invitation is accepted, the caller will receive the invitation acceptance notification onInviteeAccepted. After all callees finish processing the invitation (through acceptance, rejection, and timeout), the invitation process ends.

    Accepting/Rejecting an invitation

    Rejecting an invitation

    When receiving an invitation notification onReceiveNewInvitation, the callee can reject the invitation before the invitation times out or is canceled by the caller. If the invitation is rejected, the caller will receive the invitation rejection notification onInviteeRejected. After all callees finish processing the invitation (through acceptance, rejection, and timeout), the invitation process ends.

    Invitation timeout

    If the timeout threshold of the invitation API is greater than 0 and the callee does not respond before the timeout threshold is reached, then the invitation times out, and both the caller and callee will receive the timeout notification onInvitationTimeout. After all callees finish processing the invitation (through acceptance, rejection, and timeout), the invitation process ends. If the timeout threshold is 0, there is no timeout notification.

    Invitation timeout

    Application Scenarios Cases

    Voice and video calls

    In the open-source project TUIKit Demo, we provide a solution for one-to-one and one-to-many voice and video call scenarios on the basis of the TRTC component with minor modifications. You can directly make modifications or adaptations based on our demo. In this document, we introduce the combined use of signaling APIs and the TRTC SDK by using a 1v1 video call scenario as an example.

    1v1 video call process:

    1. Based on the roomID generated by the service layer, the caller enters the TRTC room and calls the signaling invitation API invite to initiate a voice and video call request. The roomID is placed in the custom field of the invitation API.
    2. The callee receives the signaling invitation notification onReceiveNewInvitation and obtains the roomID from the custom data. The interface starts ringing.
    3. The callee processes the invitation notification:
      • If the callee accepts the invitation, call the accept signaling API. Then, the callee enters the TRTC room based on the roomID and calls the openCamera() function to activate the callee’s local camera. After both parties receive the onRemoteUserEnterRoom callback of the TRTC SDK, record the start time of this call.
      • If the callee rejects the invitation, call the reject signaling API to end this call.
      • If the callee is in a call with another user, call the reject signaling API to reject the invitation, and in the custom data, inform the caller that the invitation was rejected because the line was busy.
    4. After the callee answers the call and a voice and video channel is established between the two parties, both parties will receive the onUserVideoAvailable event notification of the TRTC SDK, indicating that each party has obtained the video image of the other party. At this time, both parties can call the TRTC SDK API startRemoteView to display the video image from the other party. The voice from the other party is automatically played by default.
    5. When either party hangs up, the call ends, and the user quits the TRTC room. After the other party receives the onRemoteUserLeaveRoom callback of the TRTC SDK, calculate the total call duration, and initiate an invitation again. The custom data in this invitation indicates the end of the call with the call duration attached to facilitate UI display.

    Timing diagram
    Signaling combined with TRTC

    Teachers invite students to raise their hands and speak in turns in education scenarios

    In this scenario, the teacher first asks students to raise their hands, and then choose one of the students to speak. The detailed process is as follows:

    1. The teacher calls the inviteInGroup API to invite students to raise their hands. In the custom data field, enter “raise hands”. Students receive the onReceiveNewInvitation callback.
    2. Based on the inviteeList and data fields in onReceiveNewInvitation, students know that they are invited to raise their hands. Therefore, call the accept API to accept the invitation.
    3. If one or more students raise their hands, all users receive the onInviteeAccepted callback. Detect “raise hands” in the data field, and display the list of students who raised their hands.
    4. From the list of students who raised their hands, the teacher invites a student to speak. Call the inviteInGroup API, and in the custom data field, enter “speak”. Students then receive the onReceiveNewInvitation callback.
    5. Based on the inviteeList and data fields in onReceiveNewInvitation, the student knows that he or she is invited to speak. Therefore, call the accept API to accept the invitation.
    6. If the student speaks, all users receive the onInviteeAccepted callback. Detect “speak” in the data field, and display the list of students who speak.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help