IM 使用

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;