系统通知

内置系统通知概述

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

SystemMessage 字段说明：

字段	类型	说明
attach	String?	系统通知的附件内容
attachObject	Object?	系统通知附件内容解析后的对象
content	String?	系统通知的内容
customInfo	String?	自定义信息，目前只有拉人入群时可以设置
fromAccount	String?	系统通知的发起方帐号
messageId	int?	系统通知 ID
status	SystemMessageStatus?	系统通知的处理状态
targetId	String?	系统通知的目标 ID
time	int?	系统通知的发出时间，单位为 ms
type	SystemMessageType?	系统通知类型
unread	bool?	判断该系统通知是否已读

监听系统通知

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

• API 原型

dart
 /// 注册/注销系统消息接收事件观察者
 /// [observer] 观察者， 参数为接收到的系统消息
 /// [register] true为注册，false为注销
 
Stream<SystemMessage> get onReceiveSystemMsg

Web 不支持该事件回调。

• 示例

dartNimCore.instance.systemMessageService.onReceiveSystemMsg.  NimCore.instance.systemMessageService.onReceiveSystemMsg.listen((SystemMessage event) {

        });

获取系统通知

获取系统通知(Android)

• API 原型

dart/// 查询系统通知列表，只适用于Android平台
Future<NIMResult<List<SystemMessage>>> querySystemMessagesAndroid(int offset,int limit);

• 参数说明

参数	类型	说明
offset	int	数据库查询的偏移条数（offset）
limit	int	数据库查询条数

• 示例

dart//从第1条开始，查询10条系统消息
final result = await NimCore.instance.systemMessageService
              .querySystemMessagesAndroid(1,10);

获取系统通知(iOS & Desktop)

• API 原型

dart /// 查询系统通知列表只针对iOS和Desktop平台
Future<NIMResult<List<SystemMessage>>> querySystemMessagesIOSAndDesktop(SystemMessage systemMessage,int limit);

• 参数说明

参数	类型	说明
systemMessage	SystemMessage	当前最早系统通知,没有则传入nil
limit	int	数据库查询条数

获取指定类型系统通知(Android)

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

• API 原型

dart /// 根据类型查询系统通知列表，只适用于Android平台
Future<NIMResult<List<SystemMessage>>> querySystemMessageByTypeAndroid(
      List<SystemMessageType> types, int offset, int limit);

• 参数说明

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

• 示例

1、同步版本

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// 只查询“添加好友”类型的系统通知, 从头开始查询，查询3条
final result = await NimCore.instance.systemMessageService
              .querySystemMessageByTypeAndroid(systemMessageTypeList,
                  inputParams['offset'] as int, inputParams['limit'] as int);

获取指定类型系统通知(iOS & Desktop)

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

• API 原型

dart
 /// 根据类型查询系统通知列表，只适用于iOS & Desktop平台
Future<NIMResult<List<SystemMessage>>> querySystemMessageByTypeIOSAndDesktop(
     SystemMessage systemMessage,List<SystemMessageType> types,int limit);

• 参数说明

参数	类型	说明
types	List<SystemMessageType>	待查询的系统通知类型集合
systemMessage	SystemMessage	当前最早系统通知,没有则传入nil
limit	int	数据库查询条数

获取未读系统通知

dart
 /// 获取所有未读系统通知
 
Future<NIMResult<List<SystemMessage>>> querySystemMessageUnread();

系统通知未读数

监听总未读数变更

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

• API 原型

dart
 /// 注册/注销系统消息未读数变化事件观察者
 
  final StreamController<int> onUnreadCountChange =
      StreamController<int>.broadcast();

• 示例

dartNimCore.instance.systemMessageService.onUnreadCountChange.listen((int event) {

});

获取未读数

查询未读数总和

• API 介绍

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

• API 原型

dart /// 查询系统通知未读数总和

Future<NIMResult<int>> querySystemMessageUnreadCount();

• 示例

dartfinal result = await NimCore.instance.systemMessageService
              .querySystemMessageUnreadCount();

指定类型的未读数总和

• API 原型

dart
 /// 查询指定类型的系统通知未读数总和
 ///
 /// [types] 系统通知类型集合
 /// @return 指定类型的系统通知未读数总和
 
Future<NIMResult<int>> querySystemMessageUnreadCountByType(
      List<SystemMessageType> types);

• 示例

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// 查询“添加好友”类型的系统通知未读数总和
final result = await NimCore.instance.systemMessageService
              .querySystemMessageUnreadCountByType(systemMessageTypeList);

标记为已读

标记所有通知为已读

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

• API 原型

dart
 /// 将所有系统通知设为已读，系统通知的未读消息总数将清零。
 
Future<NIMResult<void>> resetSystemMessageUnreadCount()

• 示例

dart// 进入过系统通知列表后，可调用此函数将未读数值为0
final result = await NimCore.instance.systemMessageService
              .resetSystemMessageUnreadCount();

标记指定类型通知为已读

• API 原型

dart
 /// 将指定类型的系统通知设为已读
 ///
 /// [types] 系统通知类型集合
 
Future<NIMResult<void>> resetSystemMessageUnreadCountByType(
      List<SystemMessageType> types);

• 示例

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// 将“添加好友”类型的系统通知设为已读
final result = await NimCore.instance.systemMessageService
              .resetSystemMessageUnreadCountByType(systemMessageTypeList);

标记单条通知为已读

• API 原型

dart
 /// 设置单条系统通知为已读
 ///
 /// [messageId] 系统通知ID
 
Future<NIMResult<void>> setSystemMessageRead(int messageId);

• 示例

dartfinal result = await NimCore.instance.systemMessageService
              .setSystemMessageRead(messageId);

删除系统通知

删除所有系统通知

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

• API 原型

dart
 /// 删除所有系统通知
 
Future<NIMResult<void>> clearSystemMessages();

• 示例

dartfinal result = await NimCore.instance.systemMessageService.clearSystemMessages();

删除指定类型系统通知

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

• API 原型

dart
 /// 删除指定类型的系统通知
 ///
 
Future<NIMResult<void>> clearSystemMessagesByType( List<SystemMessageType> types);

• 参数说明

参数	类型	说明
types	List<SystemMessageType>	系统通知类型集合

• 示例

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// 只删除“添加好友”类型的系统通知
final result = await NimCore.instance.systemMessageService
              .clearSystemMessagesByType(systemMessageTypeList);

删除单条系统通知

• API 原型

dart
 /// 删除一条系统通知
 ///
 /// [messageId] 指定的系统通知ID
 
Future<NIMResult<void>> deleteSystemMessage(int messageId);

• 示例

dart final result = await NimCore.instance.systemMessageService
              .deleteSystemMessage(messageId);

更改通知处理状态

• API 介绍

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

• API 原型

dart
 /// 设置系统通知状态。在用户处理过系统通知之后，可调用此函数更新
 ///
 
Future<NIMResult<void>> setSystemMessageStatus(
      int messageId, SystemMessageStatus status);

• 参数说明

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

SystemMessageStatus 属性说明：

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

• 示例

dart// 以设置系统通知状态为已过期为例
SystemMessageStatus status = SystemMessageStatus.expired;
final result = await NimCore.instance.systemMessageService
              .setSystemMessageStatus(message.getMessageId(), status);

自定义系统通知

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

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

其数据结构为 CustomNotification。

CustomNotification 接口说明：

参数	类型	说明
apnsText	String	推送文案
config	CustomNotificationConfig	自定义通知的配置选项，详见 CustomNotificationConfig
content	String	消息具体内容
fromAccount	String	该通知的发出者帐号
nIMAntiSpamOption	NIMAntiSpamOption	反垃圾配置
pushPayload	Map<String, Object>	推送属性
sessionId	String	聊天对象的 Id（好友帐号，群 ID 等）
sessionType	SessionTypeEnum	会话类型
time	int	消息时间，单位为 ms
sendToOnlineUserOnly	bool	该消息是否只发送当前在线的用户/群组

CustomNotificationConfig属性说明：

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

发送自定义系统通知

• API 原型

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

• 示例

dart

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

// 配置 CustomNotificationConfig
CustomNotificationConfig config = CustomNotificationConfig(enablePush:true,enableUnreadCount:true);

// 构造自定义通知，指定接收者
CustomNotification notification = CustomNotification(sessionId: receiverId,sessionType:sessionType,content: json.toString(),apnsTest:"the_content_for_apns",config:config)


// 发送自定义通知
final result = await NimCore.instance.systemMessageService
              .sendCustomNotification(notification);

接收自定义系统通知

• API 原型

dart
 /// 注册/注销自定义通知接收观察者
 /// [observer] 观察者，参数为收到的自定义通知
 /// [register] true为注册，false为注销
 
final StreamController<CustomNotification> onCustomNotification =
      StreamController<CustomNotification>.broadcast();

• 示例

dartNimCore.instance.systemMessageService.onCustomNotification.listen((CustomNotification event) {

});