互动视频
  • 平台类型
  • 框架 / 引擎

IM

更新时间:2020-07-10 17:17

1 功能简介

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

1.大房间消息适用于高并发的场景,当高并发达到极限时会根据策略丢弃部分消息。发消息、点赞、送礼物等普通房间消息以及大房间消息 API 在ZegoLiveRoom/ZegoLiveRoomApi-IM.h文件中。 2.可靠房间消息适用于房间内业务消息和业务状态的同步场景。API 在ZegoLiveRoom/ZegoLiveRoomApi-ReliableMessage.h文件中。 3.向指定用户发消息适用于向房间指定用户发消息场景。API 在ZegoLiveRoom/ZegoLiveRoomApi.h文件中。

2 下载示例 Demo

示例 Demo 源码下载地址:互动视频示例 Demo_iOS

码云下载地址(国内推荐)
阿里云下载地址(国内推荐)
github下载地址

互动视频示例 Demo 包含了基础专题和进阶专题,展示了如何使用 SDK API,开发者可参考其用法来实现自己的业务。互动视频示例 Demo 涵盖了 SDK 的大部分功能,开发者也可在示例专题 Demo 中查找 ZEGO SDK 更多的进阶功能,测试其功能和性能,以实现特定的需求。

IM 模块源码请查看 Demo 的LiveRoomPlayground/LiveRoomPlayground-iOS/RoomMessageUI 目录下的源文件,该模块展示了使用 ZEGO SDK 实现 IM 所需调用的关键 API 接口。

注意:该示例专题的 Demo 展示了普通房间消息(RoomMessage)、大房间消息(BigRoomMessage)、指定用户消息(CustomCommand)的基本用法。 普通房间消息(RoomMessage)、大房间消息(BigRoomMessage)长度大小限制扩展至1024字节(7.10版本),之前的SDK版本接收超过512字节的消息,会丢弃超过512字节的数据。

3 房间消息

3.1 使用步骤

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

3.1.1 设置 IM 代理对象

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

// ZegoLiveRoomApi-IM.h

/**
 设置 IM 代理对象

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

3.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;

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

4 大房间消息

4.1 使用步骤

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

4.1.1 设置 IM 代理对象

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

// ZegoLiveRoomApi-IM.h

/**
 设置 IM 代理对象

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

4.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;

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

5 指定用户消息

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

5.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;

5.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人

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