NotificationListenerService
public
abstract
class
NotificationListenerService
extends Service
java.lang.Object | ||||
↳ | android.content.Context | |||
↳ | android.content.ContextWrapper | |||
↳ | android.app.Service | |||
↳ | android.service.notification.NotificationListenerService |
A service that receives calls from the system when new notifications are posted or removed, or their ranking changed.
To extend this class, you must declare the service in your manifest file with
the Manifest.permission.BIND_NOTIFICATION_LISTENER_SERVICE
permission
and include an intent filter with the SERVICE_INTERFACE
action. For example:
<service android:name=".NotificationListener" android:label="@string/service_name" android:exported="false" android:permission="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE"> <intent-filter> <action android:name="android.service.notification.NotificationListenerService" /> </intent-filter> <meta-data android:name="android.service.notification.default_filter_types" android:value="conversations|alerting"> </meta-data> <meta-data android:name="android.service.notification.disabled_filter_types" android:value="ongoing|silent"> </meta-data> </service>
The service should wait for the onListenerConnected()
event
before performing any operations. The requestRebind(android.content.ComponentName)
method is the only one that is safe to call before onListenerConnected()
or after onListenerDisconnected()
.
Notification listeners cannot get notification access or be bound by the system on
low-RAM devices running Android Q (and below).
The system also ignores notification listeners running in a work profile. A
DevicePolicyManager
might block notifications originating from a work
profile.
From Build.VERSION_CODES#N
onward all callbacks are called on the main thread. Prior
to N, there is no guarantee on what thread the callback will happen.
Summary
Nested classes | |
---|---|
class |
NotificationListenerService.Ranking
Stores ranking related information on a currently active notification. |
class |
NotificationListenerService.RankingMap
Provides access to ranking information on currently active notifications. |
Constants | |
---|---|
String |
ACTION_SETTINGS_HOME
An optional activity intent action that shows additional settings for what notifications should be processed by this notification listener service. |
int |
FLAG_FILTER_TYPE_ALERTING
A flag value indicating that this notification listener can see altering type notifications. |
int |
FLAG_FILTER_TYPE_CONVERSATIONS
A flag value indicating that this notification listener can see conversation type notifications. |
int |
FLAG_FILTER_TYPE_ONGOING
A flag value indicating that this notification listener can see important
( > |
int |
FLAG_FILTER_TYPE_SILENT
A flag value indicating that this notification listener can see silent type notifications. |
int |
HINT_HOST_DISABLE_CALL_EFFECTS
|
int |
HINT_HOST_DISABLE_EFFECTS
|
int |
HINT_HOST_DISABLE_NOTIFICATION_EFFECTS
|
int |
INTERRUPTION_FILTER_ALARMS
|
int |
INTERRUPTION_FILTER_ALL
|
int |
INTERRUPTION_FILTER_NONE
|
int |
INTERRUPTION_FILTER_PRIORITY
|
int |
INTERRUPTION_FILTER_UNKNOWN
|
String |
META_DATA_DEFAULT_AUTOBIND
The name of the |
String |
META_DATA_DEFAULT_FILTER_TYPES
The name of the |
String |
META_DATA_DISABLED_FILTER_TYPES
The name of the |
int |
NOTIFICATION_CHANNEL_OR_GROUP_ADDED
Channel or group modification reason provided to
|
int |
NOTIFICATION_CHANNEL_OR_GROUP_DELETED
Channel or group modification reason provided to
|
int |
NOTIFICATION_CHANNEL_OR_GROUP_UPDATED
Channel or group modification reason provided to
|
int |
REASON_APP_CANCEL
Notification was canceled by the app canceling this specific notification. |
int |
REASON_APP_CANCEL_ALL
Notification was canceled by the app cancelling all its notifications. |
int |
REASON_ASSISTANT_CANCEL
Notification was canceled due to an assistant adjustment update. |
int |
REASON_CANCEL
Notification was canceled by the status bar reporting a user dismissal. |
int |
REASON_CANCEL_ALL
Notification was canceled by the status bar reporting a user dismiss all. |
int |
REASON_CHANNEL_BANNED
Notification was canceled by the user banning the channel. |
int |
REASON_CHANNEL_REMOVED
Notification was canceled due to the backing channel being deleted |
int |
REASON_CLEAR_DATA
Notification was canceled due to the app's storage being cleared |
int |
REASON_CLICK
Notification was canceled by the status bar reporting a notification click. |
int |
REASON_ERROR
Notification was canceled by the status bar reporting an inflation error. |
int |
REASON_GROUP_OPTIMIZATION
Notification was canceled because it was an invisible member of a group. |
int |
REASON_GROUP_SUMMARY_CANCELED
Notification was canceled because it was a member of a canceled group. |
int |
REASON_LISTENER_CANCEL
Notification was canceled by a listener reporting a user dismissal. |
int |
REASON_LISTENER_CANCEL_ALL
Notification was canceled by a listener reporting a user dismiss all. |
int |
REASON_LOCKDOWN
Notification was canceled when entering lockdown mode, which turns off Smart Lock, fingerprint unlocking, and notifications on the lock screen. |
int |
REASON_PACKAGE_BANNED
Notification was canceled by the user banning the package. |
int |
REASON_PACKAGE_CHANGED
Notification was canceled by the package manager modifying the package. |
int |
REASON_PACKAGE_SUSPENDED
Notification was canceled by the device administrator suspending the package. |
int |
REASON_PROFILE_TURNED_OFF
Notification was canceled by the owning managed profile being turned off. |
int |
REASON_SNOOZED
Notification was snoozed. |
int |
REASON_TIMEOUT
Notification was canceled due to timeout |
int |
REASON_UNAUTOBUNDLED
Autobundled summary notification was canceled because its group was unbundled |
int |
REASON_USER_STOPPED
Notification was canceled by the owning user context being stopped. |
String |
SERVICE_INTERFACE
The |
int |
SUPPRESSED_EFFECT_SCREEN_OFF
This constant was deprecated
in API level 28.
Use the more specific visual effects in |
int |
SUPPRESSED_EFFECT_SCREEN_ON
This constant was deprecated
in API level 28.
Use the more specific visual effects in |
Inherited constants |
---|
Public constructors | |
---|---|
NotificationListenerService()
|
Public methods | |
---|---|
final
void
|
cancelAllNotifications()
Inform the notification manager about dismissal of all notifications. |
final
void
|
cancelNotification(String pkg, String tag, int id)
This method was deprecated
in API level 21.
Use |
final
void
|
cancelNotification(String key)
Inform the notification manager about dismissal of a single notification. |
final
void
|
cancelNotifications(String[] keys)
Inform the notification manager about dismissal of specific notifications. |
final
void
|
clearRequestedListenerHints()
Clears listener hints set via |
StatusBarNotification[]
|
getActiveNotifications(String[] keys)
Request one or more notifications by key. |
StatusBarNotification[]
|
getActiveNotifications()
Request the list of outstanding notifications (that is, those that are visible to the current user). |
final
int
|
getCurrentInterruptionFilter()
Gets the current notification interruption filter active on the host. |
final
int
|
getCurrentListenerHints()
Gets the set of hints representing current state. |
NotificationListenerService.RankingMap
|
getCurrentRanking()
Returns current ranking information. |
final
List<NotificationChannelGroup>
|
getNotificationChannelGroups(String pkg, UserHandle user)
Returns all notification channel groups belonging to the given package for a given user. |
final
List<NotificationChannel>
|
getNotificationChannels(String pkg, UserHandle user)
Returns all notification channels belonging to the given package for a given user. |
final
StatusBarNotification[]
|
getSnoozedNotifications()
Like |
final
void
|
migrateNotificationFilter(int defaultTypes, List<String> disallowedPkgs)
Lets an app migrate notification filters from its app into the OS. |
IBinder
|
onBind(Intent intent)
This is not the lifecycle event you are looking for. |
void
|
onDestroy()
Called by the system to notify a Service that it is no longer used and is being removed. |
void
|
onInterruptionFilterChanged(int interruptionFilter)
Implement this method to be notified when the
|
void
|
onListenerConnected()
Implement this method to learn about when the listener is enabled and connected to the notification manager. |
void
|
onListenerDisconnected()
Implement this method to learn about when the listener is disconnected from the
notification manager.You will not receive any events after this call, and may only
call |
void
|
onListenerHintsChanged(int hints)
Implement this method to be notified when the
|
void
|
onNotificationChannelGroupModified(String pkg, UserHandle user, NotificationChannelGroup group, int modificationType)
Implement this method to learn about notification channel group modifications. |
void
|
onNotificationChannelModified(String pkg, UserHandle user, NotificationChannel channel, int modificationType)
Implement this method to learn about notification channel modifications. |
void
|
onNotificationPosted(StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap)
Implement this method to learn about new notifications as they are posted by apps. |
void
|
onNotificationPosted(StatusBarNotification sbn)
Implement this method to learn about new notifications as they are posted by apps. |
void
|
onNotificationRankingUpdate(NotificationListenerService.RankingMap rankingMap)
Implement this method to be notified when the notification ranking changes. |
void
|
onNotificationRemoved(StatusBarNotification sbn)
Implement this method to learn when notifications are removed. |
void
|
onNotificationRemoved(StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap)
Implement this method to learn when notifications are removed. |
void
|
onNotificationRemoved(StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap, int reason)
Implement this method to learn when notifications are removed and why. |
void
|
onSilentStatusBarIconsVisibilityChanged(boolean hideSilentStatusIcons)
Implement this method to be notified when the behavior of silent notifications in the status bar changes. |
final
void
|
requestInterruptionFilter(int interruptionFilter)
Sets the desired |
final
void
|
requestListenerHints(int hints)
Sets the desired |
static
void
|
requestRebind(ComponentName componentName)
Request that the listener be rebound, after a previous call to |
static
void
|
requestUnbind(ComponentName componentName)
Request that the service be unbound. |
final
void
|
requestUnbind()
Request that the service be unbound. |
final
void
|
setNotificationsShown(String[] keys)
Inform the notification manager that these notifications have been viewed by the user. |
final
void
|
snoozeNotification(String key, long durationMs)
Inform the notification manager about snoozing a specific notification. |
final
void
|
updateNotificationChannel(String pkg, UserHandle user, NotificationChannel channel)
Updates a notification channel for a given package for a given user. |
Protected methods | |
---|---|
void
|
attachBaseContext(Context base)
Set the base context for this ContextWrapper. |
Inherited methods | |
---|---|
Constants
ACTION_SETTINGS_HOME
public static final String ACTION_SETTINGS_HOME
An optional activity intent action that shows additional settings for what notifications should be processed by this notification listener service. If defined, the OS may link to this activity from the system notification listener service filter settings page.
Constant Value: "android.service.notification.action.SETTINGS_HOME"
FLAG_FILTER_TYPE_ALERTING
public static final int FLAG_FILTER_TYPE_ALERTING
A flag value indicating that this notification listener can see altering type notifications.
Constant Value: 2 (0x00000002)
FLAG_FILTER_TYPE_CONVERSATIONS
public static final int FLAG_FILTER_TYPE_CONVERSATIONS
A flag value indicating that this notification listener can see conversation type notifications.
Constant Value: 1 (0x00000001)
FLAG_FILTER_TYPE_ONGOING
public static final int FLAG_FILTER_TYPE_ONGOING
A flag value indicating that this notification listener can see important
( > NotificationManager#IMPORTANCE_MIN
) ongoing type notifications.
Constant Value: 8 (0x00000008)
FLAG_FILTER_TYPE_SILENT
public static final int FLAG_FILTER_TYPE_SILENT
A flag value indicating that this notification listener can see silent type notifications.
Constant Value: 4 (0x00000004)
HINT_HOST_DISABLE_CALL_EFFECTS
public static final int HINT_HOST_DISABLE_CALL_EFFECTS
Listener hints
constant - the primary device UI
should disable phone call sounds, but not notification sound.
This does not change the interruption filter, only the effects. *
Constant Value: 4 (0x00000004)
HINT_HOST_DISABLE_EFFECTS
public static final int HINT_HOST_DISABLE_EFFECTS
Listener hints
constant - the primary device UI
should disable notification sound, vibrating and other visual or aural effects.
This does not change the interruption filter, only the effects. *
Constant Value: 1 (0x00000001)
HINT_HOST_DISABLE_NOTIFICATION_EFFECTS
public static final int HINT_HOST_DISABLE_NOTIFICATION_EFFECTS
Listener hints
constant - the primary device UI
should disable notification sound, but not phone calls.
This does not change the interruption filter, only the effects. *
Constant Value: 2 (0x00000002)
INTERRUPTION_FILTER_ALARMS
public static final int INTERRUPTION_FILTER_ALARMS
Interruption filter
constant -
Alarms only interruption filter.
Constant Value: 4 (0x00000004)
INTERRUPTION_FILTER_ALL
public static final int INTERRUPTION_FILTER_ALL
Interruption filter
constant -
Normal interruption filter.
Constant Value: 1 (0x00000001)
INTERRUPTION_FILTER_NONE
public static final int INTERRUPTION_FILTER_NONE
Interruption filter
constant -
No interruptions filter.
Constant Value: 3 (0x00000003)
INTERRUPTION_FILTER_PRIORITY
public static final int INTERRUPTION_FILTER_PRIORITY
Interruption filter
constant -
Priority interruption filter.
Constant Value: 2 (0x00000002)
INTERRUPTION_FILTER_UNKNOWN
public static final int INTERRUPTION_FILTER_UNKNOWN
Interruption filter
constant - returned when
the value is unavailable for any reason. For example, before the notification listener
is connected.
See also:
Constant Value: 0 (0x00000000)
META_DATA_DEFAULT_AUTOBIND
public static final String META_DATA_DEFAULT_AUTOBIND
The name of the meta-data
tag containing a boolean value that is used to decide if
this listener should be automatically bound by default.
If the value is 'false', the listener can be bound on demand using requestRebind(ComponentName)
An absent value means that the default is 'true'
Constant Value: "android.service.notification.default_autobind_listenerservice"
META_DATA_DEFAULT_FILTER_TYPES
public static final String META_DATA_DEFAULT_FILTER_TYPES
The name of the meta-data
tag containing a pipe separated list of default
integer notification types or "ongoing", "conversations", "alerting", or "silent"
that should be provided to this listener. See
FLAG_FILTER_TYPE_ONGOING
,
FLAG_FILTER_TYPE_CONVERSATIONS
, {@link #FLAG_FILTER_TYPE_ALERTING),
and {@link #FLAG_FILTER_TYPE_SILENT}.
This value will only be read if the app has not previously specified a default type list, and if the user has not overridden the allowed types.
An absent value means 'allow all types'. A present but empty value means 'allow no types'.
Constant Value: "android.service.notification.default_filter_types"
META_DATA_DISABLED_FILTER_TYPES
public static final String META_DATA_DISABLED_FILTER_TYPES
The name of the meta-data
tag containing a comma separated list of default
integer notification types that this listener never wants to receive. See
FLAG_FILTER_TYPE_ONGOING
,
FLAG_FILTER_TYPE_CONVERSATIONS
, {@link #FLAG_FILTER_TYPE_ALERTING),
and {@link #FLAG_FILTER_TYPE_SILENT}.
Types provided in this list will appear as 'off' and 'disabled' in the user interface, so users don't enable a type that the listener will never bridge to their paired devices.
Constant Value: "android.service.notification.disabled_filter_types"
NOTIFICATION_CHANNEL_OR_GROUP_ADDED
public static final int NOTIFICATION_CHANNEL_OR_GROUP_ADDED
Channel or group modification reason provided to
onNotificationChannelModified(java.lang.String, android.os.UserHandle, android.app.NotificationChannel, int)
or
onNotificationChannelGroupModified(java.lang.String, android.os.UserHandle, android.app.NotificationChannelGroup, int)
- the provided object was created.
Constant Value: 1 (0x00000001)
NOTIFICATION_CHANNEL_OR_GROUP_DELETED
public static final int NOTIFICATION_CHANNEL_OR_GROUP_DELETED
Channel or group modification reason provided to
onNotificationChannelModified(java.lang.String, android.os.UserHandle, android.app.NotificationChannel, int)
or
onNotificationChannelGroupModified(java.lang.String, android.os.UserHandle, android.app.NotificationChannelGroup, int)
- the provided object was deleted.
Constant Value: 3 (0x00000003)
NOTIFICATION_CHANNEL_OR_GROUP_UPDATED
public static final int NOTIFICATION_CHANNEL_OR_GROUP_UPDATED
Channel or group modification reason provided to
onNotificationChannelModified(java.lang.String, android.os.UserHandle, android.app.NotificationChannel, int)
or
onNotificationChannelGroupModified(java.lang.String, android.os.UserHandle, android.app.NotificationChannelGroup, int)
- the provided object was updated.
Constant Value: 2 (0x00000002)
REASON_APP_CANCEL
public static final int REASON_APP_CANCEL
Notification was canceled by the app canceling this specific notification.
Constant Value: 8 (0x00000008)
REASON_APP_CANCEL_ALL
public static final int REASON_APP_CANCEL_ALL
Notification was canceled by the app cancelling all its notifications.
Constant Value: 9 (0x00000009)
REASON_ASSISTANT_CANCEL
public static final int REASON_ASSISTANT_CANCEL
Notification was canceled due to an assistant adjustment update.
Constant Value: 22 (0x00000016)
REASON_CANCEL
public static final int REASON_CANCEL
Notification was canceled by the status bar reporting a user dismissal.
Constant Value: 2 (0x00000002)
REASON_CANCEL_ALL
public static final int REASON_CANCEL_ALL
Notification was canceled by the status bar reporting a user dismiss all.
Constant Value: 3 (0x00000003)
REASON_CHANNEL_BANNED
public static final int REASON_CHANNEL_BANNED
Notification was canceled by the user banning the channel.
Constant Value: 17 (0x00000011)
REASON_CHANNEL_REMOVED
public static final int REASON_CHANNEL_REMOVED
Notification was canceled due to the backing channel being deleted
Constant Value: 20 (0x00000014)
REASON_CLEAR_DATA
public static final int REASON_CLEAR_DATA
Notification was canceled due to the app's storage being cleared
Constant Value: 21 (0x00000015)
REASON_CLICK
public static final int REASON_CLICK
Notification was canceled by the status bar reporting a notification click.
Constant Value: 1 (0x00000001)
REASON_ERROR
public static final int REASON_ERROR
Notification was canceled by the status bar reporting an inflation error.
Constant Value: 4 (0x00000004)
REASON_GROUP_OPTIMIZATION
public static final int REASON_GROUP_OPTIMIZATION
Notification was canceled because it was an invisible member of a group.
Constant Value: 13 (0x0000000d)
REASON_GROUP_SUMMARY_CANCELED
public static final int REASON_GROUP_SUMMARY_CANCELED
Notification was canceled because it was a member of a canceled group.
Constant Value: 12 (0x0000000c)
REASON_LISTENER_CANCEL
public static final int REASON_LISTENER_CANCEL
Notification was canceled by a listener reporting a user dismissal.
Constant Value: 10 (0x0000000a)
REASON_LISTENER_CANCEL_ALL
public static final int REASON_LISTENER_CANCEL_ALL
Notification was canceled by a listener reporting a user dismiss all.
Constant Value: 11 (0x0000000b)
REASON_LOCKDOWN
public static final int REASON_LOCKDOWN
Notification was canceled when entering lockdown mode, which turns off Smart Lock, fingerprint unlocking, and notifications on the lock screen. All the listeners shall ensure the canceled notifications are indeed removed on their end to prevent data leaking. When the user exits the lockdown mode, the removed notifications (due to lockdown) will be restored via NotificationListeners#notifyPostedLocked()
Constant Value: 23 (0x00000017)
REASON_PACKAGE_BANNED
public static final int REASON_PACKAGE_BANNED
Notification was canceled by the user banning the package.
Constant Value: 7 (0x00000007)
REASON_PACKAGE_CHANGED
public static final int REASON_PACKAGE_CHANGED
Notification was canceled by the package manager modifying the package.
Constant Value: 5 (0x00000005)
REASON_PACKAGE_SUSPENDED
public static final int REASON_PACKAGE_SUSPENDED
Notification was canceled by the device administrator suspending the package.
Constant Value: 14 (0x0000000e)
REASON_PROFILE_TURNED_OFF
public static final int REASON_PROFILE_TURNED_OFF
Notification was canceled by the owning managed profile being turned off.
Constant Value: 15 (0x0000000f)
REASON_SNOOZED
public static final int REASON_SNOOZED
Notification was snoozed.
Constant Value: 18 (0x00000012)
REASON_TIMEOUT
public static final int REASON_TIMEOUT
Notification was canceled due to timeout
Constant Value: 19 (0x00000013)
REASON_UNAUTOBUNDLED
public static final int REASON_UNAUTOBUNDLED
Autobundled summary notification was canceled because its group was unbundled
Constant Value: 16 (0x00000010)
REASON_USER_STOPPED
public static final int REASON_USER_STOPPED
Notification was canceled by the owning user context being stopped.
Constant Value: 6 (0x00000006)
SERVICE_INTERFACE
public static final String SERVICE_INTERFACE
The Intent
that must be declared as handled by the service.
Constant Value: "android.service.notification.NotificationListenerService"
SUPPRESSED_EFFECT_SCREEN_OFF
public static final int SUPPRESSED_EFFECT_SCREEN_OFF
This constant was deprecated
in API level 28.
Use the more specific visual effects in NotificationManager.Policy
.
Whether notification suppressed by DND should not interruption visually when the screen is off.
Constant Value: 1 (0x00000001)
SUPPRESSED_EFFECT_SCREEN_ON
public static final int SUPPRESSED_EFFECT_SCREEN_ON
This constant was deprecated
in API level 28.
Use the more specific visual effects in NotificationManager.Policy
.
Whether notification suppressed by DND should not interruption visually when the screen is on.
Constant Value: 2 (0x00000002)
Public constructors
NotificationListenerService
public NotificationListenerService ()
Public methods
cancelAllNotifications
public final void cancelAllNotifications ()
Inform the notification manager about dismissal of all notifications.
Use this if your listener has a user interface that allows the user to dismiss all
notifications, similar to the behavior of Android's status bar and notification panel.
It should be called after the user invokes the "dismiss all" function of your UI;
upon being informed, the notification manager will actually remove all active notifications
and you will get multiple onNotificationRemoved(android.service.notification.StatusBarNotification)
callbacks.
The service should wait for the onListenerConnected()
event
before performing this operation.
See also:
cancelNotification
public final void cancelNotification (String pkg, String tag, int id)
This method was deprecated
in API level 21.
Use cancelNotification(java.lang.String)
instead. Beginning with Build.VERSION_CODES.LOLLIPOP
this method will no longer
cancel the notification. It will continue to cancel the notification for applications
whose targetSdkVersion
is earlier than Build.VERSION_CODES.LOLLIPOP
.
Inform the notification manager about dismissal of a single notification.
Use this if your listener has a user interface that allows the user to dismiss individual
notifications, similar to the behavior of Android's status bar and notification panel.
It should be called after the user dismisses a single notification using your UI;
upon being informed, the notification manager will actually remove the notification
and you will get an onNotificationRemoved(android.service.notification.StatusBarNotification)
callback.
Note: If your listener allows the user to fire a notification's
Notification.contentIntent
by tapping/clicking/etc., you should call
this method at that time if the Notification in question has the
Notification.FLAG_AUTO_CANCEL
flag set.
The service should wait for the onListenerConnected()
event
before performing this operation.
Parameters | |
---|---|
pkg |
String : Package of the notifying app. |
tag |
String : Tag of the notification as specified by the notifying app in
NotificationManager.notify(String, int, android.app.Notification) . |
id |
int : ID of the notification as specified by the notifying app in
NotificationManager.notify(String, int, android.app.Notification) .
|
cancelNotification
public final void cancelNotification (String key)
Inform the notification manager about dismissal of a single notification.
Use this if your listener has a user interface that allows the user to dismiss individual
notifications, similar to the behavior of Android's status bar and notification panel.
It should be called after the user dismisses a single notification using your UI;
upon being informed, the notification manager will actually remove the notification
and you will get an onNotificationRemoved(android.service.notification.StatusBarNotification)
callback.
Note: If your listener allows the user to fire a notification's
Notification.contentIntent
by tapping/clicking/etc., you should call
this method at that time if the Notification in question has the
Notification.FLAG_AUTO_CANCEL
flag set.
The service should wait for the onListenerConnected()
event
before performing this operation.
Parameters | |
---|---|
key |
String : Notification to dismiss from StatusBarNotification#getKey() . |
cancelNotifications
public final void cancelNotifications (String[] keys)
Inform the notification manager about dismissal of specific notifications.
Use this if your listener has a user interface that allows the user to dismiss multiple notifications at once.
The service should wait for the onListenerConnected()
event
before performing this operation.
Parameters | |
---|---|
keys |
String : Notifications to dismiss, or null to dismiss all.
|
clearRequestedListenerHints
public final void clearRequestedListenerHints ()
Clears listener hints set via getCurrentListenerHints()
.
The service should wait for the onListenerConnected()
event
before performing this operation.
getActiveNotifications
public StatusBarNotification[] getActiveNotifications (String[] keys)
Request one or more notifications by key. Useful if you have been keeping track of notifications but didn't want to retain the bits, and now need to go back and extract more data out of those notifications.
The service should wait for the onListenerConnected()
event
before performing this operation.
Parameters | |
---|---|
keys |
String : the keys of the notifications to request |
Returns | |
---|---|
StatusBarNotification[] |
An array of notifications corresponding to the requested keys, in the same order as the key list. |
getActiveNotifications
public StatusBarNotification[] getActiveNotifications ()
Request the list of outstanding notifications (that is, those that are visible to the current user). Useful when you don't know what's already been posted.
The service should wait for the onListenerConnected()
event
before performing this operation.
Returns | |
---|---|
StatusBarNotification[] |
An array of active notifications, sorted in natural order. |
getCurrentInterruptionFilter
public final int getCurrentInterruptionFilter ()
Gets the current notification interruption filter active on the host.
The interruption filter defines which notifications are allowed to interrupt the user
(e.g. via sound & vibration) and is applied globally. Listeners can find out whether
a specific notification matched the interruption filter via
Ranking#matchesInterruptionFilter()
.
The current filter may differ from the previously requested filter if the notification host does not support or refuses to apply the requested filter, or if another component changed the filter in the meantime.
Listen for updates using onInterruptionFilterChanged(int)
.
The service should wait for the onListenerConnected()
event
before performing this operation.
Returns | |
---|---|
int |
One of the INTERRUPTION_FILTER_ constants, or INTERRUPTION_FILTER_UNKNOWN when unavailable. |
getCurrentListenerHints
public final int getCurrentListenerHints ()
Gets the set of hints representing current state.
The current state may differ from the requested state if the hint represents state shared across all listeners or a feature the notification host does not support or refuses to grant.
The service should wait for the onListenerConnected()
event
before performing this operation.
Returns | |
---|---|
int |
Zero or more of the HINT_ constants. |
getCurrentRanking
public NotificationListenerService.RankingMap getCurrentRanking ()
Returns current ranking information.
The returned object represents the current ranking snapshot and only applies for currently active notifications.
Generally you should use the RankingMap that is passed with events such
as onNotificationPosted(android.service.notification.StatusBarNotification, android.service.notification.NotificationListenerService.RankingMap)
,
onNotificationRemoved(android.service.notification.StatusBarNotification, android.service.notification.NotificationListenerService.RankingMap)
, and
so on. This method should only be used when needing access outside of
such events, for example to retrieve the RankingMap right after
initialization.
The service should wait for the onListenerConnected()
event
before performing this operation.
Returns | |
---|---|
NotificationListenerService.RankingMap |
A RankingMap object providing access to ranking information |
getNotificationChannelGroups
public final List<NotificationChannelGroup> getNotificationChannelGroups (String pkg, UserHandle user)
Returns all notification channel groups belonging to the given package for a given user.
This method will throw a security exception if you don't have access to notifications for the given user.
The caller must have device
or be the notification assistant in order to use this method.
Parameters | |
---|---|
pkg |
String : The package to retrieve channel groups for.
This value cannot be null . |
user |
UserHandle : This value cannot be null . |
Returns | |
---|---|
List<NotificationChannelGroup> |
getNotificationChannels
public final List<NotificationChannel> getNotificationChannels (String pkg, UserHandle user)
Returns all notification channels belonging to the given package for a given user.
This method will throw a security exception if you don't have access to notifications for the given user.
The caller must have device
or be the notification assistant in order to use this method.
Parameters | |
---|---|
pkg |
String : The package to retrieve channels for.
This value cannot be null . |
user |
UserHandle : This value cannot be null . |
Returns | |
---|---|
List<NotificationChannel> |
getSnoozedNotifications
public final StatusBarNotification[] getSnoozedNotifications ()
Like getActiveNotifications()
, but returns the list of currently snoozed
notifications, for all users this listener has access to.
The service should wait for the onListenerConnected()
event
before performing this operation.
Returns | |
---|---|
StatusBarNotification[] |
An array of snoozed notifications, sorted in natural order. |
migrateNotificationFilter
public final void migrateNotificationFilter (int defaultTypes, List<String> disallowedPkgs)
Lets an app migrate notification filters from its app into the OS.
This call will be ignored if the app has already migrated these settings or the user
has set filters in the UI. This method is intended for user specific settings; if an app has
already specified defaults types in its manifest with
META_DATA_DEFAULT_FILTER_TYPES
, the defaultTypes option will be ignored.
Parameters | |
---|---|
defaultTypes |
int : A value representing the types of notifications that this listener should
receive by default
Value is either 0 or a combination of FLAG_FILTER_TYPE_CONVERSATIONS , FLAG_FILTER_TYPE_ALERTING , FLAG_FILTER_TYPE_SILENT , and FLAG_FILTER_TYPE_ONGOING |
disallowedPkgs |
List : A list of package names whose notifications should not be seen by this
listener, by default, because the listener does not process or display them, or because a
user had previously disallowed these packages in the listener app's UI
This value may be null . |
onBind
public IBinder onBind (Intent intent)
This is not the lifecycle event you are looking for.
The service should wait for the onListenerConnected()
event
before performing any operations.
Parameters | |
---|---|
intent |
Intent : The Intent that was used to bind to this service,
as given to Context.bindService . Note that any extras that were included with
the Intent at that point will not be seen here. |
Returns | |
---|---|
IBinder |
Return an IBinder through which clients can call on to the service. |
onDestroy
public void onDestroy ()
Called by the system to notify a Service that it is no longer used and is being removed. The service should clean up any resources it holds (threads, registered receivers, etc) at this point. Upon return, there will be no more calls in to this Service object and it is effectively dead. Do not call this method directly.
onInterruptionFilterChanged
public void onInterruptionFilterChanged (int interruptionFilter)
Implement this method to be notified when the
interruption filter
changed.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
interruptionFilter |
int : The current
interruption filter . |
onListenerConnected
public void onListenerConnected ()
Implement this method to learn about when the listener is enabled and connected to
the notification manager. You are safe to call getActiveNotifications()
at this time.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
onListenerDisconnected
public void onListenerDisconnected ()
Implement this method to learn about when the listener is disconnected from the
notification manager.You will not receive any events after this call, and may only
call requestRebind(android.content.ComponentName)
at this time.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
onListenerHintsChanged
public void onListenerHintsChanged (int hints)
Implement this method to be notified when the
Listener hints
change.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
hints |
int : The current listener hints . |
onNotificationChannelGroupModified
public void onNotificationChannelGroupModified (String pkg, UserHandle user, NotificationChannelGroup group, int modificationType)
Implement this method to learn about notification channel group modifications.
The caller must have device
in order to receive this callback.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
pkg |
String : The package the group belongs to. |
user |
UserHandle : The user on which the change was made. |
group |
NotificationChannelGroup : The group that has changed. |
modificationType |
int : One of NOTIFICATION_CHANNEL_OR_GROUP_ADDED ,
NOTIFICATION_CHANNEL_OR_GROUP_UPDATED ,
NOTIFICATION_CHANNEL_OR_GROUP_DELETED .
Value is NOTIFICATION_CHANNEL_OR_GROUP_ADDED , NOTIFICATION_CHANNEL_OR_GROUP_UPDATED , or NOTIFICATION_CHANNEL_OR_GROUP_DELETED |
onNotificationChannelModified
public void onNotificationChannelModified (String pkg, UserHandle user, NotificationChannel channel, int modificationType)
Implement this method to learn about notification channel modifications.
The caller must have device
in order to receive this callback.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
pkg |
String : The package the channel belongs to. |
user |
UserHandle : The user on which the change was made. |
channel |
NotificationChannel : The channel that has changed. |
modificationType |
int : One of NOTIFICATION_CHANNEL_OR_GROUP_ADDED ,
NOTIFICATION_CHANNEL_OR_GROUP_UPDATED ,
NOTIFICATION_CHANNEL_OR_GROUP_DELETED .
Value is NOTIFICATION_CHANNEL_OR_GROUP_ADDED , NOTIFICATION_CHANNEL_OR_GROUP_UPDATED , or NOTIFICATION_CHANNEL_OR_GROUP_DELETED |
onNotificationPosted
public void onNotificationPosted (StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap)
Implement this method to learn about new notifications as they are posted by apps.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
sbn |
StatusBarNotification : A data structure encapsulating the original Notification
object as well as its identifying information (tag and id) and source
(package name). |
rankingMap |
NotificationListenerService.RankingMap : The current ranking map that can be used to retrieve ranking information
for active notifications, including the newly posted one. |
onNotificationPosted
public void onNotificationPosted (StatusBarNotification sbn)
Implement this method to learn about new notifications as they are posted by apps.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
sbn |
StatusBarNotification : A data structure encapsulating the original Notification
object as well as its identifying information (tag and id) and source
(package name). |
onNotificationRankingUpdate
public void onNotificationRankingUpdate (NotificationListenerService.RankingMap rankingMap)
Implement this method to be notified when the notification ranking changes.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
rankingMap |
NotificationListenerService.RankingMap : The current ranking map that can be used to retrieve ranking information
for active notifications. |
onNotificationRemoved
public void onNotificationRemoved (StatusBarNotification sbn)
Implement this method to learn when notifications are removed.
NOTE: The StatusBarNotification
object you receive will be "light"; that is, the
result from StatusBarNotification#getNotification
may be missing some heavyweight
fields such as Notification.contentView
and
Notification.largeIcon
. However, all other fields on
StatusBarNotification
, sufficient to match this call with a prior call to
onNotificationPosted(android.service.notification.StatusBarNotification)
, will be intact.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
sbn |
StatusBarNotification : A data structure encapsulating at least the original information (tag and id)
and source (package name) used to post the Notification that
was just removed. |
onNotificationRemoved
public void onNotificationRemoved (StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap)
Implement this method to learn when notifications are removed.
NOTE: The StatusBarNotification
object you receive will be "light"; that is, the
result from StatusBarNotification#getNotification
may be missing some heavyweight
fields such as Notification.contentView
and
Notification.largeIcon
. However, all other fields on
StatusBarNotification
, sufficient to match this call with a prior call to
onNotificationPosted(android.service.notification.StatusBarNotification)
, will be intact.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
sbn |
StatusBarNotification : A data structure encapsulating at least the original information (tag and id)
and source (package name) used to post the Notification that
was just removed. |
rankingMap |
NotificationListenerService.RankingMap : The current ranking map that can be used to retrieve ranking information
for active notifications. |
onNotificationRemoved
public void onNotificationRemoved (StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap, int reason)
Implement this method to learn when notifications are removed and why.
NOTE: The StatusBarNotification
object you receive will be "light"; that is, the
result from StatusBarNotification#getNotification
may be missing some heavyweight
fields such as Notification.contentView
and
Notification.largeIcon
. However, all other fields on
StatusBarNotification
, sufficient to match this call with a prior call to
onNotificationPosted(android.service.notification.StatusBarNotification)
, will be intact.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
sbn |
StatusBarNotification : A data structure encapsulating at least the original information (tag and id)
and source (package name) used to post the Notification that
was just removed. |
rankingMap |
NotificationListenerService.RankingMap : The current ranking map that can be used to retrieve ranking information
for active notifications. |
reason |
int : Value is REASON_CLICK , REASON_CANCEL , REASON_CANCEL_ALL , REASON_ERROR , REASON_PACKAGE_CHANGED , REASON_USER_STOPPED , REASON_PACKAGE_BANNED , REASON_APP_CANCEL , REASON_APP_CANCEL_ALL , REASON_LISTENER_CANCEL , REASON_LISTENER_CANCEL_ALL , REASON_GROUP_SUMMARY_CANCELED , REASON_GROUP_OPTIMIZATION , REASON_PACKAGE_SUSPENDED , REASON_PROFILE_TURNED_OFF , REASON_UNAUTOBUNDLED , REASON_CHANNEL_BANNED , REASON_SNOOZED , REASON_TIMEOUT , REASON_CHANNEL_REMOVED , REASON_CLEAR_DATA , REASON_ASSISTANT_CANCEL , or REASON_LOCKDOWN |
onSilentStatusBarIconsVisibilityChanged
public void onSilentStatusBarIconsVisibilityChanged (boolean hideSilentStatusIcons)
Implement this method to be notified when the behavior of silent notifications in the status
bar changes. See NotificationManager#shouldHideSilentStatusBarIcons()
.
This method must be called on the thread that originally created
this UI element. This is typically the
main thread of your app.
Parameters | |
---|---|
hideSilentStatusIcons |
boolean : whether or not status bar icons should be hidden for silent
notifications |
requestInterruptionFilter
public final void requestInterruptionFilter (int interruptionFilter)
Sets the desired interruption filter
.
This is merely a request, the host may or may not choose to apply the requested interruption filter depending on other listener requests or other global state.
Listen for updates using onInterruptionFilterChanged(int)
.
Apps targeting Build.VERSION_CODES#VANILLA_ICE_CREAM
and above (with some
exceptions, such as companion device managers) cannot modify the global interruption filter.
Calling this method will instead activate or deactivate an
AutomaticZenRule
associated to the app.
The service should wait for the onListenerConnected()
event
before performing this operation.
Parameters | |
---|---|
interruptionFilter |
int : One of the INTERRUPTION_FILTER_ constants. |
requestListenerHints
public final void requestListenerHints (int hints)
Sets the desired listener hints
.
This is merely a request, the host may or may not choose to take action depending on other listener requests or other global state.
Listen for updates using onListenerHintsChanged(int)
.
The service should wait for the onListenerConnected()
event
before performing this operation.
Parameters | |
---|---|
hints |
int : One or more of the HINT_ constants. |
requestRebind
public static void requestRebind (ComponentName componentName)
Request that the listener be rebound, after a previous call to requestUnbind()
.
This method will fail for listeners that have not been granted the permission by the user.
Parameters | |
---|---|
componentName |
ComponentName |
requestUnbind
public static void requestUnbind (ComponentName componentName)
Request that the service be unbound.
This method will fail for components that are not part of the calling app.
Parameters | |
---|---|
componentName |
ComponentName : This value cannot be null . |
requestUnbind
public final void requestUnbind ()
Request that the service be unbound.
Once this is called, you will no longer receive updates and no method calls are
guaranteed to be successful, until you next receive the onListenerConnected()
event.
The service will likely be killed by the system after this call.
The service should wait for the onListenerConnected()
event
before performing this operation. I know it's tempting, but you must wait.
setNotificationsShown
public final void setNotificationsShown (String[] keys)
Inform the notification manager that these notifications have been viewed by the user. This should only be called when there is sufficient confidence that the user is looking at the notifications, such as when the notifications appear on the screen due to an explicit user interaction.
The service should wait for the onListenerConnected()
event
before performing this operation.
Parameters | |
---|---|
keys |
String : Notifications to mark as seen. |
snoozeNotification
public final void snoozeNotification (String key, long durationMs)
Inform the notification manager about snoozing a specific notification.
Use this if your listener has a user interface that allows the user to snooze a notification
for a time. It should be called after the user snoozes a single notification using
your UI; upon being informed, the notification manager will actually remove the notification
and you will get an onNotificationRemoved(android.service.notification.StatusBarNotification)
callback. When the
snoozing period expires, you will get a
onNotificationPosted(android.service.notification.StatusBarNotification, android.service.notification.NotificationListenerService.RankingMap)
callback for the
notification.
Parameters | |
---|---|
key |
String : The key of the notification to snooze |
durationMs |
long : A duration to snooze the notification for, in milliseconds. |
updateNotificationChannel
public final void updateNotificationChannel (String pkg, UserHandle user, NotificationChannel channel)
Updates a notification channel for a given package for a given user. This should only be used to reflect changes a user has made to the channel via the listener's user interface.
This method will throw a security exception if you don't have access to notifications for the given user.
The caller must have device
in order to use this method.
Parameters | |
---|---|
pkg |
String : The package the channel belongs to.
This value cannot be null . |
user |
UserHandle : The user the channel belongs to.
This value cannot be null . |
channel |
NotificationChannel : the channel to update.
This value cannot be null . |
Protected methods
attachBaseContext
protected void attachBaseContext (Context base)
Set the base context for this ContextWrapper. All calls will then be delegated to the base context. Throws IllegalStateException if a base context has already been set.
Parameters | |
---|---|
base |
Context : The new base context for this wrapper. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-06-18 UTC.