监听聊天室事件
聊天室业务为客户端 App 提供三种类型的事件委托协议:聊天室状态委托、聊天室成员变化委托、聊天室事件通知。
通过 SDK 提供的以上委托,客户端 App 可以从融云服务端获取聊天室销毁状态、用户在当前及其他客户端加入退出聊天室的状态、聊天室中成员进出的事件通知、以及聊天室中成员禁言、封禁相关的信息。
委托协议 | 名称 | 说明 |
---|---|---|
RCChatRoomStatusDelegate | 聊天室状态委托 | 接收在当前客户端上用户加入、退出聊天室的事件与聊天室销毁状态的信息。 |
RCChatRoomMemberDelegate | 聊天室成员变化委托 | 接收当前所在聊天室中用户加入、退出聊天室的信息。 |
ChatRoomNotifyEventDelegate | 聊天室事件通知委托 | 接收当前所在聊天室中成员禁言、封禁相关的信息;接收当前用户在其他端加入、退出聊天室相关的信息。 |
监听聊天室状态
要从融云服务器接收当前客户端上用户加入、退出聊天室的事件与聊天室销毁状态,您可以通过 RCChatRoomClient
(或 RCIMClient
) 的 setChatRoomStatusDelegate
或 addChatRoomStatusDelegate
添加一个 RCChatRoomStatusDelegate 代理。
聊天室状态事件
下方列出了聊天室状态委托协议 RCChatRoomStatusDelegate
提供的事件列表及代理方法。
@protocol RCChatRoomStatusDelegate <NSObject>
/*!
开始加入聊天室的回调
- Parameter chatroomId: 聊天室ID
*/
- (void)onChatRoomJoining:(NSString *)chatroomId;
/*!
加入聊天室成功的回调
- Parameter chatroomId: 聊天室ID
- Parameter response: 加入成功返回的信息
- Since: 5.6.3
*/
- (void)onChatRoomJoined:(NSString *)chatroomId response:(RCJoinChatRoomResponse *)response;
/*!
加入聊天室成功的回调
- Parameter chatroomId: 聊天室ID
*/
- (void)onChatRoomJoined:(NSString *)chatroomId __deprecated_msg("Use [RCChatRoomStatusDelegate onChatRoomJoined:response:] instead");
/*!
加入聊天室失败的回调
- Parameter chatroomId: 聊天室ID
- Parameter errorCode: 加入失败的错误码
如果错误码是KICKED_FROM_CHATROOM或RC_CHATROOM_NOT_EXIST,则不会自动重新加入聊天室,App需要按照自己的逻辑处理。
*/
- (void)onChatRoomJoinFailed:(NSString *)chatroomId errorCode:(RCErrorCode)errorCode;
/*!
加入聊天室成功,但是聊天室被重置。接收到此回调后,还会收到 onChatRoomJoined:回调。
- Parameter chatroomId: 聊天室ID
*/
- (void)onChatRoomReset:(NSString *)chatroomId;
/*!
退出聊天室成功的回调
- Parameter chatroomId: 聊天室ID
*/
- (void)onChatRoomQuited:(NSString *)chatroomId;
/*!
聊天室被销毁的回调,用户在线的时候房间被销毁才会收到此回调。
- Parameter chatroomId: 聊天室ID
- Parameter type: 聊天室销毁原因
*/
- (void)onChatRoomDestroyed:(NSString *)chatroomId type:(RCChatRoomDestroyType)type;
@end
设置聊天室状态代理委托
// 设置 IMLib 的聊天室状态监听器
[[RCChatRoomClient sharedChatRoomClient] setChatRoomStatusDelegate:self];
SDK 从 5.2.5 版本开始支持添加多代理,添加代理委托的方法如下:
// 添加 IMLib 的聊天室状态监听器 @Since 5.2.5
[[RCChatRoomClient sharedChatRoomClient] addChatRoomStatusDelegate:self];
删除聊天室状态代理委托
SDK 从 5.2.5 版本开始支持添加多代理,删除代理委托的方法如下:
// 移除 IMLib 的聊天室状态监听器 @Since 5.2.5
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomStatusDelegate:self];
监听聊天室成员变化
SDK 从 5.1.4 版本开始支持监听聊天室成员变化。
SDK 在 RCChatRoomClient
中提供 RCChatRoomMemberDelegate
协议,支持在当前客户端监听所在聊天室中其它成员的加入、退出行为。
开通服务
此功能需要开通服务后方可使用。如有需求,请提交工单,申请开通聊天室成员变化监听。
设置聊天室成员变化代理委托
以下代码示例显示了如何设置聊天室成员变化代理委托。从 5.6.7 版本 开始,新增返回 RCChatRoomMemberActionModel
对象的代理方法,其中增加了当前聊天室人数。
[RCChatRoomClient sharedChatRoomClient].memberDelegate = self;
#pragma mark - RCChatRoomMemberDelegate
- (void)memberDidChange:(NSArray<RCChatRoomMemberAction *> *)members inRoom:(NSString *)roomId {
// Handle the member change with the array of RCChatRoomMemberAction objects and the roomId
}
/**
- Since: 5.6.7
*/
- (void)memberDidChange:(RCChatRoomMemberActionModel *)actionModel {
// Handle the member change with the RCChatRoomMemberActionModel object
NSString *roomId = actionModel.roomId;
NSArray<RCChatRoomMemberAction *> *chatRoomMemberActions = actionModel.chatRoomMemberActions;
NSUInteger memberCount = actionModel.memberCount;
for (RCChatRoomMemberAction *action in chatRoomMemberActions) {
// Access the properties of RCChatRoomMemberAction object
NSString *memberId = action.memberId;
RCChatRoomMemberActionType actionType = action.action;
if (actionType == RCChatRoomMemberActionType_Join) {
NSLog(@"Action Type: Join");
} else if (actionType == RCChatRoomMemberActionType_Quit) {
NSLog(@"Action Type: Leave");
}
}
}
聊天室中有其他用户加入或退出时,SDK 会同时触发两个 memberDidChange
方法,都在子线程回调。RCChatRoomMemberAction
列表中包含了当前聊天室中加入或退出聊天室的成员信息。RCChatRoomMemberActionModel
额外封装了聊天室当前人数(指已加入未退出的人数)。推荐使用返回 RCChatRoomMemberActionModel
对象的代理方法。
如果当前用户由于网络原因和聊天室断开连接,则无法监听到断开连接期间的其他成员的加入、退出行为。
监听聊天室事件通知
SDK 从 5.4.5 版本开始支持监听聊天室事件通知。
要从融云服务端接收当前聊天室中成员禁言、封禁相关的信息,以及当前用户在其他端加入、退出聊天室相关的信息,您可以通过 RCChatRoomClient
的 addChatRoomNotifyEventDelegate
方法添加一个RCChatRoomNotifyEventDelegate
代理。
代理方法 | 触发时机 | 说明 |
---|---|---|
chatRoomNotifyMultiLoginSync:(RCChatRoomSyncEvent *)event; | 在用户在多端登录情况下,在其他客户端加入、退出聊天室 | 接收在当前客户端上用户加入、退出聊天室的事件 |
chatRoomNotifyBlock:(RCChatRoomMemberBlockEvent *)event; | 用户所在聊天室中发生了禁言、解除禁言相关的事件 | 是否接收通知取决于调用服务端封禁、解封的相关 API 时是否指定了 needNotify 为 true 。 |
chatRoomNotifyBan:(RCChatRoomMemberBanEvent *)event; | 用户所在聊天室发生了封禁用户、解除封禁相关的事件 | 是否接收通知取决于调用服务端封禁、解封的相关 API 时是否指定了 needNotify 为 true 。 |
多端登录事件通知
在用户在多端登录情况下,在其他客户端加入、退出聊天室时,触发 chatRoomNotifyMultiLoginSync:(RCChatRoomSyncEvent *)event
方法。
触发场景 | 通知范围 | 说明 |
---|---|---|
用户多端登录 ,在一台设备上加入聊天室 | 当前加入的用户 | 当前用户在一端加入聊天室时,其他端的在线设备上会接收通知,不在线的设备不会通知。返回数据包括:聊天室 ID、加入时间。 |
用户多端登录,在一台设备上退出聊天室 | 当前退出的用户 | 当前用户在一端退出聊天室时,其他端的在线设备上会接收通知,不在线的设备不会通知。 返回数据包括:聊天室 ID、退出时间。 |
用户多端登录且已在聊天室中,加入一个新的聊天室导致被踢出上一个聊天室 | 当前用户,和被踢出的聊天室所有成员 | 如果在控制台开通了单个用户加入多个聊天室,则不会通知。返回数据包括:聊天室 ID、被踢出的时间。 |
RCChatRoomSyncEvent
具体定义如下:
@interface RCChatRoomSyncEvent : NSObject
/*!
聊天室 ID
*/
@property (nonatomic, copy) NSString *chatroomId;
/**
同步通知的变更状态
*/
@property (nonatomic, assign) RCChatRoomSyncStatus status;
/**
如果status是0的情况,区分离开类型:
1,自己主动离开,
2,多端加入互踢导致离开
*/
@property (nonatomic, assign) NSInteger reason;
/**
同步通知的变更时间
用户加入/退出/被踢的时间(毫秒时间戳)
*/
@property (nonatomic, assign) long long time;
/**
附加信息
*/
@property (nonatomic, copy, nullable) NSString *extra;
@end
封禁相关事件通知
用户所在聊天室发生了封禁、解封的事件,且调用相关 Server API 时指定了需要通知(指定 needNotify
为 true
),触发 chatRoomNotifyBlock:(RCChatRoomMemberBlockEvent *)event
方法。
触发场景 | 通知范围 | 说明 |
---|---|---|
封禁聊天室用户 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被封禁成员用户 ID 列表、封禁时间与持续时长、附加信息。 |
解除封禁聊天室用户 | 被解除封禁的成员 | 返回数据包括:聊天室 ID、当前用户 ID、附加信息。 |
RCChatRoomMemberBlockEvent
具体定义如下:
@interface RCChatRoomMemberBlockEvent : NSObject
/*!
聊天室 ID
*/
@property (nonatomic, copy) NSString *chatroomId;
/**
封禁类型,0是解封,1是封禁
*/
@property (nonatomic, assign) RCChatRoomMemberOperateType operateType;
/**
封禁的总时间,封禁时有此字段(毫秒),最大值为43200分钟(1个月), 最小值1分钟
*/
@property (nonatomic, assign) NSInteger durationTime;
/**
操作时间(毫秒时间戳)
*/
@property (nonatomic, assign) long long operateTime;
/**
被封禁用户 ID 列表;解封时为当前用户 ID
*/
@property (nonatomic, copy) NSArray<NSString *> *userIdList;
/**
附加信息
*/
@property (nonatomic, copy, nullable) NSString *extra;
@end
禁言相关事件通知
用户所在聊天室发生了禁言、解除禁言相关的事件,且调用相关 Server API 时指定了需要通知(指定 needNotify
为 true
),触发 chatRoomNotifyBan:(RCChatRoomMemberBanEvent *)event
方法。
触发场景 | 通知范围 | 说明 |
---|---|---|
禁言指定聊天室用户 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被封禁成员用户 ID 列表、禁言时间与持续时长、附加信息。 |
取消禁言指定聊天室用户 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被封禁成员用户 ID 列表、解除禁言时间、附加信息。 |
设置聊天室全体禁言 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、禁言时间、附加信息。 |
取消聊天室全体禁言 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、解除禁言时间、附加信息。 |
加入聊天室全体禁言白名单 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被添加白名单的用户 ID 列表、设置白名单时间、附加信息。 |
移出聊天室全体禁言白名单 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被移出白名单的用户 ID 列表、移出白名单时间、附加信息。 |
全局禁言用户 | 被全局禁言的用户 | 返回数据包括:聊天室 ID、禁言时间与持续时长、附加信息。 |
取消全局禁言用户 | 被解除全局禁言的用户 | 返回数据包括:聊天室 ID、解除禁言时间、附加信息。 |
RCChatRoomMemberBanEvent
具体定义如下:
@interface RCChatRoomMemberBanEvent : NSObject
/*!
聊天室 ID
*/
@property (nonatomic, copy) NSString *chatroomId;
/**
禁言操作类型,详见枚举值
禁言/解除禁言操作类型:
0:解除指定聊天室中用户禁言;
1:禁言指定聊天室中用户;
2:解除聊天室全体禁言;
3:聊天室全体禁言
4: 移出禁言用户白名单
5: 添加禁言用户白名单
6: 解除用户聊天室全局禁言
7:用户聊天室全局禁言
*/
@property (nonatomic, assign) RCChatRoomMemberBanType banType;
/**
禁言的总时间(禁言的操作有此字段)(毫秒) ,最大值为43200分钟(1个月), 最小值1分钟
*/
@property (nonatomic, assign) NSInteger durationTime;
/**
操作时间(毫秒时间戳)
*/
@property (nonatomic, assign) long long operateTime;
/**
禁言/解禁言用户 ID 列表
*/
@property (nonatomic, copy) NSArray<NSString *> *userIdList;
/**
附加信息
*/
@property (nonatomic, copy, nullable) NSString *extra;
@end
设置聊天室事件通知代理委托
SDK 从 5.4.5 版本开始支持 RCChatRoomNotifyEventDelegate
委托协议。以下代码示例显示了如何设置聊天室事件通知代理委托。
[[RCChatRoomClient sharedChatRoomClient] addChatRoomNotifyEventDelegate:self];
删除聊天室事件通知代理委托
SDK 从 5.4.5 版本开始支持 RCChatRoomNotifyEventDelegate
委托协议。以下代码示例显示了如何删除聊天室事件通知代理委托。
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomNotifyEventDelegate:self];