内容介绍
TRTC SDK 提供了发送自定义消息的功能,通过该功能,角色为主播的用户都可以向同一个视频房间里的其他用户广播自己的定制消息。
支持的平台
iOS | Android | Mac OS | Windows | Electron | Flutter | 微信小程序 | |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | × | ✓ |
说明:
Web 端参考接口文档:trtc.sendCustomMessage。
微信小程序端客户,可通过 IM 提供的即时通信来实现。登录 IM 后发送消息来进行业务逻辑处理,详情请参见 Web&小程序&uni-app SDK API。
发送接收原理
某一个用户的自定义消息会被夹在音视频数据流中,随着音视频数据一起传输给房间里的其他用户。由于音视频线路本身并不是100%可靠的,为了提高可靠性,TRTC SDK 内部本身实现了一些可靠性保护机制。
消息发送
通过调用 TRTCCloud 的
sendCustomCmdMsg
接口发送的,发送时需要指定四个参数:参数名 | 参数说明 |
cmdID | 消息ID,取值范围为 1 ~ 10,不同业务类型的消息应当使用不同的 cmdID。 |
data | 待发送的消息,最大支持 1KB(1000字节)的数据大小。 |
reliable | 是否可靠发送,可靠发送的代价是会引入一定的延时,因为接收端要暂存一段时间的数据来等待重传。 |
ordered | 是否要求有序,即是否要求接收端接收的数据顺序和发送端发送的顺序一致,这会带来一定的接收延时,因为在接收端需要暂存并排序这些消息。 |
注意:
1、请将 reliable 和 ordered 同时设置为 YES 或 NO,暂不支持交叉设置。
2、仅主播身份可以发送自定义消息。
//发送自定义消息的示例代码- (void)sendHello {// 自定义消息命令字, 这里需要根据业务定制一套规则,这里以0x1代表发送文字广播消息为例NSInteger cmdID = 0x1;NSData *data = [@"Hello" dataUsingEncoding:NSUTF8StringEncoding];// reliable 和 ordered 目前需要一致,这里以需要保证消息按发送顺序到达为例[trtcCloud sendCustomCmdMsg:cmdID data:data reliable:YES ordered:YES];}
//发送自定义消息的示例代码public void sendHello() {try {// 自定义消息命令字, 这里需要根据业务定制一套规则,这里以0x1代表发送文字广播消息为例int cmdID = 0x1;String hello = "Hello";byte[] data = hello.getBytes("UTF-8");// reliable 和 ordered 目前需要一致,这里以需要保证消息按发送顺序到达为例trtcCloud.sendCustomCmdMsg(cmdID, data, true, true);} catch (UnsupportedEncodingException e) {e.printStackTrace();}}
// 发送自定义消息的示例代码void sendHello(){// 自定义消息命令字, 这里需要根据业务定制一套规则,这里以0x1代表发送文字广播消息为例uint32_t cmdID = 0x1;uint8_t* data = { '1', '2', '3' };uint32_t dataSize = 3; // data的长度// reliable 和 ordered 目前需要一致,这里以需要保证消息按发送顺序到达为例trtcCloud->sendCustomCmdMsg(cmdID, data, dataSize, true, true);}
// 发送自定义消息的示例代码private void sendHello(){// 自定义消息命令字, 这里需要根据业务定制一套规则,这里以0x1代表发送文字广播消息为例uint cmdID = 0x1;byte[] data = { '1', '2', '3' };uint dataSize = 3; // data的长度// reliable 和 ordered 目前需要一致,这里以需要保证消息按发送顺序到达为例mTRTCCloud.sendCustomCmdMsg(cmdID, data, dataSize, true, true);}
// send custom messagetrtc.sendCustomMessage({cmdId: 1,data: new TextEncoder().encode('hello').buffer});
//发送自定义消息的示例代码sendHello() {try {// 自定义消息命令字, 这里需要根据业务定制一套规则,这里以0x1代表发送文字广播消息为例int cmdID = 0x1;String hello = "Hello";// reliable 和 ordered 目前需要一致,这里以需要保证消息按发送顺序到达为例trtcCloud.sendCustomCmdMsg(cmdID, hello, true, true);} catch (e) {print(e);}}
消息接收
当房间中的一个用户通过
sendCustomCmdMsg
发出自定义消息后,房间中其他的用户可以通过 SDK 回调中的 onRecvCustomCmdMsg
接口来接收这些消息。//接收和处理房间内其他人发送的消息- (void)onRecvCustomCmdMsgUserId:(NSString *)userId cmdID:(NSInteger)cmdId seq:(UInt32)seq message:(NSData *)message{// 接收到 userId 发送的消息switch (cmdId) // 发送方和接收方协商好的cmdId{case 0:// 处理cmdId = 0消息break;case 1:// 处理cmdId = 1消息break;case 2:// 处理cmdId = 2消息break;default:break;}}
//继承 TRTCCloudListener,实现 onRecvCustomCmdMsg 方法接收和处理房间内其他人发送的消息public void onRecvCustomCmdMsg(String userId, int cmdId, int seq, byte[] message) {// 接收到 userId 发送的消息switch (cmdId) // 发送方和接收方协商好的cmdId{case 0:// 处理cmdId = 0消息break;case 1:// 处理cmdId = 1消息break;case 2:// 处理cmdId = 2消息break;default:break;}
// 接收和处理房间内其他人发送的消息void TRTCCloudCallbackImpl::onRecvCustomCmdMsg(const char* userId, int32_t cmdId, uint32_t seq, const uint8_t* msg, uint32_t msgSize){// 接收到 userId 发送的消息switch (cmdId) // 发送方和接收方协商好的cmdId{case 0:// 处理cmdId = 0消息break;case 1:// 处理cmdId = 1消息break;case 2:// 处理cmdId = 2消息break;default:break;}}
// 接收和处理房间内其他人发送的消息public void onRecvCustomCmdMsg(string userId, int cmdId, uint seq, byte[] msg, uint msgSize){// 接收到 userId 发送的消息switch (cmdId) // 发送方和接收方协商好的cmdId{case 0:// 处理cmdId = 0消息break;case 1:// 处理cmdId = 1消息break;case 2:// 处理cmdId = 2消息break;default:break;}}
// receive custom messagetrtc.on(TRTC.EVENT.CUSTOM_MESSAGE, event => {// event.userId: 远端发消息的 userId// event.cmdId: 您自定义的消息 Id// event.seq: 消息的序号// event.data: 消息内容,ArrayBuffer 类型console.log(`received custom msg from ${event.userId}, message: ${new TextDecoder().decode(event.data)}`)})
// 注册trtc回调trtcCloud.registerListener(_onRtcListener);// 实现 onRecvCustomCmdMsg 方法接收和处理房间内其他人发送的消息_onRtcListener(type, param) async {if (type == TRTCCloudListener.onRecvCustomCmdMsg) {// 接收到 userId 发送的消息String userId = param['userId'];// 发送方和接收方协商好的cmdIdswitch (param['cmdID']) {case 0:// 处理 cmdID = 0 消息break;case 1:// 处理 cmdID = 1 消息break;case 2:// 处理 cmdID = 2 消息break;default:break;}}}
使用限制
由于自定义消息享受比音视频数据更高的传输优先级,如果自定义数据发送过多,音视频数据可能会被干扰到,从而导致画面卡顿或者模糊。所以,我们针对自定义消息的发送进行了如下的频率限制:
自定义消息会被云广播给房间内所有用户,所以每秒最多能发送 30 条消息。
每个消息包(即 data 的大小)最大为 1 KB,超过则很有可能会被中间路由器或者服务器丢弃。
每个客户端每秒最多能发送总计 8 KB 数据,也就是如果每个数据包都是 1KB,那么每秒钟您最多只能发送 8 个数据包。