系统通知

除消息通道外，SDK 还提供系统通知这种通道用于消息之外的通知分发。目前有两种类型:内置系统通知和自定义系统通知。现在主要包括群变动的相关通知，例如入群申请，入群邀请等，如果第三方应用还托管了好友关系，好友的添加、删除也是这个类型的通知。系统通知由 SDK 负责接收和存储，并提供较简单的未读数管理。发送自定义系统通知可以设置推送相关的参数。

注意：这里的入群申请、入群邀请的通知要区别于群操作的结果通知，比如创建群，解散群、踢人、拉人等群操作的通知。群操作的通知是通过IM消息通道来下发的（详见群通知事件）

SysMessage参数说明

类型	参数	说明
NIMResCode	rescode_	通知错误码 详见 NIMResCode
NIMMessageFeature	feature_	通知属性，区分离线，多端同步，漫游通知等等,详见NIMMessageFeature
int	total_unread_count_	总计的通知未读数
int64_t	timetag_	通知时间戳（毫秒），选填
NIMSysMsgType	type_	通知的类型，如申请入群、邀请入群、添加好友等等，详见NIMSysMsgType
string	receiver_accid_	接收者id,如果是个人,则是对方用户id,如果是群,则是群id,必填
string	sender_accid_	发送者id,选填，如发送自定义通知消息时，可选填
string	content_	通知附言，按需填写
string	attach_	附件,按需填写，类似于普通IM消息的附件内容,查看发送消息
int64_t	id_	服务器消息id（自定义通知消息,必须填0）,发送方不需要填写
NIMSysMsgStatus	status_	本地定义的系统消息状态,见NIMSysMsgStatus,发送方不需要填写
SysMessageSetting	msg_setting_	消息属性设置 详见SysMessageSetting
string	client_msg_id_	通知ID（客户端）

SysMessageSetting通知类型说明

类型	参数	说明
int	need_offline_	(选填)自定义通知消息是否存离线:0-只发给在线用户,1-可发给离线用户
string	push_content_	(选填)自定义通知消息推送文本，不填则不推送
int	need_push_	(可选)是否需要推送, 0:不需要,1:需要,默认填1,配合push_content_使用
int	push_need_badge_	(可选)推送是否要做消息计数(角标)， 0:不需要,1:需要,默认填1,配合push_content_使用
int	push_need_prefix_	(可选)推送是否需要推送昵称，0：不需要，1：需要，默认填0,配合need_push_使用
Json::Value	push_payload_	(可选)第三方自定义的推送负载内容，必须为可以解析为json的非格式化的字符串，长度2048
bool	anti_spam_enable_	是否需要过易盾反垃圾,默认false
string	anti_spam_content_	(可选)开发者自定义的反垃圾字段,长度限制：5000字符,配合anti_spam_enable_使用

NIMSysMsgType通知类型说明

枚举	值	说明
kNIMSysMsgTypeTeamApply	0	申请入群
kNIMSysMsgTypeTeamReject	1	拒绝申请入群
kNIMSysMsgTypeTeamInvite	2	邀请入群
kNIMSysMsgTypeTeamInviteReject	3	拒绝邀请入群
kNIMSysMsgTypeFriendAdd	5	加好友
kNIMSysMsgTypeFriendDel	6	删除好友
kNIMSysMsgTypeCustomP2PMsg	100	点对点透传消息
kNIMSysMsgTypeCustomTeamMsg	101	群透传消息
kNIMSysMsgTypeUnknown	1000	未知类型，作为默认

推送、反垃圾等等消息设置类似IM的消息设置

接收系统通知

注册/注销系统消息接收事件。需要在登录之前先注册。为了保证整个程序逻辑的一致性，APP 需要针对不同类型的系统通知进行相应的操作。

• API 原型

static void RegSysmsgCb(const ReceiveSysmsgCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
cb	通知回调
json_extension	扩展字段，预留

• 示例

//监听事件
nim::SystemMsg::RegSysmsgCb([&](const nim::SysMessage& ret){
	...
});

//取消监听
nim::SystemMsg::RegSysmsgCb(nullptr);

创建自定义系统通知

方便用户创建自定义通知的内容。

• API 原型

static std::string CreateCustomNotificationMsg(const std::string& receiver_id, const NIMSysMsgType type, const std::string& client_msg_id, const std::string& content, const SysMessageSetting& msg_setting, int64_t timetag = 0);

• 参数说明

参数	说明
receiver_id	接收者id
type	通知类型，详见NIMSysMsgType
client_msg_id	消息唯一id
content	通知内容
msg_setting	消息设置，详见SysMessageSetting
timetag	当前时间戳（毫秒）

发送自定义系统通知

除了内置系统通知外，SDK 也额外提供了自定义系统给开发者，方便开发者进行业务逻辑的通知。这个通知既可以由客户端发起也可以由开发者服务器发起。

客户端发起的自定义通知，该类型通知格式由开发者自定义(Attachment )，SDK 仅负责发送、接收，支持在线或离线发送，且支持点对点通知和群通知，不做任何解析，也不会存储，因此也不会在聊天记录中体现，可以使用的场景例如发送正在输入的状态等。

此外，自定义系统通知内容（SysMessage）还提供了属性设置如下(SysMessageSetting)：

• 自定义通知消息是否存离线
• 自定义通知消息推送文本
• 第三方自定义的推送属性
• 是否需要推送
• 推送是否要做消息计数
• 推送是否需要推送昵称

注意:SDK 并不负责自定义通知的持久化，APP 需要根据自己的业务逻辑按需进行解析和持久化的工作。

• API 原型

static void SendCustomNotificationMsg(const std::string& json_msg);

• 参数说明

参数	说明
json_msg	消息内容，详见SysMessage

• 示例

//以测试账号test1为例;
Json::FastWriter writer;
int64_t timetag = 1520423612222;//当前时间UNIX时间戳 13位（毫秒）

nim::SysMessageSetting setting;
setting.need_push_ = true;
setting.need_offline_ = true;//存离线
setting.push_need_badge_ = true;//推送并计数
setting.push_need_prefix_ = true;//推送通知有前缀显示，比如mmm:通知内容
setting.push_content_ = "这是一条推送通知消息";//推送消息的内容
//可以添加推送负载信息
Json::Value payload;
payload["Content"] = "这是推送负载信息";
setting.push_payload_ = writer.write(payload);


Json::Value values;
values["content"] = "这是attachment内容";
values["id"] = 2;

//创建通知内容
std::string msg = nim::SystemMsg::CreateCustomNotificationMsg("test1",kNIMSysMsgTypeCustomP2PMsg,"开发生成唯一者uuid",writer.write(values),setting,timetag);

....

//发送消息
nim::SystemMsg::SendCustomNotificationMsg(msg);

发送自定义系统通知结果

发送自定义通知消息结果通知。

• API 原型

static void RegSendCustomSysmsgCb(const SendCustomSysmsgCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
cb	通知回调
json_extension	扩展字段，预留

• 示例

//监听事件
nim::SystemMsg::RegSendCustomSysmsgCb([&](const nim::SendMessageArc& ret)
{
	...
});

//取消监听
nim::SystemMsg::RegSendCustomSysmsgCb(nullptr);

通知消息管理

SDK提供接口查询历史消息，查询消息未读数、设置已读、删除通知等功能支持

查询系统通知

查询本地系统消息（按时间逆序起查，逆序排列）。

QueryMsgCallback参数说明

类型	参数	说明
int	count	消息总数
int	unread_count	未读通知消息总数
std::list< nim::SysMessage >	result	通知消息集合，详见SysMessage)

• API 原型

static bool QueryMsgAsync(int limit_count, int64_t last_time, const QueryMsgCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
limit	一次查询数量，建议20
last_time	上次查询最后一条消息的时间戳（按时间逆序起查，即最小的时间戳）,起始查询填0
cb	操作结果回调
json_extension	扩展字段，预留

• 示例

//起始查询
nim::SystemMsg::QueryMsgAsync(20,0,[&](int count, int unread, const std::list<nim::SysMessage>& result)
{
	...
});

//假设起始查询的最后一条消息时间戳是 '1520423612222'
nim::SystemMsg::QueryMsgAsync(20,1520423612222,[&](int count, int unread, const std::list<nim::SysMessage>& result)
{
	...
});

查询未读消息数

• API 原型

static void QueryUnreadCount(const QuerySysmsgUnreadCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
cb	操作结果回调
json_extension	扩展字段，预留

• 示例

//查询未读通知数
nim::SystemMsg::QueryUnreadCount([&](NIMResCode ret, int count)
{
	...
});

设置消息状态

可以将消息状态设置为通过，拒绝，已读，已失效等状态。

NIMSysMsgStatus枚举说明

枚举	值	说明
kNIMSysMsgStatusNone	0	默认,未读
kNIMSysMsgStatusPass	1	收到消息,通过
kNIMSysMsgStatusDecline	2	收到消息,拒绝
kNIMSysMsgStatusRead	3	收到消息,已读
kNIMSysMsgStatusDeleted	4	已删
kNIMSysMsgStatusInvalid	5	已失效

• API 原型

static bool SetStatusAsync(int64_t msg_id, nim::NIMSysMsgStatus status, const SetStatusCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
msg_id	消息id
status	消息状态，详见NIMSysMsgStatus
cb	操作结果回调
json_extension	扩展字段，预留

• 示例

//设置消息状态
int64_t msgId = 213213111;
nim::SystemMsg::SetStatusAsync(msgId,kNIMSysMsgStatusPass,[&](NIMResCode ret, int64_t id, int count)
{
	if (ret == 200)//成功
    {
		...
    }
});

按消息类型批量设置消息状态

• API 原型

 static void SetStatusByTypeAsync(NIMSysMsgType type, NIMSysMsgStatus status, const BatchSetCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
type	消息类型，详见NIMSysMsgType
status	消息状态，详见NIMSysMsgStatus
cb	操作结果回调
json_extension	扩展字段，预留

• 示例

//按类型设置消息状态
nim::SystemMsg::SetStatusByTypeAsync(kNIMSysMsgTypeTeamApply, kNIMSysMsgStatusPass, [&](NIMResCode ret, int count)
{
    if (code == 200)//成功
    {
		...
    }
});

设置全部消息已读

• API 原型

static void ReadAllAsync(const ReadAllCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
cb	操作结果回调
json_extension	扩展字段，预留

• 示例

//设置全部消息已读
nim::SystemMsg::ReadAllAsync([&](NIMResCode ret, int unread_count)
{
    ...
});

删除单条通知消息

• API 原型

static bool DeleteAsync(int64_t msg_id, const DeleteCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
msg_id	消息id
cb	操作结果回调
json_extension	扩展字段，预留

• 示例

//删除消息
int64_t msgId = 213213111;
nim::SystemMsg::DeleteAsync(msgid, [&](NIMResCode ret, int64_t id, int count)
{
    ...
});

按消息类型批量删除消息

• API 原型

static void DeleteByTypeAsync(NIMSysMsgType type, const BatchSetCallback& cb, const std::string& json_extension = "");

• 参数说明

参数	说明
type	消息类型，详见NIMSysMsgType
cb	操作结果回调
json_extension	扩展字段，预留

• 示例

//删除kNIMSysMsgTypeTeamApply类型的所有消息
nim::SystemMsg::DeleteByTypeAsync(kNIMSysMsgTypeTeamApply, [&](NIMResCode ret, int count)
{
    if (ret == 200)//成功
    {
		...
    }
});