In this document
Android O introduces functionality for displaying notification badges on app icons in supported launchers. Notification badges show notifications associated with one or more notification channels in an app, which the user has not yet dismissed or acted on. Notification badges are also known as notification dots. Users can turn off badges for notification channels or apps from the Settings app.
Users can also long-press on an app icon to glance at the notifications associated with a notification badge in supported launchers. Users can then dismiss or act on notifications from the long-press menu in a similar way to the notification drawer.
Note: To learn how to implement notification channels, see the Notification Channels guide.
By default, each new notification in a channel increments the number displayed on the associated launcher long-press menu by one. After a user dismisses a notification or triggers a related action, that number decrements to reflect the change. You can override the count displayed in the long-press menu as a result of a notification. For example, you can set the value for the number of incoming messages to display in a long-press menu when creating a notification for a messaging app. To learn how to override the count displayed in the long-press menu, see Adjusting notification badges.
A folder's notification badge indicates the presence of notification badges for one or more of the apps inside the folder.
Caution: Don't badge every notification, as there are cases where badges don't make sense. Consider the following examples when planning to create notifications in a notification channel for your app:
- Ongoing notifications: Most ongoing notifications, such as image processing, media playback controls, or current navigation instructions, don't make sense as a badge.
- Calendaring apps: Avoid badging events occurring at the current time.
- Clock or alarm apps: Avoid badging notifications related to current alarms.
Note: If you don't target Android O, your app displays a badge to indicate the presence of any notifications posted by your app.
Adjusting notification badges
By default, each notification channel reflects its active notifications in
your app's launcher icon badge. You can use the
setShowBadge() method to
stop the presence of notifications from a channel being reflected by a badge.
You can't programmatically modify this setting for a notification channel after
it's created and submitted to the notification manager.
Note: Users can turn off badges for notification channels or apps from the Settings app at any time.
The following sample code illustrates how to hide badges in association with notifications from a notification channel:
NotificationManager mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); // The ID of the channel. String id = "my_channel_01"; // The user visible name of the channel. CharSequence name = getString(R.string.channel_name); // The user visible description of the channel. String description = getString(R.string.channel_description); int importance = NotificationManager.IMPORTANCE_LOW; NotificationChannel mChannel = new NotificationChannel(id, name, importance); // Configure the notification channel. mChannel.setDescription(description); mChannel.setShowBadge(false); mNotificationManager.createNotificationChannel(mChannel);
You can call
Notification.Builder.setNumber() to set a custom number to display in the
long-press menu of an app in supported launchers, as illustrated by the
following sample code for a messaging app:
mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); int notificationID = 1; String CHANNEL_ID = "my_channel_01"; // Set a message count to associate with this notification in the long-press menu. int messageCount = 3; // Create a notification and set a number to associate with it. Notification notification = new Notification.Builder(MainActivity.this) .setContentTitle("New Messages") .setContentText("You've received 3 new messages.") .setSmallIcon(R.drawable.ic_notify_status) .setChannelId(CHANNEL_ID) .setNumber(messageCount) .build(); // Issue the notification. mNotificationManager.notify(notificationID, notification);
The long-press menu displays the large or small icon associated with a
notification if available. By default, the system displays the large icon,
but you can call
Notification.Builder.setBadgeIconType() and pass in the
to display the small icon.
If your app creates a notification that duplicates a shortcut, you can
temporarily hide the shortcut while the notification is active. To hide a
shortcut while a notification is active, call
and pass the ID of the shortcut. For more information on shortcuts, see