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.

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 Push with Badges - iOS

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.

Android Badges

The OneSignal SDK automatically sets the badge count on your app to the number of notifications that are currently in the notification shade. If you want to disable this you can do the following...

For Android 8+ you can turn off the badges from showing using Notification Categories. The notification dot was added in Android Oreo (8.0) but a badge number may still be showing instead if the device is using an Android Launcher that uses the non-standardized badge number.

Pre Android 8 will need to follow this guide below and set the badges manually.

Disable Badges for Pre Android 8 Devices

This guide is only for Android 7 and lower. If you only want to support Android 8+ use Notification Categories.

Add the following to your AndroidManifest.xml

<application ...>
   <meta-data android:name="com.onesignal.BadgeCount" android:value="DISABLE" />
</application>

You can remove the badge permissions with the following entries.

<uses-permission android:name="com.sec.android.provider.badge.permission.READ" tools:node="remove" />
<uses-permission android:name="com.sec.android.provider.badge.permission.WRITE" tools:node="remove" />
<uses-permission android:name="com.htc.launcher.permission.READ_SETTINGS" tools:node="remove" />
<uses-permission android:name="com.htc.launcher.permission.UPDATE_SHORTCUT" tools:node="remove" />
<uses-permission android:name="com.sonyericsson.home.permission.BROADCAST_BADGE" tools:node="remove" />
<uses-permission android:name="com.sonymobile.home.permission.PROVIDER_INSERT_BADGE" tools:node="remove" />
<uses-permission android:name="com.anddoes.launcher.permission.UPDATE_COUNT" tools:node="remove" />
<uses-permission android:name="com.majeur.launcher.permission.UPDATE_BADGE" tools:node="remove" />
<uses-permission android:name="com.huawei.android.launcher.permission.CHANGE_BADGE" tools:node="remove"/>
<uses-permission android:name="com.huawei.android.launcher.permission.READ_SETTINGS" tools:node="remove" />
<uses-permission android:name="com.huawei.android.launcher.permission.WRITE_SETTINGS" tools:node="remove" />
<uses-permission android:name="android.permission.READ_APP_BADGE" tools:node="remove" />
<uses-permission android:name="com.oppo.launcher.permission.READ_SETTINGS" tools:node="remove" />
<uses-permission android:name="com.oppo.launcher.permission.WRITE_SETTINGS" tools:node="remove" />

You will also need to add the the following to your manifest tag at the top of the file.
xmlns:tools="http://schemas.android.com/tools"

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools"
          package="com.onesignal.example">
          ...
</manifest>

You can now set badges manually with a library like https://github.com/leolin310148/ShortcutBadger

🚧

Android Launcher Limitations

Note: Android badges are only supported by our latest SDK and only on the following Android Launchers: Sony, Samsung, LG, HTC, Xiaomi, Huawei, ASUS, ZUK, OPPO, ADW, APEX, and NOVA. More details here.