系统通知
更新时间: 2024/09/18 11:11:45
系统通知指系统下发的通知,不属于会话内消息,例如单聊场景中的 对方正在输入 功能,及群聊场景中的入群申请、入群邀请等。系统通知包括广播通知和自定义系统通知两种类型。
本文介绍自定义系统通知收发相关 API。更多系统通知相关功能请参考开发指南文档 系统通知概述。
支持平台
Android | iOS | macOS/Windows | Web/uni-app/小程序 | HarmonyOS |
---|---|---|---|---|
✔️️️ | ✔️️️ | ✔️️️ | ✔️️️ | ✔️️️ |
API 概览
系统通知监听
Android/iOS/macOS/Windows
API | 说明 | 起始版本 |
---|---|---|
addNoticationListener | 注册系统通知相关监听器 | v10.2.0 |
removeNotificationListener | 移除系统通知相关监听器 | v10.2.0 |
Web/uni-app/小程序/HarmonyOS
API | 说明 | 起始版本 |
---|---|---|
on("EventName") | 注册系统通知相关监听 | v10.2.0(对应 HarmonyOS v0.5.0) |
off("EventName") | 取消注册系统通知相关监听 | v10.2.0(对应 HarmonyOS v0.5.0) |
系统通知发送
API | 说明 | 起始版本 |
---|---|---|
sendCustomNotification | 发送自定义系统通知 | v10.2.0(对应 HarmonyOS v0.5.0) |
接口类
V2NIMNotificationService
类提供自定义通知相关接口。
addNoticationListener
接口描述
注册系统通知监听器。
注册成功后,当事件发生时,SDK 会返回对应的回调。
-
建议在初始化后调用该方法。
-
全局只需注册一次。
-
该方法为同步。
参数说明
Android
Javavoid addNotificationListener(V2NIMNotificationListener listener);
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
listener |
V2NIMNotificationListener |
是 | 系统通知相关监听器 |
iOS
Objective-C- (void)addNoticationListener:(id<V2NIMNotificationListener>)listener;
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
listener |
V2NIMNotificationListener |
是 | 系统通知相关监听器 |
macOS/Windows
C++virtual void addNotificationListener(V2NIMNotificationListener listener) = 0;
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
listener |
V2NIMNotificationListener |
是 | 系统通知相关监听器 |
示例代码
Android
JavaV2NIMNotificationService v2NotificationService = NIMClient.getService(V2NIMNotificationService.class);
V2NIMNotificationListener notificationListener = new V2NIMNotificationListener() {
@Override
public void onReceiveCustomNotifications(List<V2NIMCustomNotification> customNotifications) {
// your code
}
@Override
public void onReceiveBroadcastNotifications(List<V2NIMBroadcastNotification> broadcastNotifications) {
// your code
}
};
v2NotificationService.addNotificationListener(notificationListener);
iOS
Objective-C// listener 实现 V2NIMNotificationListener 协议
[[[NIMSDK sharedSDK] v2NotificationService] addNoticationListener:listener];
macOS/Windows
C++V2NIMNotificationListener listener;
listener.onReceiveCustomNotifications = [](nstd::vector<V2NIMCustomNotification> customNotifications) {
// handle custom notifications
};
listener.onReceiveBroadcastNotifications = [](nstd::vector<V2NIMBroadcastNotification> broadcastNotifications) {
// handle broadcast notifications
};
notificationService.addNotificationListener(listener);
返回参数
无。
removeNotificationListener
接口描述
移除系统通知监听器。
该方法为同步。
参数说明
Android
Javavoid removeNotificationListener(V2NIMNotificationListener listener);
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
listener |
V2NIMNotificationListener |
是 | 系统通知相关监听器 |
iOS
Objective-C- (void)removeNotificationListener:(id<V2NIMNotificationListener>)listener;
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
listener |
V2NIMNotificationListener |
是 | 系统通知相关监听器 |
macOS/Windows
C++virtual void removeNotificationListener(V2NIMNotificationListener listener) = 0;
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
listener |
V2NIMNotificationListener |
是 | 系统通知相关监听器 |
示例代码
Android
JavaV2NIMNotificationService v2NotificationService = NIMClient.getService(V2NIMNotificationService.class);
v2NotificationService.removeNotificationListener(notificationListener);
iOS
Objective-C// listener 实现 V2NIMNotificationListener 协议
[[[NIMSDK sharedSDK] v2NotificationService] removeNoticationListener:listener];
macOS/Windows
C++V2NIMNotificationListener notificationListener;
notificationListener.onReceiveCustomNotifications = [=](nstd::vector<V2NIMCustomNotification> customNotifications) {
// process custom notifications
};
notificationListener.onReceiveBroadcastNotifications = [=](nstd::vector<V2NIMBroadcastNotification> broadcastNotifications) {
// process broadcast notifications
};
v2::V2NIMClient::get().getNotificationService().addNotificationListener(notificationListener);
返回参数
无。
on("EventName")
-
建议在初始化后调用该方法。
-
全局只需注册一次。
-
该接口为同步。
接口描述
注册系统通知相关监听。
注册成功后,当消息事件发生时,SDK 会触发相关回调通知。
-
建议在初始化后调用该方法。
-
全局只需注册一次。
-
该方法为同步。
参数说明
Web/uni-app/小程序
TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
/**
* 继承自 EventEmitter3 的监听事件方法。
*/
on<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void;
/**
* 继承自 EventEmitter3 的监听事件方法。
*/
once<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void;
}
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
eventName |
V2NIMMessageListener |
是 | 事件名称:onReceiveCustomNotifications :自定义通知接收回调,返回自定义通知列表,包括本端接收的自定义通知及其他端同步的自定义通知。onReceiveBroadcastNotifications :服务端下发的广播通知接收回调,返回广播通知列表。 |
fn |
function | 是 | 监听事件的回调函数。当事件触发时,会调用该函数进行处理。 |
HarmonyOS
TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
/**
* 继承自 eventEmitter3 的监听事件方法
*/
on<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void
/**
* 继承自 eventEmitter3 的监听事件方法
*/
once<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void
}
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
eventName |
V2NIMMessageListener |
是 | 事件名称:onReceiveCustomNotifications :自定义通知接收回调,返回自定义通知列表,包括本端接收的自定义通知及其他端同步的自定义通知。onReceiveBroadcastNotifications :服务端下发的广播通知接收回调,返回广播通知列表。 |
fn |
function | 是 | 监听事件的回调函数。当事件触发时,会调用该函数进行处理。 |
示例代码
Web/uni-app/小程序
TypeScriptnim.V2NIMNotificationService.on("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
nim.V2NIMNotificationService.on("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
HarmonyOS
TypeScriptnim.messageService.on("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
nim.messageService.on("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
返回参数
无。
off("EventName")
接口描述
取消注册系统通知相关监听。
该方法为同步。
参数说明
Web/uni-app/小程序
TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
/**
* 继承自 eventEmitter3 的取消监听方法
*/
off<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void
/**
* 继承自 eventEmitter3 的移除事件方法
*/
removeAllListeners<T extends keyof I>(eventName?: T): void
}
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
eventName |
V2NIMMessageListener |
是 | 事件名称:onReceiveCustomNotifications :自定义通知接收回调,返回自定义通知列表,包括本端接收的自定义通知及其他端同步的自定义通知。onReceiveBroadcastNotifications :服务端下发的广播通知接收回调,返回广播通知列表。 |
fn |
function | 是 | 监听事件的回调函数。当事件触发时,会调用该函数进行处理。 |
HarmonyOS
TypeScriptexport interface NIMEBaseServiceInterface<I extends NIMEBaseListener> {
/**
* 继承自 eventEmitter3 的取消监听方法
*/
off<T extends keyof I>(eventName: T, fn: (...args: I[T]) => void): void
/**
* 继承自 eventEmitter3 的移除事件方法
*/
removeAllListeners<T extends keyof I>(eventName?: T): void
}
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
eventName |
V2NIMMessageListener |
是 | 事件名称:onReceiveCustomNotifications :自定义通知接收回调,返回自定义通知列表,包括本端接收的自定义通知及其他端同步的自定义通知。onReceiveBroadcastNotifications :服务端下发的广播通知接收回调,返回广播通知列表。 |
fn |
function | 是 | 监听事件的回调函数。当事件触发时,会调用该函数进行处理。 |
示例代码
Web/uni-app/小程序
TypeScriptnim.V2NIMNotificationService.off("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
nim.V2NIMNotificationService.off("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
HarmonyOS
TypeScriptnim.messageService.off("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
nim.messageService.off("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
返回参数
无。
sendCustomNotification
接口描述
发送一条自定义通知。
本端发送自定义通知成功后,其他登录客户端和通知接收方会收到自定义通知接收回调 onReceiveCustomNotifications
。
自定义通知仅适用于单聊和群聊场景。
参数说明
Android
Javavoid sendCustomNotification(String conversationId, String content, V2NIMSendCustomNotificationParams params, V2NIMSuccessCallback<Void> success, V2NIMFailureCallback failure);
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
conversationId |
String | 是 | 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。V2NIMConversationType )| 聊天对象账号(accountId)或群组 ID。 |
content |
String | 是 | 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。 |
params |
V2NIMSendCustomNotificationParams |
否 | 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。 |
success |
V2NIMSuccessCallback |
是 | 自定义通知发送成功回调 |
failure |
V2NIMFailureCallback |
是 | 自定义通知发送失败回调,返回 错误码。 |
iOS
Objective-C- (void)sendCustomNotification:(NSString *)converstaionId
content:(NSString *)content
params:(V2NIMSendCustomNotificationParams *)params
success:(V2NIMSuccessCallback)success
failure:(V2NIMFailureCallback)failure;
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
conversationId |
NSString * | 是 | 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。V2NIMConversationType )| 聊天对象账号(accountId)或群组 ID。 |
content |
NSString * | 是 | 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。 |
params |
V2NIMSendCustomNotificationParams |
否 | 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。 |
success |
V2NIMSuccessCallback |
是 | 自定义通知发送成功回调 |
failure |
V2NIMFailureCallback |
是 | 自定义通知发送失败回调,返回 错误码。 |
macOS/Windows
C++virtual void sendCustomNotification(nstd::string conversationId,
nstd::string content,
V2NIMSendCustomNotificationParams params,
V2NIMSuccessCallback<void> success,
V2NIMFailureCallback failure) = 0;
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
conversationId |
nstd::string | 是 | 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。V2NIMConversationType )| 聊天对象账号(accountId)或群组 ID。 |
content |
nstd::string | 是 | 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。 |
params |
V2NIMSendCustomNotificationParams |
否 | 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。 |
success |
V2NIMSuccessCallback |
是 | 自定义通知发送成功回调 |
failure |
V2NIMFailureCallback |
是 | 自定义通知发送失败回调,返回 错误码。 |
Web/uni-app/小程序
TypeScriptsendCustomNotification(conversationId: string, content: string, params?: V2NIMSendCustomNotificationParams): Promise<void>
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
conversationId |
string | 是 | 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。V2NIMConversationType )| 聊天对象账号(accountId)或群组 ID。 |
content |
string | 是 | 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。 |
params |
V2NIMSendCustomNotificationParams |
否 | 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。 |
HarmonyOS
TypeScriptsendCustomNotification(conversationId: string, content: string, params?: V2NIMSendCustomNotificationParams): Promise<void>
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
conversationId |
string | 是 | 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。V2NIMConversationType )| 聊天对象账号(accountId)或群组 ID。 |
content |
string | 是 | 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。 |
params |
V2NIMSendCustomNotificationParams |
否 | 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。 |
示例代码
Android
JavaV2NIMNotificationService v2NotificationService = NIMClient.getService(V2NIMNotificationService.class);
V2NIMNotificationAntispamConfig antispamConfig = V2NIMNotificationAntispamConfig.V2NIMNotificationAntispamConfigBuilder.builder()
// .withAntispamCustomNotification()
// .withAntispamEnabled()
.build();
V2NIMNotificationConfig config = V2NIMNotificationConfig.V2NIMNotificationConfigBuilder.builder()
// .withOfflineEnabled()
// .withUnreadEnabled()
.build();
V2NIMNotificationPushConfig pushConfig = V2NIMNotificationPushConfig.V2NIMNotificationPushConfigBuilder.builder()
// .withForcePush()
// .withForcePushAccountIds()
// .withForcePushContent()
// .withPushContent()
// .withPushEnabled()
// .withPushNickEnabled()
// .withPushPayload()
.build();
V2NIMNotificationRouteConfig routeConfig = V2NIMNotificationRouteConfig.V2NIMNotificationRouteConfigBuilder.builder()
// .withRouteEnabled()
// .withRouteEnvironment()
.build();
V2NIMSendCustomNotificationParams params = V2NIMSendCustomNotificationParams.V2NIMSendCustomNotificationParamsBuilder.builder()
// .withAntispamConfig(antispamConfig)
// .withNotificationConfig(config)
// .withPushConfig(pushConfig)
// .withRouteConfig(routeConfig)
.build();
v2NotificationService.sendCustomNotification("x|x|x", "xxx", params,
new V2NIMSuccessCallback<Void>() {
@Override
public void onSuccess(Void unused) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-CV2NIMSendCustomNotificationParams *notifyParams = [[V2NIMSendCustomNotificationParams alloc] init];
[[[NIMSDK sharedSDK] v2NotificationService] sendCustomNotification:@"conversationId"
content:@"custom notification"
params:notifyParams
success:^{
// success
}
failure:^(V2NIMError * _Nonnull error) {
// failed, handle error
}];
macOS/Windows
C++auto conversationId = V2NIMConversationIdUtil::p2pConversationId("target_account_id");
V2NIMSendCustomNotificationParams params;
notificationService.sendCustomNotification(
conversationId,
"hello world",
params,
[]() {
// send notification succeeded
},
[](V2NIMError error) {
// send notification failed
});
Web/uni-app/小程序
TypeScriptawait nim.V2NIMNotificationService.sendCustomNotification(
"me|1|another",
"content",
{
"notificationConfig": {},
"pushConfig": {},
"antispamConfig": {},
"routeConfig": {}
}
)
HarmonyOS
TypeScriptawait nim.notificationService.sendCustomNotification(
"me|1|another",
"content",
{
"notificationConfig": {},
"pushConfig": {},
"antispamConfig": {},
"routeConfig": {}
}
)
返回参数
Android/iOS/macOS/Windows
无返回值。
Web/uni-app/小程序/HarmonyOS
Promise<void>
相关回调
Android/iOS/macOS/Windows
- 请求成功,返回
V2NIMSuccessCallback
回调。 - 请求失败,返回
V2NIMFailuerCallback
回调,包含通知相关错误码。
Web/uni-app/小程序/HarmonyOS
无。
此文档是否对你有帮助?