即时通信 IM 自定义角标

一、功能概述

效果示例

二、厂商通道支持说明

由于不同手机操作系统的限制，并非所有厂商通道都支持自定义角标。具体支持情况如下表：

三、配置说明

完成下表所列厂商的配置后，应用角标会自动与 IM 未读消息总数关联，无需客户额外开发。具体行为如下：

·基准角标：App 进入后台或进程退出时 IMSDK 会将当前 IM 未读消息总数同步为应用角标，作为本次的 "基准角标"。

·增量更新：App 处于后台 / 进程不在时每收到一条新的离线推送，角标在基准角标的基础上 +1 逐条递增，确保用户即使未打开 App 也能感知新消息数量。

·自定义场景：若业务侧已通过接口设置了自定义角标值，则以自定义值作为基准角标，叠加规则不变。

AndroidiOSFlutteruni-appReact Native微信小程序多端框架

四、支持厂商

华为、荣耀。

五、配置方法

控制台配置华为角标参数为应用的启动类，例如 “com.tencent.qcloud.tim.demo.SplashActivity”。完成配置后，组件会自动解析并更新角标；若未配置，角标不会更新。

六、支持厂商

APNs。

七、自定义角标步骤

如果想自定义角标，可按照如下步骤设置：

1. App 调用 – (void)setAPNSListener:(id<V2TIMAPNSListener>)apnsListener 接口设置监听。

2. App 实现 – (uint32_t)onSetAPPUnreadCount 接口，在内部计算并返回你需要的角标总数。

OCSwift// 1. 设置监听- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // 监听推送 [V2TIMManager.sharedInstance setAPNSListener:self]; // 监听会话的未读数 [[V2TIMManager sharedInstance] setConversationListener:self]; return YES;}// 2. 未读数发生变化后保存未读数- (void)onTotalUnreadMessageCountChanged:(UInt64)totalUnreadCount { self.unreadNumber = totalUnreadCount;}// 3. App 推到后台后上报自定义未读数/** 程序进后台后，自定义 App 的未读数，如果不处理，App 未读数默认为所有会话未读数之和 * <pre> * * – (uint32_t)onSetAPPUnreadCount { * return 100; // 自定义未读数 * } * * </pre> */- (uint32_t)onSetAPPUnreadCount { // 1. 获取自定义的角标 uint32_t customBadgeNumber = … // 2. 加上 IM 的消息未读数 customBadgeNumber += self.unreadNumber; // 3. 通过 IMSDK 上报给 IM 服务器 return customBadgeNumber;}import ImSDK_Plusclass AppDelegate: UIResponder, UIApplicationDelegate, V2TIMAPNSListener, V2TIMConversationListener { // 存储未读数 var unreadNumber: UInt64 = 0 // 1. 设置监听 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // 监听推送 V2TIMManager.sharedInstance()?.setAPNSListener(self) // 监听会话的未读数 V2TIMManager.sharedInstance()?.setConversationListener(self) return true } // 2. 未读数发生变化后保存未读数 func onTotalUnreadMessageCountChanged(_ totalUnreadCount: UInt64) { self.unreadNumber = totalUnreadCount } // 3. App 推到后台后上报自定义未读数 /// 程序进后台后，自定义 App 的未读数，如果不处理，App 未读数默认为所有会话未读数之和 /// – Returns: 自定义未读数 func onSetAPPUnreadCount() -> UInt32 { // 1. 获取自定义的角标 var customBadgeNumber: UInt32 = 0 // … 替换为你的自定义逻辑 // 2. 加上 IM 的消息未读数 customBadgeNumber += UInt32(self.unreadNumber) // 3. 通过 IMSDK 上报给 IM 服务器 return customBadgeNumber }}

Flutter 版本的 IM SDK 提供了与原生同名的方法，调用方式与原生一致。请分别参考上文的 iOS 原生和 Android 原生章节进行配置。

八、支持厂商

华为。

九、步骤1. 控制台配置华为角标参数为应用的启动类。

注意：说明：

注意：uniapp 应用的启动类为 io.dcloud.PandoraEntry。

十、步骤2. 监听 Chat SDK 未读总数变化自行设置角标数量。

1. 通过 TOTAL_UNREAD_MESSAGE_COUNT_UPDATED 监听 Chat SDK 会话未读总数更新。

2. 通过 plus.runtime.setBadgeNumber 设置角标数量。

let onTotalUnreadMessageCountUpdated = function(event) { const unreadCount = event.data; // 当前会话的未读总数 plus.runtime.setBadgeNumber(unreadCount); // 设置角标数量};chat.on(TencentCloudChat.EVENT.TOTAL_UNREAD_MESSAGE_COUNT_UPDATED, onTotalUnreadMessageCountUpdated);

十一、支持厂商

华为。

十二、获取应用启动类

从 MyReactNativeApp/android/app/src/main/AndroidManifest.xml 中获取启动类名。如下：

注意：说明：

注意：应用的启动类 = “包名” + 启动类名。

十三、配置方法

控制台配置华为角标参数为应用的启动类，例如 “com.tencent.qcloud.tim.demo.MainActivity ”。组件会自动解析和更新角标，反之不会更新角标。

十四、支持厂商：

华为、iOS。

十五、自定义角标步骤：

1. 调用 registerPush 注册推送服务。

2. 监听业务角标的变化，将变化数通过接口 setCustomBadgeNumber 同步给 Push。

3. 应用退后台或者离线后，Push 会根据离线消息自动更新角标数。

4. 再次打开应用回到前台，业务也可以继续通过该接口清理或者更新角标数。

注意：1. 每次打开应用回到前台，都应该设置自定义角标，否则在 iOS 设备上，角标数会在之前自定义的基础上加 1 。

注意：2. 在华为设备上实现角标功能时，需要在 IM 控制台额外配置角标参数。该参数需指定应用的主入口 Activity 类路径，格式为：[应用包名].ui.MainActivity。以包名 com.tencent.weauth 为例，对应的角标参数应配置为：com.tencent.weauth.ui.MainActivity。

注意：