网易云信 NIM SDK 支持接收和存储内置系统通知。同时提供处理、查询、删除内置系统通知、修改通知状态等内置系统通知管理功能。

技术原理

内置系统通知是云信系统内建的通知，由云信服务器推送给用户或群组，用于云信系统类的事件通知。

网易云信 NIM SDK 的 SystemMessageService 提供系统通知操作相关接口， SystemMessageObserver 提供系统通知相关观察者通知接口，帮助您快速实现和使用云信系统的系统通知功能。

监听内置系统通知

只有在注册监听内置系统通知相关事件后，用户才会收到对应的系统通知。

  flowchart LR
    classDef default fill:#337EFF,stroke:#337EFF,stroke-width:0px,color:#FFFFFF;
    
    A("监听内置系统通知接收事件") --> B("产生触发内置系统通知的事件") --> C("接收具体类型的内置系统通知")

通过调用 observeReceiveSystemMs 方法监听内置系统通知接收事件。

示例代码如下：

//注册内置系统通知接收事件观察者
NIMClient.getService(SystemMessageObserver.class)
	.observeReceiveSystemMsg(new Observer<SystemMessage>() {
            @Override
            public void onEvent(SystemMessage message) {
	            // 收到内置系统通知，可以做相应操作
            }
        }, register);

目前云信内置的能触发系统通知的事件包括：

通知类型	说明
TeamInvite	邀请用户加入高级群
ApplyJoinTeam	用户申请加入高级群
DeclineTeamInvite	用户拒绝加入高级群邀请
RejectTeamApply	拒绝用户的加入高级群申请
SuperTeamInvite	邀请用户加入超大群
SuperTeamApply	用户申请加入超大群
SuperTeamInviteReject	用户拒绝加入超大群邀请
SuperTeamApplyReject	拒绝用户的加入超大群申请
AddFriend	对方（请求/已经）加你为好友
undefined	自定义事件

查询内置系统通知

查询内置系统通知列表

SDK 提供同步和异步两种类型的查询接口，均查询本地的内置系统通知：

• 异步接口 querySystemMessages
• 同步接口 querySystemMessagesBlock

参数说明：

参数	说明
offset	数据库查询偏移量，如100，则代码从第100条开始查询
limit	数据库查询系统通知的数量

示例代码：

// 异步调用
// 从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
    }
});

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

查询指定类型内置系统通知列表

SDK 提供同步和异步两种类型的查询接口，其中：

• 异步接口 querySystemMessageByType 调用后，如果本地没有指定类型的内置系统通知，则自动去服务器查询。
• 同步接口 querySystemMessageByTypeBlock 则仅查询本地的指定类型的内置系统通知。

参数说明：

参数	说明
types	待查询的系统通知类型列表，具体系统类型请参见SystemMessageType
offset	数据库查询偏移量，如100，则代码从第100条开始查询
limit	数据库查询系统通知的数量

示例代码：

//异步接口

List<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
    }
});


//同步接口

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

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

查询所有未读内置系统通知

通过调用 querySystemMessageUnread 方法查询所有未读的内置系统通知。

内置系统通知对象SystemMessage 中通过属性 unread 标志该条内置系统通知是否未读。

您也可以调用 isUnread 方法查询某条内置系统通知是否已读，或者调用 setUnread 方法设置该条通知为已读或未读。

示例代码如下：

NIMClient.getService(SystemMessageService.class).querySystemMessageUnread();

删除内置系统通知

删除所有内置系统通知

通过调用 clearSystemMessages 方法删除所有的内置系统通知。示例代码如下：

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

删除指定类型的内置系统通知

通过调用 clearSystemMessagesByType 方法删除指定类型的内置系统通知。

其中入参需要传入待查询的系统通知类型列表，具体系统类型请参见SystemMessageType

示例代码如下：

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

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

删除指定的单条内置系统通知

通过调用 deleteSystemMessage 方法删除指定的单条内置系统通知。

其中入参需要传入需要删除的系统通知 ID。示例代码如下：

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

设置内置系统通知状态

SDK 的内置系统通知状态通过 SystemMessageStatus 来定义，目前主要内置了以下五种状态。除此之外，还提供五个自定义扩展类型，供第三方开发者使用。

• init：未处理状态
• passed：已通过验证
• ignored：已忽略
• declined：已拒绝
• expired：已过期

当用户处理过系统通知后，相应的系统通知状态会自动变更；也可以主动调用 setSystemMessageStatus 方法手动变更某个系统通知的状态。变更后，您可以调用 getStatus 方法查询该系统通知的状态。

参数说明：

参数	说明
messageId	系统通知的 ID
status	待设置的状态

示例代码：

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

API 参考

API	说明
observeReceiveSystemMs	监听内置系统通知接收事件
querySystemMessages	查询内置系统通知列表（异步接口）
querySystemMessagesBlock	查询内置系统通知列表（同步接口）
querySystemMessageByType	查询指定类型的内置系统通知列表（异步接口）
querySystemMessageByTypeBlock	查询指定类型的内置系统通知列表（同步接口）
querySystemMessageUnread	查询所有未读的内置系统通知
SystemMessage.isUnread	查询某条内置系统通知是否已读
SystemMessage.setUnread	设置某条通知为已读或未读
clearSystemMessages	删除所有内置系统通知
clearSystemMessagesByType	删除指定类型的内置系统通知
deleteSystemMessage	删除指定的单条内置系统通知
setSystemMessageStatus	设置内置系统通知状态
SystemMessage.getStatus	查询某条内置系统通知的状态