监听聊天室事件
聊天室业务为客户端 App 提供三种类型的事件监听器:聊天室状态监听器、聊天室成员变化监听器、聊天室事件通知监听器。
通过 SDK 提供的以上监听 器,客户端 App 可以从融云服务端获取聊天室销毁状态、用户在当前及其他客户端加入退出聊天室的状态、聊天室中成员进出的事件通知、以及聊天室中成员禁言、封禁相关的信息。
监听器 | 名称 | 说明 |
---|---|---|
ChatroomStatusListener | 聊天室状态监听器 | 接收在当前客户端登录的用户加入、退出聊天室的事件与聊天室销毁状态的信息。 |
ChatroomMemberActionListener | 聊天室成员变化监听器 | 接收当前用户所在聊天室中其他用户加入、退出聊天室的信息。 |
ChatroomNotifyEventListener | 聊天室事件通知监听器 | 接收当前所在聊天室中成员禁言、封禁相关的信息;接收当前用户在其他端加入、退出聊天室相关的信息。 |
监听聊天室状态
应用程序可以监听当前客户端上用户加入、退出聊天室的事件与聊天室销毁状态变更。
使用 setChatroomStatusListener
来设置聊天室状态监听器。
let listener: ChatroomStatusListener = {
onChatroomJoining(roomId: string): void {
hilog.info(0x0000, 'IM-App', 'onChatroomJoining roomId:%{public}s', roomId);
},
onChatroomJoined(roomId: string, info: ChatroomJoinedInfo): void {
hilog.info(0x0000, 'IM-App', 'onChatroomJoined roomId:%{public}s info:%{public}s', roomId,
JSON.stringify(info));
},
onChatroomJoinFailed(roomId: string, code: EngineError): void {
hilog.info(0x0000, 'IM-App', 'onChatroomJoined roomId:%{public}s code:%{public}d', roomId, code);
},
onChatroomQuited(roomId: string): void {
hilog.info(0x0000, 'IM-App', 'onChatroomQuited roomId:%{public}s', roomId);
},
onChatroomDestroyed(roomId: string, type: ChatroomDestroyType): void {
hilog.info(0x0000, 'IM-App', 'onChatroomDestroyed roomId:%{public}s type:%{public}d', roomId, type);
},
}
IMEngine.getInstance().setChatroomStatusListener(listener);
监听聊天室成员变化
SDK 从 1.1.0 版本开始支持监听聊天室成员变化。
从 1.1.0 版本,SDK 开始新增 ChatroomMemberActionListener,支持当前登录用户监听所在聊天室中其它成员的加入、退出行为。
开通服务
此功能需要开通服务后方可使用。如有需求,请提交工单,申请开通聊天室成员变化监听。
设置聊天室成员变化监听器
let listener: ChatroomMemberActionListener = {
onMemberChange: (actionModel: ChatRoomMemberActionModel): void => {
hilog.info(0x0000, 'IM-App', 'onMemberChange actionModel:%{public}s', JSON.stringify(actionModel));
}
}
IMEngine.getInstance().setChatroomMemberListener(listener);
如果当前用户由于网络原因和聊天室断开连接,则无法监听到断开连接期间的其他成员的加入、退出行为。
监听聊天室事件通知
SDK 从 1.1.0 开始支持监听聊天室事件通知。
应用程序可以监听当前聊天室中成员禁言、封禁相关的通知,以及当前用户在其他端加入、退出聊天室相关的通知。
let listener: ChatroomNotifyEventListener = {
onChatroomNotifyMultiLoginSync: (syncEvent: ChatroomSyncEvent): void => {
hilog.info(0x0000, 'IM-App', 'onChatroomNotifyMultiLoginSync syncEvent:%{public}s', JSON.stringify(syncEvent));
},
onChatroomNotifyBlock: (blockEvent: ChatroomMemberBlockEvent): void => {
hilog.info(0x0000, 'IM-App', 'onChatroomNotifyBlock blockEvent:%{public}s', JSON.stringify(blockEvent));
},
onChatRoomNotifyBan: (banEvent: ChatroomMemberBanEvent): void => {
hilog.info(0x0000, 'IM-App', 'onChatRoomNotifyBan banEvent:%{public}s', JSON.stringify(banEvent));
}
}
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
),触发 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
),触发 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,
}