系统通知

内置系统通知概述

系统通知是云信系统内建的消息/通知，其对应的数据结构为 SystemMessage。由云信服务器推送给用户的通知类消息，用于云信系统类的事件通知。现在主要包括群变动的相关通知，例如入群申请，入群邀请等，如果第三方应用还托管了好友关系，好友的添加、删除也是这个类型的通知。系统通知由 SDK 负责接收和存储，并提供较简单的未读数管理。

SystemMessage 接口说明：

返回值	SystemMessage 接口	说明
String	getAttach()	获取系统通知的附件内容
Object	getAttachObject()	获取系统通知附件内容解析后的对象
String	getContent()	获取系统通知的内容
String	getCustomInfo()	获取自定义信息，目前只有拉人入群时可以设置
String	getFromAccount()	该系统通知的发起方帐号
long	getMessageId()	获取系统通知 ID
SystemMessageStatus	getStatus()	获取系统通知的处理状态
String	getTargetId()	获取系统通知的目标 ID
long	getTime()	获取系统通知的发出时间，单位为 ms
SystemMessageType	getType()	获取系统通知类型
boolean	isUnread()	判断该系统通知是否已读
void	setAttach(String attach)	设置系统通知的附件内容
void	setAttachObject(Object object)	设置解析后的附件对象
void	setContent(String content)	设置系统通知的内容
void	setFromAccount(String fromAccount)	设置发起方帐号
void	setMessageId(long messageId)	设置系统通知 ID
void	setStatus(SystemMessageStatus status)	设置系统通知的处理状态
void	setTargetId(String targetId)	设置系统通知的目标 ID
void	setTime(long time)	设置系统通知的发出时间
void	setType(int type)	设置系统通知类型
void	setUnread(boolean unread)	设置改系统通知已读/未读

监听系统通知

监听系统通知的到达事件。

• API 原型

java/**
 * 注册/注销系统消息接收事件观察者
 * @param observer 观察者， 参数为接收到的系统消息
 * @param register true为注册，false为注销
 */
public void observeReceiveSystemMsg(Observer<SystemMessage> observer, boolean register);

• 示例

javaNIMClient.getService(SystemMessageObserver.class)
	.observeReceiveSystemMsg(new Observer<SystemMessage>() {
            @Override
            public void onEvent(SystemMessage message) {
	            // 收到系统通知，可以做相应操作
            }
        }, register);

获取系统通知

获取系统通知

• API 原型

java/**
 * 查询系统通知列表
 *
 * @return InvocationFuture, 可设置回调函数，参数为系统通知列表
 */
 // 异步
public InvocationFuture<List<SystemMessage>> querySystemMessages(int offset, int limit);

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

• 参数说明

参数	说明
offset	数据库查询偏移量
limit	数据库查询条数

• 示例

1、异步版本

java// 从10条开始，查询10条系统消息
NIMClient.getService(SystemMessageService.class).querySystemMessages(10, 10)
        .setCallback(new RequestCallback<List<SystemMessage>>() {
    @Override
    public void onSuccess(List<SystemMessage> param) {
        // 查询成功
    }

    @Override
    public void onFailed(int code) {
		// 查询失败
    }

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

2、同步版本

java// 参数offset为当前已经查了offset条，limit为要继续查询limit条。
List<SystemMessage> temps = NIMClient.getService(SystemMessageService.class).querySystemMessagesBlock(offset, limit); 

获取指定类型系统通知

需要传入系统消息类型 SystemMessageType 集合。

• API 原型

java/**
 * 根据类型查询系统通知列表
 *
 * @return 指定类型的系统通知集合
 */
 // 同步
public List<SystemMessage> querySystemMessageByTypeBlock(List<SystemMessageType> types, int offset, int limit);

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

• 参数说明

参数	说明
types	待查询的系统通知类型集合
offset	数据库查询偏移条数
limit	数据库查询条数

• 示例

1、同步版本

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

// 只查询“添加好友”类型的系统通知, 从头开始查询，查询3条
List<SystemMessage> temps = NIMClient.getService(SystemMessageService.class)
    .querySystemMessageByTypeBlock(types, 0, 3);

2、异步版本

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

// 只查询“添加好友”类型的系统通知, 从头开始查询，查询3条
NIMClient.getService(SystemMessageService.class).querySystemMessageByType(types, 0, 3)
        .setCallback(new RequestCallback<List<SystemMessage>>() {
    @Override
    public void onSuccess(List<SystemMessage> param) {
	     // 查询成功
    }

    @Override
    public void onFailed(int code) {
		// 查询失败
    }

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

获取未读系统通知

java/**
 * 获取所有未读系统通知
 *
 * @return 可设置回调函数，参数为所有未读的系统通知集合
 */
InvocationFuture<java.util.List<SystemMessage>> querySystemMessageUnread();

系统通知未读数

监听总未读数变更

此接口可以监听系统消息总未读数的变化。

• API 原型

java/**
 * 注册/注销系统消息未读数变化事件观察者
 * @param observer 观察者， 参数当前的系统消息未读数
 * @param register true为注册，false为注销
 */
public void observeUnreadCountChange(Observer<Integer> observer, boolean register);

• 示例

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

private Observer<Integer> sysMsgUnreadCountChangedObserver = new Observer<Integer>() {
        @Override
        public void onEvent(Integer unreadCount) {
            // 更新未读数变化
        }
    };

获取未读数

查询未读数总和

• API 介绍

SystemMessage 中属性 unread 用来标志该条系统通知是否未读，该函数将返回所有未读的系统通知总数。

• API 原型

java/**
 * 查询系统通知未读数总和
 *
 * @return 系统通知未读总数
 */
public int querySystemMessageUnreadCountBlock();

• 示例

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

指定类型的未读数总和

• API 原型

java/**
 * 查询指定类型的系统通知未读数总和
 *
 * @param types 系统通知类型集合
 * @return 指定类型的系统通知未读数总和
 */
public int querySystemMessageUnreadCountByType(List<SystemMessageType> types);

• 示例

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

// 查询“添加好友”类型的系统通知未读数总和
int unread = NIMClient.getService(SystemMessageService.class)
	.querySystemMessageUnreadCountByType(types);

标记为已读

标记所有通知为已读

该函数调用后系统通知未读数将为零。

• API 原型

java/**
 * 将所有系统通知设为已读，系统通知的未读消息总数将清零。
 */
public void resetSystemMessageUnreadCount();

• 示例

java// 进入过系统通知列表后，可调用此函数将未读数值为0
NIMClient.getService(SystemMessageService.class).resetSystemMessageUnreadCount();

标记指定类型通知为已读

• API 原型

java/**
 * 将指定类型的系统通知设为已读
 *
 * @param types 系统通知类型集合
 */
public void resetSystemMessageUnreadCountByType(List<SystemMessageType> types);

• 示例

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

// 将“添加好友”类型的系统通知设为已读
NIMClient.getService(SystemMessageService.class).resetSystemMessageUnreadCountByType(types);

标记单条通知为已读

• API 原型

java/**
 * 设置单条系统通知为已读
 *
 * @param messageId 系统通知ID
 */
public void setSystemMessageRead(long messageId);

• 示例

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

删除系统通知

删除所有系统通知

此接口将删除所有的系统通知。

• API 原型

java/**
 * 删除所有系统通知
 */
public void clearSystemMessages();

• 示例

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

删除指定类型系统通知

调用此接口，可以删除指定类型的系统通知。删除的类型见 SystemMessageType。

• API 原型

java/**
 * 删除指定类型的系统通知
 *
 */
public void clearSystemMessagesByType(List<SystemMessageType> types);

• 参数说明

参数	说明
types	系统通知类型集合

• 示例

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

// 只删除“添加好友”类型的系统通知
NIMClient.getService(SystemMessageService.class).clearSystemMessagesByType(types);

删除单条系统通知

• API 原型

java/**
 * 删除一条系统通知
 *
 * @param messageId 指定的系统通知ID
 */
public void deleteSystemMessage(long messageId);

• 示例

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

更改通知处理状态

• API 介绍

系统通知状态枚举见 SystemMessageStatus，目前除了提供了未处理、已通过、已拒绝、已忽略、已过期这五种内置状态之外，提供了五个自定义扩展类型，供第三方开发者使用。在用户处理过系统通知之后，调用 setSystemMessageStatus 更新系统通知状态。

• API 原型

java/**
 * 设置系统通知状态。在用户处理过系统通知之后，可调用此函数更新
 *
 */
public void setSystemMessageStatus(long messageId, SystemMessageStatus status);

• 参数说明

参数	说明
messageId	系统通知的 ID
status	待更新的状态

SystemMessageStatus 属性说明：

参数	说明
declined	已拒绝
expired	已过期
extension1	开发者可自定义的扩展类型1
extension2	开发者可自定义的扩展类型2
extension3	开发者可自定义的扩展类型3
extension4	开发者可自定义的扩展类型4
extension5	开发者可自定义的扩展类型5
ignored	已忽略
init	未处理状态
passed	已通过验证

• 示例

java// 以设置系统通知状态为已过期为例
SystemMessageStatus status = SystemMessageStatus.expired;
NIMClient.getService(SystemMessageService.class).setSystemMessageStatus(message.getMessageId(), status);

自定义系统通知

除内置系统通知外，NIM SDK 也额外提供自定义系统给开发者，方便开发者进行业务逻辑的通知（如实现对方正在输入中···等功能）。这个通知既可以由客户端发起也可以由开发者服务器发起。

注意：自定义通知和自定义消息的不同之处在于，自定义消息归属于 NIM SDK 消息体系内，适用于会话，由 SDK 存储在消息数据库中，与 NIM SDK 其他内建消息类型一同展现给用户。而自定义通知主要用于第三方的一些事件状态通知，SDK 不存储，不计入未读数，也不解析这些通知。SDK 仅仅负责替第三方传递和通知这些事件，起到透传的作用，收到自定义通知后的持久化工作需要由上层开发负责。

其数据结构为 CustomNotification。

CustomNotification 接口说明：

返回值	参数	说明
String	getApnsText()	获取推送文案
CustomNotificationConfig	getConfig()	自定义通知的配置选项，详见 CustomNotificationConfig
String	getContent()	获取消息具体内容
String	getFromAccount()	获取该通知的发出者帐号
NIMAntiSpamOption	getNIMAntiSpamOption()	获取反垃圾配置
Map	getPushPayload()	获取推送属性
String	getSessionId()	获取聊天对象的 Id（好友帐号，群 ID 等）
SessionTypeEnum	getSessionType()	获取会话类型
long	getTime()	获取消息时间，单位为 ms
boolean	isSendToOnlineUserOnly()	该消息是否只发送当前在线的用户/群组
void	setApnsText(String apnsText)	设置推送文案
void	setConfig(CustomNotificationConfig config)	设置自定义通知的配置选项
void	setContent(String content)	设置消息内容
void	setFromAccount(String fromAccount)	设置该通知的发起者帐号
void	setNIMAntiSpamOption(NIMAntiSpamOption antiSpamOption)	设置反垃圾配置项
void	setPushPayload(Map pushPayload)	设置推送属性
void	setSendToOnlineUserOnly(boolean sendToOnlineUserOnly)	设置该消息是否只发送给当前在线的用户/群组
void	setSessionId(String sessionId)	设置聊天对象ID
void	setSessionType(SessionTypeEnum sessionType)	设置会话类型
void	setTime(long time)	设置消息时间

CustomNotificationConfig属性说明：

CustomNotificationConfig 属性	说明
enablePush	该通知是否进行推送（包括Android消息提醒）。默认为 true
enablePushNick	该通知是否需要推送昵称（针对iOS客户端有效）， 如果为false，那么对方收到通知后，iOS端将不显示推送昵称。 默认为 false
enableUnreadCount	该通知是否要计入未读数， 如果为true，那么对方收到通知后，可以通过读取此配置项决定自己业务的未读计数变更。 默认为 true

发送自定义系统通知

• API 原型

java/**
 * 发送一条自定义系统通知。
 * 由于SDK仅负责透传该消息，因此不会记录指令消息状态，但可以设置回调函数监听发送结果。
 *
 * @param notification 指令消息
 * @return InvocationFuture 可设置回调函数，监听发送结果。
 */
public InvocationFuture<Void> sendCustomNotification(CustomNotification notification);

• 示例

java// 构造自定义通知，指定接收者
CustomNotification notification = new CustomNotification();
notification.setSessionId(receiverId);
notification.setSessionType(sessionType);

// 构建通知的具体内容。为了可扩展性，这里采用 json 格式，以 "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());

// 若接收者不在线，则当其再次上线时，将收到该自定义系统通知。若设置为 true，则再次上线时，将收不到该通知。
notification.setSendToOnlineUserOnly(false);

// 配置 CustomNotificationConfig
CustomNotificationConfig config = new CustomNotificationConfig();
// 需要推送
config.enablePush = true; 
config.enableUnreadCount = true;
notification.setConfig(config);

// 设置的推送文案
notification.setApnsText("the_content_for_apns");

// 自定义推送属性
Map<String,Object> pushPayload = new HashMap<>();
pushPayload.put("key1", "payload 1");
pushPayload.put("key2", 2015);
notification.setPushPayload(pushPayload);

// 发送自定义通知
NIMClient.getService(MsgService.class).sendCustomNotification(notification);

接收自定义系统通知

• API 原型

java/**
 * 注册/注销自定义通知接收观察者
 * @param observer 观察者，参数为收到的自定义通知
 * @param register true为注册，false为注销
 */
public void observeCustomNotification(Observer<CustomNotification> observer, boolean register);

• 示例

java// 如果有自定义通知是作用于全局的，不依赖某个特定的 Activity，那么这段代码应该在 Application 的 onCreate 中就调用
NIMClient.getService(MsgServiceObserve.class).observeCustomNotification(new Observer<CustomNotification>() {
    @Override
    public void onEvent(CustomNotification message) {
        // 在这里处理自定义通知。
    }
}, register);