互动视频
  • iOS : Objective-C
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • 小程序
  • Electron
  • 概述
  • 限制说明
  • SDK 下载
  • 快速开始
  • 常用功能
  • 推拉流进阶
  • 视频进阶
  • 音频进阶
  • 其他功能
  • 废弃接口
  • API 文档
  • 常见错误码
  • 常见问题
  • AI教育
  • KTV 合唱
  • 视频直播
  • 视频通话
  • 游戏直播
  • 直播答题
  • 娃娃机
  • 文档中心
  • 互动视频
  • 常用功能
  • 实时消息

实时消息

更新时间:2022-08-18 14:29

1 功能简介

ZegoLiveRoom SDK 内集成了实时消息功能,实现了直播间内的 发消息点赞送礼物等互动功能,同时提供高并发场景下大房间消息指定用户消息房间附加信息等特殊场景 API。

1.大房间消息适用于高并发的场景,当高并发达到极限时会根据策略丢弃部分消息。发消息、点赞、送礼物等普通房间消息以及大房间消息 API 在ZegoLiveRoom/ZegoLiveRoomApi-IM.h文件中。 2.向指定用户发消息适用于向房间指定用户发消息场景。API 在ZegoLiveRoom/ZegoLiveRoomApi.h文件中。 3.房间附加信息适用于设置房间状态,低频操作的场景。API 在ZegoLiveRoom/ZegoLiveRoomApi-RoomExtraInfo.h文件中。

相关功能的 Demo 源码,请联系 ZEGO 技术支持获取。

2 房间消息

2.1 使用步骤

下面以 A、B 用户的交互来说明房间消息的使用,时序图如下:

2.1.1 设置实时消息代理对象

消息接收端在初始化 SDK 后,登录前调用方法 -setIMDelegate:设置代理对象,并在对象中实现代理方法-onRecvRoomMessage:messageList:对接收到的消息进行业务逻辑处理。

// ZegoLiveRoomApi-IM.h

/**
 设置实时消息代理对象

 * 注意:
 * 1.建议在登录房间之前设置,否则无法进行相关回调。
 * 2.需要使用点赞主播、评论、送礼、房间内成员列表变化通知等实时消息功能时,需要设置该类型代理对象。未设置代理对象,或代理对象未实现相关代理方法,会导致无法进行相关回调。
 * 3.SDK 内部弱引用该代理对象。

 @param imDelegate 遵循 ZegoIMDelegate 协议的代理对象
 @return 设置结果。true 成功,false 失败
 */
- (bool)setIMDelegate:(id<ZegoIMDelegate>)imDelegate;
// ZegoLiveRoomApi-IM.h

/**
 收到房间的广播消息

 * 调用 -sendRoomMessage:type:category:priority:completion: 发送消息后,会触发房间内其他用户进行该回调,用户自己发送的消息不会通过此回调得到通知。

 @param roomId 房间 Id
 @param messageList 消息列表,包括消息内容,消息分类,消息类型,发送者等信息
 */
- (void)onRecvRoomMessage:(NSString *)roomId messageList:(NSArray<ZegoRoomMessage*> *)messageList;

2.1.2 发送房间消息

消息发送端在登录房间后,可以调用方法-sendRoomMessage:type:category:completion:发送房间消息。

/**
 房间发送广播消息

 * 可以调用该 API 发送点赞主播、评论、送礼物等消息。

 * 注意:
 * 1.在登录房间后调用该 API 才有效。
 * 2.调用该 API 后,房间的其他用户可以通过回调 [ZegoIMDelegate -onRecvRoomMessage:messageList:] 收到该条消息。

 @param content 消息内容, 不超过 1024 字节
 @param type 消息类型,可以自定义。详见 ZegoMessageType
 @param category 消息分类,可以自定义。详见 ZegoMessageCategory
 @param completionBlock 消息发送结果回调。回调信息包含 server 下发的 messageId
 @return true 成功,false 失败
 */
- (bool)sendRoomMessage:(NSString *)content type:(ZegoMessageType)type category:(ZegoMessageCategory)category completion:(ZegoRoomMessageCompletion)completionBlock;

初始化参考快速开始-初始化,登录房间参考快速开始-登录房间

3 大房间消息

3.1 使用步骤

下面以 A、B 用户的交互来说明大房间消息的使用,时序图如下:

3.1.1 设置实时消息代理对象

消息接收端在初始化 SDK 后,登录前调用方法 -setIMDelegate:设置代理对象,并在对象中实现代理方法-onRecvBigRoomMessage:messageList:对接收到的大房间消息进行业务逻辑处理。

// ZegoLiveRoomApi-IM.h

/**
 设置实时消息代理对象

 * 注意:
 * 1.建议在登录房间之前设置,否则无法进行相关回调。
 * 2.需要使用点赞主播、评论、送礼、房间内成员列表变化通知等实时消息功能时,需要设置该类型代理对象。未设置代理对象,或代理对象未实现相关代理方法,会导致无法进行相关回调。
 * 3.SDK 内部弱引用该代理对象。

 @param imDelegate 遵循 ZegoIMDelegate 协议的代理对象
 @return 设置结果。true 成功,false 失败
 */
- (bool)setIMDelegate:(id<ZegoIMDelegate>)imDelegate;
// ZegoLiveRoomApi-IM.h

/**
 收到房间的不可靠消息广播

 * 调用 -sendBigRoomMessage:type:category:completion: 发送消息后,会触发房间内其他用户进行该回调,用户自己发送的消息不会通过此回调得到通知。

 @param roomId 房间 Id
 @param messageList 消息列表,包括消息内容,消息分类,消息类型,发送者等信息
 */
- (void)onRecvBigRoomMessage:(NSString *)roomId messageList:(NSArray<ZegoBigRoomMessage*> *)messageList;

3.1.2 发送大房间消息

消息发送端在登录房间后,可以调用方法-sendBigRoomMessage:type:category:completion:发送大房间消息。

/**
 房间发送不可靠信道的消息

 * 用于高并发的场景,消息可能被丢弃,当高并发达到极限时会根据策略丢弃部分消息。

 * 注意:
 * 1.在登录房间后调用该 API 才有效。
 * 2.调用该 API 后,房间的其他用户可以通过回调 [ZegoIMDelegate -onRecvBigRoomMessage:messageList:] 收到该条消息。

 @param content 消息内容, 不超过 1024 字节
 @param type 消息类型,可以自定义。详见 ZegoMessageType
 @param category 消息分类,可以自定义。详见 ZegoMessageCategory
 @param completionBlock 消息发送结果回调。回调信息包含 server 下发的 messageId
 @return true 成功,false 失败
 */
- (bool)sendBigRoomMessage:(NSString *)content type:(ZegoMessageType)type category:(ZegoMessageCategory)category completion:(ZegoBigRoomMessageCompletion)completionBlock;

初始化参考快速开始-初始化,登录房间参考快速开始-登录房间

4 指定用户消息

下面以 A、B 用户的交互来说明指定用户消息的使用,时序图如下:

4.1.1 设置 Room 代理对象

消息接收端在初始化 SDK 后,登录前调用方法 -setRoomDelegate:设置代理对象,并在对象中实现代理方法-onReceiveCustomCommand:userName:content:roomID:对接收到的消息进行业务逻辑处理。

// ZegoLiveRoomApi.h

/**
 设置 room 代理对象

 @param roomDelegate 遵循 ZegoRoomDelegate 协议的代理对象
 @return true 成功,false 失败
 @discussion 使用 room 功能,初始化相关视图控制器时需要设置代理对象。未设置代理对象,或对象设置错误,可能导致无法正常收到相关回调
 */
- (bool)setRoomDelegate:(id<ZegoRoomDelegate>) roomDelegate;
// ZegoLiveRoomApi.h

/**
 收到自定义信令

 * 调用 -sendCustomCommand:content:completion: 发送自定义信令后,消息列表中的用户会触发此回调,用户自己发送的消息不会通过此回调得到通知。

 @param fromUserID 消息来源 UserID
 @param fromUserName 消息来源 UserName
 @param content 消息内容
 @param roomID 房间 ID
 */
- (void)onReceiveCustomCommand:(NSString *)fromUserID userName:(NSString *)fromUserName content:(NSString*)content roomID:(NSString *)roomID;

4.1.2 发送指定用户消息

消息发送端在登录房间后,可以调用方法-sendCustomCommand:content:completion:发送指定用户消息。

/**
 发送自定义信令

 * 该 API 可以向指定列表内的用户发送自定义信令,信令内容由用户自定义。发送结果通过 block 回调。
 * 用户可通过代理 [ZegoRoomDelegate -onReceiveCustomCommand:userName:content:roomID:] 方法收到信令。

 @param memberList 发送对象列表
 @param content 消息内容。长度不超过 1024 字节
 @param block 消息发送结果
 @return 发起请求是否成功
 */
- (bool)sendCustomCommand:(NSArray<ZegoUser*> *)memberList content:(NSString *)content completion:(ZegoCustomCommandBlock)block;

注意: 1.指定用户ZegoUser必须同时填写 userID 和 userName,否则目标用户接收不到消息。 2.发送指定用户消息必须指定用户列表,因此常常需要知道房间内的用户的增删变化。监听房间内用户的变化,需要在初始化 SDK 调用 setRoomConfig:userStateUpdate:设置userStateUpdateYES,然后实现[ZegoLiveRoomApi (IM) -onUserUpdate:updateType:]代理方法,该方法会回调房间内其他用户的增删事件。

// ZegoLiveRoomApi.h

/**
 设置房间配置信息
 注意:userStateUpdate为房间属性而非用户属性,设置的是该房间内是否会进行用户状态的广播。如果需要在房间内用户状态改变时,其他用户能收到通知,请为所有用户设置为true;反之,设置为false。设置为true后,方可从[ZegoLiveRoomApi (IM) -onUserUpdate:updateType:]回调收到用户状态变更通知。
 @param audienceCreateRoom 观众是否可以创建房间。true 可以,false 不可以。默认 true
 @param userStateUpdate 用户状态(用户进入、退出房间)是否广播。true 广播,false 不广播。默认 false
 @discussion 在 userStateUpdate 为 true 的情况下,用户进入、退出房间会触发 [ZegoLiveRoomApi (IM) -onUserUpdate:updateType:] 回调
 @discussion 在登录房间前调用有效,退出房间后失效
 */
- (void)setRoomConfig:(bool)audienceCreateRoom userStateUpdate:(bool)userStateUpdate;
// ZegoLiveRoomApi-IM.h

/**
 房间成员更新回调

 * 注意:
 * 1.必须调用 [ZegoLiveRoomApi +setRoomConfig:userStateUpdate:] 开启用户状态(用户进入、退出房间)广播,当房间成员变化(用户进入、退出房间)时,才会触发此回调。

 @param userList 成员更新列表
 @param type  更新类型(增量,全量),详见 ZegoUserUpdateType
 */
- (void)onUserUpdate:(NSArray<ZegoUserState *> *)userList updateType:(ZegoUserUpdateType)type;

注意:onUserUpdate回调的人数上限为500人

初始化参考快速开始-初始化,登录房间参考快速开始-登录房间

5 房间附加信息

5.1.1 设置 RoomExtraInfoUpdate 代理对象

消息接收端在初始化 SDK 后,登录前调用方法 -setRoomExtraInfoUpdateDelegate:设置代理对象,并在对象中实现代理方法-onRoomExtraInfoUpdated:roomExtraInfoList:对接收到的消息进行业务逻辑处理。

// ZegoLiveRoomApi-RoomExtraInfo.h

/**
 设置房间附加信息回调

 @param RoomExtraInfoDelegate 遵循 ZegoLiveRoomExtraInfoDelegate 协议的代理对象
 @return true 成功,false 失败
 */
- (bool)setRoomExtraInfoUpdateDelegate:(id<ZegoLiveRoomExtraInfoDelegate>) RoomExtraInfoDelegate;
// ZegoLiveRoomApi-RoomExtraInfo.h

/**
 房间附加信息更新回调 全量回调当前房间内最新的extrainfo信息(注意列表为空时表示数据已被删除)

 @param roomId 回调的roomid
 @param roomExtraInfoList 回调的列表
 */
- (void)onRoomExtraInfoUpdated:(NSString *)roomId roomExtraInfoList:(NSArray<ZegoRoomExtraInfo *> *)roomExtraInfoList;

5.1.2 设置房间附加信息内容

消息发送端在登录房间后,可以调用方法-setRoomExtraInfo:value:completion:设置房间附加信息内容。

// ZegoLiveRoomApi-RoomExtraInfo.h

/**
 设置房间附加信息内容 登录房间成功后使用

 @param key 设置的key值 不能超过 10字节, 不允许为空字符串, 一个房间内只允许1个消息类型
 @param value 设置的value值 不能超过 128 字节, 允许为空字符串
 @param completionBlock 回调
 @return true 成功,false 失败
 */
- (bool)setRoomExtraInfo:(NSString*)key value:(NSString*)value completion:(ZegoSetRoomExtraInfoCompletionBlock)completionBlock;

注意: RoomExtraInfo常用于标识房间某些状态或属性,属于低频操作,最好是仅限房主进行此类操作。

初始化参考快速开始-初始化,登录房间参考快速开始-登录房间

本篇目录