IM 使用

下载pdf
更新时间:2019-09-27 10:07

1 简介

ZegoAudioRoom SDK 内集成了即时通信功能,即 ZegoAudioRoomApi (IM),用户可调用相关 API 实现语音直播间内的 发消息点赞送礼物 等互动功能,也可选择直播间内的成员,发起会话。

本文主要讲述如何利用 ZegoAudioRoomApi (IM) 中的 API 实现相关功能,以下 API 在 ZegoAudioRoom/ZegoAudioRoomApi-IM.h 文件中。

2 步骤

2.1 登录房间

使用 IM 功能的前置条件是登录同一个房间。

快速集成-手动发布直播快速集成-播放直播 中的登录流程一致,开发者可调用以下 API 进行登录。

ZegoAudioRoomApi.h

/**
 登录房间

 @param roomID 房间唯一 ID,不超过 255 bytes,支持可打印字符
 @param block 房间登录结果回调
 @return 调用登录房间的结果
 */
- (bool)loginRoom:(NSString *)roomID completionBlock:(ZegoAudioRoomBlock)block;

请开发者在使用 IM 功能前,确保登录成功。

2.2 设置 IM 代理对象

调用如下 API 设置 ZegoAudioIMDelegate 代理对象。设置代理对象失败,会导致 App 收不到相关回调

ZegoAudioRoomApi-IM.h

/**
 设置 IM 代理对象

 @param imDelegate 遵循 ZegoAudioIMDelegate 协议的代理对象
 @attention 使用 IM 功能,初始化相关视图控制器时需要设置代理对象
 @note 未设置代理对象,或对象设置错误,可能导致无法正常收到相关回调
 */
- (void)setAudioIMDelegate:(id<ZegoAudioIMDelegate>)imDelegate;

2.3 语音直播间内互动消息

直播间中的聊天、点赞、送礼物等互动功能,均是通过消息收发来实现的。

发送消息

开发者可调用此 API 在指定房间内发送广播消息,通过入参中的 ZegoMessageCategory 来区分消息类别。

ZegoAudioRoomApi-IM.h

/**
 房间发送广播消息

 @param content 消息内容,不超过 1024 bytes,支持可打印字符
 @param type 消息类型,可以自定义
 @param category 消息分类,可以自定义 
 @param completionBlock 消息发送结果,回调 server 下发的 messageId
 @return true 成功,false 失败
 @attention 实现点赞主播、评论、送礼物等 IM 功能时,需要调用本 API
 */
- (bool)sendRoomMessage:(NSString *)content type:(ZegoMessageType)type category:(ZegoMessageCategory)category completion:(ZegoRoomMessageCompletion)completionBlock;

其中,ZegoMessageCategory 支持的内置类别有:

/** 消息类别 */
typedef enum
{
    ZEGO_CHAT = 1,              /**< 聊天 */
    ZEGO_SYSTEM,                /**< 系统 */
    ZEGO_LIKE,                  /**< 点赞 */
    ZEGO_GIFT,                  /**< 送礼物 */
    ZEGO_OTHER_CATEGORY = 100,  /**< 其他 */
} ZegoMessageCategory;

收取房间消息

设置 ZegoAudioIMDelegate 代理对象成功后,房间内成员调用 sendRoomMessage:type:category:completion: 发送消息成功,同一房间内的其他成员会在此回调中收到此消息。

ZegoAudioRoomApi-IM.h

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

 @param roomId 房间 Id
 @param messageList 消息列表,包括消息内容,消息分类,消息类型,发送者等信息
 @attention 调用 [ZegoAudioRoomApi (IM) -sendRoomMessage:type:category:completion:] 发送消息,会触发此通知
 */
- (void)onRecvAudioRoomMessage:(NSString *)roomId messageList:(NSArray<ZegoRoomMessage*> *)messageList;

2.4 语音直播间内会话

直播间中除了成员间互动外,还可以选择直播间成员,创建会话组,进行会话。

设置用户状态更新(可选)

创建会话前,开发者需要调用此 API 设置用户状态更新。如果设置为不通知,则用户进入/退出房间不会通知其他用户。请开发者按需调用。

ZegoAudioRoomApi.h

/**
 设置用户进入/退出房间是否通知其他用户

 @param userStateUpdate 是否需要通知其他用户
 @attention 默认不通知
 */
- (void)setUserStateUpdate:(bool)userStateUpdate

创建会话

开发者调用此 API 创建会话。

请注意,会话成员必须是同一直播间内的成员,不可以跨房间创建会话!

ZegoAudioRoomApi-IM.h

/**
 在房间中创建一个会话

 @param conversationName 会话名称,不超过 255 bytes,支持可打印字符
 @param memberList 会话成员列表
 @param completionBlock 创建结果,回调 server 下发的会话 Id
 @return true 成功,false 失败
 */
- (bool)createConversation:(NSString *)conversationName memberList:(NSArray<ZegoUser *> *)memberList completion:(ZegoCreateConversationCompletion)completionBlock;

发送会话消息

会话创建成功后,开发者调用此 API 向会话发送消息。

其中的 conversationId 是创建会话成功后,由 Server 通过 ZegoCreateConversationCompletion Block 返回。

ZegoAudioRoomApi-IM.h

/**
 在会话中发送一条消息

 @param content 消息内容,不超过 1024 bytes,支持可打印字符
 @param type 消息类型,可以自定义
 @param conversationId 会话 Id,不超过 255 bytes,支持可打印字符
 @param completionBlock 发送消息结果,回调 server 下发的 messageId
 @return true 成功,false 失败
 */
- (bool)sendConversationMessage:(NSString *)content type:(ZegoMessageType)type conversationId:(NSString *)conversationId completion:(ZegoConversationMessageCompletion)completionBlock;

收取会话消息

设置 ZegoAudioIMDelegate 代理对象成功后,某成员向会话中发送消息成功,其他成员会在此回调中收到消息。

ZegoAudioRoomApi-IM.h

/**
 收到会话消息

 @param roomId 房间 Id
 @param conversationId 会话 Id
 @param message 会话消息,包括消息内容,消息类型,发送者,发送时间等信息
 @attention 调用 [ZegoAudioRoomApi (IM) -sendConversationMessage:type:conversationId:completion] 发送消息,会触发此通知
 */
- (void)onRecvConversationMessage:(NSString *)roomId conversationId:(NSString *)conversationId message:(ZegoConversationMessage *)message;

获取会话信息

开发者可调用此 API 查询会话的信息。

ZegoAudioRoomApi-IM.h

/**
 获取会话相关信息

 @param conversationId 会话 Id,不超过 255 bytes,支持可打印字符
 @param completionBlock 获取结果,包括会话名称,会话成员,创建者等信息
 @return true 成功,false 失败
 */
- (bool)getConversationInfo:(NSString *)conversationId completion:(ZegoConversationInfoBlock)completionBlock;

2.5 直播间内成员更新

设置 ZegoAudioIMDelegate 代理对象成功,并且调用 2.4.1 中的 setUserStateUpdate 设置用户进入/退出通知其他用户。当直播间内有成员增减时,用户才可在此回调中收到通知。

ZegoAudioRoomApi.h

/**
 房间成员更新回调

 @param userList 成员更新列表
 @param type  更新类型(增量,全量)
 @attention 当房间成员变化(例如用户进入、退出房间)时,会触发此通知
 */
- (void)onUserUpdate:(NSArray<ZegoUserState *> *)userList updateType:(ZegoUserUpdateType)type;