Instant Messaging
iOS
Getting Started
Product Introduction
Overview
Features
Feature overview
Account Integration and Login
Basic Message Features
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Limits
Development Integration
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
System Notification
APNs
Superteam
Chat Room
Anti-spam
Chat Extension
Miscellaneous Features
Reference Documents
Configuration Instruction for PushKit
Push Configuration for Apple iOS
API References
iOS API Reference
Status Codes

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                                                                                              

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
Was this topic helpful?
Yes
No
  • Overview
  • Monitor system notification
  • System Notification Filter
  • Get system notification
  • Get system notification
  • Get specified types of system notifications
  • Number of unread system notifications
  • Monitor changes in total unread count
  • Get unread count
  • Mark as read
  • Mark all notifications as read
  • Mark specified notification types as read
  • Mark a single notification as read
  • Delete system notification
  • Delete all system notifications
  • Delete specified types of system notifications
  • Delete a single system notification
  • Change notification processing state
  • Custom system notification
  • Send custom system notification
  • Receive custom system notification