事件处理

概述

当 SDK 收到某些后台下发的数据，或者发生了某些需要上层关注的事件时，SDK 会上抛事件对象通知给上层，例如，好友事件、入群申请事件、用户登录状态变更事件等。
应用上层需要根据实际情况决定是否需要接收并且处理事件。

添加监听代理

只有添加了代理，并且上层实现代理方法，才能够接收到相关事件，SDK 所有代理的添加都是通过此接口设置：

JMessage
  1. /*!
  2.  * @abstract 增加回调(delegate protocol)监听
  3.  *
  4.  * @param delegate 需要监听的 Delegate Protocol
  5.  * @param conversation 允许为nil
  6.  *
  7.  * - 为 nil, 表示接收所有的通知, 不区分会话.
  8.  * - 不为 nil，表示只接收指定的 conversation 相关的通知.
  9.  *
  10.  * @discussion 默认监听全局 JMessageDelegate 即可.
  11.  *
  12.  * 这个调用可以在任何地方, 任何时候调用, 可以在未进行 SDK
  13.  * 启动 setupJMessage:appKey:channel:apsForProduction:category: 时就被调用.
  14.  *
  15.  * 并且, 如果你有必要接收数据库升级通知 JMSGDBMigrateDelegate,
  16.  * 就应该在 SDK 启动前就调用此方法, 来注册通知接收.
  17.  * 这样, SDK启动过程中发现需要进行数据库升级, 给 App 发送数据库升级通知时,
  18.  * App 才可以收到并进行处理.
  19.  */
  20. + (void)addDelegate:(id <JMessageDelegate>)delegate withConversation:(JMSGConversation *)conversation;

用户事件

此类事件总体分为：用户信息变更和登录状态变更事件，当前登录用户的登录状态发生变化或者异常时，SDK 会上抛此类型事件，上层通过 JMSGUserDelegate 类里的方法来监听此类事件。

事件类型
  1. typedef NS_ENUM(NSInteger, JMSGLoginStatusChangeEventType) {
  2.   // 用户登录状态变更事件
  3.   /// 事件类型: 登录被踢
  4.   kJMSGEventNotificationLoginKicked = 1,
  5.   /// 事件类型: 非客户端修改密码强制登出事件
  6.   kJMSGEventNotificationServerAlterPassword = 2,
  7.   /// 事件类型：用户登录状态异常事件（需要重新登录）
  8.   kJMSGEventNotificationUserLoginStatusUnexpected = 70,
  9.   /// 事件类型：当前登录用户信息变更通知事件(非客户端修改)
  10.   kJMSGEventNotificationCurrentUserInfoChange = 40,
  11.   /// 事件类型：当前登录用户被删除事件（本地用户信息会被清空）
  12.   kJMSGEventNotificationCurrentUserDeleted = 10001,
  13.   /// 事件类型：当前登录用户被禁用事件（本地用户信息会被清空）
  14.   kJMSGEventNotificationCurrentUserDisabled = 10002,
  15. };
监听方法
  1. /*!
  2.  * @abstract 监听当前用户登录状态变更事件
  3.  *
  4.  * @discussion 可监听：当前登录用户被踢、非客户端修改密码强制登出、登录状态异常、被删除、被禁用、信息变更等事件
  5.  *
  6.  * @since 3.5.0
  7.  */
  8. @optional
  9. - (void)onReceiveUserLoginStatusChangeEvent:(JMSGUserLoginStatusChangeEvent *)event;

消息事件

与消息 JMSGMessage 有关的事件都称之为消息事件，但是消息事件又可分为如下两类：

  • 普通的消息事件：这类事件都是有单独的方法监听，不会入库，SDK 也不会将其主动加入消息记录中。
  • 特殊的消息事件：这是类事件 SDK 会封装为一个消息对象 message 上抛，这些消息事件会入库到消息记录里。这类事件其实就是群会话里的事件，比如：用户加入群组、用户被踢出群组等，

特殊的消息事件

称之为“特殊”，是因为写类型的事件 SDK 会封装成 JMSGMessage 对象后上抛给上层，而其他类型的消息则是通过 JMSGNotificationEvent 对象上抛的。

事件类型
  1. typedef NS_ENUM(NSInteger, JMSGEventNotificationType) {
  2.   // 消息事件
  3.   /// 事件类型: 群组被创建
  4.   kJMSGEventNotificationCreateGroup = 8,
  5.   /// 事件类型: 退出群组
  6.   kJMSGEventNotificationExitGroup = 9,
  7.   /// 事件类型: 群组添加新成员
  8.   kJMSGEventNotificationAddGroupMembers = 10,
  9.   /// 事件类型: 群组成员被踢出
  10.   kJMSGEventNotificationRemoveGroupMembers = 11,
  11.   /// 事件类型: 群信息更新
  12.   kJMSGEventNotificationUpdateGroupInfo = 12,
  13.   /// 事件类型: 群禁言通知事件
  14.   kJMSGEventNotificationGroupMemberSilence = 65,
  15.   /// 事件类型: 管理员角色变更通知事件
  16.   kJMSGEventNotificationGroupAdminChange = 80,
  17.   /// 事件类型: 群主变更通知事件
  18.   kJMSGEventNotificationGroupOwnerChange = 82,
  19.   /// 事件类型: 群类型变更通知事件
  20.   kJMSGEventNotificationGroupTypeChange = 83,
  21.   /// 事件类型: 解散群组
  22.   kJMSGEventNotificationDissolveGroup = 11001,
  23.   /// 事件类型: 群组成员上限变更
  24.   kJMSGEventNotificationGroupMaxMemberCountChange = 11002,
  25. };
监听方法

这类特殊的消息事件的监听分为：在线、离线、漫游。

  • 在线监听方法
  1. /*!
  2.  * @abstract 接收消息(服务器端下发的)回调
  3.  *
  4.  * @param message 接收到下发的消息
  5.  * @param error 不为 nil 表示接收消息出错
  6.  *
  7.  * @discussion 应检查 error 是否为空来判断有没有出错. 如果未出错, 则成功.
  8.  * 留意的是, 这里的 error 不包含媒体消息下载文件错误. 这类错误有单独的回调 onReceiveMessageDownloadFailed:
  9.  *
  10.  * 收到的消息里, 也包含服务器端下发的各类消息事件, 比如有人被加入了群聊. 这类消息事件处理为特殊的 JMSGMessage 类型.
  11.  *
  12.  * 事件类的消息, 基于 JMSGMessage 类里的 contentType 属性来做判断,
  13.  * contentType = kJMSGContentTypeEventNotification.
  14.  */
  15. @optional
  16. - (void)onReceiveMessage:(JMSGMessage *)message error:(NSError *)error;
  • 离线监听方法
  1. /*!
  2.  * @abstract 同步离线消息、离线事件通知
  3.  *
  4.  * @param conversation    同步离线消息的会话
  5.  * @param offlineMessages 离线消息、离线事件数组
  6.  *
  7.  * @discussion 注意：
  8.  *
  9.  * SDK 会将消息下发分为在线下发和离线下发两种情况,
  10.  * 其中用户在离线状态(包括用户登出或者网络断开)期间所收到的消息我们称之为离线消息.
  11.  *
  12.  * 当用户上线收到这部分离线消息后,这里的处理与之前版本不同的是:
  13.  *
  14.  * 3.1.0 版本之前: SDK 会和在线时收到的消息一样,每收到一条消息都会上抛一个在线消息 JMSGMessage 来通知上层.
  15.  *
  16.  * 3.1.0 版本之后: SDK 会以会话为单位，不管该会话有多少离线消息，SDK同步完成后每个会话只上抛一次.
  17.  *
  18.  * 3.2.1 版本之后: SDK 会以会话为单位，不管该会话有多少离线事件，SDK同步完成后每个会话只上抛一次
  19.  *
  20.  * 注意：一个会话最多触发两次这个代理，即：离线消息和离线事件各一次,这样会大大减轻上层在收到消息刷新 UI 的压力.
  21.  *
  22.  * 上层通过此代理方法监听离线消息同步的会话,详见官方文档.
  23.  *
  24.  */
  25. @optional
  26. - (void)onSyncOfflineMessageConversation:(JMSGConversation *)conversation
  27.                          offlineMessages:(NSArray JMSG_GENERIC(__kindof JMSGMessage *)*)offlineMessages;

  • 漫游监听方法

    漫游消息事件则是通过如下方法监听，此方法只会通知上层是某个会话有漫游消息事件，而不会上抛具体的消息事件列表，需上层调用接口从本地获取。

  1. /*!
  2.  * @abstract 同步漫游消息通知
  3.  *
  4.  * @param conversation 同步漫游消息的会话
  5.  *
  6.  * @discussion 注意：
  7.  *
  8.  * 当 SDK 触发此函数时，说明该会话有同步下漫游消息，并且已经存储到本地数据库中，
  9.  * 上层可通过 JMSGConversation 类中的获取message的方法刷新UI.
  10.  *
  11.  * @since 3.1.0
  12.  */
  13. @optional
  14. - (void)onSyncRoamingMessageConversation:(JMSGConversation *)conversation;

普通的消息事件

消息撤回事件

由消息发送方发起调用，在一定时间内，SDK 可以撤回会话中某条消息，一旦消息撤回成功，用户会收到 SDK 上抛的一个 JMSGMessageRetractEvent 事件，上层通过下面的代理来监听。

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
conversation JMSGConversation 消息撤回所属会话
retractMessage JMSGMessage 撤回之后的消息
监听方法
  1. /*!
  2.  * @abstract 监听消息撤回事件
  3.  *
  4.  * @param retractEvent 下发的通知事件，事件类型请查看 JMSGMessageRetractEvent 类
  5.  *
  6.  * @since 3.2.0
  7.  */
  8. @optional
  9. - (void)onReceiveMessageRetractEvent:(JMSGMessageRetractEvent *)retractEvent;
消息回执事件

对于消息接收方，可以将一条消息标记为已读，标记成功后，这条消息的已读状态会记录在本地，SDK 还将主动上抛一个 JMSGMessageReceiptStatusChangeEvent 通知事件

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
conversation JMSGConversation 消息所属会话
messages NSArray(JMSGMessage) 已读回执变更的消息列表
监听方法
  1. /*!
  2.  * @abstract 监听消息回执状态变更事件
  3.  *
  4.  * @param receiptEvent 下发的通知事件，事件类型请查看 JMSGMessageReceiptStatusChangeEvent 类
  5.  *
  6.  * @discussion 上层可以通过 receiptEvent 获取相应信息
  7.  *
  8.  * @since 3.3.0
  9.  */
  10. @optional
  11. - (void)onReceiveMessageReceiptStatusChangeEvent:(JMSGMessageReceiptStatusChangeEvent *)receiptEvent;

群组事件

这里说的群组事件是指需要单独方法来监听的群事件，与消息事件是有区别的。此类事件上层通过 JMSGGroupDelegate 类里的代理方法来监听。

群信息变更通知事件

群信息变更后，后台下发的通知给到SDK，SDK 会主动更新群信息，然后再出发上抛并触发代理方法，上层通过实现该代理可监听群信息变更通知。

监听方法
  1. /*!
  2.  * @abstract 群组信息 (GroupInfo) 变更通知
  3.  *
  4.  * @param group 变更后的群组对象
  5.  *
  6.  * @discussion 如果想要获取通知, 需要先注册回调. 具体请参考 JMessageDelegate 里的说明.
  7.  */
  8. @optional
  9. - (void)onGroupInfoChanged:(JMSGGroup *)group;

申请入群通知事件

该事件通知只适用于公开群，并且只有群主和管理员会收到此事件，事件内的具体参数请查看 JMSGApplyJoinGroupEvent

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
eventID NSString 事件的 id
groupID NSString 群 gid
isInitiativeApply BOOL YES：主动申请加入，NO：被邀请加入
sendApplyUser JMSGUser 发起申请的 user
joinGroupUsers NSArray(JMSGUser) 被邀请入群的 user 数组
reason NSString 原因
监听方法
  1. /*!
  2.  * @abstract 监听申请入群通知
  3.  *
  4.  * @param event 申请入群事件
  5.  *
  6.  * @discussion 只有群主和管理员能收到此事件；申请入群事件相关参数请查看 JMSGApplyJoinGroupEvent 类，在群主审批此事件时需要传递事件的相关参数
  7.  *
  8.  * @since 3.4.0
  9.  */
  10. @optional
  11. - (void)onReceiveApplyJoinGroupApprovalEvent:(JMSGApplyJoinGroupEvent *)event;

管理员拒绝入群申请通知事件

该事件通知只适用于公开群，只有申请方和被申请方会收到此事件，相关参数和返回值请详看 JMSGGroupAdminRejectApplicationEvent

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
groupID NSString 群 gid
rejectReason NSString 拒绝原因
groupManager JMSGUser 操作的管理员
监听方法
  1. /*!
  2.  * @abstract 监听管理员拒绝入群申请通知
  3.  *
  4.  * @param event 拒绝入群申请事件
  5.  *
  6.  * @discussion 只有申请方和被申请方会收到此事件；拒绝的相关描述和原因请查看 JMSGGroupAdminRejectApplicationEvent 类
  7.  *
  8.  * @since 3.4.0
  9.  */
  10. @optional
  11. - (void)onReceiveGroupAdminRejectApplicationEvent:(JMSGGroupAdminRejectApplicationEvent *)event;

管理员审批通知事件

该事件通知只适用于公开群，只有管理员才会收到该事件,当管理员同意或拒绝了某个入群申请事件时，其他管理员就会收到该事件，相关属性请查看 JMSGGroupAdminApprovalEvent 类

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
isAgreeApply BOOL 管理员是否同意申请，YES：同意，NO：拒绝
applyEventID NSString 申请入群事件的事件 id
groupID NSString 群 gid
groupAdmin JMSGUser 操作的管理员
users NSArray(JMSGUser) 申请或被邀请加入群的用户，即：实际入群的用户
监听方法
  1. /*!
  2.  * @abstract 监听管理员审批通知
  3.  *
  4.  * @param event 管理员审批事件
  5.  *
  6.  * @discussion 只有管理员才会收到该事件；当管理员同意或拒绝了某个入群申请事件时，其他管理员就会收到该事件，相关属性请查看 JMSGGroupAdminApprovalEvent 类
  7.  *
  8.  * @since 3.5.0
  9.  */
  10. @optional
  11. - (void)onReceiveGroupAdminApprovalEvent:(JMSGGroupAdminApprovalEvent *)event;

群成员群昵称变更通知事件

该事件适用于任何类型的群组，当群内某个成员改变了在群里的群昵称，SDK 会上抛该事件，如果是离线修改，SDK 会把同一个群内的所有修改昵称的事件一起上抛，事件具体相关属性请查看 JMSGGroupNicknameChangeEvent 类

事件
属性 类型 说明
group JMSGGroup 群组
fromMemberInfo JMSGGroupMemberInfo 修改昵称的群成员
toMemberInfo JMSGGroupMemberInfo 被修改昵称的群成员
ctime UInt64 事件时间
监听方法
  1. /*!
  2.  * @abstract 群成员群昵称变更通知
  3.  *
  4.  * @param events 群成员昵称变更事件列表
  5.  *
  6.  * @discussion 如果是离线事件，SDK 会将所有的修改记录加入数组上抛。事件具体相关属性请查看 JMSGGroupNicknameChangeEvent 类
  7.  *
  8.  * @since 3.7.0
  9.  */
  10. @optional
  11. - (void)onReceiveGroupNicknameChangeEvents:(NSArray<__kindof JMSGGroupNicknameChangeEvent*>*)events;

群公告变更通知事件

该事件适用于任何类型群组，群公告最多100条，发布公告、置顶公告、删除公告都会有事件下发，下发的 JMSGGroupAnnouncementEvent 属性并不是全部都有值，比如：删除公告事件里只有公告 id 是有值的。

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
announcement JMSGGroupAnnouncement 群公告
fromUser JMSGUser 事件操作者
group JMSGGroup 群组
ctime UInt64 事件时间
监听方法
  1. /*!
  2.  * @abstract 群公告变更通知
  3.  *
  4.  * @param event 群公告事件列表
  5.  *
  6.  * @discussion 事件具体相关属性请查看 JMSGGroupAnnouncementEvent 类
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. @optional
  11. - (void)onReceiveGroupAnnouncementEvents:(NSArray<__kindof JMSGGroupAnnouncementEvent*>*)events;

群组黑名单变更通知事件

该事件适用于任何类型群组，黑名单上限100个，超出将无法设置成功，被拉入黑名单用户会被主动踢出群组，且无法再次加入。事件具体相关属性请查看 JMSGGroupBlacklistChangeEvent 类

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
group JMSGGroup 群组
fromUser JMSGUser 事件操作者
targetList NSArray(JMSGUser) 被加入/被删除 群组黑名单的用户列表
监听方法
  1. /*!
  2.  * @abstract 群组黑名单变更通知
  3.  *
  4.  * @param event 群组黑名单事件列表
  5.  *
  6.  * @discussion 事件具体相关属性请查看 JMSGGroupBlacklistChangeEvent 类
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)onReceiveGroupBlacklistChangeEvents:(NSArray<__kindof JMSGGroupBlacklistChangeEvent*>*)events;

聊天室事件

聊天室管理员变更事件通知

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
chatRoom JMSGChatRoom 聊天室
fromUser JMSGUser 事件操作者
targetList NSArray(JMSGUser) 被添加/被删除 聊天室管理员的用户列表
监听方法
  1. /*!
  2.  * @abstract 聊天室管理员变更通知
  3.  *
  4.  * @param event 管理员事件列表
  5.  *
  6.  * @discussion 事件具体相关属性请查看 JMSGChatRoomAdminChangeEvent 类
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)onReceiveChatRoomAdminChangeEvents:(NSArray<__kindof JMSGChatRoomAdminChangeEvent*>*)events;

聊天室黑名单变更事件通知

事件
属性 类型 说明
eventType JMSGEventNotificationType 事件类型
chatRoom JMSGChatRoom 聊天室
fromUser JMSGUser 事件操作者
targetList NSArray(JMSGUser) 被添加/被删除 聊天室黑名单的用户列表
监听方法
  1. /*!
  2.  * @abstract 聊天室黑名单变更通知
  3.  *
  4.  * @param event 黑名单事件列表
  5.  *
  6.  * @discussion 事件具体相关属性请查看 JMSGChatRoomBlacklisChangetEvent 类
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)onReceiveChatRoomBlacklistChangeEvents:(NSArray<__kindof JMSGChatRoomBlacklisChangetEvent*>*)events;

好友事件

可监听：加好友、删除好友、好友更新等事件，具体相关属性请查看 JMSGFriendNotificationEvent

注意：好友相关事件 SDK 并没有做本地化存储，上层想要做记录这些事件，则需要上层自己实现存储。

事件
属性/方法 类型/返回值 说明
eventType JMSGEventNotificationType 事件类型
eventID NSString 事件的 id
getReason NSString 获取事件发生的理由
getFromUsername NSString 事件发送者的username
getFromUser JMSGUser 获取事件发送者user
监听方法
  1. /*!
  2.  * @abstract 监听好友相关事件
  3.  *
  4.  * @discussion 可监听：加好友、删除好友、好友更新等事件
  5.  *
  6.  * @since 3.5.0
  7.  */
  8. @optional
  9. - (void)onReceiveFriendNotificationEvent:(JMSGFriendNotificationEvent *)event;

透传命令事件

  • 命令透传发送后台不会为其离线保存，只会在对方用户在线的前提下将命令推送给对方。
  • SDK 收到命令之后也不会本地保存，不发送通知栏通知，整体快速响应。
  • 透传命令分为会话间透传、设备间透传

开发者可以通过命令透传拓展一些在线场景下的辅助功能，如：实现输入状态提示、控制其他端下线等。 事件相关属性请查看 JMSGMessageTransparentEvent 类

事件

属性 类型 说明
eventType JMSGEventNotificationType 事件类型
transMessageType JMSGTransMessageType 消息透传的类型,单聊、群聊、设备间透传消息
sendUser JMSGUser 透传消息的发送者
target id 透传消息的目标对象，JMSGUser、JMSGGroup
transparentText NSString 透传消息内容
conversation JMSGConversation 透传消息所属会话

监听方法

  1. /*!
  2.  * @abstract 监听消息透传事件
  3.  *
  4.  * @param transparentEvent 下发的通知事件，事件类型请查看 JMSGMessageTransparentEvent 类
  5.  *
  6.  * @discussion 消息透传的类型：单聊、群聊、设备间透传消息
  7.  *
  8.  * @since 3.3.0
  9.  */
  10. @optional
  11. - (void)onReceiveMessageTransparentEvent:(JMSGMessageTransparentEvent *)transparentEvent;