系统通知
更新时间: 2023/08/22 03:07:44
除消息通道外,SDK 还提供系统通知这种通道用于消息之外的通知分发。目前有两种类型:内置系统通知和自定义系统通知。现在主要包括群变动的相关通知,例如入群申请,入群邀请等,如果第三方应用还托管了好友关系,好友的添加、删除也是这个类型的通知。系统通知由 SDK 负责接收和存储,并提供较简单的未读数管理。发送自定义系统通知可以设置推送相关的参数。
注意:这里的入群申请、入群邀请的通知要区别于群操作的结果通知,比如创建群,解散群、踢人、拉人等群操作的通知。群操作的通知是通过IM消息通道来下发的(详见群通知事件)
SysMessage
参数说明
类型 | 参数 | 说明 |
---|---|---|
NIMResCode | kNIMSysMsgKeyLocalRescode | 通知错误码 详见 NIMResCode |
NIMMessageFeature | kNIMSysMsgKeyLocalFeature | 通知属性,区分离线,多端同步,漫游通知等等,详见NIMMessageFeature |
int | kNIMSysMsgKeyLocalUnreadCount | 总计的通知未读数 |
string | kNIMSysMsgKeyLocalContent | 通知内容,无格式json字符串,字段定义详见NIMSysMessageContent |
NIMSysMessageContent
参数说明
类型 | 参数 | 说明 |
---|---|---|
int64_t | kNIMSysMsgKeyTime | 通知时间戳(毫秒),选填 |
int | kNIMSysMsgKeyType | 通知的类型,如申请入群、邀请入群、添加好友等等,详见NIMSysMsgType |
string | kNIMSysMsgKeyToAccount | 接收者id,如果是个人,则是对方用户id,如果是群,则是群id,必填 |
string | kNIMSysMsgKeyFromAccount | 发送者id,选填,如发送自定义通知消息时,可选填 |
string | kNIMSysMsgKeyMsg | 通知附言,按需填写 |
string | kNIMSysMsgKeyAttach | 附件,按需填写,类似于普通IM消息的附件内容,查看发送消息 |
int64_t | kNIMSysMsgKeyMsgId | 服务器消息id(自定义通知消息,必须填0),发送方不需要填写 |
int | kNIMSysMsgKeyLocalStatus | 本地定义的系统消息状态,见NIMSysMsgStatus,发送方不需要填写 |
string | kNIMSysMsgKeyLocalClientMsgId | 通知ID(客户端) |
-- | 消息设置 | 以下字段是消息内的设置字段,也属于通知内容一部分 |
int | kNIMSysMsgKeyCustomSaveFlag | (选填)自定义通知消息是否存离线:0-只发给在线用户,1-可发给离线用户 |
string | kNIMSysMsgKeyCustomApnsText | (选填)自定义通知消息推送文本,不填则不推送 |
int | kNIMSysMsgKeyPushEnable | (可选)是否需要推送, 0:不需要,1:需要,默认填1,配合kNIMSysMsgKeyCustomApnsText 使用 |
int | kNIMSysMsgKeyPushNeedBadge | (可选)推送是否要做消息计数(角标), 0:不需要,1:需要,默认填1,配合kNIMSysMsgKeyCustomApnsText 使用 |
int | kNIMSysMsgKeyPushNeedPrefix | (可选)推送是否需要推送昵称,0:不需要,1:需要,默认填0,配合kNIMSysMsgKeyPushEnable 使用 |
string | kNIMSysMsgKeyPushPayload | (可选)第三方自定义的推送负载内容,必须为可以解析为json的非格式化的字符串,长度2048 |
bool | kNIMSysMsgKeyAntiSpamEnable | 是否需要过易盾反垃圾,默认false |
string | kNIMSysMsgKeyAntiSpamContent | (可选)开发者自定义的反垃圾字段,长度限制:5000字符,配合kNIMSysMsgKeyAntiSpamEnable 使用 |
NIMSysMessageContent
解析示例:
//假设message是消息内容的json对象
void ParseSysMessageContent(Json::Value message)
{
if (message.isObject())
{
int64_t timetag = message[kNIMSysMsgKeyTime].asUInt64();
NIMSysMsgType type = (NIMSysMsgType)message[kNIMSysMsgKeyType].asUInt();
char* receiver_accid = message[kNIMSysMsgKeyToAccount].asString();
char* sender_accid = message[kNIMSysMsgKeyFromAccount].asString();
char* content = message[kNIMSysMsgKeyMsg].asString();
char* attach = message[kNIMSysMsgKeyAttach].asString();
int64_t id = message[kNIMSysMsgKeyMsgId].asUInt64();
NIMSysMsgStatus status = (NIMSysMsgStatus)message[kNIMSysMsgKeyLocalStatus].asUInt();
//解析消息设置
int push_need_badge = (BoolStatus)message[kNIMSysMsgKeyPushNeedBadge].asInt() == 1 ? BS_TRUE : BS_FALSE;
int need_push = (BoolStatus)message[kNIMSysMsgKeyPushEnable].asInt() == 1 ? BS_TRUE : BS_FALSE;
int push_need_prefix = (BoolStatus)message[kNIMSysMsgKeyPushNeedPrefix].asInt() == 1 ? BS_TRUE : BS_FALSE;
int need_offline = (BoolStatus)message[kNIMSysMsgKeyCustomSaveFlag].asInt() == 1 ? BS_TRUE : BS_FALSE;
char* push_payload = message[kNIMSysMsgKeyPushPayload].asString();
char* push_content = message[kNIMSysMsgKeyCustomApnsText].asString();
int anti_spam_enable = message[kNIMSysMsgKeyAntiSpamEnable].asInt() == 1 ? BS_TRUE : BS_FALSE;
char* anti_spam_content = message[kNIMSysMsgKeyAntiSpamContent].asString();
...
}
}
NIMSysMsgType
通知类型说明
枚举 | 值 | 说明 |
---|---|---|
kNIMSysMsgTypeTeamApply | 0 | 申请入群 |
kNIMSysMsgTypeTeamReject | 1 | 拒绝申请入群 |
kNIMSysMsgTypeTeamInvite | 2 | 邀请入群 |
kNIMSysMsgTypeTeamInviteReject | 3 | 拒绝邀请入群 |
kNIMSysMsgTypeFriendAdd | 5 | 加好友 |
kNIMSysMsgTypeFriendDel | 6 | 删除好友 |
kNIMSysMsgTypeCustomP2PMsg | 100 | 点对点透传消息 |
kNIMSysMsgTypeCustomTeamMsg | 101 | 群透传消息 |
kNIMSysMsgTypeUnknown | 1000 | 未知类型,作为默认 |
推送、反垃圾等等消息设置类似IM的消息设置
接收系统通知
注册/注销系统消息接收事件。需要在登录之前先注册。为了保证整个程序逻辑的一致性,APP 需要针对不同类型的系统通知进行相应的操作。
- API 原型
void nim_sysmsg_reg_sysmsg_cb(const char *json_extension, nim_sysmsg_receive_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
cb | 通知回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
//收到系统通知回调
void my_nim_sysmsg_receive_cb_func(const char *content, const char *json_extension, const void *user_data)
{
//content解析为SysMessage
Json::Value values;
Json::Reader reader;
if (reader.parse(content, values) && values.isObject())
{
NIMResCode rescode_ = (NIMResCode)values[kNIMSysMsgKeyLocalRescode].asUInt();
NIMMessageFeature feature_ = (NIMMessageFeature)values[kNIMSysMsgKeyLocalFeature].asUInt();
int total_unread_count_ = values[kNIMSysMsgKeyLocalUnreadCount].asUInt();
//解析通知内容为NIMSysMessageContent定义内容
Json::Value message = values[kNIMSysMsgKeyLocalContent];
ParseSysMessageContent(message);
}
}
//监听事件
nim_sysmsg_reg_sysmsg_cb(0,my_nim_sysmsg_receive_cb_func,0);
//取消监听
nim_sysmsg_reg_sysmsg_cb(0,0,0);
发送自定义系统通知
除了内置系统通知外,SDK 也额外提供了自定义系统给开发者,方便开发者进行业务逻辑的通知。这个通知既可以由客户端发起也可以由开发者服务器发起。
客户端发起的自定义通知,该类型通知格式由开发者自定义(kNIMSysMsgKeyAttach
),SDK 仅负责发送、接收,支持在线或离线发送,且支持点对点通知和群通知,不做任何解析,也不会存储,因此也不会在聊天记录中体现,可以使用的场景例如发送正在输入的状态等。
此外,自定义系统通知内容(SysMessage)还提供了属性设置如下:
- 自定义通知消息是否存离线
- 自定义通知消息推送文本
- 第三方自定义的推送属性
- 是否需要推送
- 推送是否要做消息计数
- 推送是否需要推送昵称
注意:SDK 并不负责自定义通知的持久化,APP 需要根据自己的业务逻辑按需进行解析和持久化的工作。
- API 原型
void nim_sysmsg_send_custom_notification(const char *json_msg, const char *json_extension);
- 参数说明
参数 | 说明 |
---|---|
json_msg | 消息内容,详见SysMessage |
json_extension | 扩展字段,预留 |
- 示例
//以测试账号test1为例;
Json::FastWriter fw;
//创建通知内容
Json::Value message;
message[kNIMSysMsgKeyToAccount] = "test1";
message[kNIMSysMsgKeyType] = type;
message[kNIMSysMsgKeyLocalClientMsgId] = "消息唯一uuid";//开发者生成
values[kNIMSysMsgKeyTime] = 1520423612222;//当前时间UNIX时间戳 13位(毫秒)
//消息设置,按需
message[kNIMSysMsgKeyPushNeedBadge] = 1;
message[kNIMSysMsgKeyPushEnable] = 1;
message[kNIMSysMsgKeyPushNeedPrefix] = 1;
message[kNIMSysMsgKeyCustomSaveFlag] = 1;
message[kNIMSysMsgKeyCustomApnsText] = "这是一条推送通知消息";//推送消息的内容
message[kNIMSysMsgKeyAntiSpamEnable] = 1;
message[kNIMSysMsgKeyAntiSpamContent] = "{\"type\":0,\"data\":\"sss\"}";//参考IM 反垃圾设置
//可以创建附件内容
Json::Value attchment;
attchment["content"] = "这是attachment内容";
attchment["id"] = 2;
message[kNIMSysMsgKeyAttach] = fw.write(attchment);
//可以添加推送负载信息
Json::Value payload;
payload["Content"] = "这是推送负载信息";
message[kNIMSysMsgKeyPushPayload] = fw.write(payload);
char* msg = fw.write(message);
....
//发送消息
nim_sysmsg_send_custom_notification(msg,0);
发送自定义系统通知结果
发送自定义通知消息结果通知。
- API 原型
void nim_sysmsg_reg_custom_notification_ack_cb(const char *json_extension, nim_custom_sysmsg_ack_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
cb | 通知回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_custom_sysmsg_ack_cb_func(const char *result, const void *user_data)
{
//解析result
Json::Value values;
Json::Reader reader;
if (reader.parse(result, values) && values.isObject())
{
NIMResCode rescode = (NIMResCode)values[kNIMSendAckKeyRescode].asUInt();
char* msg_id = values[kNIMSendAckKeyMsgId].asString();
char* talk_id = values[kNIMSendAckKeyTalkId].asString();
int64_t msg_timetag = values[kNIMSendAckKeyTimetag].asInt64();
...
}
...
}
//监听事件
nim_sysmsg_reg_custom_notification_ack_cb(0,my_nim_custom_sysmsg_ack_cb_func,0);
//取消监听
nim_sysmsg_reg_custom_notification_ack_cb(0,0,0);
通知消息管理
SDK提供接口查询历史消息,查询消息未读数、设置已读、删除通知等功能支持
查询系统通知
查询本地系统消息(按时间逆序起查,逆序排列)。
nim_sysmsg_query_cb_func
参数说明
类型 | 参数 | 说明 |
---|---|---|
int | count | 消息总数 |
int | unread_count | 未读通知消息总数 |
string | result | 通知消息集合,详见SysMessage) |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- API 原型
//查询结果回调
void nim_sysmsg_query_msg_async(int limit_count, int64_t last_time, const char *json_extension, nim_sysmsg_query_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
limit_count | 一次查询数量,建议20 |
last_time | 上次查询最后一条消息的时间戳(按时间逆序起查,即最小的时间戳),起始查询填0 |
cb | 操作结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_sysmsg_query_cb_func(int count, const char *result, const char *json_extension, const void *user_data)
{
//解析result
Json::Value values;
Json::Reader reader;
if (reader.parse(sysmsgs_json, values) && values.isObject())
{
uint unread = values[kNIMSysMsglogQueryKeyUnreadCount].asUInt();
Json::Value content = values[kNIMSysMsglogQueryKeyContent];
int len = content.size();
for (int i = 0; i < len; i++)
{
//解析为NIMSysMessageContent所定义的数据
Json::Value message = content[i];
ParseSysMessageContent(message);
...
}
...
}
}
//起始查询
nim_sysmsg_query_msg_async(20,0,0,my_nim_sysmsg_query_cb_func,0);
//假设起始查询的最后一条消息时间戳是 '1520423612222'
nim_sysmsg_query_msg_async(20,1520423612222,0,my_nim_sysmsg_query_cb_func,0);
查询未读消息数
- API 原型
void nim_sysmsg_query_unread_count(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
cb | 操作结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
...
}
//查询未读通知数
nim_sysmsg_query_unread_count(0,my_nim_sysmsg_res_cb_func,0);
设置消息状态
可以将消息状态设置为通过,拒绝,已读,已失效等状态。
NIMSysMsgStatus
枚举说明
枚举 | 值 | 说明 |
---|---|---|
kNIMSysMsgStatusNone | 0 | 默认,未读 |
kNIMSysMsgStatusPass | 1 | 收到消息,通过 |
kNIMSysMsgStatusDecline | 2 | 收到消息,拒绝 |
kNIMSysMsgStatusRead | 3 | 收到消息,已读 |
kNIMSysMsgStatusDeleted | 4 | 已删 |
kNIMSysMsgStatusInvalid | 5 | 已失效 |
- API 原型
void nim_sysmsg_set_status_async(int64_t msg_id, enum NIMSysMsgStatus status, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
msg_id | 消息id |
status | 消息状态,详见NIMSysMsgStatus |
cb | 操作结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_sysmsg_res_ex_cb_func(int res_code, int64_t msg_id, int unread_count, const char *json_extension, const void *user_data)
{
if (res_code == 200)//成功
{
...
}
}
//设置消息状态
int64_t msgId = "213213111";
nim_sysmsg_set_status_async(msgId,kNIMSysMsgStatusPass,0,my_nim_sysmsg_res_ex_cb_func,0);
按消息类型批量设置消息状态
- API 原型
void nim_sysmsg_set_logs_status_by_type_async(enum NIMSysMsgType type, enum NIMSysMsgStatus status, const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
type | 消息类型,详见NIMSysMsgType |
status | 消息状态,详见NIMSysMsgStatus |
cb | 操作结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
if (res_code == 200)//成功
{
...
}
}
//按类型设置消息状态
nnim_sysmsg_set_logs_status_by_type_async(kNIMSysMsgTypeTeamApply, kNIMSysMsgStatusPass, 0,my_nim_sysmsg_res_cb_func,0);
设置全部消息已读
- API 原型
void nim_sysmsg_read_all_async(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
cb | 操作结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
...
}
//设置全部消息已读
nim_sysmsg_read_all_async(0,my_nim_sysmsg_res_cb_func,0);
删除单条通知消息
- API 原型
void nim_sysmsg_delete_async(int64_t msg_id, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
msg_id | 消息id |
cb | 操作结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_sysmsg_res_ex_cb_func(int res_code, int64_t msg_id, int unread_count, const char *json_extension, const void *user_data)
{
if (res_code == 200)//成功
{
...
}
}
//删除消息
int64_t msgId = 213213111;
nim_sysmsg_delete_async(msgid,0, my_nim_sysmsg_res_ex_cb_func,0);
按消息类型批量删除消息
- API 原型
void nim_sysmsg_delete_logs_by_type_async(enum NIMSysMsgType type, const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
type | 消息类型,详见NIMSysMsgType |
cb | 操作结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
...
}
//删除kNIMSysMsgTypeTeamApply类型的所有消息
nim_sysmsg_delete_logs_by_type_async(kNIMSysMsgTypeTeamApply,0, my_nim_sysmsg_res_cb_func,0);