系统通知 - IM 即时通讯（含 UI）

开发者中心

IM 即时通讯（含 UI）

了解产品

系统通知

更新时间： 2023/07/21 06:56:54

本文已废弃，请前往系统通知概述等系统通知文档查看相关说明。

初始化参数

这里的参数并不是所有的初始化参数, 请查阅初始化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|系统通知}
- 以下情况会收到此回调
- 这些操作的发起方会收到此回调, 接收被更新的系统通知, 根据操作的类型系统通知会被更新为下面两种状态
  - 'passed': 已通过
  - 'rejected': 已拒绝
onsysmsgunread: 收到系统通知未读数的回调
- SDK 会管理内建系统通知的未读数, 此回调接收的对象包括以下字段
  - friend: 所有跟好友相关的系统通知的未读数
  - addFriend: 直接加为好友的未读数
  - applyFriend: 申请加为好友的未读数
  - passFriendApply: 通过好友申请的未读数
  - rejectFriendApply: 拒绝好友申请的未读数
  - deleteFriend: 删除好友的未读数
  - team: 所有跟群相关的系统通知的未读数
  - teamInvite: 入群邀请的未读数
  - rejectTeamInvite: 接受入群邀请的未读数
  - applyTeam: 入群申请的未读数
  - rejectTeamApply: 拒绝入群申请的未读数
  - deleteMsg: 撤回消息的未读数
onupdatesysmsgunread: 更新系统通知未读数的回调
onofflinecustomsysmsgs, 同步离线自定义系统通知的回调, 会传入系统通知数组
oncustomsysmsg, 收到自定义系统通知的回调, 会传入系统通知
onbroadcastmsg, 收到广播消息的回调，一条
onbroadcastmsgs, 收到离线广播消息的回调，多条

系统通知分为两种

内建系统通知
- 目前所有的内建系统通知都是与高级群相关的通知, 某些群操作后相关的群成员会收到相应的系统通知。
- 内建系统通知与群通知消息的区别是系统通知是发给单人的通知, 群通知消息是发给所有群成员的消息。
自定义系统通知

系统通知对象

系统通知对象有以下字段

time: 时间戳
type: 系统通知类型, 自定义系统通知无此字段
from: 系统通知的来源, 账号或者群ID
to: 系统通知的目标, 账号或者群ID
idServer: 内建系统通知的 idServer
read: 内建系统通知是否已读
category: 内建系统通知种类
state: 内建系统通知状态
error: 内建系统通知的状态为 'error' 时, 此字段包含错误的信息
localCustom: 内建系统通知的本地自定义扩展字段
- 在支持数据库时可以调用更新本地会话来更新此字段, 此字段只会被更新到本地数据库, 不会被更新到服务器上
ps: 内建系统通知的附言
attach: 内建系统通知的附加信息, 参考系统通知类型来查看不同类型的系统通知对应的附加信息
scene: 自定义系系统通知的场景, 参考消息场景
content: 自定义系统通知的内容
isPushable: 是否需要推送
apnsText: 自定义系统通知的apns推送文案, 仅对接收方为iOS设备有效
pushPayload: 自定义系统通知的推送属性
- 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
needPushNick: 是否需要推送昵称
sendToOnlineUsersOnly: 自定义系统通知是否只发送给在线用户。
- true时只发送给在线用户, 适合发送即时通知, 比如正在输入。
- false时假如目标用户或群不在线, 会在其上线后推送过去。
- 该参数只对点对点自定义系统通知有效, 对群自定义系统通知无效, 群自定义系统通知只会发给在线的群成员, 不会存离线。
cc: 自定义系统通知是否抄送

系统通知类型

系统通知对象有一个字段type来标明系统通知的类型, 自定义系统通知无此字段, 具体类型如下

'teamInvite' (入群邀请)
- 高级群的群主和管理员在邀请成员加入群（通过操作创建群或拉人入群）之后, 被邀请的人会收到一条类型为'teamInvite'的系统通知, 此类系统通知的from字段的值为邀请方的帐号, to字段的值为对应的群ID, 此类系统通知的attach有一个字段team的值为被邀请进入的群, 被邀请的人可以选择接受邀请或者拒绝邀请。
  - 如果接受邀请, 那么该群的所有群成员会收到一条类型为'acceptTeamInvite'的群通知消息, 此类群通知消息的from字段的值为接受入群邀请的人的帐号, to字段的值为对应的群ID, attach有一个字段team的值为对应的群对象, attach有一个字段members的值为接收入群邀请的群成员列表。
  - 如果拒绝邀请, 那么邀请你的人会收到一条类型为'rejectTeamInvite'的系统通知, 此类系统通知的from字段的值为拒绝入群邀请的用户的帐号, to字段的值为对应的群ID。
'rejectTeamInvite' (拒绝入群邀请)
- 见'teamInvite'
'applyTeam' (入群申请)
- 用户可以申请加入高级群, 目标群的群主和管理员会收到一条类型为'applyTeam'的系统通知, 此类系统通知的from字段的值为申请方的帐号, to字段的值为对应的群ID, 高级群的群主和管理员在收到入群申请后, 可以选择通过或者拒绝入群申请。
  - 如果通过申请, 那么该群的所有群成员会收到一条类型为'passTeamApply'的群通知消息, 此类群通知消息的from字段的值为通过入群申请的人的帐号, to字段的值为对应的群ID, attach有一个字段team的值为对应的群对象, attach有一个字段account的值为申请方的帐号, attach有一个字段members的值为被通过申请的群成员列表。
  - 如果拒绝申请, 那么申请人会收到一条类型为'rejectTeamApply'的系统通知, 此类系统通知的from字段的值为拒绝方的帐号, to字段的值为对应的群ID, attach有一个字段team的值为对应的群。
'rejectTeamApply' (拒绝入群申请)
- 见'applyTeam'
'addFriend'
- 直接加某个用户为好友后, 对方不需要确认, 直接成为当前登录用户的好友
- 对方会收到一条类型为'addFriend'的系统通知, 此类系统通知的from字段的值为申请方的帐号, to字段的值为接收方的账号。
'applyFriend'
- 申请加某个用户为好友后, 对方会收到一条类型为'applyFriend'的系统通知, 此类系统通知的from字段的值为申请方的帐号, to字段的值为接收方的账号, 用户在收到好友申请后, 可以选择通过或者拒绝好友申请。
  - 如果通过好友申请, 那么申请方会收到一条类型为'passFriendApply'的系统通知, 此类系统通知的from字段的值为通过方的帐号, to字段的值为申请方的账号。
  - 如果拒绝好友申请, 那么申请方会收到一条类型为'rejectFriendApply'的系统通知, 此类系统通知的from字段的值为拒绝方的帐号, to字段的值为申请方的账号。
'passFriendApply'
- 见 'applyFriend'
'rejectFriendApply'
- 见 'applyFriend'
'deleteFriend'
- 删除好友后, 被删除的人会收到一条类型为'deleteFriend'的系统通知, 此类系统通知的from字段的值为删除方的帐号, to字段的值为被删除方的账号。
'deleteMsg'
- 撤回消息后, 消息接收方会收到一条类型为'deleteMsg'的系统通知, 此类系统通知的 msg 为被删除的消息的部分字段。如果是群消息, 那么群里的所有人都会收到这条系统通知. 如果同时在多个端登录了同一个账号, 那么其它端也会收到这条系统通知.
'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不会解析这些通知, SDK仅仅负责传递这些通知。
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: 广播消息id
- body: 广播消息体
- fromAccid: 发送该广播消息的账号
- time: 广播消息发送时间戳

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

初始化参数
系统通知对象
系统通知类型
内建系统通知种类
内建系统通知状态
处理系统通知
标记系统通知为已读状态
获取本地系统通知
更新本地系统通知
删除本地系统通知
删除所有本地系统通知
自定义系统通知
广播消息