IM

下载pdf
更新时间:2020-01-02 19:04

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)的基本用法。并未展示可靠房间消息(ReliableMessage)用法,开发者可参考本文档的可靠房间消息章节实现业务需求。

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 消息内容, 不超过 512 字节
 @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 消息内容, 不超过 512 字节
 @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

/**
 设置房间配置信息

 @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;

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

6 可靠房间消息

6.1 使用步骤

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

6.1.1 设置可靠房间消息代理对象

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

// ZegoLiveRoomApi-ReliableMessage.h

/**
 设置可靠消息代理对象

 * 当需要使用房间内业务消息和业务状态同步功能时,需要使用可靠消息。

 * 注意:
 * 1.建议在登录房间之前设置,否则无法进行相关回调。
 * 2.未设置代理对象,或代理对象未实现相关代理方法,会导致无法进行相关回调。
 * 3.SDK 内部弱引用该代理对象。

 @param delegate 遵循 ZegoReliableMessageDelegate 协议的代理对象
 @return true 设置成功,false 设置失败
 */
- (bool)setReliableMessageDelegate:(id<ZegoReliableMessageDelegate>)delegate;
// ZegoLiveRoomApi-ReliableMessage.h

/**
 收到房间内的可靠消息

 * 调用 -sendReliableMessage:type:latestSeq:completion: 发送消息后,会触发房间内其他用户进行该回调。

 @param message 可靠消息
 @param roomId 房间 ID
 */
- (void)onRecvReliableMessage:(ZegoReliableMessage *)message room:(NSString *)roomId;

6.1.2 发送可靠房间消息

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

// ZegoLiveRoomApi-ReliableMessage.h

/**
 发送可靠业务消息

 * 可以调用该 API 发送房间内业务消息和业务状态的同步消息。
 * 调用该 API 后,房间的其他用户可以通过回调 [ZegoReliableMessageDelegate -onRecvReliableMessage:room:] 收到该条消息。

 * 注意:
 * 1.在登录房间后调用该 API 才有效。
 * 2.可靠消息是通过版本控制思想来实现的,通过 type 来唯一定义一种消息。服务端通过 -sendReliableMessage:type:latestSeq:completion: 请求的 latestSeq 和服务端维护的该 type 消息的 latestSeq 的比对,来判断该类型消息是否需要同步。如果客户端 latestSeq 小于服务端 latestSeq,则说明客户端的消息版本太低,则回调一个错误码,客户端据此需要去获取最新消息进行同步。如果客户端 latestSeq 大于或等于服务端 latestSeq,则服务端认为可以同步,然后服务端 latestSeq 更新为请求的 latestSeq,并发消息给所有房间内其他成员。因此当开发者需要维护当前 type 消息的本地 latestSeq,当调用同步方法 -sendReliableMessage:type:latestSeq:completion: 回调时传入 latestSeq+1 成功后需要将更新本地 latestSeq,回调失败则需要拉取最新的可靠消息,更新本地 latestSeq。

 @param content 可靠业务消息数据,不能超过 2048 字节, 允许为空字符串
 @param type 可靠业务消息类型,不能超过 128 字节, 不允许为空字符串,一个房间内只允许不超过10个不同的消息类型
 @param seq 当前最新的业务消息seq
 @param completionBlock 发送可靠业务消息结果
 @return true 成功,false 失败
 */
- (bool)sendReliableMessage:(NSString *)content type:(NSString *)type latestSeq: (unsigned int)seq completion:(ZegoSendReliableMessageCompletionBlock)completionBlock;

当发送可靠消息回调返回消息版本不同步错误时,需要调用-getReliableMessages:completion:获取最新的消息版本,然后使用最新的 seq参数发送消息。

/**
 获取可靠业务消息

 @param messageTypes 可靠业务消息类型列表
 @param completionBlock 获取可靠业务消息结果
 @return true 成功,false 失败
 @discussion messageTypes的个数不能超过10个
 */
- (bool)getReliableMessages:(NSArray<NSString*> *)messageTypes completion:(ZegoGetReliableMessageCompletionBlock)completionBlock;

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