A notification is a message that android displays outside of your app’s user interface to provide the user with reminders, communications from other people, or other timely information from your app. users can tap the notification to open your app or perform an action directly from the notification.
This page provides an overview of where notifications appear and the features available. if you want to start creating your notifications, read create a notification.
For more information on design and interaction patterns, see the notification design guide.
appearances on a device
Notifications appear to users in different locations and formats, such as an icon in the status bar, a more detailed entry in the notification drawer, as a badge on the app icon, and on automatically paired wearables.
status bar and notification drawer
When you issue a notification, it first appears as an icon in the status bar.
figure 1. notification icons appear on the left side of the status bar
Users can slide down the status bar to open the notification drawer, where they can see more details and take action on the notification.
figure 2. notifications in the notification drawer
Users can drag a notification down in the drawer to reveal the expanded view, which displays additional content and action buttons, if provided. As of android 13, this extended view includes a button that allows users to stop an app that has foreground services in progress.
a notification remains visible in the notification drawer until the app or user dismisses it.
warning notification
As of android 5.0, notifications may briefly appear in a floating window called a warning notification. this behavior is typically for important notifications that the user should know about right away, and appears only if the device is unlocked.
figure 3. a notification appears in front of the application in the foreground
the notification popup appears the moment your app issues the notification and disappears after a moment, but remains visible in the notification drawer as usual.
Example conditions that could trigger pop-up notifications include the following:
- user activity is in full screen mode (app uses full screen intent).
- notification has high priority and uses ringtones or vibrations on devices running android 7.1 (api level 25) and earlier.
- The notification channel is of great importance on devices running android 8.0 (api level 26) and higher.
lock screen
As of android 5.0, notifications can appear on the lock screen.
You can programmatically set the level of detail visible in notifications posted by your app on a secure lock screen, or even whether the notification will be displayed on the lock screen.
Users can use system settings to choose the level of detail visible in lock screen notifications, including the option to turn off all lock screen notifications. As of Android 8.0, users can choose to enable or disable lock screen notifications for each notification channel.
figure 4. lock screen notifications with hidden sensitive content
For more information, see how to set lock screen visibility.
app icon badge
In supported launchers on devices running android 8.0 (api level 26) and higher, app icons indicate new notifications with a colored “badge” (also known as a “notification dot”) on the app icon. corresponding application launcher.
Users can long press an app icon to view notifications from that app. users can dismiss or act on notifications from that menu, similar to the notification drawer.
figure 5. notification badges and the long press menu
To learn more about how badges work, read notification badges.
use os devices
if the user has a paired wear os device, all of their notifications appear there automatically, including action buttons and expandable details.
You can also enhance the experience by customizing some appearances for the notification on portable devices and providing different actions, including suggested replies and voice input replies. For more information, see how to add portable device-specific features to your notification.
figure 6. notifications appear automatically on a paired wear os device
notification anatomy
The layout of a notification is determined by system templates: your application simply defines the content of each part of the template. some notification details only appear in the expanded view.
figure 7. a notification with basic details
The most common parts of a notification are indicated in Figure 7 as follows:
- small icon: Required and set with setsmallicon().
- application name: provided by the system.
- timestamp: provided by the system, but you can override it with setwhen() or hide it with setshowwhen(false).
- large icon – This is optional (usually used only for contact photos – don’t use it for your app icon) and is set with setlargeicon().
- title: this is optional and is set with setcontenttitle().
- text: this is optional and is set with setcontenttext().
We strongly recommend using system templates to ensure proper design compatibility on all devices. however, if needed, you can create a custom notification layout.
To learn more about how to create a notification with these features and more, read Create a notification.
notification actions
While not required, each notification should open an appropriate app activity when tapped. In addition to this default notification action, you can add action buttons that complete an app-related task from within the notification (often without opening an activity), as shown in Figure 9.
figure 9. a notification with action buttons
As of android 7.0 (api level 24), you can also add an action to reply to messages or enter other text directly from the notification.
As of android 10 (api level 29), the platform can automatically generate action buttons with suggested actions based on intent.
adding action buttons is explained in more detail in creating a notification.
requires an unlocked device
Users can see notification actions on the device’s lock screen. if a certain notification action causes an app to launch an activity or send a direct response, users must unlock the device before the app can invoke that notification action.
In android 12 (api level 31) and higher, you can configure a notification action so that the device must be unlocked for your app to invoke that action, no matter what workflow launches the action. this option helps add an extra layer of security to notifications on locked devices.
To require a device to be unlocked before your app invokes a particular notification action, pass true to setauthenticationrequired() when creating your notification action, as shown in the following code snippet:
expandable notification
By default, the text content of the notification is truncated to fit on one line. If you want your notification to be longer, you can enable a larger text area that can be expanded by applying an additional template, as shown in figure 8.
figure 8. an expandable notification for large text
You can also create an expandable notification with an image, inbox style, a chat conversation or media playback controls. for more information, read create an expandable notification.
notification and group updates
To avoid bombarding your users with multiple or redundant notifications when you have additional updates, you should consider updating an existing notification instead of issuing a new one, or consider using the inbox-style notification to display conversation updates.
>
However, if multiple notifications need to be sent, you should consider grouping those separate notifications into one group (available on android 7.0 and above). A notification group allows you to collapse multiple notifications into a single post in the notification drawer, with a summary. the user can expand the notification to reveal the details of each individual notification.
The user can progressively expand the notification group and each notification within it to get more details.
figure 10. a collapsed and expanded notification group
For information on how to add notifications to a group, see Create a notification group.
notification channels
As of android 8.0 (api level 26), all notifications must be assigned to a channel or it will not appear. By categorizing notifications into channels, users can disable specific notification channels for their app (instead of disabling all of their notifications), and users can control the visual and audible options for each channel, all from the android system settings ( figure 11). users can also long press on a notification to change behaviors for the associated channel.
On devices running android 7.1 (api level 25) and lower, users can manage notifications only per app (in fact, each app only has one channel on android 7.1 and lower).
figure 11. notification settings for the clock app and one of its channels
An application can have multiple notification channels: a separate channel for each type of notification that the application emits. An app can also create notification channels in response to choices made by users of its app. for example, you can set up separate notification channels for each chat group created by a user in a messaging app.
channel is also where you specify the level of importance for your notifications in android 8.0 and above. so all notifications published in the same notification channel have the same behavior.
for more information, see create and manage notification channels.
importance of notification
Android uses the importance of a notification to determine how much the notification should interrupt the user (visually and audibly). the higher the importance of a notification, the more disruptive the notification will be.
In android 8.0 (api level 26) and higher, the importance of a notification is determined by the importance of the channel in which the notification was published. users can change the importance of a notification channel in the system settings (figure 12). On android 7.1 (api level 25) and lower, the importance of each notification is determined by the priority of the notification.
figure 12. users can change the importance of each channel in android 8.0 and above
the possible levels of importance are the following:
- Urgent – Plays a sound and appears as a pop-up notification.
- High – Plays a sound.
- Medium – No sound.
- low: no sound and does not appear in the status bar.
All notifications, regardless of their importance, appear in seamless system UI locations, such as in the notification drawer and as a badge on the launcher icon (although you can modify the appearance of the notification badge). notification).
for more information, see how to set importance.
do not disturb mode
As of android 5.0 (api level 21), users can enable do not disturb mode, which mutes sounds and vibrations for all notifications. notifications continue to appear in the system UI as normal, unless the user specifies otherwise.
There are three different levels available in Do Not Disturb mode:
- Total silence: Blocks all sounds and vibrations, including alarms, music, videos, and games.
- Alarms only: Blocks all sounds and vibrations, except alarms.
- Priority Only: Users can configure which system-wide categories can interrupt them (such as only alarms, reminders, events, calls, or messages). for messages and calls, users can also choose to filter based on who the sender or caller is (figure 13).
Figure 13. Users can allow notifications to be sent based on system-wide categories (left) and based on who sent a message or who called (right).
In android 8.0 (api level 26) and higher, users can also allow notifications to pass through for specific app categories (also known as channels) by overriding do not disturb on a channel-by-channel basis. for example, a payment application may have channels for notifications related to withdrawals and deposits. the user can choose to allow withdrawal notifications, deposit notifications or both when in priority mode. On devices running android 7.1 (api level 25) and lower, users can allow notifications to be sent on an app-by-app basis, rather than channel-by-channel.
To properly configure your notifications for this user setting, you must set a system-wide category and channel.
notifications for foreground services
A notification is required when your application is running a “foreground service”, a service running in the background that lasts a long time and is noticeable to the user, such as a media player. this notification cannot be dismissed like other notifications. to remove the notification, the service must be stopped or removed from the “foreground” state.
For more information, read how to run a service in the foreground. and if you’re building a media player, read also using media-style notifications with a service in the foreground.
post limits
As of android 8.1 (api level 27), apps cannot make a notification sound more than once per second. if your app posts multiple notifications in a second, they all appear as expected, but only the first notification per second makes a sound.
however, android also enforces a rate limit when updating a notification. If you post updates to a single notification too often (too many in less than a second), the system might drop some updates.
notification support
Since android 1.0, the notification system UI and notification-related APIs have continually evolved. To use the latest notification api features while still supporting older devices, use the support library notification api: notificationcompat and its subclasses, as well as notificationmanagercompat. this will allow you to avoid writing conditional code to check api levels because these api handle that for you.
notificationcompat is updated as the platform evolves to include the latest methods. it is important to note that the availability of a method in notificationcompat does not guarantee that the corresponding function will be provided on older devices. in some cases calling a newly introduced api results in no operation on older devices. for example, notificationcompat.addaction() displays the action button on a device running android 4.1 (api level 16) and higher only.
The following is a summary of the most notable behavior changes for android notifications.
android 4.1, api level 16
- introduced expandable notification templates (called notification styles), allowing a larger notification content area to display information. users can use a finger swipe up/down gesture to expand a notification.
- It also introduced the ability to add additional actions, in the form of buttons, to a notification.
- added ability for users to disable notifications per app in settings.
android 4.4, api level 19 and 20
- added notification listener services to the api.
- added support for android wear (now called wear os) in api level 20.
android 5.0, api level 21
- introduced lock screen and push notifications.
- user can now put the phone in do not disturb mode and configure which notifications can interrupt them when the device has priority only. mode.
- methods added to the api to set whether or not a notification is displayed on the lock screen (setvisibility()) and to specify the “public” version of the notification text.
- setpriority() method added that tells the system how “stopped” this notification should be (for example, setting it to high makes the notification appear as an alert notification).
- se added notification stack support to android wear (now called wear os) devices. put notifications on a stack using setgroup(). Please note that notification stacks were not yet supported on tablets and phones. notification stacks would later be known as a group or bundle.
android 7.0, api level 24
- notification templates have been redesigned to emphasize the hero image and avatar.
- three notification templates have been added: one for messaging apps and the other two for decorating content views with expandability and other system decorations.
- added support for portable devices (phones and tablets) for notification groups. uses the same api as the android wear (now called wear os) notification stacks introduced in android 5.0 (api level 21).
- users can reply directly within a notification (they can enter text that then it will be routed to the notification’s parent app) via the inline response.
android 8.0, api level 26
- Individual notifications must now be placed in a specific channel.
- Users can now turn off notifications per channel, instead of turning off all notifications for an app.
- Apps with active notifications display a notification “badge” on top of the app icon on the home/launcher screen.
- Users can now snooze a notification from the drawer. you can set an automatic timeout for a notification.
- you can also set the background color of the notification.
- some api related to notification behaviors moved from notification to channel of notification. eg use notificationchannel.setiportance() instead of notificationcompat.builder.setpriority() for android 8.0 and above.
android 13.0, api level 33
- a runtime permission has been added. In order for your app to send non-exempt notifications, the user must grant this permission to your app.