Badges generally refer to the little numbered dots that show up on your mobile app icon and are meant to help capture a response from the user. However, they provide some additional behavior when it comes to notifications, especially on iOS as detailed in this doc.

Web Push badges are the small icon shown on android web notifications and can be customized.

Android badges

Starting with Android 8 you can control badges from showing with Android notification categories.

iOS badges

In order for badges to correctly increment when sending, you must setup the OneSignalNotificationServiceExtension and App Groups as directed in our Mobile SDK setup docs.

When users open your app, our SDK has a specific automatic badge management system that will both:

1. Remove badges on the App icon.
2. Remove notifications from the device's Notification Center.

If you prefer to prevent notifications from being removed and control badge counts yourself, you can disable our SDK's automatic clearing.

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.

This prevents OneSignal from automatically removing notifications and resetting badges when users interact with your app. Useful when implementing custom badge logic (e.g., maintaining separate counts for different types of notifications)

Send iOS push with badges

When using our Create message API, use the ios_badgeType and ios_badgeCount properties.

When sending Push via our Dashboard or Templates, under Platform Settings > Send to Apple iOS > Badges, use either Set to or Increase by and enter a number.

iOS native badge management

If you set OneSignal_disable_badge_clearing to YES in your info.plist this is how you can manage badges with Apple's APIs.

Note: 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:

import UserNotifications

UNUserNotificationCenter.current().setBadgeCount(5) { error in
    if let error = error {
        print("Failed to set badge count: \(error.localizedDescription)")
    } else {
        print("Badge count updated successfully.")
    }
}

Get current badge count

To retrieve the current badge count (e.g., to calculate a new value):

UNUserNotificationCenter.current().getBadgeCount { currentCount in
    print("Current badge count: \(currentCount)")
}

Increment or decrement badge

You must manage badge logic manually, as relative changes (like +1 or -1) are not supported in payloads:

UNUserNotificationCenter.current().getBadgeCount { currentCount in
    let updatedCount = max(0, currentCount + 1) // Or -1 for decrement
    UNUserNotificationCenter.current().setBadgeCount(updatedCount)
}

Clear badge

To remove the badge entirely:

UNUserNotificationCenter.current().setBadgeCount(0)

Common use cases

• Reset badge when the app launches or resumes
• Increment badge when a new notification is received in foreground
• Decrement when a notification is read or dismissed
• Sync badge state across devices or between app extensions via your server or App Groups