Android 13 (API level 33) and higher supports a
runtime permission
for sending
non-exempt
(including Foreground Services (FGS)) notifications
from an app:
POST_NOTIFICATIONS
.
This change helps users focus on the notifications that are most important to
them.
We highly recommend that you target Android 13 or higher as soon
as possible to benefit from the additional control and flexibility of this
feature. If you continue to target 12L (API level 32) or lower, you
lose some flexibility with
requesting the permission in the context of your app's
functionality
.
Declare the permission
To request the new notification permission from your app, update your app to
target Android 13 and complete a similar process compared to
requesting other runtime permissions
, as
shown in the following sections.
The permission that you need to
declare in your app's manifest file
appears in the following code snippet:
<manifest ...>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<application ...>
...
</application>
</manifest>
App capabilities depend on user choice in permissions dialog
In this dialog, users have the
following actions available to them:
The following sections describe how your app behaves, based on which action the
user takes.
User selects "Allow"
If the user selects the
allow
option, your app can do the following:
User selects "Don't allow"
If the user selects the
don't allow
option, your app can't send
notifications unless it qualifies for an
exemption
. All
notification channels are blocked, except for a few specific
roles. This is similar to the behavior that occurs when the user manually turns
off all notifications for your app in system settings.
Caution:
If your app targets 12L or lower
and the user taps
Don't allow
, even just once, they aren't prompted
again until one of the following occurs:
- The user uninstalls and reinstalls your app.
- You update your app to target Android 13 or higher.
User swipes away from dialog
If the user swipes away from the dialog?that is, they don't select either
allow
or
don't allow
?the state of the notification permission doesn't
change.
Effects on newly-installed apps
If a user installs your app on a device that runs Android 13
or higher, your app's
notifications are off by default
. Your app must wait
to
send notifications until after you request the new permission and the user
grants that permission to your app.
The time at which the permissions dialog appears is based on your app's target
SDK version:
- If your app targets Android 13 or higher, your app has complete
control over when the permission dialog is displayed.
Use this opportunity to explain to users why the app needs this permission,
encouraging them to grant it.
- If your app targets 12L (API level 32) or lower, the system shows
the permission dialog the first time your app starts an activity after you
create a
notification channel
, or when your
app starts an activity and then creates its first notification channel. This
is usually on app startup.
Effects on updates to existing apps
To minimize disruptions associated with the notification permission, the
system automatically pre-grants the permission to all
eligible apps
when the user upgrades their device to
Android 13 or higher. In other words, these apps can continue to
send notifications to users, and users don't see a runtime permission prompt.
Eligibility for permission pre-grant
For your app to be
eligible
for an automatic pre-grant, it must have an
existing notification channel and not have its notifications explicitly disabled
by the user on a device that runs 12L or lower.
If the user disabled notifications for your app on a device that runs
12L or lower, that denial persists when the device
upgrades to Android 13 or higher.
Exemptions
This section contains the set of notifications and apps that are exempt from the
notification permission behavior change. On Android 13 (API level 33) or higher,
if the user denies the notification permission, they still see notices related
to foreground services in the
Task Manager
but don't see them in the
notification drawer
.
Notifications related to
media sessions
are
exempt from this behavior change.
Apps configured to self-manage phone calls
If your app configures itself to self-manage phone calls, you
don't need the
POST_NOTIFICATIONS
permission in order for your app to send
notifications that use the
Notification.CallStyle
notification style.
The system considers your app to have configured itself for self-managing phone
calls if it does each of the following:
- Declares the
MANAGE_OWN_CALLS
permission.
- Implements the
ConnectionService
interface.
- Registers with the device's telecom provider by calling
registerPhoneAccount()
.
Test your app
You can evaluate how the notification permission affects your app when it's
first used on a device that runs Android 13 or higher. The
following
sets of
Android Debug Bridge (ADB)
commands allow
you to simulate the most common sequences of user choices and device upgrades
without needing to reset your test device:
App is newly installed on a device that runs
Android 13 or higher:
adb shell pm revoke
PACKAGE_NAME
android.permission.POST_NOTIFICATIONS
adb shell pm clear-permission-flags
PACKAGE_NAME
\
android.permission.POST_NOTIFICATIONS user-set
adb shell pm clear-permission-flags
PACKAGE_NAME
\
android.permission.POST_NOTIFICATIONS user-fixed
The user keeps notifications enabled when the app is installed on a
device that runs 12L or lower, then the device
upgrades to Android 13 or higher:
adb shell pm grant
PACKAGE_NAME
android.permission.POST_NOTIFICATIONS
adb shell pm set-permission-flags
PACKAGE_NAME
\
android.permission.POST_NOTIFICATIONS user-set
adb shell pm clear-permission-flags
PACKAGE_NAME
\
android.permission.POST_NOTIFICATIONS user-fixed
The user manually disables notifications when the app is installed on a
device that runs 12L or lower, then the device
upgrades to Android 13 or higher:
adb shell pm revoke
PACKAGE_NAME
android.permission.POST_NOTIFICATIONS
adb shell pm set-permission-flags
PACKAGE_NAME
\
android.permission.POST_NOTIFICATIONS user-set
adb shell pm clear-permission-flags
PACKAGE_NAME
\
android.permission.POST_NOTIFICATIONS user-fixed
Best practices
This section describes several ways that you can use the new notification
permission most effectively in your app.
Update your app's target SDK version
To give your app more flexibility over when the permission dialog appears,
update your app so that it targets Android 13 or higher.
Wait to show notification permission prompt
Before you ask users to grant any permissions, let them familiarize themselves
with your app.
New users may want to explore the app and realize first-hand the
benefits of each individual notification request. You can
trigger a permissions prompt
from a user action. The following list shows several examples of when it's a
good time to show the notification permission prompt:
- The user taps an "alert bell" button.
- The user chooses to follow someone's social media account.
- The user submits an order for food delivery.
Figure 1 shows a recommended workflow for requesting the notification
permission. Unless
shouldShowRequestPermissionRationale()
returns
true
, your app doesn't need to display the middle screen?the one that
has the title text "Get notified!".
Alternatively, you can set a request to appear after you give users a chance to
familiarize themselves with your app. For example, you might wait until the
third or fourth time the user launches your app.
Request the permission in context
When you request notification permissions within your app, do so in the correct
context, so that it's explicitly clear what the notifications are used for and
why the user should opt in. For example, an email app might include options to
send notifications for every new email, or only the emails where the user is the
only recipient.
Use this opportunity to give transparency to your intentions, and users are more
likely to grant the notification permission to your app.
Check whether your app can send notifications
Before your app sends a notification, confirm whether the user has enabled
notifications for your app. To do so, call
areNotificationsEnabled()
.
Use the permission responsibly
After you receive approval to send notifications, remember to use the permission
responsibly. Users can see the number of daily notifications that your app
sends, and
they can revoke the permission
at any time.