系统通知
更新时间: 2024/08/20 15:45:46
本文已废弃,请前往系统通知概述等系统通知文档查看相关说明。
初始化参数
- 这里的参数并不是所有的初始化参数, 请查阅初始化SDK, 以及其它章节的初始化参数
示例代码
javascriptvar nim = NIM.getInstance({
onofflinesysmsgs: onOfflineSysMsgs,
onsysmsg: onSysMsg,
onupdatesysmsg: onUpdateSysMsg,
onsysmsgunread: onSysMsgUnread,
onupdatesysmsgunread: onUpdateSysMsgUnread,
onofflinecustomsysmsgs: onOfflineCustomSysMsgs,
oncustomsysmsg: onCustomSysMsg,
syncBroadcastMsgs: true, // 是否同步离线广播消息,默认false
onbroadcastmsg: onBroadcastMsg, // 收到广播消息的回调
onbroadcastmsgs: onBroadcastMsgs, // 登录后同步到离线广播消息的回调
});
function onOfflineSysMsgs(sysMsgs) {
console.log('收到离线系统通知', sysMsgs);
pushSysMsgs(sysMsgs);
}
function onSysMsg(sysMsg) {
console.log('收到系统通知', sysMsg)
pushSysMsgs(sysMsg);
}
function onUpdateSysMsg(sysMsg) {
pushSysMsgs(sysMsg);
}
function pushSysMsgs(sysMsgs) {
data.sysMsgs = nim.mergeSysMsgs(data.sysMsgs, sysMsgs);
refreshSysMsgsUI();
}
function onSysMsgUnread(obj) {
console.log('收到系统通知未读数', obj);
data.sysMsgUnread = obj;
refreshSysMsgsUI();
}
function onUpdateSysMsgUnread(obj) {
console.log('系统通知未读数更新了', obj);
data.sysMsgUnread = obj;
refreshSysMsgsUI();
}
function refreshSysMsgsUI() {
// 刷新界面
}
function onOfflineCustomSysMsgs(sysMsgs) {
console.log('收到离线自定义系统通知', sysMsgs);
}
function onCustomSysMsg(sysMsg) {
console.log('收到自定义系统通知', sysMsg);
}
function onBroadcastMsg(msg) {
console.log('收到广播消息', msg);
}
function onBroadcastMsgs(msgs) {
console.log('收到广播消息', msgs);
}
参数解释
onofflinesysmsgs
, 同步离线系统通知的回调, 会传入系统通知数组- 在支持数据库时并且启用了多 tab 同时登录, 那么如果多个 tab 页同时断线重连之后, 只会有一个 tab 页负责存储离线系统通知, 即只会有一个 tab 页会收到
onofflinesysmsgs
回调, 其它 tab 页在同步完成之后, 需要调用获取本地系统通知来从本地缓存中拉取系统通知 onsysmsg
, 收到系统通知的回调, 会传入系统通知- 收到系统通知后需要调用标记系统通知为已读状态来将系统通知标记为已读状态
onupdatesysmsg
, 更新系统通知后的回调, 会传入{@link SystemMessage|系统通知}onsysmsgunread
: 收到系统通知未读数的回调- SDK 会管理内建系统通知的未读数, 此回调接收的对象包括以下字段
friend
: 所有跟好友相关的系统通知的未读数addFriend
: 直接加为好友的未读数applyFriend
: 申请加为好友的未读数passFriendApply
: 通过好友申请的未读数rejectFriendApply
: 拒绝好友申请的未读数deleteFriend
: 删除好友的未读数team
: 所有跟群相关的系统通知的未读数teamInvite
: 入群邀请的未读数rejectTeamInvite
: 接受入群邀请的未读数applyTeam
: 入群申请的未读数rejectTeamApply
: 拒绝入群申请的未读数deleteMsg
: 撤回消息的未读数
- SDK 会管理内建系统通知的未读数, 此回调接收的对象包括以下字段
onupdatesysmsgunread
: 更新系统通知未读数的回调onofflinecustomsysmsgs
, 同步离线自定义系统通知的回调, 会传入系统通知数组oncustomsysmsg
, 收到自定义系统通知的回调, 会传入系统通知onbroadcastmsg
, 收到广播消息的回调,一条onbroadcastmsgs
, 收到离线广播消息的回调,多条
系统通知分为两种
- 内建系统通知
- 目前所有的内建系统通知都是与高级群相关的通知, 某些群操作后相关的群成员会收到相应的系统通知。
- 内建系统通知与群通知消息的区别是系统通知是发给单人的通知, 群通知消息是发给所有群成员的消息。
- 自定义系统通知
系统通知对象
系统通知对象有以下字段
time
: 时间戳type
: 系统通知类型, 自定义系统通知无此字段from
: 系统通知的来源, 账号或者群IDto
: 系统通知的目标, 账号或者群IDidServer
: 内建系统通知的 idServerread
: 内建系统通知是否已读category
: 内建系统通知种类state
: 内建系统通知状态error
: 内建系统通知的状态为'error'
时, 此字段包含错误的信息localCustom
: 内建系统通知的本地自定义扩展字段ps
: 内建系统通知的附言attach
: 内建系统通知的附加信息, 参考系统通知类型来查看不同类型的系统通知对应的附加信息scene
: 自定义系系统通知的场景, 参考消息场景content
: 自定义系统通知的内容isPushable
: 是否需要推送apnsText
: 自定义系统通知的apns推送文案, 仅对接收方为iOS设备有效pushPayload
: 自定义系统通知的推送属性- 推荐使用
JSON
格式构建, 非JSON
格式的话, Web端会正常接收, 但是会被其它端丢弃
- 推荐使用
needPushNick
: 是否需要推送昵称sendToOnlineUsersOnly
: 自定义系统通知是否只发送给在线用户。true
时只发送给在线用户, 适合发送即时通知, 比如正在输入。false
时假如目标用户或群不在线, 会在其上线后推送过去。- 该参数只对点对点自定义系统通知有效, 对群自定义系统通知无效, 群自定义系统通知只会发给在线的群成员, 不会存离线。
cc
: 自定义系统通知是否抄送
系统通知类型
系统通知对象有一个字段type
来标明系统通知的类型, 自定义系统通知无此字段, 具体类型如下
'teamInvite'
(入群邀请)'rejectTeamInvite'
(拒绝入群邀请)- 见
'teamInvite'
- 见
'applyTeam'
(入群申请)'rejectTeamApply'
(拒绝入群申请)- 见
'applyTeam'
- 见
'addFriend'
- 直接加某个用户为好友后, 对方不需要确认, 直接成为当前登录用户的好友
- 对方会收到一条类型为
'addFriend'
的系统通知, 此类系统通知的from
字段的值为申请方的帐号,to
字段的值为接收方的账号。
'applyFriend'
'passFriendApply'
- 见
'applyFriend'
- 见
'rejectFriendApply'
- 见
'applyFriend'
- 见
'deleteFriend'
'deleteMsg'
'custom'
- 自定义系统通知
内建系统通知种类
上文中的系统通知类型除了'custom'
之外的其它类型都属于内建系统通知, 这些类型归为两大种类
'team'
'friend'
内建系统通知状态
'init'
: 未处理状态'passed'
: 已通过'rejected'
: 已拒绝'error'
: 错误
处理系统通知
这里涉及到了好友的处理, 请跟好友关系托管合在一起看
javascriptfunction handleSysMsgs(sysMsgs) {
if (!Array.isArray(sysMsgs)) {sysMsgs=[sysMsgs];}
sysMsgs.forEach(function(sysMsg) {
var idServer = sysMsg.idServer;
switch (sysMsg.type) {
case 'addFriend':
onAddFriend(sysMsg.friend);
break;
case 'applyFriend':
break;
case 'passFriendApply':
onAddFriend(sysMsg.friend);
break;
case 'rejectFriendApply':
break;
case 'deleteFriend':
onDeleteFriend(sysMsg.from);
break;
case 'applyTeam':
break;
case 'rejectTeamApply':
break;
case 'teamInvite':
break;
case 'rejectTeamInvite':
break;
default:
break;
}
});
}
标记系统通知为已读状态
- SDK 在收到系统通知后会更新系统通知未读数, 开发者需要调用此接口来通知 SDK 将某条系统通知标记为已读状态, 标记后会触发
onupdatesysmsgunread
回调 sysMsgs
为通过onofflinesysmsgs
或者onsysmsg
接收到的系统通知或者系统通知数组
javascriptnim.markSysMsgRead({
sysMsgs: someSysMsg, // or [someSysMsg]
done: markSysMsgReadDone
});
function markSysMsgReadDone(error, obj) {
console.log(error);
console.log(obj);
console.log('标记系统通知为已读状态' + (!error?'成功':'失败'));
}
获取本地系统通知
- 在支持数据库的时候, SDK 会将内建系统通知存储于数据库中
- 当开发者发现系统通知的未读数大于系统通知数量时, 说明有未读系统通知存储于数据库里面, 需要从本地拉取这部分系统通知
- 默认获取所有种类的系统通知, 可以传入参数
category
来限制系统通知种类 - 默认获取所有类型的系统通知, 可以传入参数
type
来限制系统通知类型 - 默认获取所有已读和未读的系统通知, 可以传入参数
read
来限制已读状态- 如果不传, 默认获取所有已读和未读的系统通知
- 如果传
true
, 那么只获取已读的系统通知 - 如果传
false
, 那么只获取未读的系统通知
lastIdServer
为上次查询的最后一条系统通知的idServer
, 第一次不填limit
为本次查询的消息数量限制, 最多 100 条, 默认 100 条- 默认从最近的系统通知开始往前查找本地系统通知, 可以传入参数
reverse=true
来从第一条系统通知开始往后查找本地系统通知
javascriptnim.getLocalSysMsgs({
lastIdServer: 'lastIdServer',
limit: 100,
done: getLocalSysMsgsDone
});
function getLocalSysMsgsDone(error, obj) {
console.log(error);
console.log(obj);
console.log('获取本地系统通知' + (!error?'成功':'失败'));
if (!error) {
console.log(obj.sysMsgs);
}
}
更新本地系统通知
- 更新
idServer
对应的本地系统通知 - 如果不支持数据库, 算成功
- 如果对应的系统通知不存在, 算成功, 返回 null
- 这些字段只会被更新到本地数据库, 不会被更新到服务器上
javascriptnim.updateLocalSysMsg({
idServer: '1234',
status: 'bingo',
localCustom: '{"key","value"}',
done: updateLocalSysMsgDone
});
function updateLocalSysMsgDone(error, obj) {
console.log(error);
console.log(obj);
console.log('更新本地系统通知' + (!error?'成功':'失败'));
}
删除本地系统通知
- 删除
idServer
对应的本地系统通知 - 如果不支持数据库, 算成功
- 如果对应的系统通知不存在, 算成功
javascriptnim.deleteLocalSysMsg({
idServer: '1234',
done: deleteLocalSysMsgDone
});
function deleteLocalSysMsgDone(error, obj) {
console.log(error);
console.log(obj);
console.log('删除本地系统通知' + (!error?'成功':'失败'));
}
删除所有本地系统通知
- 如果不支持数据库, 算成功
- 此方法同时会清空系统通知未读数, 开发者会收到
onupdatesysmsgunread
javascriptnim.deleteAllLocalSysMsgs({
done: deleteAllLocalSysMsgsDone
});
function deleteAllLocalSysMsgsDone(error, obj) {
console.log(error);
console.log(obj);
console.log('删除所有本地系统通知' + (!error?'成功':'失败'));
}
自定义系统通知
- 开发者可以向其他用户或群发送自定义系统通知, 默认只发给在线用户, 如果需要发送给离线用户, 那么需要设置参数
sendToOnlineUsersOnly=false
, 请参考下面的示例代码 - 自定义系统通知和自定义消息的区别如下
- SDK 不存储自定义系统通知, 不管理自定义系统通知的未读数
- 可选参数有
yidunEnable
: 指定是否需要使用自定义反垃圾字段,即antiSpamContent
,默认false
不需要。antiSpamContent
: 在开启yidunEnable
后, 开发者自定义的反垃圾字段(json格式),格式如下:{"type": 1, "data": "custom content"} 字段说明:type:1.文本,2.图片,3视频,data内容:文本内容or图片地址or视频地址
javascriptvar content = {
type: 'type',
value: 'value'
};
content = JSON.stringify(content);
var msgId = nim.sendCustomSysMsg({
scene: 'p2p',
to: 'account',
content: content,
sendToOnlineUsersOnly: false,
apnsText: content,
done: sendCustomSysMsgDone
});
console.log('正在发送p2p自定义系统通知, id=' + msgId);
function sendCustomSysMsgDone(error, msg) {
console.log('发送' + msg.scene + '自定义系统通知' + (!error?'成功':'失败') + ', id=' + msg.idClient);
console.log(error);
console.log(msg);
}
广播消息
- 用户可以通过应用服务器发送广播消息,应用内的所有指定的在线用户都会收到广播包,此外广播消息支持离线存储,并设置有效期,最长7天,单个应用最多离线存储最近的100条广播通知
- 广播消息参数:
broadcastId
: 广播消息idbody
: 广播消息体fromAccid
: 发送该广播消息的账号time
: 广播消息发送时间戳
此文档是否对你有帮助?