跳转到主要内容
徽章是出现在您的移动应用图标上的小数字点。它们有助于吸引用户注意力并可以影响参与行为。特别是在 iOS 上，徽章需要额外的设置并提供灵活的控制，如下所述。
对于 Android Web 推送通知，徽章是指显示在通知上的小图标——而不是应用图标——并且可以自定义。请参阅 Web 推送徽章。

​
Android 徽章

Android 应用图标徽章行为可以通过 Android 通知类别 来管理。您可以控制某个类别（通道）是否显示徽章，并在每个类别的基础上设置徽章行为。

​
华为徽章

在华为设备上，徽章可以在应用图标上显示为数字或圆点，具体取决于用户的设备设置。徽章有助于指示未读消息或待处理操作，鼓励用户打开应用。OneSignal 允许您通过仪表板或 API 直接控制华为徽章计数。

​
华为徽章的工作原理

徽章在应用图标上显示为数字计数或圆点，具体取决于用户的设备设置（设置 > 通知 > 应用图标徽章）。您的 API 调用控制底层计数；设备决定视觉样式。

​
参数

参数类型范围描述
huawei_badge_classstring—（必需） 您应用启动器 Activity 的完全限定类名（例如，com.example.myapp.MainActivity）。告知华为系统要显示徽章的应用图标。
huawei_badge_set_numinteger0–99将徽章设置为精确数字。0 清除徽章。
huawei_badge_add_numinteger1–99将现有徽章计数增加此数量。

​
行为规则

  • huawei_badge_class 对于任何徽章操作都是必需的。
  • 如果同时提供 huawei_badge_set_num 和 huawei_badge_add_num，huawei_badge_set_num 优先。
  • 如果两者都未提供（但已设置 huawei_badge_class），徽章计数默认增加 1。

​
发送带徽章的华为推送

  1. 转到 消息 > 推送 或 模板
  2. 在 平台设置 > 发送到华为 Android > 徽章 下
  3. 选择以下任一选项：
    • 不设置 — 此通知不影响徽章
    • 设置为 — 将徽章设置为特定数字（0-99）
    • 增加 — 增加现有徽章计数（1-99）

​
清除徽章

华为不会在用户打开应用或点击通知时自动清除徽章。要清除徽章，您有两个选项：
  • 通过 API 或仪表板：发送 huawei_badge_set_num 设置为 0 的通知（或在仪表板中使用 设置为 > 0）。如果您不想显示可见通知，可以使用数据/后台通知。
  • 通过客户端代码：您的应用可以使用华为徽章 API 在本地清除徽章。这需要在您的 AndroidManifest.xml 中添加 com.huawei.android.launcher.permission.CHANGE_BADGE 权限。有关实现详情，请参阅华为徽章开发指南。
huawei_badge_set_num 参数需要 EMUI 10.0.0 或更高版本以及 Push SDK 10.1.0 或更高版本。在较旧的设备上，仅支持 huawei_badge_add_num。

​
iOS 徽章

要确保徽章计数在 iOS 上正确递增，您必须配置：
  • OneSignalNotificationServiceExtension
  • 应用组（App Groups）
请参阅 移动 SDK 设置 获取完整说明。 默认情况下，OneSignal SDK 将：
  1. 在应用打开时清除应用图标徽章。
  2. 从通知中心移除通知。
如果您想保留通知并手动管理徽章逻辑（例如，使用您自己的计数器或在设备间同步状态），您可以禁用此自动行为。 手动徽章控制的常见用例
  • 在应用启动或恢复时重置徽章
  • 在前台接收通知时递增徽章
  • 在消息被阅读或关闭时递减
  • 通过应用组或您的后端在设备或应用扩展间同步徽章状态

​
禁用自动通知和徽章清除

在您的应用的 info.plist 中，添加键：OneSignal_disable_badge_clearing，布尔类型，值为 YES
Xcode Info.plist editor showing OneSignal_disable_badge_clearing set to YES
<key>OneSignal_disable_badge_clearing</key>
<true/>
这可以防止 SDK 在应用打开时自动移除通知或重置徽章。

​
iOS 原生徽章管理

如果您禁用 OneSignal 的自动徽章清除，您可以使用 Apple 的原生 API 来控制徽章行为。
Apple 在 iOS 17 中弃用了 UIApplication.shared.applicationIconBadgeNumber。您现在应该使用来自 UserNotifications 框架 的以下方法：
设置徽章计数 要将应用图标上的徽章设置为特定值： 
import UserNotifications
import UIKit

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(5) { error in
    if let error = error {
      print("Failed to set badge count: \(error.localizedDescription)")
    } else {
      print("Badge count updated successfully.")
    }
  }
} else {
  UIApplication.shared.applicationIconBadgeNumber = 5
}
获取当前徽章计数 iOS 不提供从系统检索当前徽章计数的方法。您必须在应用的状态中跟踪徽章计数（例如，使用 UserDefaults、应用的数据模型或与后端同步）。 
// Example: Store and retrieve badge count using UserDefaults
let badgeCount = UserDefaults.standard.integer(forKey: "badgeCount")
// Update badge count as needed
UserDefaults.standard.set(badgeCount, forKey: "badgeCount")
递增或递减徽章 您必须手动管理徽章逻辑，因为载荷中不支持相对变化（如 +1 或 -1）。更新您存储的徽章计数然后设置它： 
// Example: Increment badge count and update system badge
let currentCount = UserDefaults.standard.integer(forKey: "badgeCount")
let updatedCount = max(0, currentCount + 1)
UserDefaults.standard.set(updatedCount, forKey: "badgeCount")

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(updatedCount)
} else {
  UIApplication.shared.applicationIconBadgeNumber = updatedCount
}
清除徽章 要完全移除徽章： 
if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(0)
} else {
  UIApplication.shared.applicationIconBadgeNumber = 0
}

​
发送带有徽章的 iOS 推送

您可以在 OneSignal 控制面板中或使用 API 设置徽章计数。
  1. 转到 消息 > 推送 或 模板。
  2. 在 平台设置 > 发送到 Apple iOS > 徽章 下。
  3. 选择任一选项：
    • 设置为特定数字。
    • 按相对数量增加。
OneSignal dashboard push message form showing iOS badge count options
发送 iOS 推送通知时，徽章计数会根据这些选项进行更改。 如果应用是打开的，除非您禁用自动徽章清除，否则徽章计数将重置。

​
常见问题

​
为什么 iOS 上的徽章计数没有递增？

确保您已配置 OneSignalNotificationServiceExtension 和应用组（App Groups）。没有这些，徽章计数无法正确递增。请参阅 移动 SDK 设置 获取完整说明。

​
如何清除华为上的徽章？

发送 huawei_badge_set_num 设置为 0 的通知，或在仪表板中使用 设置为 > 0。您也可以使用数据/后台通知在不显示可见通知的情况下清除徽章。或者，使用华为徽章 API 在客户端清除徽章。

​
我可以为 Web 推送设置徽章吗？

不可以。应用图标徽章仅在 iOS、Android 和华为上受支持。对于 Android Web 推送，“徽章”是指通知本身上显示的小图标——请参阅 Web 推送徽章。

​
相关页面

Android 通知类别

在 Android 上按通知渠道控制徽章显示和行为。

华为授权

使用 OneSignal 设置华为推送消息。

推送概述

推送通知功能的完整参考，包括 Web 推送徽章。

移动 SDK 设置

配置 OneSignal SDK，包括 iOS 的徽章先决条件。