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                                                                                              

NIMSystemNotificationFilterrefer 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

NIMSystemNotificationFilterrefer 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

NIMSystemNotificationFilterrefer 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

NIMSystemNotificationFilterrefer 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