In addition to in-session messages, the NIM SDK also provides system notifications for notification distribution other than messages. You can implement built-in system notifications and custom system notification.

System notification overview

The built-in system notifications are sent for events, such as sending a join request, rejecting a join request, sending an invitation, rejecting an invitation, and friend operations. The SDK can receive notifications, store the data on the local database, and manage the unread count of notifications.

NIMSystemNotification representation

Prototype

objc/**
 *  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, group ID or user ID
 */
@property (nullable,nonatomic,copy,readonly)         NSString *targetID;

/**
 *  Additional message
 */
@property (nullable,nonatomic,copy,readonly)         NSString *postscript;

/**
 *  Check whether a message is read
 *  @discussion Editing the property will not modify the data in the database
 */
@property (nonatomic,assign)                BOOL read;

/**
 *  Handle the status of a notification.
 * @discussion Editing this property will automatically update the data in the database. The SDK can persist the result using this value. The default value is 0.
 */
@property (nonatomic,assign)                NSInteger handleStatus;


/**
 *  Custom extension field for system notifications
 */
@property (nullable,nonatomic,readonly)   NSString *notifyExt;

/**
 * Message attachment
 * @discussion extra information, only the friend request. The attachment added by the friend request is NIMUserAddAttachment
 */
@property (nullable,nonatomic,strong,readonly)       id attachment;

@end

Properties

Parameter	Type	Description
type	NIMSystemNotificationType	The type of notifications
timestamp	NSTimeInterval	The timestamp.
sourceID	NSString	The operator
targetID	NSString	Target ID, group ID, or user ID
postscript	NSString	The additional message
read	BOOL	Whether a notification is read. Updating this property will not modify the data in the database.
handleStatus	NSInteger	The status of a notification.
notifyExt	NSString	Custom extension field for system notifications
attachment	id	The attachment added by the friend request is NIMUserAddAttachment.

Listener for system notifications

• Add a delegate:

objc//NIMSystemNotificationManager.m
//Global listener
- (void)viewDidLoad {
    ...
    [[NIMSDK sharedSDK].systemNotificationManager addDelegate:self];
}

System notifications can be monitored by the following callback:

objc@protocol NIMSystemNotificationManagerDelegate <NSObject>
@optional
/**
 *  Listener to system notifications
 *
 *  @param notification system notification
 */
-(void)onReceiveSystemNotification:(NIMSystemNotification *)notification;
@end

Filter for system notifications

In case a client receives system notifications, you can set filter rules can filter out some types of system notifications.

Prototype

objc@interface NIMSystemNotificationFilter : NSObject
/**
* Type list. The value range is: NIMSystemNotificationType enums
*/
@property (nonatomic, copy) NSArray<NSNumber*> *notificationTypes
@end

Get a system notification

Get a system notification

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 * Get a system message stored locally
 *
 * @param notification The current earliest system notification. If no system notification exist, pass nil.
 *  @param limit        the maximum allowed messages
 *
 * @return A list of system messages
 */
- (NSArray *)fetchSystemNotifications:(NIMSystemNotification *)notification                                                        
                                limit:(NSInteger)limit;
@end                                                                                                

Properties

Parameter	Type	Description
notification	NIMSystemNotification	The current earliest system notification. If no system notification exist, pass nil.
limit	NSInteger	the maximum allowed messages

Get system notifications of a specified type

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 * Get a system message stored locally
 *
 * @param notification The current earliest system notification. If no system notification exist, pass nil.
 *  @param limit        the maximum allowed messages
 *  @param filter       filter
 * @return A list of system messages
 */
- (nullable NSArray<NIMSystemNotification*> *)fetchSystemNotifications:(nullable NIMSystemNotification *)notification 
                                                                 limit:(NSInteger)limit 
                                                                filter:(nullable NIMSystemNotificationFilter *)filter;
@end                                                                                              

NIMSystemNotificationFilter see System Notification Filters section.

Get the unread count of system notifications

Listen to changes of unread count

objc@protocol NIMSystemNotificationManagerDelegate <NSObject>
/**
 * Listener to changes of the total unread count
 *
 *  @param unreadCount unread count of system notifications
 */
- (void)onSystemNotificationCountChanged:(NSInteger)unreadCount;
@end

Get the unread count

Get the unread count of built-in system notifications from the local storage.

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 * Get the unread count of system notifications
 *
 *  @return the unread count of system notifications
 */
- (NSInteger)allUnreadCount;

/**
 * Get the unread count of system notifications
 *  @param filter  The filter
 *  @return the unread count of system notifications
 */
- (NSInteger)allUnreadCount:(nullable NIMSystemNotificationFilter *)filter

@end

NIMSystemNotificationFilter see System Notification Filters section.

Mark as read

Mark all system notifications as read

Mark all local built-in system notifications read.

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  Mark all system notifications as read
 */
- (void)markAllNotificationsAsRead;
@end

Mark all system notifications of a specified type as read

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 * Mark all system messages of a specified type as read
 *
 *  @param filter filter
 */
- (void)markAllNotificationsAsRead:(nullable NIMSystemNotificationFilter *)filter;
@end

NIMSystemNotificationFilter see System Notification Filters section.

Mark a system notification as read

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  Mark an unread system notification as read
 *
 *  @param notification system notification
 */
- (void)markNotificationsAsRead:(NIMSystemNotification *)notification;
@end

Properties

Parameter	Type	Description
notification	NIMSystemNotification	The current earliest system notification. If no system notification exist, pass nil.

Delete system notifications

Delete all system notifications

Delete all local built-in system notifications

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 * Delete all system messages.
 */
- (void)deleteAllNotifications;
@end

Deleted system notifications of a specified type

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 * Delete system messages of a specified type
 *
 *  @param filter filter
 */
- (void)deleteAllNotifications:(nullable NIMSystemNotificationFilter *)filter;
@end

NIMSystemNotificationFilter see System Notification Filters section.

Delete a system notification

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 * Delete an unread system notification
 *
 *  @param notification system notification
 */
- (void)deleteNotification:(NIMSystemNotification *)notification;
@end

Properties

Parameter	Type	Description
notification	NIMSystemNotification	The current earliest system notification. If no system notification exist, pass nil.

Set the state of system messages

After handling the system notification event, you can change the status of a system notification.

You can define and parse custom states for handling system notification.

objc@interface NIMSystemNotification : NSObject
/**
 *  Handle the status of a notification.
 * @discussion Editing this property will automatically update the data in the database. The SDK can persist the result using this value. The default value is 0.
 */
@property (nonatomic,assign)        NSInteger handleStatus;
@end

Custom system notifications

In addition to the built-in system notification, the NIM SDK also provides an additional custom system to facilitate the notification of business logic, such as that the peer is typing.... This notification can be initiated by either the client or the app server.

** Note that custom messages belongs to the messaging system of CommsEase, which is suitable for conversations, stored in the message database by the SDK, and displayed to users together with other built-in message types of CommsEase. Custom notifications are used for third-party event status notifications, and the SDK does not store, count unread counts, or parse these notifications. The SDK transmits and notify these events. The upper layer of your app can handle the persistence of custom notifications.**

Custom system notifications prototype

objc@interface NIMCustomSystemNotification : NSObject
/**
 *  Notification ID
 * @discussion Only received custom system notifications have notification IDs
 */
@property (nonatomic,assign,readonly)       int64_t notificationId;

/**
 *  Timestamp
 */
@property (nonatomic,assign,readonly)       NSTimeInterval timestamp;

/**
 *  Sender ID
 */
@property (nullable,nonatomic,copy,readonly)         NSString *sender;

/**
 *  Recipient ID
 */
@property (nullable,nonatomic,copy,readonly)         NSString *receiver;


/**
 *  Recipient types
 */
@property (nonatomic,assign,readonly)       NIMSessionType  receiverType;

/**
 *  Message body in pass-through mode
 */
@property (nullable,nonatomic,copy,readonly)         NSString    *content;

/**
 * Specify whether to deliver messages only to online users
 * @discussion The default value is YES. If this value is set to NO, the recipient will receive the notification the next time the user logs in
 */
@property (nonatomic,assign)                BOOL sendToOnlineUsersOnly;

/**
 * Push notification content that can contain up to 500 characters
 * @discussion The default value is nil, users can specify the content of the current notification.
 */
@property (nullable,nonatomic,copy)                  NSString *apnsContent;


/**
 * APNS payload of a push notification
 * @discussion The field can contain a custom notification as payload. For more information about supported types, see the official Apple documentation.
 */
@property (nullable,nonatomic,copy)                  NSDictionary *apnsPayload;

/**
 *  Custom settings of system notifications
 *  @discussion The field can be specified for settings, such as count as unread, and multi-device sync
 */
@property (nullable,nonatomic,strong)                NIMCustomSystemNotificationSetting *setting;

/**
 *  Initialization method of custom system notifications
 *
 *  @param content  custom content of a system notification
 *
 *@return custom system notifications instance
 */
- (instancetype)initWithContent:(NSString *)content;
@end

Send a custom system notification

Custom system notifications only supports P2P chats and group chats, not chat rooms.

• By default, up to 100 calls per second are allowed. - To increase the limit, contact the sales manager over the Whatsapp on the CommsEase website.

objc@protocol NIMSystemNotificationManager <NSObject>
/**
 *  Send custom system notifications
 *
 *  @param notification system notification
 *  @param session      receipient
 *  @param completion   Completion callback
 */
- (void)sendCustomNotification:(NIMCustomSystemNotification *)notification
                     toSession:(NIMSession *)session
                    completion:(NIMSystemNotificationHandler)completion
@end                    

Properties

Parameter	Type	Description
notification	NIMCustomSystemNotification	Custom system notification
session	NIMSession	Session
completion	NIMSystemNotificationHandler	Callback for completion.

Example:

objcNSDictionary *dict = @{
                        NTESNotifyID : @(NTESCustom),
                        NTESCustomContent : content,
                      };
NSData *data = [NSJSONSerialization dataWithJSONObject:dict
                                               options:0
                                                 error:nil];
NSString *json = [[NSString alloc] initWithData:data
                                       encoding:NSUTF8StringEncoding];
// Instantiate a custom system notification
NIMCustomSystemNotification *notification = [[NIMCustomSystemNotification alloc] initWithContent:json];
// Add the content for the push notification
notification.apnsContent = content;
// Send the notifications to online users. Offline users cannot recieve the notification.
notification.sendToOnlineUsersOnly = NO;

NIMCustomSystemNotificationSetting *setting = [[NIMCustomSystemNotificationSetting alloc] init];
// The default value is YES. By default, custom system notifications received by users are counted unread on the app badge.
setting.shouldBeCounted = NO;
// Enable the APNs service for the notification
setting.apnsEnabled = YES;
//  Specify whether a prefix is added to the notification. The default value is NO.
setting.apnsWithPrefix = YES;
notification.setting = setting;
[[[NIMSDK sharedSDK] systemNotificationManager] sendCustomNotification:notification
                                                             toSession:session
                                                            completion:nil];

Receive custom system notifications

Receive custom system notifications

objc@protocol NIMSystemNotificationManagerDelegate <NSObject>
/**
 *  Get notified when a custom system notification is received
 * @discussion The notification is sent by the app server or client and is transmitted in transparent data transmission mode by CommsEase. The SDK does not store the data.
 *  @param notification Custom notification
 */
- (void)onReceiveCustomSystemNotification:(NIMCustomSystemNotification *)notification;
@end

Properties

Parameter	Type	Description
notification	NIMCustomSystemNotification	Custom system notification