System Notification
Update time: 2021/12/06 15:12:37
In addition to the messages in IM sessions, NIM SDK also provides system notifications for notification distribution beyond messages. There are currently two types: built-in system notification and custom system notification.
Overview
Built-in system notification mainly involves "Apply for joining a group", "reject application", "invite to team", "reject invitation to team" and "add friends". SDK is used for reception and storage, and supports easier unread management.
Built-in system notification is represented by NIMSystemNotification
.
Prototype
/**
* System notification
*/
@interface NIMSystemNotification : NSObject
/**
* Notification type
*/
@property (nonatomic,assign,readonly) NIMSystemNotificationType type;
/**
* Timestamp
*/
@property (nonatomic,assign,readonly) NSTimeInterval timestamp;
/**
* Operator
*/
@property (nullable,nonatomic,copy,readonly) NSString *sourceID;
/**
* Target ID, team ID or user ID
*/
@property (nullable,nonatomic,copy,readonly) NSString *targetID;
/**
* P.S.
*/
@property (nullable,nonatomic,copy,readonly) NSString *postscript;
/**
* It determines to be read.
* @discussion - Updating this attribute will not result in data update in db.
*/
@property (nonatomic,assign) BOOL read;
/**
* Notification processing state
* @discussion - If this attribute is updated, related data in DB will be updated automatically at background. SDK invoker can use the value to persist their handling results for notification. The value is 0 by default.
*/
@property (nonatomic,assign) NSInteger handleStatus;
/**
* Custom extension information published in the system notification
*/
@property (nullable,nonatomic,readonly) NSString *notifyExt;
/**
* Appendix
* @discussion - Extra information. It can be added by friends only. The attachment that is added by friends is NIMUserAddAttachment.
*/
@property (nullable,nonatomic,strong,readonly) id attachment;
@end
Parameter List
Parameter | Type | Description |
---|---|---|
type | NIMSystemNotificationType | Notification type |
timestamp | NSTimeInterval | Timestamp |
sourceID | NSString | Operator |
targetID | NSString | Target ID, team ID or user ID |
postscript | NSString | P.S. |
read | BOOL | Read or not (any modification to this attribute will not affect the data in db) |
handleStatus | NSInteger | Handle status |
notifyExt | NSString | Custom extension information issued by system notification |
attachment | id | Attachment, additional information. Only "Add friends" and "Attachment" are NIMUserAddAttachment |
Monitor system notification
Add agency entrustment:
//NIMSystemNotificationManager.m
//Global monitoring
- (void)viewDidLoad {
...
[[NIMSDK sharedSDK].systemNotificationManager addDelegate:self];
}
Monitor system notifications in the following callback:
@protocol NIMSystemNotificationManagerDelegate <NSObject>
@optional
/**
* Monitor the callback for system notification
*
* @param notification - System notification
*/
-(void)onReceiveSystemNotification:(NIMSystemNotification *)notification;
@end
System Notification Filter
In the event of fetching system notifications from the client, filter rules may be prepared to filter system notifications in part.
Prototype
@interface NIMSystemNotificationFilter : NSObject
/**
* List of types, with value range: Enumeration type NIMSystemNotificationType
*/
@property (nonatomic, copy) NSArray<NSNumber*> *notificationTypes
@end
Get system notification
Get system notification
@protocol NIMSystemNotificationManager <NSObject>
/**
* Get system notification in a local database
*
* @param notification - The current earliest system notification. If there is no such notification, nil will be input.
* @param limit - Acquisition limit
*
* @return - List of system notifications
*/
- (NSArray *)fetchSystemNotifications:(NIMSystemNotification *)notification
limit:(NSInteger)limit;
@end
Parameter List
Parameter | Type | Description |
---|---|---|
notification | NIMSystemNotification | Earliest system notification (input nil if none) |
limit | NSInteger | Maximum number of acquisitions |
Get specified types of system notifications
@protocol NIMSystemNotificationManager <NSObject>
/**
* Get system notification in the local database
*
* @param notification - The current earliest system notification. If there is no such notification, nil will be input.
* @param limit - Acquisition limit
* @param filter - Filter
* @return - List of system notifications
*/
- (nullable NSArray<NIMSystemNotification*> *)fetchSystemNotifications:(nullable NIMSystemNotification *)notification
limit:(NSInteger)limit
filter:(nullable NIMSystemNotificationFilter *)filter;
@end
NIMSystemNotificationFilter
refer to the chapter "System Notification Filter".
Number of unread system notifications
Monitor changes in total unread count
@protocol NIMSystemNotificationManagerDelegate <NSObject>
/**
* Monitor change in total unread count
*
* @param unreadCount - Total unread count of system notifications
*/
- (void)onSystemNotificationCountChanged:(NSInteger)unreadCount;
@end
Get unread count
Get the unread count of built-in systems stored locally
@protocol NIMSystemNotificationManager <NSObject>
/**
* Unread count of system notifications
*
* @return - Unread count of system notifications
*/
- (NSInteger)allUnreadCount;
/**
* Unread count of system notifications
* @param filter - Filter
* @return - Unread count of system notifications
*/
- (NSInteger)allUnreadCount:(nullable NIMSystemNotificationFilter *)filter
@end
NIMSystemNotificationFilter
refer to the chapter "System Notification Filter".
Mark as read
Mark all notifications as read
Mark the built-in system notifications stored locally as read
@protocol NIMSystemNotificationManager <NSObject>
/**
* Mark all system notifications as "Read"
*/
- (void)markAllNotificationsAsRead;
@end
Mark specified notification types as read
@protocol NIMSystemNotificationManager <NSObject>
/**
* Mark designated type of notification as "Read"
*
* @param filter - Filter
*/
- (void)markAllNotificationsAsRead:(nullable NIMSystemNotificationFilter *)filter;
@end
NIMSystemNotificationFilter
refer to the chapter "System Notification Filter".
Mark a single notification as read
@protocol NIMSystemNotificationManager <NSObject>
/**
* Mark a single system notification as "Read"
*
* @param notification - System notification
*/
- (void)markNotificationsAsRead:(NIMSystemNotification *)notification;
@end
Parameter List
Parameter | Type | Description |
---|---|---|
notification | NIMSystemNotification | Earliest system notification (input nil if none) |
Delete system notification
Delete all system notifications
Delete the built-in system notifications stored locally
@protocol NIMSystemNotificationManager <NSObject>
/**
* Delete all system notifications
*/
- (void)deleteAllNotifications;
@end
Delete specified types of system notifications
@protocol NIMSystemNotificationManager <NSObject>
/**
* Delete designated type of system notification
*
* @param filter - Filter
*/
- (void)deleteAllNotifications:(nullable NIMSystemNotificationFilter *)filter;
@end
NIMSystemNotificationFilter
refer to the chapter "System Notification Filter".
Delete a single system notification
@protocol NIMSystemNotificationManager <NSObject>
/**
* Delete a single system notification
*
* @param notification - System notification
*/
- (void)deleteNotification:(NIMSystemNotification *)notification;
@end
Parameter List
Parameter | Type | Description |
---|---|---|
notification | NIMSystemNotification | Earliest system notification (input nil if none) |
Change notification processing state
After handling of the system notification event, the developer may change the handling status of the system notification.
The handling status is defined and analyzed by the developer.
@interface NIMSystemNotification : NSObject
/**
* Notification processing state
* @discussion - If this attribute is updated, related data in DB will be updated automatically at background. SDK invoker can use the value to persist their handling results for notification. The value is 0 by default.
*/
@property (nonatomic,assign) NSInteger handleStatus;
@end
Custom system notification
In addition to built-in system notifications, NIM SDK also provides a custom system to the developer for notification of business logic (such as the function of "Typing……"). The notification may be issued by either the client or the developer server.
Note: The difference between custom notifications and custom messages is that the latter is in the NIM SDK message system and applies to sessions, and the latter is stored by SDK in the message database, and displayed to users together with other built-in message types of NIM SDK. However, custom notifications are mainly used for the notification of some event status of a third party, which SDK will not store, nor include in unread, nor analyze. SDK only helps the third party send and notify these events, while the persistence work after receiving user-defined notification will be undertaken by the upper developer.
Prototype of custom system notification
@interface NIMCustomSystemNotification : NSObject
/**
* Notification ID
* @discussion - Only received custom system notification has notification ID.
*/
@property (nonatomic,assign,readonly) int64_t notificationId;
/**
* Timestamp
*/
@property (nonatomic,assign,readonly) NSTimeInterval timestamp;
/**
* ID of notification sender
*/
@property (nullable,nonatomic,copy,readonly) NSString *sender;
/**
* ID of a notification receiver
*/
@property (nullable,nonatomic,copy,readonly) NSString *receiver;
/**
* Type of notification receiver
*/
@property (nonatomic,assign,readonly) NIMSessionType receiverType;
/**
* Content of transferred message body
*/
@property (nullable,nonatomic,copy,readonly) NSString *content;
/**
* It determines that system notification will be sent to online users only.
* @discussion - The value is "YES" by default. When it is set to "NO", if the notification receiver is not online when the notification is sent, he will receive the notification next time at login.
*/
@property (nonatomic,assign) BOOL sendToOnlineUsersOnly;
/**
* Push text is up to 500 characters in length.
* @discussion - The value is nil by default. Users can set push text of the current notification.
*/
@property (nullable,nonatomic,copy) NSString *apnsContent;
/**
* apns Payload
* @discussion - Users can define push Payload of custom notification by the field. For available fields, refer to Apple technical document.
*/
@property (nullable,nonatomic,copy) NSDictionary *apnsPayload;
/**
* Set custom system notification
* @discussion - Users can configure various settings of current notification by the field, for example, it is included in unread count of pushes, or push prefix is required.
*/
@property (nullable,nonatomic,strong) NIMCustomSystemNotificationSetting *setting;
/**
* Initialization API for custom system notification
*
* @param content - Content of custom system notification
*
* @return - Instance of custom system notification
*/
- (instancetype)initWithContent:(NSString *)content;
@end
Send custom system notification
Custom system notifications are only sent to individuals and teams, instead of chat rooms.
@protocol NIMSystemNotificationManager <NSObject>
/**
* Send custom system notification
*
* @param notification - System notification
* @param session - Receiver
* @param completion - Send the callback for results
*/
- (void)sendCustomNotification:(NIMCustomSystemNotification *)notification
toSession:(NIMSession *)session
completion:(NIMSystemNotificationHandler)completion
@end
Parameter List
Parameter | Type | Description |
---|---|---|
notification | NIMCustomSystemNotification | System notification |
session | NIMSession | Receiver |
completion | NIMSystemNotificationHandler | Result callback |
Example:
NSDictionary *dict = @{
NTESNotifyID : @(NTESCustom),
NTESCustomContent : content,
};
NSData *data = [NSJSONSerialization dataWithJSONObject:dict
options:0
error:nil];
NSString *json = [[NSString alloc] initWithData:data
encoding:NSUTF8StringEncoding];
// Initialize content of custom system notification, and return instance
NIMCustomSystemNotification *notification = [[NIMCustomSystemNotification alloc] initWithContent:json];
// Set push text
notification.apnsContent = content;
// Set to send to online users only. If the receiver is not online, he cannot receive the message.
notification.sendToOnlineUsersOnly = NO;
NIMCustomSystemNotificationSetting *setting = [[NIMCustomSystemNotificationSetting alloc] init];
// The value is "YES" by default. By default, custom system notification that is received by a user will be included in unread count in app icon.
setting.shouldBeCounted = NO;
// Push is required for a message.
setting.apnsEnabled = YES;
// It determines that nickname prefix is required for push. The value is "NO" by default.
setting.apnsWithPrefix = YES;
notification.setting = setting;
[[[NIMSDK sharedSDK] systemNotificationManager] sendCustomNotification:notification
toSession:session
completion:nil];
Receive custom system notification
Receive custom notification
@protocol NIMSystemNotificationManagerDelegate <NSObject>
/**
* A callback for receiving custom notification
* @discussion - The notification is sent from developer server/client and transferred by our server. SDK will not store the information.
* @param notification - Custom notification
*/
- (void)onReceiveCustomSystemNotification:(NIMCustomSystemNotification *)notification;
@end
Parameter List
Parameter | Type | Description |
---|---|---|
notification | NIMCustomSystemNotification | System notification |