监听聊天室事件
聊天室业务为客户端 App 提供三种类型的事件监听器:聊天室状态监听器、聊天室成员变化监听器、聊天室事件通知监听器。
通过 IMLib SDK 提供的以上委托,您可以从融云服务端获取聊天室销毁状态、用户在当前及其他客户端加入退出聊天室的状态、聊天室中成员进出的事件通知、以及聊天室中成员禁言、封禁相关的信息。
监听器 | 名称 | 说明 |
---|---|---|
ChatroomStatusListener* | 聊天室状态监听器 | 接收在当前客户端登录的用户加入、退出聊天室的事件与聊天室销毁状态的信息。 |
ChatroomMemberActionListener | 聊天室成员变化监听器 | 接收当前用户所在聊天室中其他用户加入、退出聊天室的信息。 |
ChatroomNotifyEventListener | 聊天室事件通知监听器 | 接收当前所在聊天室中成员禁言、封禁相关的信息;接收当前用户在其他端加入、退出聊天室相关的信息。 |
监听聊天室状态
您可以使用 setChatroomStatusListener
设置聊天室状态监听器来监听当前用户加入、退出聊天室的事件与已加入的聊天室销毁状态。。
接口原型
interface ChatroomStatusListener {
/**
* 开始加入聊天室的回调
* @param roomId 聊天室 id
*/
onChatroomJoining(roomId: string): void;
/**
* 加入聊天室成功的回调
* @param roomId 聊天室 id
* @param info 加入的聊天室信息
*/
onChatroomJoined(roomId: string, info: ChatroomJoinedInfo): any;
/**
* 加入聊天室失败的回调
* @param roomId 聊天室 id
* @param code 加入失败的错误码
* @discussion 如果 code 是 ChatroomKicked 或 ChatroomNotExist,则不会自动重新加入聊天室,App 需要按照自己的逻辑处理
*/
onChatroomJoinFailed(roomId: string, code: EngineError): any;
/**
* 退出聊天室成功的回调
* @param roomId 聊天室 id
*/
onChatroomQuited(roomId: string): any;
/**
* 聊天室被销毁的回调,用户在线的时候房间被销毁才会收到此回调
* @param roomId 聊天室 id
* @param type 聊天室销毁原因
*/
onChatroomDestroyed(roomId: string, type: ChatroomDestroyType): any;
}
示例代码
let listener: ChatroomStatusListener = {
onChatroomJoining(roomId: string): void {
},
onChatroomJoined(roomId: string, info: ChatroomJoinedInfo): void {
},
onChatroomJoinFailed(roomId: string, code: EngineError): void {
},
onChatroomQuited(roomId: string): void {
},
onChatroomDestroyed(roomId: string, type: ChatroomDestroyType): void {
},
}
IMEngine.getInstance().setChatroomStatusListener(listener);
监听聊天室成员变化
SDK 从 1.1.0 版本开始支持监听聊天室成员变化。
从 1.1.0 版本,SDK 开始新增 ChatroomMemberActionListener,支持当前登录用户监听所在聊天室中其它成员的加入、退出行为。
开通服务
您可以在融云控制台,通过应用配置>IM 服务>免费基础功能>聊天室>聊天室成员变化监听,开启此功能。开启后,用户加入、退出聊天室后,系统会使用消息的方式向聊天室中的其他成员发送回调通知,消息量会因此增加。
设置聊天室成员变化监听器
示例代码
let listener: ChatroomMemberActionListener = {
onMemberChange: (actionModel: ChatRoomMemberActionModel): void => {
}
}
IMEngine.getInstance().setChatroomMemberListener(listener);
如果当前用户由于网络原因和聊天室断开连接,则无法监听到断开连接期间的其他成员的加入、退出行为。
监听聊天室事件通知
SDK 从 1.1.0 开始支持监听聊天室事件通知。
应用程序可以监听当前聊天室中成员禁言、封禁相关的通知,以及当前用户在其他端加入、退出聊天室相关的通知。
示例代码
let listener: ChatroomNotifyEventListener = {
onChatroomNotifyMultiLoginSync: (syncEvent: ChatroomSyncEvent): void => {
},
onChatroomNotifyBlock: (blockEvent: ChatroomMemberBlockEvent): void => {
},
onChatRoomNotifyBan: (banEvent: ChatroomMemberBanEvent): void => {
}
}
IMEngine.getInstance().setChatroomNotifyEventListener(listener);
方法说明
回调方法 | 触发时机 | 说明 |
---|---|---|
onChatroomNotifyMultiLoginSync | 在用户在多端登录情况下,在其他客户端加入、退出聊天室 | 接收在当前客户端上用户加入、退出聊天室的事件 |
onChatroomNotifyBlock | 用户所在聊天室中发生了禁言、解除禁言相关的事件 | 是否接收通知取决于调用服务端封禁、解封的相关 API 时是否指定了 needNotify 为 true 。 |
onChatRoomNotifyBan | 用户所在聊天室发生了封禁用户、解除封禁相关的事件 | 是否接收通知取决于调用服务端封禁、解封的相关 API 时是否指定了 needNotify 为 true 。 |
多端登录事件通知
在用户在多端 登录情况下,在其他客户端加入、退出聊天室时,触发 onChatroomNotifyMultiLoginSync
方法。
触发场景 | 通知范围 | 说明 |
---|---|---|
用户多端登录,在一台设备上加入聊天室 | 当前加入的用户 | 当前用户在一端加入聊天室时,其他端的在线设备上会接收通知,不在线的设备不会通知。返回数据包括:聊天室 ID、加入时间。 |
用户多端登录,在一台设备上退出聊天室 | 当前退出的用户 | 当前用户在一端退出聊天室时,其他端的在线设备上会接收通知,不在线的设备不会通知。 返回数据包括:聊天室 ID、退出时间。 |
用户多端登录且已在聊天室中,加入一个新的聊天室导致被踢出上一个聊天室 | 当前用户,和被踢出的聊天室所有成员 | 如果在控制台开通了单个用户加入多个聊天室,则不会通知。返回数据包括:聊天室 ID、被踢出的时间。 |
ChatRoomSyncEvent
具体属性定义如下:
/**
* 聊天室同步事件,事件发生时,当前用户在线时能收到该事件
* @discussion 事件发生时,当前用户不在线,那么用户上线后,不会收到该事件。
* @version 1.1.0
*/
class ChatroomSyncEvent {
/**
* 聊天室 ID
*/
chatroomId: string = "";
/**
* 同步通知的变更状态
*/
status: ChatroomSyncStatus;
/**
* status 是 Quit 的情况, reason 区分离开类型: LeaveOnMyOwn,自己主动离开, OtherDeviceLogin,多端加入互踢导致离开
*
* status 是 Join 的情况,无需关心 reason 值
*/
reason: ChatroomSyncStatusReason;
/**
* 用户加入/退出/被踢的时间戳,精确到毫秒
*/
time: number;
/**
* 附加信息
*/
extra: string = "";
}
封禁相关事件通知
用户所在聊天室发生了封禁、解封的事件,且调用相关 Server API 时指定了需要通知(指定 needNotify
为 true
),SDK 会触发 onChatroomNotifyBlock
方法。
触发场景 | 通知范围 | 说明 |
---|---|---|
封禁聊天室用户 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被封禁成员用户 ID 列表、封禁时间与持续时长、附加信息。 |
解除封禁聊天室用户 | 被解除封禁的成员 | 返回数据包括:聊天室 ID、当前用户 ID、附加信息。 |
ChatroomMemberBlockEvent
具体属性定义如下:
/**
* 聊天室成员封禁事件
* ```
* 本事件只能通过 ServerApi 触发,端上只能被动接收到该事件
* 事件发生时,当前用户在线时能收到该事件
* 事件发生时,当前用户不在线,那么用户上线后,不会收到该事件。
* ```
* @version 1.1.0
*/
class ChatroomMemberBlockEvent {
/**
* 聊天室 Id
*/
chatroomId: string = "";
/**
* 封禁类型
*/
operateType: ChatroomBlockOperateType;
/**
* 封禁时长,单位为毫秒,最大值为43200分钟(1个月), 最小值1分钟。 operateType 为 Blocked 时,该字段有效
*/
durationTime: number;
/**
* 操作时间(毫秒时间戳)
*/
operateTime: number;
/**
* 被封禁/解封的用户 ID 列表
*/
userIdList: List<string>;
/**
* 附加信息
*/
extra: string = "";
}
/**
* 聊天室封禁类型
*/
enum ChatroomBlockOperateType {
/**
* 解封
*/
Unblock = 0,
/**
* 封禁
*/
Blocked = 1,
}
禁言相关事件通知
用户所在聊天室发生了禁言、解除禁言相关的事件,且调用相关 Server API 时指定了需要通知(指定 needNotify
为 true
),SDK 会触发 onChatRoomNotifyBan
方法。
触发场景 | 通知范围 | 说明 |
---|---|---|
禁言指定聊天室用户 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被封禁成员用户 ID 列表、禁言时间与持续时长、附加信息。 |
取消禁言指定聊天室用户 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被封禁成员用户 ID 列表、解除禁言时间、附加信息。 |
设置聊天室全体禁言 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、禁言时间、附加信息。 |
取消聊天室全体禁言 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、解除禁言时间、附加信息。 |
加入聊天室全体禁言白名单 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被添加白名单的用户 ID 列表、设置白名单时间、附加信息。 |
移出聊天室全体禁言白名单 | 聊天室中所有成员 | 返回数据包括:聊天室 ID、被移出白名单的用户 ID 列表、移出白名单时间、附加信息。 |
全局禁言用户 | 被全局禁言的用户 | 返回数据包括:聊天室 ID、禁言时间与持续时长、附加信息。 |
取消全局禁言用户 | 被解除全局禁言的用户 | 返回数据包括:聊天室 ID、解除禁言时间、附加信息。 |
ChatroomMemberBanEvent
具体属性定义如下:
/**
* 聊天室禁言事件
* ```
* 本事件只能通过 ServerApi 触发,端上只能被动接收到该事件
* 事件发生时,当前用户在线时能收到该事件
* 事件发生时,当前用户不在线,那么用户上线后,不会收到该事件
* ```
* @version 1.1.0
*/
class ChatroomMemberBanEvent {
/**
* 聊天室 Id
*/
chatroomId: string = "";
/**
* 禁言操作类型
*/
banType: ChatroomMemberBanType;
/**
* 禁言时长,单位为毫秒:最大值为43200分钟(1个月), 最小值1分钟。 banType 为 禁言 类型时,该字段有效
*/
durationTime: number;
/**
* 操作时间(毫秒时间戳)
*/
operateTime: number;
/**
* 被禁言/解禁言的用户 ID 列表
*/
userIdList: List<string>;
/**
* 附加信息
*/
extra: string = "";
}
/**
* 聊天室禁言/解除禁言操作类型枚举
*/
enum ChatroomMemberBanType {
/**
* 解除指定聊天室中用户禁言
*/
UnmuteUsers = 0,
/**
* 禁言指定聊天室中用户
*/
MuteUsers = 1,
/**
* 解除聊天室全体禁言
*/
UnmuteAll = 2,
/**
* 聊天室全体禁言
*/
MuteAll = 3,
/**
* 移出禁言用户白名单
*/
RemoveWhitelist = 4,
/**
* 添加禁言用户白名单
*/
AddWhitelist = 5,
/**
* 解除用户聊天室全局禁言
*/
UnmuteGlobal = 6,
/**
* 用户聊天室全局禁言
*/
MuteGlobal = 7,
}