系统通知


概述

除消息通道外,NIM SDK 还提供系统通知这种通道用于消息之外的通知分发。目前有两种类型:内置系统通知和自定义系统通知。 现在主要包括群变动的相关通知,例如入群申请,入群邀请等,如果第三方应用还托管了好友关系,好友的添加、删除也是这个类型的通知。系统通知由 SDK 负责接收和存储,并提供较简单的未读数管理。

内置系统通知

内置系统通知由 NIMSystemNotification 表示。

原型

/**
 *  系统通知
 */
@interface NIMSystemNotification : NSObject
/**
 *  通知类型
 */
@property (nonatomic,assign,readonly)       NIMSystemNotificationType type;

/**
 *  时间戳
 */
@property (nonatomic,assign,readonly)       NSTimeInterval timestamp;

/**
 *  操作者
 */
@property (nullable,nonatomic,copy,readonly)         NSString *sourceID;

/**
 *  目标ID,群ID或者是用户ID
 */
@property (nullable,nonatomic,copy,readonly)         NSString *targetID;

/**
 *  附言
 */
@property (nullable,nonatomic,copy,readonly)         NSString *postscript;

/**
 *  是否已读
 *  @discussion 修改这个属性并不会修改db中的数据
 */
@property (nonatomic,assign)                BOOL read;

/**
 *  消息处理状态
 *  @discussion 修改这个属性,后台会自动更新db中对应的数据,SDK调用者可以使用这个值来持久化他们对消息的处理结果,默认为0
 */
@property (nonatomic,assign)                NSInteger handleStatus;


/**
 *  系统通知下发的自定义扩展信息
 */
@property (nullable,nonatomic,readonly)   NSString *notifyExt;

/**
 *  附件
 *  @discussion 额外信息,只有 好友添加
 *              好友添加的 attachment 为 NIMUserAddAttachment
 */
@property (nullable,nonatomic,strong,readonly)       id attachment;

@end

参数列表

参数 类型 说明
type NIMSystemNotificationType 通知类型
timestamp NSTimeInterval 时间戳
sourceID NSString 操作者
targetID NSString 目标ID,群ID或者是用户ID
postscript NSString 附言
read BOOL 是否已读,修改这个属性并不会修改db中的数据
handleStatus NSInteger 消息处理状态
notifyExt NSString 系统通知下发的自定义扩展信息
attachment id 附件,额外信息,目前只有 好友添加,attachment 为 NIMUserAddAttachment

所有的内置系统通知都是通过

@protocol NIMSystemNotificationManagerDelegate <NSObject>
@optional
/**
 *  收到系统通知回调
 *
 *  @param notification 系统通知
 */
-(void)onReceiveSystemNotification:(NIMSystemNotification *)notification;
@end

群相关系统通知请参考群组功能章节。

添加好友系统通知请参考好友系统通知章节。

下发给 APP。为了保证整个程序逻辑的一致性,APP 需要针对不同类型的系统通知进行相应的操作。

内置系统通知的本地存储:(以下接口分为全量和过滤,过滤接口需要传入过滤器 NIMSystemNotificationFilter,可以按类型选择获取内置系统通知)

NIMSystemNotificationFilter 原型

@interface NIMSystemNotificationFilter : NSObject
/**
 *  类型列表
 */
@property (nonatomic,copy)    NSArray<NSNumber *>     *notificationTypes;
@end

属性列表

属性 类型 说明
notificationTypes NSArray 类型列表

示例

NIMSystemNotificationFilter *filter = [[NIMSystemNotificationFilter alloc] init];
//只对 邀请人群 和 拒绝入群邀请 的系统通知做已读
filter.notificationTypes = @[@(NIMSystemNotificationTypeTeamIviteReject),@(NIMSystemNotificationTypeTeamInvite)];
[[[NIMSDK sharedSDK] systemNotificationManager] markAllNotificationsAsRead:filter];
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  获取本地存储的系统通知
 *
 *  @param notification 当前最早系统消息,没有则传入nil
 *  @param limit        最大获取数
 *
 *  @return 系统消息列表
 */
- (NSArray *)fetchSystemNotifications:(NIMSystemNotification *)notification                                                        
                                  limit:(NSInteger)limit;
@end

参数列表

参数 类型 说明
notification NIMSystemNotification 当前最早系统消息,没有则传入nil
limit NSInteger 最大获取数
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  获取本地存储的系统通知
 *
 *  @param notification 当前最早系统消息,没有则传入nil
 *  @param limit        最大获取数
 *  @param filter       过滤器
 *
 *  @return 系统消息列表
 */
- (NSArray *)fetchSystemNotifications:(NIMSystemNotification *)notification 
                                  limit:(NSInteger)limit                          
                                  filter:(NIMSystemNotificationFilter *)filter;    
@end

参数列表

参数 类型 说明
notification NIMSystemNotification 当前最早系统消息,没有则传入nil
limit NSInteger 最大获取数
filter NIMSystemNotificationFilter 过滤器
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  未读系统消息数
 *
 *  @return 未读系统消息数
 */
- (NSInteger)allUnreadCount;
@end
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  未读系统消息数
 *
 *  @param filter 过滤器
 *
 *  @return 未读系统消息数
 */
- (NSInteger)allUnreadCount:(nullable NIMSystemNotificationFilter *)filter;
@end

参数列表

参数 类型 说明
filter NIMSystemNotificationFilter 过滤器
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  删除所有系统消息
 */
- (void)deleteAllNotifications;
@end
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  删除所有系统消息
 */
- (void)deleteAllNotifications:(NIMSystemNotificationFilter *)filter;   
@end

参数列表

参数 类型 说明
filter NIMSystemNotificationFilter 过滤器
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  删除单条系统消息
 *
 *  @param notification 系统消息
 */
- (void)deleteNotification:(NIMSystemNotification *)notification;
@end

参数列表

参数 类型 说明
notification NIMSystemNotification 当前最早系统消息,没有则传入nil
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  标记所有系统消息为已读
 */
- (void)markAllNotificationsAsRead;
@end
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  标记所有命中过滤器的系统消息为已读
 *
 *  @param filter 过滤器
 */
- (void)markAllNotificationsAsRead:(NIMSystemNotificationFilter *)filter;
@end

参数列表

参数 类型 说明
filter NIMSystemNotificationFilter 过滤器
@protocol NIMSystemNotificationManager <NSObject>
/**
 *  标记单条系统消息为已读
 *
 *  @param notification 系统消息
 */
- (void)markNotificationsAsRead:(NIMSystemNotification *)notification;
@end

参数列表

参数 类型 说明
notification NIMSystemNotification 当前最早系统消息,没有则传入nil

自定义

除内置系统通知外,NIM SDK 也额外提供自定义系统给开发者,方便开发者进行业务逻辑的通知。这个通知既可以由客户端发起也可以由开发者服务器发起。

注意:自定义通知和自定义消息的不同之处在于,自定义消息归属于 NIM SDK 消息体系内,适用于会话,由 SDK 存储在消息数据库中,与 NIM SDK 其他内建消息类型一同展现给用户。而自定义通知主要用于第三方的一些事件状态通知,SDK 不存储,也不解析这些通知。SDK 仅仅负责替第三方传递和通知这些事件,起到透传的作用,收到自定义通知后的持久化工作需要由上层开发负责。

发送自定义通知(客户端)

@protocol NIMSystemNotificationManager <NSObject>
/**
 *  发送自定义系统通知
 *
 *  @param notification 系统通知
 *  @param session      接收方
 *  @param completion   发送结果回调
 */
- (void)sendCustomNotification:(NIMCustomSystemNotification *)notification
                     toSession:(NIMSession *)session
                    completion:(NIMSystemNotificationHandler)completion
@end

参数列表

参数 类型 说明
notification NIMCustomSystemNotification 系统通知
session NIMSession 接收方
completion NIMSystemNotificationHandler 发送结果回调

客户端发起的自定义通知目前支持自定义如下字段:通知内容(推荐使用 json 组织),推送文案(如果没有则不进行 APNS 推送),是否只发给在线用户。最后一个字段的意义在于区分自定义通知的使用场景。选择只发给在线用户,当目标用户不在线时这条通知会被云信服务器丢弃,这种实现比较适合发送即时通知,如正在输入。反之云信服务器会缓存当前通知(有上限),并在目标用户上线后推送给目标用户。

仅支持个人和群。不支持聊天室。

接收自定义通知

@protocol NIMSystemNotificationManagerDelegate <NSObject>
/**
 *  收到自定义通知回调
 *  @discussion 这个通知是由开发者服务端/客户端发出,由我们的服务器进行透传的通知,SDK不负责这个信息的存储
 *  @param notification 自定义通知
 */
- (void)onReceiveCustomSystemNotification:(NIMCustomSystemNotification *)notification;
@end

参数列表

参数 类型 说明
notification NIMCustomSystemNotification 系统通知