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.

​
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

Example info.plist with ` OneSignal_disable_badge_clearing` turned off (set to `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

Set badges in the OneSignal dashboard message form.

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: