徽章是出现在您的移动应用图标上的小数字点。它们有助于吸引用户注意力并可以影响参与行为。特别是在 iOS 上，徽章需要额外的设置并提供灵活的控制，如下所述。
对于 Android Web 推送通知，徽章是指显示在通知上的小图标——而不是应用图标——并且可以自定义。请参阅 Web 推送徽章。
Android 徽章
Android 应用图标徽章行为可以通过 Android 通知类别 来管理。您可以控制某个类别（通道）是否显示徽章，并在每个类别的基础上设置徽章行为。
华为徽章
在华为设备上，徽章可以在应用图标上显示为数字或圆点，具体取决于用户的设备设置。徽章有助于指示未读消息或待处理操作，鼓励用户打开应用。OneSignal 允许您通过仪表板或 API 直接控制华为徽章计数。
华为徽章的工作原理
- 徽章在您的应用图标上显示为数字计数或圆点，具体取决于用户的设备级徽章显示设置（在设备的设置 > 通知 > 应用图标徽章中控制）。您的 API 调用控制底层计数；设备决定视觉样式。
huawei_badge_class 对于任何徽章操作都是必需的。这是您应用入口 Activity 的完全限定类名，格式为 <package_name>.<ActivityName>（例如，com.example.myapp.MainActivity）。它告诉华为系统将徽章应用于哪个应用图标。- 如果您在同一请求中同时设置
huawei_badge_set_num 和 huawei_badge_add_num，huawei_badge_set_num 优先。
- 如果既未提供
huawei_badge_set_num 也未提供 huawei_badge_add_num（但设置了 huawei_badge_class），徽章计数默认增加 1。
huawei_badge_set_num 接受 0 到 99 的值。将其设置为 0 可清除徽章。huawei_badge_add_num 接受 1 到 99 的值。例如，如果应用当前显示徽章为 5，您发送 huawei_badge_add_num: 3，徽章变为 8。
发送带徽章的华为推送
- 转到 消息 > 推送 或 模板
- 在 平台设置 > 发送到华为 Android > 徽章 下
- 选择以下任一选项：
- 不设置 — 此通知不影响徽章
- 设置为 — 将徽章设置为特定数字（0-99）
- 增加 — 增加现有徽章计数（1-99）
在 创建消息 API 中使用以下参数：
huawei_badge_class — （字符串，徽章必需） 应用启动器 Activity 的完全限定类名（例如，"com.example.myapp.MainActivity"）huawei_badge_set_num — （整数，0-99） 将徽章计数设置为此精确数字。设置为 0 可清除徽章。huawei_badge_add_num — （整数，1-99） 将现有徽章计数增加此数字。如果与 huawei_badge_set_num 一起省略，默认增加 1。
将徽章设置为特定数字：{
"huawei_badge_class": "com.example.myapp.MainActivity",
"huawei_badge_set_num": 5
}
{
"huawei_badge_class": "com.example.myapp.MainActivity",
"huawei_badge_add_num": 1
}
{
"huawei_badge_class": "com.example.myapp.MainActivity",
"huawei_badge_set_num": 0
}
清除徽章
华为不会在用户打开应用或点击通知时自动清除徽章。要清除徽章，您有两个选项：
- 通过 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 将：
- 在应用打开时清除应用图标徽章。
- 从通知中心移除通知。
如果您想保留通知并手动管理徽章逻辑（例如，使用您自己的计数器或在设备间同步状态），您可以禁用此自动行为。
手动徽章控制的常见用例
- 在应用启动或恢复时重置徽章
- 在前台接收通知时递增徽章
- 在消息被阅读或关闭时递减
- 通过应用组或您的后端在设备或应用扩展间同步徽章状态
禁用自动通知和徽章清除
在您的应用的 info.plist 中，添加键：OneSignal_disable_badge_clearing，布尔类型，值为 YES
<key>OneSignal_disable_badge_clearing</key>
<true/>
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
}
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")
// 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 设置徽章计数。
- 转到 消息 > 推送 或 模板
- 在 平台设置 > 发送到 Apple iOS > 徽章 下
- 选择任一选项：
在 创建消息 API 中使用以下参数：
ios_badgeType - 设置为 SetTo 或 Increaseios_badgeCount - 要设置或增加的数字
{
"ios_badgeType": "Increase",
"ios_badgeCount": 1
}
