Overview

System notification is built-in message CommsEase system and corresponding data structure is SystemMessage. The notification messages pushed from CommsEase server to users are used for event notifications of CommsEase system. System notifications mainly include team change notifications, such as application for joining a team and team invitation. If the third-party app also hosts friendship, addition and removal of friends are also included into this type of notification. System notifications are received and stored by SDK that supports simple management of unread count.

SystemMessage interface:

Return	SystemMessage interface	Description
String	getAttach()	Get attachment of system notification.
Object	getAttachObject()	Get object after analysis for attachment of system notification.
String	getContent()	Get content of system notification.
String	getCustomInfo()	Get user-defined information. It can be set only when members are invited and added to the group.
String	getFromAccount()	Account of system notification sender.
long	getMessageId()	Get ID of system notification.
SystemMessageStatus	getStatus()	Get processing state of system notification.
String	getTargetId()	Get target ID of system notification.
long	getTime()	Get the time of sending system notification, unit: ms.
SystemMessageType	getType()	Get the type of system notification.
boolean	isUnread()	Determine that the system notification is read.
void	setAttach(String attach)	Set attachment content of system notification.
void	setAttachObject(Object object)	Set attachment object after analysis.
void	setContent(String content)	Set content of system notification.
void	setFromAccount(String fromAccount)	Set account of message sender.
void	setMessageId(long messageId)	Set ID of system notification.
void	setStatus(SystemMessageStatus status)	Set processing state of system notification.
void	setTargetId(String targetId)	Set target ID of system notification.
void	setTime(long time)	Set sending time of system notification.
void	setType(int type)	Set type of system notification.
void	setUnread(boolean unread)	Set and alter system notification to "Read/Unread".

Listening for system notifications

The API is used to listen for the events that trigger specific system notifications.

• API prototype

java/**
 * Register or unregister the observer for system notification receiving event.
 * @param observer - Observer. The parameter is received system message.
 * @param register true indicates registered, and true indicates unregistered.
 */
public void observeReceiveSystemMsg(Observer<SystemMessage> observer, boolean register);

• Example

javaNIMClient.getService(SystemMessageObserver.class)
	.observeReceiveSystemMsg(new Observer<SystemMessage>() {
            @Override
            public void onEvent(SystemMessage message) {
	            // The system notification is received, and related operations can be made.
            }
        }, register);

System notifications

Getting system notifications

• API prototype

java/**
 * Query the list of system notifications
 *
 * @return InvocationFuture - Configurable callback feature. The parameter is list of system notifications.
 */
 // asynchronous
public InvocationFuture<List<SystemMessage>> querySystemMessages(int offset, int limit);

 // synchronous 
public List<SystemMessage> querySystemMessagesBlock(int offset, int limit);

• Parameters

Parameter	Description
offset	Offset quantity of database query
limit	Quantity of database query

• Example

1. Asynchronous interface

java// Start from 10 messages and query 10 system notifications
NIMClient.getService(SystemMessageService.class).querySystemMessages(10, 10)
       .setCallback(new RequestCallback<List<SystemMessage>>() {
    @Override
    public void onSuccess(List<SystemMessage> param) {
        // Query successful
    }

    @Override
    public void onFailed(int code) {
		// Query failed
    }

    @Override
    public void onException(Throwable exception) {
		// error
    }
});

2. Synchronous interface

java// The parameter is that offset messages have been queried now, and limit is to continue querying limit messages.
List<SystemMessage> temps = NIMClient.getService(SystemMessageService.class).querySystemMessagesBlock(offset, limit); 

Getting system notifications of a specified type

The system message type SystemMessageType is required.

• API prototype

java/**
 * Query the list of system notifications by type.
 *
 * @return - Set of system notifications of specified type
 */
 // synchronous
public List<SystemMessage> querySystemMessageByTypeBlock(List<SystemMessageType> types, int offset, int limit);

 // asynchronous
public InvocationFuture<List<SystemMessage>> querySystemMessageByType(List<SystemMessageType> types, int offset, int limit);

• Parameters

Parameter	Description
types	Set of system notification type to be queried
offset	Offset quantity of database query
limit	Quantity of database query

• Example

1. Synchronous interface

javaList<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// Query "Add friends" type system notifications only, start from the beginning to query 3 notifications.
List<SystemMessage> temps = NIMClient.getService(SystemMessageService.class)
   .querySystemMessageByTypeBlock(types, 0, 3);

2. Asynchronous interface

javaList<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// Query "Add friends" type system notifications only, start from the beginning to query 3 notifications.
NIMClient.getService(SystemMessageService.class).querySystemMessageByType(types, 0, 3)
       .setCallback(new RequestCallback<List<SystemMessage>>() {
    @Override
    public void onSuccess(List<SystemMessage> param) {
	     // Successful query 
    }

    @Override
    public void onFailed(int code) {
		// Query failure
    }

    @Override
    public void onException(Throwable exception) {
		// error
    }
});

Getting the unread count of system notifications

java/**
 * Get all unread system notifications
 *
 * @return - Configurable callback feature. The parameter is set of all unread system notifications.
 */
InvocationFuture<java.util.List<SystemMessage>> querySystemMessageUnread();

Unread count of system notifications

Listening for changes in total unread count

The change in a total number of unread system messages can be tracked using this interface.

• API prototype

java/**
 * Register or cancel observer forunread count change event of system notifications.
 * @param observer - The parameter is unread count of current system messages.
 * @param register true indicates registered, and true indicates unregistered.
 */
public void observeUnreadCountChange(Observer<Integer> observer, boolean register);

• Example

javaNIMClient.getService(SystemMessageObserver.class)
   .observeUnreadCountChange(sysMsgUnreadCountChangedObserver, register);

private Observer<Integer> sysMsgUnreadCountChangedObserver = new Observer<Integer>() {
        @Override
        public void onEvent(Integer unreadCount) {
            // Update change in unread count
        }
    };

Getting the unread count

Queryig the total unread count

The attribute "unread" in SystemMessage is used to mark that the system notification is unread. The feature will return total number of unread system notifications.

• API prototype

java/**
 * Query total unread count of system notifications
 *
 * @return - Total unread count of system notifications
 */
public int querySystemMessageUnreadCountBlock();

• Example

javaint unread = NIMClient.getService(SystemMessageService.class).querySystemMessageUnreadCountBlock();

Total unread count of specified type

• API prototype

java/**
 * Query total unread count of system notifications of specified type
 *
 * @param types - Set of system notification types
 * @return - Total unread count of system notifications of specified type
 */
public int querySystemMessageUnreadCountByType(List<SystemMessageType> types);

• Example

javaList<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// Query total unread count of system notifications of "Add friends" type
int unread = NIMClient.getService(SystemMessageService.class)
	.querySystemMessageUnreadCountByType(types);

Mark as read

Mark all notifications as read

The unread count of system notifications becomes 0 after the operation is performed.

• API prototype

java/**
 * Set all system notifications to acknowledged. The total unread count of system notifications will be cleared.
 */
public void resetSystemMessageUnreadCount();

• Example

java// After accessing the list of system notifications, you can set the unread count to 0.
NIMClient.getService(SystemMessageService.class).resetSystemMessageUnreadCount();

Markig specified notification types as read

• API prototype

java/**
 * Set system notifications of specified type to "acknowledged"
 *
 * @param types - Set of system notification types
 */
public void resetSystemMessageUnreadCountByType(List<SystemMessageType> types);

• Example

javaList<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// Set system notifications of "Add friends" type to "acknowledged"
NIMClient.getService(SystemMessageService.class).resetSystemMessageUnreadCountByType(types);

Mark a notification as read

• API prototype

java/**
 * Set a system notification as "Acknowledged"
 *
 * @param messageId - ID of system notification
 */
public void setSystemMessageRead(long messageId);

• Example

javaNIMClient.getService(SystemMessageService.class).setSystemMessageRead(messageId);

Deleting system notifications

Deleting all system notifications

All system notifications can be deleted using this interface.

• API prototype

java/**
 * Delete all system notifications
 */
public void clearSystemMessages();

• Example

javaNIMClient.getService(SystemMessageService.class).clearSystemMessages();

Deleting system notifications of specified type

The specified type of system notification can be deleted using the API. For more information about types of notifications, see SystemMessageType.

• API prototype

java/**
 * Delete specified type of system notifications
 *
 */
public void clearSystemMessagesByType(List<SystemMessageType> types);

• Parameters

Parameter	Description
types	Set of system notification type

• Example

javaList<SystemMessageType> types = new ArrayList<>();
types.add(SystemMessageType.AddFriend);

// Delete system notifications of "Add friends" type only
NIMClient.getService(SystemMessageService.class).clearSystemMessagesByType(types);

Deleting a system notification

• API prototype

java/**
 * Delete a system notification
 *
 * @param messageId - The ID of the specified system notification.
 */
public void deleteSystemMessage(long messageId);

• Example

javaNIMClient.getService(SystemMessageService.class).deleteSystemMessage(message.getMessageId());

Changing the system notification state

The states of system notifications are described in SystemMessageStatus. In addition to five built-in states, such as initail, passed, declined, ignored, and expired, five user-defined extension types are provided for the third-party developers. When the user handles system notifications, "setSystemMessageStatus" is called to update the state of a system notification.

• API prototype

java/**
 * Set status of system notification Users can invoke this feature to update after handling system notifications.
 *
 */
public void setSystemMessageStatus(long messageId, SystemMessageStatus status);

• Parameters

Parameter	Description
messageId	ID of system notification
status	State to be updated

SystemMessageStatus attribute:

Parameter	Description
declined	The declined state
expired	The expired state
extension1	User-defined extension type 1 by developers.
extension2	User-defined extension type 2 by developers.
extension3	User-defined extension type 3 by developers.
extension4	User-defined extension type 4 by developers.
extension5	User-defined extension type 5 by developers.
ignored	The ignored state
init	The initial state
passed	The passed state

• Example

java// Take "Set status of system notification to expired" for an example
SystemMessageStatus status = SystemMessageStatus.expired;
NIMClient.getService(SystemMessageService.class).setSystemMessageStatus(message.getMessageId(), status);

User-defined system notifications

In addition to built-in system notifications, NIM SDK allows developers to build custom system notifications based on the business requirements, such as the typing indictor. The notification may be sent 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.

The data structure is CustomNotification.

CustomNotification interface:

Return	Method	Description
String	getApnsText()	Get APNS text.
CustomNotificationConfig	getConfig()	Configuration option of user-defined notification. See "CustomNotificationConfig".
String	getContent()	Get detailed message content.
String	getFromAccount()	Get account of the notification sender.
NIMAntiSpamOption	getNIMAntiSpamOption()	Get anti-spam configuration
Map	getPushPayload()	Get push configuration.
String	getSessionId()	Get ID of chat object (friend account, team ID.)
SessionTypeEnum	getSessionType()	Get session type.
long	getTime()	Get message time. Unit: ms.
boolean	isSendToOnlineUserOnly()	Determine that the message is sent to current online users/teams only.
void	setApnsText(String apnsText)	Set push content.
void	setConfig(CustomNotificationConfig config)	Set configuration option of user-defined notification.
void	setContent(String content)	Set message content.
void	setFromAccount(String fromAccount)	Set account of notification sender.
void	setNIMAntiSpamOption(NIMAntiSpamOption antiSpamOption)	Set anti-spam configuration.
void	setPushPayload(Map pushPayload)	Set APNS attributes.
void	setSendToOnlineUserOnly(boolean sendToOnlineUserOnly)	Set that the message is sent to current online users/teams.
void	setSessionId(String sessionId)	Set ID of chat object.
void	setSessionType(SessionTypeEnum sessionType)	Set session type.
void	setTime(long time)	Set message time.

CustomNotificationConfig attribute:

CustomNotificationConfig attribute	Description
enablePush	Enable push for the notification (including Android message reminding) It is "true" by default.
enablePushNick	Enable push display name for the notification (applicable to iOS client). If it is "false", then push display name will not be displayed at iOS client when notification is received by the recipient. It is "false" by default.
enableUnreadCount	Enable unread count for the notification. If it is "true", then the recipient can read this configuration option to determine change in unread count of services after receiving notification. It is "true" by default.

Sending user-defined system notifications

• API prototype

java/**
 * Send a User-defined system notification.
 * SDK only transfers the message and therefore will not record status of directive message, but can set the callback feature to monitor the sending result.
 *
 * @param notification - Directive messages.
 * @return InvocationFuture - Configurable callback feature. It can monitor the sending result.
 */
public InvocationFuture<Void> sendCustomNotification(CustomNotification notification);

• Example

java// Construct custom notification, and specify recipient.
CustomNotification notification = new CustomNotification();
notification.setSessionId(recipientId);
notification.setSessionType(sessionType);

// Create detailed content of notification For extendibility, json format can be used here to distinguish the type by "ID".
JSONObject json = new JSONObject();
json.put("id", "2");
JSONObject data = new JSONObject();
data.put("body", "the_content_for_display");
data.put("url", "url_of_the_game_or_anything_else");
json.put("data", data);
notification.setContent(json.toString());

// If the recipient is not online, he will receive the User-defined system notification next time when he is online again. If it is set to "true", the recipient cannot receive the notification next time when he is online again.
notification.setSendToOnlineUserOnly(false);

// Configure CustomNotificationConfig.
CustomNotificationConfig config = new CustomNotificationConfig();
// Require push
config.enablePush = true; 
config.enableUnreadCount = true;
notification.setConfig(config);

// Configured push text.
notification.setApnsText("the_content_for_apns");

// Custom push attribute.
Map<String,Object> pushPayload = new HashMap<>();
pushPayload.put("key1", "payload 1");
pushPayload.put("key2", 2015);
notification.setPushPayload(pushPayload);

* Send custom notification
NIMClient.getService(MsgService.class).sendCustomNotification(notification);

Receiving user-defined system notifications

• API prototype

java/**
 * Register or cancel the observer for receiving custom notification.
 * @param observer - Observer. The parameter is received custom notification.
 * @param register true indicates registered, and true indicates unregistered.
 */
public void observeCustomNotification(Observer<CustomNotification> observer, boolean register);

• Example

java// If there are custom notifications that are used globally and not dependent on a certain Activity, the code must be invoked in onCreate under Application.
NIMClient.getService(MsgServiceObserve.class).observeCustomNotification(new Observer<CustomNotification>() {
    @Override
    public void onEvent(CustomNotification message) {
        // The custom notification is processed here.
    }
}, register);