tencent cloud

文档反馈

最后更新时间:2024-07-08 15:38:17

    概述

    信令接口是基于消息提供的一套邀请流程控制的接口,可以实现多种实时场景,例如:
    直播聊天室中进行上麦、下麦管理。
    聊天场景中实现音视频通话功能。
    教育场景中老师邀请同学们举手、发言的流程控制。

    功能

    信令接口支持以下功能:

    单聊邀请

    在使用 简单收发消息接口 或 富媒体消息接口 进行单聊的同时,可以使用 Invite 信令接口进行点对点呼叫,对方收到邀请通知 OnReceiveNewInvitation 后可以选择接受、拒绝或等待超时。

    群聊邀请

    首先需通过 建群加群退群解散群以及群资料 和 群成员 相关接口完成对群组的管理,并监听群内的相关事件回调 V2TIMGroupListener。然后群成员可以在群内发起群呼叫邀请 InviteInGroup,被邀请的群成员会收到邀请通知 OnReceiveNewInvitation 后可以选择接受、拒绝或等待超时。

    取消邀请

    邀请者可以在超时前且被邀请者未处理前取消邀请 Cancel。被邀请者会收到取消通知 OnInvitationCancelled,该邀请流程结束。
    
    
    

    接受邀请

    被邀请者收到邀请通知 OnReceiveNewInvitation 后可以在超时前且邀请者取消前接受邀请 Accept,邀请者会收到接受邀请通知 OnInviteeAccepted,所有被邀请者处理完后(包括接受、拒绝、超时)该邀请流程结束。
    
    
    

    拒绝邀请

    被邀请者收到邀请通知 OnReceiveNewInvitation后可以在超时前且邀请者取消前拒绝邀请 Reject,邀请者会收到拒绝邀请通知 OnInviteeRejected,所有被邀请者处理完后(包括接受、拒绝、超时)该邀请流程结束。

    邀请超时

    若邀请接口的超时时间大于0,且被邀请者未在超时时间之内响应则邀请超时,邀请者和被邀请者都会收到超时通知 OnInvitationTimeout,所有被邀请者处理完后(包括接受、拒绝、超时)该邀请流程结束。若邀请接口的超时时间等于0,则不会有超时通知。
    
    
    
    警告:
    必须在 login SDK 之前调用 addSignalingListener 添加信令监听器,否则可能导致以上功能收不到通知。

    应用场景案例

    音视频通话

    我们以1v1视频通话为例介绍下信令接口跟 TRTC SDK 的结合使用。
    1v1视频通话的流程
    1. 邀请者根据业务层生成的 roomID 进入该 TRTC 房间,同时调用信令邀请接口 Invite 发起音视频通话请求,并把 roomID 放到邀请接口的自定义字段中。
    2. 被邀请者收到信令邀请通知 OnReceiveNewInvitation,并通过自定义数据拿到 roomID,界面开始响铃。
    3. 被邀请者处理邀请通知:
    接受邀请需调用信令 Accept 接口,并根据 roomID 进入到 TRTC 房间,并同时调用 openCamera() 函数打开自己本地的摄像头,双方收到 TRTC SDK 的 OnRemoteUserEnterRoom 回调后记录本次通话的开始时间。
    拒绝邀请需调用信令 Reject 接口结束本次通话。
    如果被邀请者正在跟其他人通话,则调用信令 Reject 接口拒绝本次邀请,并在自定义数据中告诉对方是由于本地线路忙而拒绝。
    4. 接听并当双方的音视频通道建立完成后,通话的双方都会接收到 TRTC SDK 的 OnUserVideoAvailable 的事件通知,表示对方的视频画面已经拿到。此时双方用户均可以调用 TRTC SDK 接口 StartRemoteView 展示远端的视频画面。远端的声音默认是自动播放的。
    5. 通话结束即某一方挂断电话,该用户退出 TRTC 房间。对方收到 TRTC SDK 的 OnRemoteUserLeaveRoom 回调后计算通话总时长并再次发起一次邀请,此邀请的自定义数据中标明是结束通话并附带通话时长,方便 UI 界面做展示。
    
    

    老师邀请学生举手发言

    该场景为老师先让同学们举手,再从举手的同学中选一个同学进行发言。详细流程如下:
    1. 老师调用 InviteInGroup 接口邀请同学们举手,自定义 data 中填入“举手操作”,同学们收到 OnReceiveNewInvitation 回调。
    2. 同学们根据 OnReceiveNewInvitation 中的 inviteeList 和 data 字段判断被邀请者里有自己且是举手操作,那么调用  Accept 接口举手。
    3. 如果有学生举手,所有人都可以收到 OnInviteeAccepted 回调,判断 data 中的字段为“举手操作”,展示举手学生列表。
    4. 老师从举手成员列表中邀请某个同学进行发言,调用  InviteInGroup 接口,此时自定义 data 中填入“发言操作”,学生们都收到 OnReceiveNewInvitation 回调。
    5. 学生根据  OnReceiveNewInvitation 回调中的 inviteeList 和 data 字段判断被邀请者里有自己且是发言操作,则调用 Accept 接口发言。
    6. 如果有学生发言,所有人都可以收到  OnInviteeAccepted 回调,判断 data 中的字段为“发言操作”,展示发言成员列表。

    常见问题

    用户 A 邀请用户 B 时,用户 C 可以邀请用户 B 吗?
    SDK 提供的信令接口( iOS | Android | Windows )本身不限制邀请的逻辑,一个用户可以同时收到多个邀请信令。对于音视频通话场景,我们的 TUICalling 组件做了“忙线”提醒。
    发送信令邀请时,是否可以同时发送多个 Invite 请求?
    可以,上层根据实际业务需求加以区分。
    SDK 的信令接口只有邀请、同意/拒绝、取消,如何实现挂断操作?
    邀请操作,上层语义可以理解成请求建连。
    挂断操作,上层语义可以理解成请求挂断。
    可以使用 SDK 的邀请接口,结合自定义 data 来表示当前的邀请是请求建连还是请求挂断,由 Chat 透传给对端处理。
    发送信令邀请时,对于信令邀请超时的处理逻辑是怎么样的?
    当邀请发送方和接收方都在线时,超时信令由接收方触发,且发送方和接收方都会收到 OnInvitationTimeout回调。
    当接收方不在线时,超时信令由发送发触发,发送方会收到 OnInvitationTimeout 回调。
    超时信令均由 SDK 发出。
    离线再上线,会收到未超时的信令消息吗?
    App 冷启动(杀进程后再次点击 App 图标启动)时,根据聊天类型,有两种情况:
    如果是单聊,SDK 会自动同步所有信令消息。如果信令未超时,则会回调 OnReceiveNewInvitation
    如果是群聊,SDK 会自动同步最近 30 秒的消息,如果包含了未超时的信令消息,则会回调 OnReceiveNewInvitation。 App 热启动(App 在后台,点击 App 图标启动)时,不管是单聊还是群聊,都会同步所有的未超时信令消息,并回调 OnReceiveNewInvitation
    信令回调中 inviteID 是不是唯一的?
    是唯一的。inviteID 唯一标识了一组信令消息(包括邀请、同意/拒绝、超时)。
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持