系统通知 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

系统通知

更新时间： 2024/03/14 17:08:34

除IM会话内消息外，NIM SDK 还提供系统通知用于消息之外的通知分发。目前有两种类型:内置系统通知和自定义系统通知。

内置系统通知概述

内置系统通知主要分为申请入群、拒绝申请入群、邀请入群、拒绝邀请入群和好友添加相关。由 SDK 负责接收和存储，并提供较简单的未读数管理。

内置系统通知由 NIMSystemNotification 表示。

原型

objc/**
 *  系统通知
 */
@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

监听系统通知

先添加代理委托：

objc//NIMSystemNotificationManager.m
//全局监听
- (void)viewDidLoad {
    ...
    [[NIMSDK sharedSDK].systemNotificationManager addDelegate:self];
}

在以下回调里可以监听到系统通知：

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

系统通知过滤器

在从客户端本地获取系统通知等情况下，可以设定过滤规则，过滤出部分类型的系统通知。

原型

objc@interface NIMSystemNotificationFilter : NSObject
/**
* 类型列表,取值范围为: NIMSystemNotificationType 枚举类型
*/
@property (nonatomic, copy) NSArray<NSNumber*> *notificationTypes
@end

获取系统通知

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  获取本地存储的系统通知
 *
 *  @param notification 当前最早系统通知,没有则传入nil
 *  @param limit        最大获取数
 *
 *  @return 系统通知列表
 */
- (NSArray *)fetchSystemNotifications:(NIMSystemNotification *)notification                                                        
                                limit:(NSInteger)limit;
@end

参数列表

参数	类型	说明
notification	NIMSystemNotification	当前最早系统通知,没有则传入nil
limit	NSInteger	最大获取数

获取指定类型系统通知

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

NIMSystemNotificationFilter参见系统通知过滤器章节。

系统通知未读数

监听总未读数变更

objc@protocol NIMSystemNotificationManagerDelegate <NSObject>
/**
 *  监听总未读数变更
 *
 *  @param unreadCount 系统通知总未读数
 */
- (void)onSystemNotificationCountChanged:(NSInteger)unreadCount;
@end

获取未读数

获取本地存储的内置系统未读数

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  未读系统通知数
 *
 *  @return 未读系统通知数
 */
- (NSInteger)allUnreadCount;

/**
 *  未读系统通知数
 *  @param filter  过滤器
 *  @return 未读系统通知数
 */
- (NSInteger)allUnreadCount:(nullable NIMSystemNotificationFilter *)filter

@end

NIMSystemNotificationFilter参见系统通知过滤器章节。

标记为已读

标记所有通知为已读

标记本地存储的内置系统通知为已读

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  标记所有系统通知为已读
 */
- (void)markAllNotificationsAsRead;
@end

标记指定类型通知为已读

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  标记指定类型通知为已读
 *
 *  @param filter 过滤器
 */
- (void)markAllNotificationsAsRead:(nullable NIMSystemNotificationFilter *)filter;
@end

NIMSystemNotificationFilter参见系统通知过滤器章节。

标记单条通知为已读

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  标记单条系统通知为已读
 *
 *  @param notification 系统通知
 */
- (void)markNotificationsAsRead:(NIMSystemNotification *)notification;
@end

参数列表

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

删除系统通知

删除所有系统通知

删除本地存储的内置系统通知

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  删除所有系统通知
 */
- (void)deleteAllNotifications;
@end

删除指定类型系统通知

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  删除指定类型系统通知
 *
 *  @param filter 过滤器
 */
- (void)deleteAllNotifications:(nullable NIMSystemNotificationFilter *)filter;
@end

NIMSystemNotificationFilter参见系统通知过滤器章节。

删除单条系统通知

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  删除单条系统通知
 *
 *  @param notification 系统通知
 */
- (void)deleteNotification:(NIMSystemNotification *)notification;
@end

参数列表

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

更改通知处理状态

当对系统通知事件作出相应的处理后，开发者可以更改该系统通知的处理状态。

当前，处理状态由开发者自定义，解析工作也由开发者负责。

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

自定义系统通知

除内置系统通知外，NIM SDK 也额外提供自定义系统给开发者，方便开发者进行业务逻辑的通知（如实现对方正在输入中···等功能）。这个通知既可以由客户端发起也可以由开发者服务器发起。

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

自定义系统通知原型

objc@interface NIMCustomSystemNotification : NSObject
/**
 *  通知 ID
 *  @discussion 只有收到的自定义系统通知才有通知 ID
 */
@property (nonatomic,assign,readonly)       int64_t notificationId;

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

/**
 *  通知发起者id
 */
@property (nullable,nonatomic,copy,readonly)         NSString *sender;

/**
 *  通知接受者id
 */
@property (nullable,nonatomic,copy,readonly)         NSString *receiver;


/**
 *  通知接受者类型
 */
@property (nonatomic,assign,readonly)       NIMSessionType  receiverType;

/**
 *  透传的消息体内容
 */
@property (nullable,nonatomic,copy,readonly)         NSString    *content;

/**
 *  是否只发送给在线用户
 *  @discussion 默认为YES 如果这个值为NO,通知接受者如果在通知投递时不在线,那么他会在下次登录时收到这个通知
 */
@property (nonatomic,assign)                BOOL sendToOnlineUsersOnly;

/**
 *  推送文案，长度限制500字
 *  @discussion 默认为nil,用户可以设置当前通知的推送文案
 */
@property (nullable,nonatomic,copy)                  NSString *apnsContent;


/**
 *  apns推送Payload
 *  @discussion 可以通过这个字段定义自定义通知的推送Payload,支持字段参考苹果技术文档
 */
@property (nullable,nonatomic,copy)                  NSDictionary *apnsPayload;

/**
 *  自定义系统通知设置
 *  @discussion 可以通过这个字段制定当前通知的各种设置,如是否需要计入推送未读，是否需要带推送前缀等等
 */
@property (nullable,nonatomic,strong)                NIMCustomSystemNotificationSetting *setting;

/**
 *  自定义系统通知初始化方法
 *
 *  @param content 自定义系统通知内容
 *
 *  @return 自定义系统通知实例
 */
- (instancetype)initWithContent:(NSString *)content;
@end

发送自定义系统通知

自定义系统通知的发送仅支持个人和群，不支持聊天室。

一秒内默认最多调用该接口100次。如需上调上限，请在官网首页通过微信、在线消息或电话等方式咨询商务人员。

objc@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	发送结果回调

示例：

objcNSDictionary *dict = @{
                        NTESNotifyID : @(NTESCustom),
                        NTESCustomContent : content,
                      };
NSData *data = [NSJSONSerialization dataWithJSONObject:dict
                                               options:0
                                                 error:nil];
NSString *json = [[NSString alloc] initWithData:data
                                       encoding:NSUTF8StringEncoding];
// 初始化自定义系统通知内容，并返回实例
NIMCustomSystemNotification *notification = [[NIMCustomSystemNotification alloc] initWithContent:json];
// 设置推送文案
notification.apnsContent = content;
// 设置只发给在线用户，若接收者不在线，则收不到。
notification.sendToOnlineUsersOnly = NO;

NIMCustomSystemNotificationSetting *setting = [[NIMCustomSystemNotificationSetting alloc] init];
// 默认为YES。默认情况下，用户收到的自定义系统通知会在应用图标上累计未读。
setting.shouldBeCounted = NO;
// 消息需要推送
setting.apnsEnabled = YES;
// 推送是否需要带昵称前缀。默认为NO。
setting.apnsWithPrefix = YES;
notification.setting = setting;
[[[NIMSDK sharedSDK] systemNotificationManager] sendCustomNotification:notification
                                                             toSession:session
                                                            completion:nil];

接收自定义系统通知

接收自定义通知

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

参数列表

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

此文档是否对你有帮助？

有帮助

去反馈

内置系统通知概述
监听系统通知
系统通知过滤器
获取系统通知
获取系统通知
获取指定类型系统通知
系统通知未读数
监听总未读数变更
获取未读数
标记为已读
标记所有通知为已读
标记指定类型通知为已读
标记单条通知为已读
删除系统通知
删除所有系统通知
删除指定类型系统通知
删除单条系统通知
更改通知处理状态
自定义系统通知
发送自定义系统通知
接收自定义系统通知