系统通知

除消息通道外,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 msgsetting 消息属性设置 详见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 需要针对不同类型的系统通知进行相应的操作。

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

创建自定义系统通知

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

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 需要根据自己的业务逻辑按需进行解析和持久化的工作。

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

发送自定义系统通知结果

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

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)
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)
{
    ...
});

查询未读消息数

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 已失效
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)//成功
    {
        ...
    }
});

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

 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)//成功
    {
        ...
    }
});

设置全部消息已读

static void ReadAllAsync(const ReadAllCallback& cb, const std::string& json_extension = "");
参数 说明
cb 操作结果回调
json_extension 扩展字段,预留
//设置全部消息已读
nim::SystemMsg::ReadAllAsync([&](NIMResCode ret, int unread_count)
{
    ...
});

删除单条通知消息

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)
{
    ...
});

按消息类型批量删除消息

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)//成功
    {
        ...
    }
});