Instant Messaging
Android
Getting Started
Introduction
Overview
Features
Limits
Features
Account Integration and Login
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Integration
Interface Overview
Integrate and Initialize SDK
Login
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
System Notification
Push and Message Alert
Team
Superteam
Chat Room
Moderation
Chat Extension
Miscellaneous Features
Best Practice
Traffic Control in Chat Rooms
API Reference
Android API Reference
Android Status Codes

System Notification

Update time: 2021/12/03 17:12:51

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
/**
 * 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
NIMClient.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
/**
 * 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

// 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

// 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
/**
 * 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

List<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

List<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

/**
 * 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
/**
 * 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
NIMClient.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
/**
 * Query total unread count of system notifications
 *
 * @return - Total unread count of system notifications
 */
public int querySystemMessageUnreadCountBlock();
  • Example
int unread = NIMClient.getService(SystemMessageService.class).querySystemMessageUnreadCountBlock();

Total unread count of specified type

  • API prototype
/**
 * 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
List<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
/**
 * Set all system notifications to acknowledged. The total unread count of system notifications will be cleared.
 */
public void resetSystemMessageUnreadCount();
  • Example
// 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
/**
 * Set system notifications of specified type to "acknowledged"
 *
 * @param types - Set of system notification types
 */
public void resetSystemMessageUnreadCountByType(List<SystemMessageType> types);
  • Example
List<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
/**
 * Set a system notification as "Acknowledged"
 *
 * @param messageId - ID of system notification
 */
public void setSystemMessageRead(long messageId);
  • Example
NIMClient.getService(SystemMessageService.class).setSystemMessageRead(messageId);

Deleting system notifications

Deleting all system notifications

All system notifications can be deleted using this interface.

  • API prototype
/**
 * Delete all system notifications
 */
public void clearSystemMessages();
  • Example
NIMClient.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
/**
 * Delete specified type of system notifications
 *
 */
public void clearSystemMessagesByType(List<SystemMessageType> types);
  • Parameters
Parameter Description
types Set of system notification type
  • Example
List<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
/**
 * Delete a system notification
 *
 * @param messageId - The ID of the specified system notification.
 */
public void deleteSystemMessage(long messageId);
  • Example
NIMClient.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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
// 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);
Was this topic helpful?
Yes
No
  • Overview
  • Listening for system notifications
  • System notifications
  • Getting system notifications
  • Getting system notifications of a specified type
  • Getting the unread count of system notifications
  • Unread count of system notifications
  • Listening for changes in total unread count
  • Getting the unread count
  • Queryig the total unread count
  • Total unread count of specified type
  • Mark as read
  • Mark all notifications as read
  • Markig specified notification types as read
  • Mark a notification as read
  • Deleting system notifications
  • Deleting all system notifications
  • Deleting system notifications of specified type
  • Deleting a system notification
  • Changing the system notification state
  • User-defined system notifications
  • Sending user-defined system notifications
  • Receiving user-defined system notifications