自定义系统通知收发

更新时间: 2024/04/17 15:00:36

本文介绍通过 NetEase IM SDK(以下简称 NIM SDK) 实现自定义系统通知的技术原理、实现流程。

技术原理

自定义系统通知仅适用于单聊和群聊场景,由开发者根据其具体业务场景自行定义并下发,SDK 仅负责透传,不负责解析和存储。

发送自定义通知不支持重试机制,开发者需要自行实现重试。若 2 分钟内未收到服务器的 ACK,SDK 则上报发送失败。

前提条件

初始化 SDK

实现流程

uml diagram
  1. 通知接收方监听自定义系统通知接收回调。

    注册系统通知监听器的自定义通知接收事件 onReceiveCustomNotifications

    Android

    若自定义的系统通知需要作用于全局,不依赖某个特定的 Activity,那么需要提前在 Application 的 onCreate 中调用该监听接口。

    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);
    
    Web/uni-app/小程序
    typescript// 自定义通知接收回调
    nim.V2NIMMessageService.on("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
    nim.V2NIMMessageService.on("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
    
    Harmony
    typescript// 自定义通知接收回调
    nim.messageService.on("onReceiveCustomNotifications", function (customNotification: V2NIMCustomNotification[]) {})
    nim.messageService.on("onReceiveBroadcastNotifications", function (broadcastNotification: V2NIMBroadcastNotification[]) {})
    
  2. (可选)通知发送方配置自定义系统通知扩展信息 V2NIMSendCustomNotificationParams

    参数名称 类型 是否只读 描述
    notificationConfig V2NIMNotificationConfig 通知相关配置
    pushConfig V2NIMNotificationPushConfig 第三方推送相关配置。
    第三方推送功能需要在云信控制台配置
    antispamConfig V2NIMNotificationAntispamConfig 反垃圾相关配置。
    反垃圾功能包括客户端反垃圾和安全通,均需要在云信控制台开通
    routeConfig V2NIMNotificationRouteConfig 系统通知事件抄送相关配置。
    消息抄送功能需要在云信控制台开通
  3. 通知发送方调用 sendCustomNotification 方法发送自定义系统通知。 指定具体会话 ID,构建自定义通知的具体内容。为了可扩展性,必须采用 JSON 格式。

    一秒内默认最多调用该接口 100 次。如需上调上限,请联系技术支持。

  • 参数说明:
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 V2NIMFailuerCallback - 自定义通知发送失败回调,返回错误码
    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 V2NIMFailuerCallback - 自定义通知发送失败回调,返回错误码
    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 V2NIMFailuerCallback - 自定义通知发送失败回调,返回错误码
    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": {}
      }
    )
    
    1. SDK 触发 onReceiveCustomNotifications 回调事件,通知接收方接收自定义系统通知。

    相关信息

    此文档是否对你有帮助?
    有帮助
    去反馈
    • 技术原理
    • 前提条件
    • 实现流程
    • 相关信息