系统通知

更新时间: 2024/04/18 18:11:00

系统通知指系统下发的通知,不属于会话内消息,例如单聊场景中的“对方正在输入”功能,及群聊场景中的入群申请、入群邀请等。系统通知包括广播通知和自定义系统通知两种类型。

本文介绍自定义系统通知收发相关 API。更多系统通知相关功能请参考开发指南文档系统通知概述

支持平台

Android iOS macOS/Windows Web/uni-app/小程序 Harmony

API 概览

系统通知监听

Android/iOS/macOS/Windows
API 描述 起始版本
addNoticationListener 注册系统通知相关监听器 v10.2.0
removeNotificationListener 移除系统通知相关监听器 v10.2.0
Web/uni-app/小程序/Harmony
API 描述 起始版本
on("EventName") 注册系统通知相关监听 v10.2.0(对应 Harmony v0.5.0)
off("EventName") 取消注册系统通知相关监听 v10.2.0(对应 Harmony v0.5.0)

系统通知发送

API 描述 起始版本
sendCustomNotification 发送自定义系统通知 v10.2.0(对应 Harmony 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
cppvirtual 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
cppV2NIMNotificationListener 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
cppvirtual 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
cppnim.V2NIMMessageService.off("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
nim.V2NIMMessageService.off("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})

返回值

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 - 监听事件的回调函数。当事件触发时,会调用该函数进行处理。
    Harmony
    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.V2NIMMessageService.on("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
    nim.V2NIMMessageService.on("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
    
    Harmony
    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 - 监听事件的回调函数。当事件触发时,会调用该函数进行处理。
    Harmony
    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.V2NIMMessageService.off("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
    nim.V2NIMMessageService.off("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
    
    Harmony
    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 的对应函数创建。
  • 组成方式:用户账号(accountId)|会话类型(V2NIMConversationType)|聊天对象账号(accountId)或群组 ID。
  • 如果为空或不存在则返回 191004 参数错误。
  • content String - 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。
    params V2NIMSendCustomNotificationParams null 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    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 的对应函数创建。
  • 组成方式:用户账号(accountId)|会话类型(V2NIMConversationType)|聊天对象账号(accountId)或群组 ID。
  • 如果为空或不存在则返回 191004 参数错误。
  • content NSString * - 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。
    params V2NIMSendCustomNotificationParams null 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    success V2NIMSuccessCallback - 自定义通知发送成功回调
    failure V2NIMFailureCallback - 自定义通知发送失败回调,返回错误码
    macOS/Windows
    cppvirtual void sendCustomNotification(nstd::string conversationId,
        nstd::string content,
        V2NIMSendCustomNotificationParams params,
        V2NIMSuccessCallback<void> success,
        V2NIMFailureCallback failure) = 0;
    
    参数名称 类型 是否必填 默认值 描述
    conversationId nstd::string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(accountId)|会话类型(V2NIMConversationType)|聊天对象账号(accountId)或群组 ID。
  • 如果为空或不存在则返回 191004 参数错误。
  • content nstd::string - 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。
    params V2NIMSendCustomNotificationParams null 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    success V2NIMSuccessCallback - 自定义通知发送成功回调
    failure V2NIMFailureCallback - 自定义通知发送失败回调,返回错误码
    Web/uni-app/小程序
    typescriptsendCustomNotification(conversationId: string, content: string, params?: V2NIMSendCustomNotificationParams): Promise<void>
    
    参数名称 类型 是否必填 默认值 描述
    conversationId string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(accountId)|会话类型(V2NIMConversationType)|聊天对象账号(accountId)或群组 ID。
  • 如果为空或不存在则返回 191004 参数错误。
  • content string - 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。
    params V2NIMSendCustomNotificationParams null 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    Harmony
    typescriptsendCustomNotification(conversationId: string, content: string, params?: V2NIMSendCustomNotificationParams): Promise<void>
    
    参数名称 类型 是否必填 默认值 描述
    conversationId string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
  • 组成方式:用户账号(accountId)|会话类型(V2NIMConversationType)|聊天对象账号(accountId)或群组 ID。
  • 如果为空或不存在则返回 191004 参数错误。
  • content string - 自定义通知内容。必须封装为 JSON 格式,长度上限为 4096 字节。
    params V2NIMSendCustomNotificationParams null 自定义通知发送配置参数,包括发送、推送、抄送、反垃圾等配置。

    示例代码

    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
    cppauto 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": {}
      }
    )
    
    Harmony
    typescriptawait nim.notificationService.sendCustomNotification(
      "me|1|another",
      "content",
      {
        "notificationConfig": {},
        "pushConfig": {},
        "antispamConfig": {},
        "routeConfig": {}
      }
    )
    

    返回值

    Android/iOS/macOS/Windows

    无返回值

    Web/uni-app/小程序/Harmony

    Promise<void>

    相关回调

    Android/iOS/macOS/Windows
    • 请求成功,返回 V2NIMSuccessCallback 回调。
    • 请求失败,返回 V2NIMFailuerCallback 回调,包含通知相关错误码。
    Web/uni-app/小程序/Harmony

    此文档是否对你有帮助?
    有帮助
    去反馈
    • 支持平台
    • API 概览
    • 系统通知监听
    • 系统通知发送
    • 接口类
    • addNoticationListener
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • removeNotificationListener
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • on("EventName")
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • off("EventName")
    • 支持平台
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • sendCustomNotification
    • 接口描述
    • 参数说明
    • 示例代码
    • 返回值
    • 相关回调