系统通知(已废弃)
更新时间: 2024/08/20 15:45:46
本文已废弃,请前往圈组系统通知相关查看已更新的内容。
圈组系统通知概览
系统通知可分为内置系统通知和自定义系统通知。
系统通知类型 | 说明 | 离线系统通知限制 |
---|---|---|
内置系统通知 | 圈组内置的系统通知, 类型包括“邀请服务器成员”、“踢除服务器成员”、“修改频道信息” 等 | 服务器成员管理事件的系统通知支持存离线,每月至多存 1,000 条离线通知。其他内置系统通知不存离线 |
自定义系统通知 | 开发者自定义系统通知, 如“正在输入” 。 SDK 不解析自定义系统通知,仅负责传递 | 每月 1,000 条离线通知 |
内置系统通知分类
圈组内置系统通知,可进一步分为服务器成员管理事件的系统通知、服务器其他相关事件的系统通知、频道事件系统通知、频道分组事件系统通知、身份组成员管理事件的系统通知和身份组权限事件系统通知。除了服务器成员管理事件的系统通知,其余类型都通过参与者与观察者机制控制接收人及其接收条件。
每个类型的具体触发条件和接收条件,请参考服务端的圈组系统通知。
技术原理
圈组中的系统通知是由云信服务器下发给用户的通知类消息,用于包括创建 Server、创建 Channel、申请加入 Server 等事件的通知。
SDK 通过 QChatSystemNotification
接口来定义圈组的系统通知。
QChatSystemNotification
的参数如下:
返回值类型 | 参数 | 说明 |
---|---|---|
long | getServerId() | 通知所属的圈组服务器的 ID |
long | getChannelId() | 通知所属的频道的 ID |
List |
getToAccids() | 通知接收者账号列表 |
String | getFromAccount() | 通知发送者的 accid |
QChatSystemMessageToType |
getToType() | 通知发送对象类型。主要分为服务器,服务器成员,频道,频道成员 |
int | getFromClientType() | 通知发送者的客户端类型 |
String | getFromDeviceId() | 发送方设备 ID |
String | getFromNick() | 发送方昵称 |
long | getTime() | 消息发送时间 |
long | getUpdateTime() | 通知更新时间 |
QChatSystemNotificationType |
getType() | 通知类型,具体系统通知类型的接收条件等信息,可参考服务器的 QChatSystemMsgType |
String | getMsgIdClient() | 客户端生成的消息 ID,会用于去重 |
long | getMsgIdServer() | 服务器生成的通知 ID,全局唯一 |
String | getBody() | 通知内容 |
String | getAttach() | 通知附件 |
QChatSystemNotificationAttachment |
getAttachment() | 通知附件字符串解析后的结构 |
String | getExtension() | 扩展字段 |
int | getStatus() | 状态,可以自定义。默认为 0,大于 10,000 为用户自定义的状态 |
String | getPushPayload() | 第三方自定义的推送属性,限制使用 JSON 格式 |
String | getPushContent() | 自定义推送文案 |
boolean | isPersistEnable() | 是否存离线,只有toAccids 不为空,才能设置为存离线 |
boolean | isPushEnable() | 是否需要推送,默认 false |
boolean | isNeedBadge() | 是否需要消息计数 |
boolean | isNeedPushNick() | 是否需要推送昵称 |
boolean | isRouteEnable() | 是否需要抄送,默认 true |
String | getEnv() | 获取环境变量,用于指向不同的抄送,第三方回调等配置 |
void | setEnv(String env) | 设置环境变量,用于指向不同的抄送,第三方回调等配置 |
String | getCallbackExtension() | 获取第三方回调回来的自定义扩展字段 |
实现方法
发送自定义系统通知
SDK 提供发送自定义系统通知的能力。
SDK 通过圈组消息 QChatMessageService
中的 sendSystemNotification
发送自定义系统通知。
/**
* 发送系统通知
* @param param
* @return InvocationFuture 可设置回调函数,监听操作结果。回调中返回发送成功的自定义系统通知
*/
InvocationFuture<QChatSendSystemNotificationResult> sendSystemNotification(@NonNull QChatSendSystemNotificationParam param);
其中 QChatSendSystemNotificationParam
是发送自定义系统通知入参,提供四种构造方法,分别代表需要通知给不同的系统通知对象:
/**
* 通知给服务器
* @param serverId 服务器id
*/
public QChatSendSystemNotificationParam(long serverId)
/**
* 通知给频道
* @param serverId 服务器id
* @param channelId 频道id
*/
public QChatSendSystemNotificationParam(long serverId, long channelId)
/**
* 通知给服务器成员
* @param serverId 服务器id
* @param toAccids 通知的账号列表
*/
public QChatSendSystemNotificationParam(long serverId, List<String> toAccids)
/**
* 通知给频道成员
* @param serverId 服务器id
* @param channelId 频道id
* @param toAccids 通知的账号列表
*/
public QChatSendSystemNotificationParam(long serverId, long channelId, List<String> toAccids)
如果您希望在发送自定义系统通知前提前构造一个QChatSystemNotification
,您可以通过QChatSendSystemNotificationParam
的 toSystemNotification
方法构造出一个QChatSystemNotification
。
QChatSendSystemNotificationParam
的参数说明如下:
返回值类型 | 参数 | 说明 |
---|---|---|
String | getBody() | 获取通知内容 |
void | setBody(Stringbody) | 设置通知内容 |
void | setAttach(Stringattach) | 设置通知附件 |
void | setExtension(Map<String,Object>extension) | 设置扩展字段 |
void | setStatus(Integerstatus) | 如果设置状态,状态只能设置成自定义的状态(status>=10000),否则提示 414 参数错误 |
void | setPushPayload(Map<String,Object>pushPayload) | 设置推送 payload |
void | setPushContent(StringpushContent) | 设置推送内容 |
Long | getServerId() | 获取服务器 ID |
Long | getChannelId() | 获取频道 ID |
List< String> | getToAccids() | 获取通知的账号列表 |
String | getAttach() | 获取附件字符串 |
Map<String,Object> | getExtension() | 获取扩展字段 |
Integer | getStatus() | 获取状态 |
Map<String,Object> | getPushPayload() | 获取推送payload |
String | getPushContent() | 获取推送内容 |
boolean | isPersistEnable() | 是否保存离线消息 |
void | setPersistEnable(booleanpersistEnable) | 设置是否存离线 |
Integer | getToType() | 获取通知发送对象类型 |
boolean | isPushEnable() | 是否需要推送,默认true |
void | setPushEnable(booleanpushEnable) | 设置是否需要推送 |
boolean | isNeedBadge() | 是否需要消息计数,默认true |
void | setNeedBadge(booleanneedBadge) | 设置是否需要消息计数 |
boolean | isNeedPushNick() | 是否需要推送昵称,默认true |
void | setNeedPushNick(booleanneedPushNick) | 设置是否需要推送昵称 |
QChatSystemNotificationType |
getType() | 获取系统通知类型,用户发送的系统通知一定是QChatSystemMsgType.CUSTOM |
String | getUuid() | 获取系统通知 uuid |
boolean | isRouteEnable() | 是否需要抄送,默认 true |
void | setRouteEnable(boolean routeEnable) | 设置是否需要抄送 |
String | getEnv() | 获取环境变量,用于指向不同的抄送,第三方回调等配置 |
void | setEnv(String env) | 设置环境变量,用于指向不同的抄送,第三方回调等配置 |
QChatSystemNotification |
toSystemNotification() | 转换成QChatSystemNotification |
示例代码
QChatSendSystemNotificationParam param = new QChatSendSystemNotificationParam(943445L,885305L);
param.setBody("测试自定义系统通知");
param.setExtension(getExtension());
param.setPushPayload(getPushPayload());
param.setPushContent("测试推送自定义系统通知");
param.setPushEnable(true);
param.setNeedBadge(true);
param.setNeedPushNick(true);
QChatSystemNotification currentSystemNotification = param.toSystemNotification();
NIMClient.getService(QChatMessageService.class).sendSystemNotification(param).setCallback(new RequestCallback<QChatSendSystemNotificationResult>() {
@Override
public void onSuccess(QChatSendSystemNotificationResult result) {
//发送自定义系统通知成功,返回发送成功的自定义系统通知具体信息
QChatSystemNotification notification = result.getSentCustomNotification();
}
@Override
public void onFailed(int code) {
//发送自定义系统通知息失败,返回错误code
}
@Override
public void onException(Throwable exception) {
//发送自定义系统通知异常
}
});
重发自定义系统通知
SDK 支持重发自定义系统通知,重发已经发送成功的自定义系统通知。通知接收方不会再次收到系统通知。
SDK 通过圈组消息 QChatMessageService
中的 resendSystemNotification
重新发送自定义系统通知。
/**
* 重发系统通知
* @param param
* @return InvocationFuture 可设置回调函数,监听操作结果。回调中返回发送成功的自定义系统通知
*/
InvocationFuture<QChatSendSystemNotificationResult> resendSystemNotification(@NonNull QChatResendSystemNotificationParam param);
其中 QChatResendSystemNotificationParam
是重发自定义系统通知入参,重新构造出一个QChatSystemNotification
。
示例代码
NIMClient.getService(QChatMessageService.class).resendSystemNotification(new QChatResendSystemNotificationParam(currentSystemNotification)).setCallback(new RequestCallback<QChatSendSystemNotificationResult>() {
@Override
public void onSuccess(QChatSendSystemNotificationResult result) {
//重发自定义系统通知成功,返回发送成功的自定义系统通知具体信息
QChatSystemNotification notification = result.getSentCustomNotification();
}
@Override
public void onFailed(int code) {
//重发自定义系统通知息失败,返回错误code
}
@Override
public void onException(Throwable exception) {
//重发自定义系统通知异常
}
});
系统通知接收监听
SDK 通过注册监听 QChatServiceObserver
中的 observeReceiveSystemNotification
监听系统通知事件。
可以通过注册监听的方式监听圈组中发送给自己的系统通知:
/**
* 注册/注销系统通知接收事件观察者
* @param observer 观察者, 参数为接收到的系统消息
* @param register true为注册,false为注销
*/
void observeReceiveSystemNotification(Observer<List<QChatSystemNotification>> observer, boolean register);
示例代码
NIMClient.getService(QChatServiceObserver.class).observeReceiveSystemNotification(new Observer<List<QChatSystemNotification>>() {
@Override
public void onEvent(List<QChatSystemNotification> qChatSystemNotifications) {
//收到系统通知
for (QChatSystemNotification qChatSystemNotification : qChatSystemNotifications) {
//处理系统通知
}
}
}, true);
更新系统通知
对于已发送的系统通知,可以修改系统通知中部分信息。
SDK 通过圈组消息 QChatMessageService
中的 updateSystemNotification
更新系统通知。
/**
* 更新系统通知,除了更新自定义系统通知外,还允许更新邀请服务器成员、拒绝邀请、申请加入服务器、拒绝申请这几种内置系统通知
* @param param
* @return InvocationFuture 可设置回调函数,监听操作结果。回调中返回更新成功的系统通知
*/
InvocationFuture<QChatUpdateSystemNotificationResult> updateSystemNotification(@NonNull QChatUpdateSystemNotificationParam param);
其中 QChatUpdateSystemNotificationParam
是更新系统通知的入参,必须传入更新操作通用参数updateParam
、系统通知服务端 ID msgIdServer
(全局唯一)、系统通知类型type
。可以修改系统通知中的内容、自定义扩展和状态,其中只有自定义系统通知类型才可以更改状态值,且必须大于等于 1000,否则会返回 414 错误码。
示例代码
QChatUpdateParam updateParam = new QChatUpdateParam();
updateParam.setPostscript("附言");
updateParam.setExtension("操作扩展字段");
QChatUpdateSystemNotificationParam updateSystemNotificationParam = new QChatUpdateSystemNotificationParam(updateParam, currentSystemNotification.getMsgIdServer(),
currentSystemNotification.getType());
updateSystemNotificationParam.setBody("修改系统通知内容");
//修改系统通知自定义扩展
updateSystemNotificationParam.setExtension(getExtension());
//只有自定义系统通知类型才可以更改状态值,且必须大于等于1000
updateSystemNotificationParam.setStatus(10001);
NIMClient.getService(QChatMessageService.class).updateSystemNotification(updateSystemNotificationParam).setCallback(
new RequestCallback<QChatUpdateSystemNotificationResult>() {
@Override
public void onSuccess(QChatUpdateSystemNotificationResult result) {
//更新成功,返回更新后的系统通知
result.getSentCustomNotification();
}
@Override
public void onFailed(int code) {
//更新失败,返回错误code
}
@Override
public void onException(Throwable exception) {
//更新异常
}
});
系统通知更新状态监听
SDK 通过注册监听 QChatServiceObserver
中的 observeSystemNotificationUpdate
监听系统通知更新事件。
/**
* 注册/注销系统通知更新观察者
*
* @param observer 观察者,参数为改变的系统通知事件
* @param register true为注册,false为注销
*/
void observeSystemNotificationUpdate(Observer<QChatSystemNotificationUpdateEvent> observer, boolean register);
其中 QChatSystemNotificationUpdateEvent
是更新系统通知状态的入参,包含了系统通知更新的操作信息和更新后的系统通知。
示例代码
NIMClient.getService(QChatServiceObserver.class).observeSystemNotificationUpdate(new Observer<QChatSystemNotificationUpdateEvent>() {
@Override
public void onEvent(QChatSystemNotificationUpdateEvent event) {
//更新成功,返回更新后的系统通知
QChatSystemNotification systemNotification = event.getSystemNotification();
}
}, true);
系统通知标志已读
SDK 通过圈组消息 QChatMessageService
中的 markSystemNotificationsRead
标志系统通知已读。
可以对系统通知标记已读。标记已读后的系统通知将从服务端删除,后续不会在其他端接收到了。
/**
* 标记系统通知已读
* @param param
* @return InvocationFuture 可设置回调函数,监听操作结果。
*/
InvocationFuture<Void> markSystemNotificationsRead(@NonNull QChatMarkSystemNotificationsReadParam param);
其中 QChatMarkSystemNotificationsReadParam
是标记系统通知已读的入参。
示例代码
QChatSystemNotification systemNotification = getMarkSystemNotification();
List<Pair<Long, QChatSystemNotificationType>> pairs = new ArrayList<>();
pairs.add(new Pair<>(systemNotification.getMsgIdServer(),systemNotification.getType()));
QChatMarkSystemNotificationsReadParam param = new QChatMarkSystemNotificationsReadParam(pairs);
NIMClient.getService(QChatMessageService.class).markSystemNotificationsRead(param).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void result) {
//标记成功
}
@Override
public void onFailed(int code) {
//标记失败
}
@Override
public void onException(Throwable exception) {
//标记异常
}
});