Android APIs
public abstract class

NotificationListenerService

extends Service
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.notification.NotificationListenerService

Class Overview

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 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:permission="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE">
     <intent-filter>
         <action android:name="android.service.notification.NotificationListenerService" />
     </intent-filter>
 </service>

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
int HINT_HOST_DISABLE_EFFECTS Listener hints constant - the primary device UI should disable notification sound, vibrating and other visual or aural effects.
int INTERRUPTION_FILTER_ALARMS Interruption filter constant - Alarms only interruption filter.
int INTERRUPTION_FILTER_ALL Interruption filter constant - Normal interruption filter.
int INTERRUPTION_FILTER_NONE Interruption filter constant - No interruptions filter.
int INTERRUPTION_FILTER_PRIORITY Interruption filter constant - Priority interruption filter.
int INTERRUPTION_FILTER_UNKNOWN Interruption filter constant - returned when the value is unavailable for any reason.
String SERVICE_INTERFACE The Intent that must be declared as handled by the service.
[Expand]
Inherited Constants
From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2
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 cancelNotification(String) instead. Beginning with LOLLIPOP this method will no longer cancel the notification. It will continue to cancel the notification for applications whose targetSdkVersion is earlier than LOLLIPOP.
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.
StatusBarNotification[] getActiveNotifications()
Request the list of outstanding notifications (that is, those that are visible to the current user).
StatusBarNotification[] getActiveNotifications(String[] keys)
Request one or more notifications by key.
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.
IBinder onBind(Intent intent)
Return the communication channel to the service.
void onInterruptionFilterChanged(int interruptionFilter)
Implement this method to be notified when the interruption filter changed.
void onListenerConnected()
Implement this method to learn about when the listener is enabled and connected to the notification manager.
void onListenerHintsChanged(int hints)
Implement this method to be notified when the Listener hints change.
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.
final void requestInterruptionFilter(int interruptionFilter)
Sets the desired interruption filter.
final void requestListenerHints(int hints)
Sets the desired listener hints.
final void setNotificationsShown(String[] keys)
Inform the notification manager that these notifications have been viewed by the user.
[Expand]
Inherited Methods
From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

Constants

public static final int HINT_HOST_DISABLE_EFFECTS

Added in API level 21

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)

public static final int INTERRUPTION_FILTER_ALARMS

Added in API level 23

Interruption filter constant - Alarms only interruption filter.

Constant Value: 4 (0x00000004)

public static final int INTERRUPTION_FILTER_ALL

Added in API level 21

Interruption filter constant - Normal interruption filter.

Constant Value: 1 (0x00000001)

public static final int INTERRUPTION_FILTER_NONE

Added in API level 21

Interruption filter constant - No interruptions filter.

Constant Value: 3 (0x00000003)

public static final int INTERRUPTION_FILTER_PRIORITY

Added in API level 21

Interruption filter constant - Priority interruption filter.

Constant Value: 2 (0x00000002)

public static final int INTERRUPTION_FILTER_UNKNOWN

Added in API level 23

Interruption filter constant - returned when the value is unavailable for any reason. For example, before the notification listener is connected.

Constant Value: 0 (0x00000000)

public static final String SERVICE_INTERFACE

Added in API level 18

The Intent that must be declared as handled by the service.

Constant Value: "android.service.notification.NotificationListenerService"

Public Constructors

public NotificationListenerService ()

Added in API level 18

Public Methods

public final void cancelAllNotifications ()

Added in API level 18

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(StatusBarNotification) callbacks.

public final void cancelNotification (String pkg, String tag, int id)

Added in API level 18

This method was deprecated in API level 21.
Use cancelNotification(String) instead. Beginning with LOLLIPOP this method will no longer cancel the notification. It will continue to cancel the notification for applications whose targetSdkVersion is earlier than 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(StatusBarNotification) callback.

Note: If your listener allows the user to fire a notification's contentIntent by tapping/clicking/etc., you should call this method at that time if the Notification in question has the FLAG_AUTO_CANCEL flag set.

Parameters
pkg Package of the notifying app.
tag Tag of the notification as specified by the notifying app in notify(String, int, android.app.Notification).
id ID of the notification as specified by the notifying app in notify(String, int, android.app.Notification).

public final void cancelNotification (String key)

Added in API level 21

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(StatusBarNotification) callback.

Note: If your listener allows the user to fire a notification's contentIntent by tapping/clicking/etc., you should call this method at that time if the Notification in question has the FLAG_AUTO_CANCEL flag set.

Parameters
key Notification to dismiss from getKey().

public final void cancelNotifications (String[] keys)

Added in API level 21

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.

Parameters
keys Notifications to dismiss, or null to dismiss all.

public StatusBarNotification[] getActiveNotifications ()

Added in API level 18

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.

Returns
  • An array of active notifications, sorted in natural order.

public StatusBarNotification[] getActiveNotifications (String[] keys)

Added in API level 21

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.

Parameters
keys the keys of the notifications to request
Returns
  • An array of notifications corresponding to the requested keys, in the same order as the key list.

public final int getCurrentInterruptionFilter ()

Added in API level 21

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 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).

Returns
  • One of the INTERRUPTION_FILTER_ constants, or INTERRUPTION_FILTER_UNKNOWN when unavailable.

public final int getCurrentListenerHints ()

Added in API level 21

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.

Returns
  • Zero or more of the HINT_ constants.

public NotificationListenerService.RankingMap getCurrentRanking ()

Added in API level 21

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(StatusBarNotification, RankingMap), onNotificationRemoved(StatusBarNotification, 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.

Returns

public IBinder onBind (Intent intent)

Added in API level 18

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
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
  • Return an IBinder through which clients can call on to the service.

public void onInterruptionFilterChanged (int interruptionFilter)

Added in API level 21

Implement this method to be notified when the interruption filter changed.

Parameters
interruptionFilter The current interruption filter.

public void onListenerConnected ()

Added in API level 21

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.

public void onListenerHintsChanged (int hints)

Added in API level 21

Implement this method to be notified when the Listener hints change.

Parameters
hints The current listener hints.

public void onNotificationPosted (StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap)

Added in API level 21

Implement this method to learn about new notifications as they are posted by apps.

Parameters
sbn A data structure encapsulating the original Notification object as well as its identifying information (tag and id) and source (package name).
rankingMap The current ranking map that can be used to retrieve ranking information for active notifications, including the newly posted one.

public void onNotificationPosted (StatusBarNotification sbn)

Added in API level 18

Implement this method to learn about new notifications as they are posted by apps.

Parameters
sbn A data structure encapsulating the original Notification object as well as its identifying information (tag and id) and source (package name).

public void onNotificationRankingUpdate (NotificationListenerService.RankingMap rankingMap)

Added in API level 21

Implement this method to be notified when the notification ranking changes.

Parameters
rankingMap The current ranking map that can be used to retrieve ranking information for active notifications.

public void onNotificationRemoved (StatusBarNotification sbn)

Added in API level 18

Implement this method to learn when notifications are removed.

This might occur because the user has dismissed the notification using system UI (or another notification listener) or because the app has withdrawn the notification.

NOTE: The StatusBarNotification object you receive will be "light"; that is, the result from getNotification() may be missing some heavyweight fields such as contentView and largeIcon. However, all other fields on StatusBarNotification, sufficient to match this call with a prior call to onNotificationPosted(StatusBarNotification), will be intact.

Parameters
sbn 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.

public void onNotificationRemoved (StatusBarNotification sbn, NotificationListenerService.RankingMap rankingMap)

Added in API level 21

Implement this method to learn when notifications are removed.

This might occur because the user has dismissed the notification using system UI (or another notification listener) or because the app has withdrawn the notification.

NOTE: The StatusBarNotification object you receive will be "light"; that is, the result from getNotification() may be missing some heavyweight fields such as contentView and largeIcon. However, all other fields on StatusBarNotification, sufficient to match this call with a prior call to onNotificationPosted(StatusBarNotification), will be intact.

Parameters
sbn 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 The current ranking map that can be used to retrieve ranking information for active notifications.

public final void requestInterruptionFilter (int interruptionFilter)

Added in API level 21

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).

Parameters
interruptionFilter One of the INTERRUPTION_FILTER_ constants.

public final void requestListenerHints (int hints)

Added in API level 21

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).

Parameters
hints One or more of the HINT_ constants.

public final void setNotificationsShown (String[] keys)

Added in API level 23

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.

Parameters
keys Notifications to mark as seen.