Skip to main content
Badges are the little numbered dots that appear on your mobile app icon. They help capture user attention and can influence engagement behavior. On iOS in particular, badges require additional setup and offer flexible control, as outlined below.
For Android Web Push notifications, the badge refers to the small icon shown on notifications—not the app icon—and can be customized. See Web Push Badges.

​
Android badges

Android app icon badge behavior can be managed through Android notification categories. You can control whether a category (channel) displays a badge and set badge behavior on a per-category basis.

​
Huawei badges

On Huawei devices, a badge can be displayed as a number or a dot on the app icon, depending on the user’s device settings. Badges help indicate unread messages or pending actions, encouraging users to open the app. OneSignal lets you control Huawei badge counts directly through the dashboard or API.

​
How Huawei badges work

  • The badge displays on your app icon as either a numeric count or a dot, depending on the user’s device-level badge display setting (controlled in the device’s Settings > Notifications > App icon badges). Your API call controls the underlying count; the device decides the visual style.
  • huawei_badge_class is required for any badge operation. This is the fully qualified class name of your app’s entry Activity in the format <package_name>.<ActivityName> (e.g., com.example.myapp.MainActivity). It tells the Huawei system which app icon to apply the badge to.
  • If you set both huawei_badge_set_num and huawei_badge_add_num in the same request, huawei_badge_set_num takes priority.
  • If neither huawei_badge_set_num nor huawei_badge_add_num is provided (but huawei_badge_class is set), the badge count increments by 1 by default.
  • huawei_badge_set_num accepts values from 0 to 99. Setting it to 0 clears the badge.
  • huawei_badge_add_num accepts values from 1 to 99. For example, if the app currently shows a badge of 5 and you send huawei_badge_add_num: 3, the badge becomes 8.

​
Send Huawei push with badges

  1. Go to Messages > Push or Templates
  2. Under Platform Settings > Send to Huawei Android > Badge
  3. Choose either:
    • Don’t set — badge is not affected by this notification
    • Set to — sets the badge to a specific number (0–99)
    • Increase by — increments the existing badge count (1–99)

​
Clearing badges

Huawei does not automatically clear the badge when a user opens the app or taps a notification. To clear the badge, you have two options:
  • Via the API or dashboard: Send a notification with huawei_badge_set_num set to 0 (or use Set to > 0 in the dashboard). This can be a data/background notification if you don’t want a visible notification to appear.
  • Via client-side code: Your app can clear the badge locally using the Huawei badge API. This requires the com.huawei.android.launcher.permission.CHANGE_BADGE permission in your AndroidManifest.xml. See Huawei’s badge development guide for implementation details.
The huawei_badge_set_num parameter requires EMUI 10.0.0 or later and Push SDK 10.1.0 or later. On older devices, only huawei_badge_add_num is supported.

​
iOS badges

To ensure badge counts increment correctly on iOS, you must configure:
  • The OneSignalNotificationServiceExtension
  • App Groups
See Mobile SDK setup for full instructions. By default, the OneSignal SDK will:
  1. Clear the app icon badge when the app is opened.
  2. Remove notifications from the Notification Center.
If you want to retain notifications and manage badge logic manually (e.g., using your own counter or syncing state across devices), you can disable this automatic behavior. Common use cases for manual badge control
  • Reset badge when the app launches or resumes
  • Increment badge when a notification is received in the foreground
  • Decrement when a message is read or dismissed
  • Sync badge state across devices or app extensions via App Groups or your backend

​
Disable automatic notification and badge clearing

In your app’s info.plist, add the Key: OneSignal_disable_badge_clearing with Boolean type to Value YES 
<key>OneSignal_disable_badge_clearing</key>
<true/>
This prevents the SDK from automatically removing notifications or resetting the badge when the app opens.

​
iOS native badge management

If you disable OneSignal’s automatic badge clearing, you can use Apple’s native APIs to control badge behavior.
Apple deprecated UIApplication.shared.applicationIconBadgeNumber in iOS 17. You should now use the following methods from the UserNotifications framework:
Set badge count To set the badge on the app icon to a specific value:
Swift
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
}
Get current badge count iOS does not provide a method to retrieve the current badge count from the system. You must keep track of the badge count in your app’s state (for example, using UserDefaults, your app’s data model, or syncing with your backend).
Swift
// 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")
Increment or decrement badge You must manage badge logic manually, as relative changes (like +1 or -1) are not supported in payloads. Update your stored badge count and then set it:
Swift
// 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
}
Clear badge To remove the badge entirely:
Swift

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(0)
} else {
  UIApplication.shared.applicationIconBadgeNumber = 0
}

​
Send iOS push with badges

You can set the badge count in the OneSignal dashboard or using the API.
  1. Go to Messages > Push or Templates
  2. Under Platform Settings > Send to Apple iOS > Badges
  3. Choose either:
    • Set to a specific number
    • Increase by a relative amount
When sending iOS push notifications, the badge count will change based on these options. If the app is open, the badge count will reset unless you followed the instructions above to disable automatic badge clearing.
Badges tutorial complete! Next steps: