Android APIs
public abstract class

AccessibilityService

extends Service
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.accessibilityservice.AccessibilityService

Class Overview

An accessibility service runs in the background and receives callbacks by the system when AccessibilityEvents are fired. Such events denote some state transition in the user interface, for example, the focus has changed, a button has been clicked, etc. Such a service can optionally request the capability for querying the content of the active window. Development of an accessibility service requires extending this class and implementing its abstract methods.

Developer Guides

For more information about creating AccessibilityServices, read the Accessibility developer guide.

Lifecycle

The lifecycle of an accessibility service is managed exclusively by the system and follows the established service life cycle. Additionally, starting or stopping an accessibility service is triggered exclusively by an explicit user action through enabling or disabling it in the device settings. After the system binds to a service it calls onServiceConnected(). This method can be overriden by clients that want to perform post binding setup.

Declaration

An accessibility is declared as any other service in an AndroidManifest.xml but it must also specify that it handles the "android.accessibilityservice.AccessibilityService" Intent. Failure to declare this intent will cause the system to ignore the accessibility service. Additionally an accessibility service must request the BIND_ACCESSIBILITY_SERVICE permission to ensure that only the system can bind to it. Failure to declare this intent will cause the system to ignore the accessibility service. Following is an example declaration:

 <service android:name=".MyAccessibilityService"
         android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
     <intent-filter>
         <action android:name="android.accessibilityservice.AccessibilityService" />
     </intent-filter>
     . . .
 </service>

Configuration

An accessibility service can be configured to receive specific types of accessibility events, listen only to specific packages, get events from each type only once in a given time frame, retrieve window content, specify a settings activity, etc.

There are two approaches for configuring an accessibility service:

  • Providing a meta-data entry in the manifest when declaring the service. A service declaration with a meta-data tag is presented below:
     <service android:name=".MyAccessibilityService">
         <intent-filter>
             <action android:name="android.accessibilityservice.AccessibilityService" />
         </intent-filter>
         <meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibilityservice" />
     </service>

    Note: This approach enables setting all properties.

    For more details refer to SERVICE_META_DATA and <accessibility-service>.

  • Calling setServiceInfo(AccessibilityServiceInfo). Note that this method can be called any time to dynamically change the service configuration.

    Note: This approach enables setting only dynamically configurable properties: eventTypes, feedbackType, flags, notificationTimeout, packageNames

    For more details refer to AccessibilityServiceInfo.

Retrieving window content

A service can specify in its declaration that it can retrieve the active window content which is represented as a tree of AccessibilityNodeInfo. Note that declaring this capability requires that the service declares its configuration via an XML resource referenced by SERVICE_META_DATA.

For security purposes an accessibility service can retrieve only the content of the currently active window. The currently active window is defined as the window from which was fired the last event of the following types: TYPE_WINDOW_STATE_CHANGED, TYPE_VIEW_HOVER_ENTER, TYPE_VIEW_HOVER_EXIT, In other words, the last window that was shown or the last window that the user has touched during touch exploration.

The entry point for retrieving window content is through calling AccessibilityEvent.getSource() of the last received event of the above types or a previous event from the same window (see AccessibilityEvent.getWindowId()). Invoking this method will return an AccessibilityNodeInfo that can be used to traverse the window content which represented as a tree of such objects.

Note An accessibility service may have requested to be notified for a subset of the event types, thus be unaware that the active window has changed. Therefore accessibility service that would like to retrieve window content should:

  • Register for all event types with no notification timeout and keep track for the active window by calling getWindowId() of the last received event and compare this with the getWindowId() before calling retrieval methods on the latter.
  • Prepare that a retrieval method on AccessibilityNodeInfo may fail since the active window has changed and the service did not get the accessibility event yet. Note that it is possible to have a retrieval method failing even adopting the strategy specified in the previous bullet because the accessibility event dispatch is asynchronous and crosses process boundaries.

Notification strategy

For each feedback type only one accessibility service is notified. Services are notified in the order of registration. Hence, if two services are registered for the same feedback type in the same package the first one wins. It is possible however, to register a service as the default one for a given feedback type. In such a case this service is invoked if no other service was interested in the event. In other words, default services do not compete with other services and are notified last regardless of the registration order. This enables "generic" accessibility services that work reasonably well with most applications to coexist with "polished" ones that are targeted for specific applications.

Note: The event notification timeout is useful to avoid propagating events to the client too frequently since this is accomplished via an expensive interprocess call. One can think of the timeout as a criteria to determine when event generation has settled down.

Event types

Feedback types

Summary

Constants
int GESTURE_SWIPE_DOWN The user has performed a swipe down gesture on the touch screen.
int GESTURE_SWIPE_DOWN_AND_LEFT The user has performed an down and left gesture on the touch screen.
int GESTURE_SWIPE_DOWN_AND_RIGHT The user has performed an down and right gesture on the touch screen.
int GESTURE_SWIPE_DOWN_AND_UP The user has performed a swipe down and up gesture on the touch screen.
int GESTURE_SWIPE_LEFT The user has performed a swipe left gesture on the touch screen.
int GESTURE_SWIPE_LEFT_AND_DOWN The user has performed a left and down gesture on the touch screen.
int GESTURE_SWIPE_LEFT_AND_RIGHT The user has performed a swipe left and right gesture on the touch screen.
int GESTURE_SWIPE_LEFT_AND_UP The user has performed a left and up gesture on the touch screen.
int GESTURE_SWIPE_RIGHT The user has performed a swipe right gesture on the touch screen.
int GESTURE_SWIPE_RIGHT_AND_DOWN The user has performed a right and down gesture on the touch screen.
int GESTURE_SWIPE_RIGHT_AND_LEFT The user has performed a swipe right and left gesture on the touch screen.
int GESTURE_SWIPE_RIGHT_AND_UP The user has performed a right and up gesture on the touch screen.
int GESTURE_SWIPE_UP The user has performed a swipe up gesture on the touch screen.
int GESTURE_SWIPE_UP_AND_DOWN The user has performed a swipe up and down gesture on the touch screen.
int GESTURE_SWIPE_UP_AND_LEFT The user has performed an up and left gesture on the touch screen.
int GESTURE_SWIPE_UP_AND_RIGHT The user has performed an up and right gesture on the touch screen.
int GLOBAL_ACTION_BACK Action to go back.
int GLOBAL_ACTION_HOME Action to go home.
int GLOBAL_ACTION_NOTIFICATIONS Action to open the notifications.
int GLOBAL_ACTION_QUICK_SETTINGS Action to open the quick settings.
int GLOBAL_ACTION_RECENTS Action to open the recent apps.
String SERVICE_INTERFACE The Intent that must be declared as handled by the service.
String SERVICE_META_DATA Name under which an AccessibilityService component publishes information about itself.
[Expand]
Inherited Constants
From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2
Public Constructors
AccessibilityService()
Public Methods
AccessibilityNodeInfo findFocus(int focus)
Find the view that has the specified focus type.
AccessibilityNodeInfo getRootInActiveWindow()
Gets the root node in the currently active window if this service can retrieve window content.
final AccessibilityServiceInfo getServiceInfo()
Gets the an AccessibilityServiceInfo describing this AccessibilityService.
List<AccessibilityWindowInfo> getWindows()
Gets the windows on the screen.
abstract void onAccessibilityEvent(AccessibilityEvent event)
Callback for AccessibilityEvents.
final IBinder onBind(Intent intent)
Implement to return the implementation of the internal accessibility service interface.
abstract void onInterrupt()
Callback for interrupting the accessibility feedback.
final boolean performGlobalAction(int action)
Performs a global action.
final void setServiceInfo(AccessibilityServiceInfo info)
Sets the AccessibilityServiceInfo that describes this service.
Protected Methods
boolean onGesture(int gestureId)
Called by the system when the user performs a specific gesture on the touch screen.
boolean onKeyEvent(KeyEvent event)
Callback that allows an accessibility service to observe the key events before they are passed to the rest of the system.
void onServiceConnected()
This method is a part of the AccessibilityService lifecycle and is called after the system has successfully bound to the service.
[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.ComponentCallbacks
From interface android.content.ComponentCallbacks2

Constants

public static final int GESTURE_SWIPE_DOWN

Added in API level 16

The user has performed a swipe down gesture on the touch screen.

Constant Value: 2 (0x00000002)

public static final int GESTURE_SWIPE_DOWN_AND_LEFT

Added in API level 16

The user has performed an down and left gesture on the touch screen.

Constant Value: 15 (0x0000000f)

public static final int GESTURE_SWIPE_DOWN_AND_RIGHT

Added in API level 16

The user has performed an down and right gesture on the touch screen.

Constant Value: 16 (0x00000010)

public static final int GESTURE_SWIPE_DOWN_AND_UP

Added in API level 16

The user has performed a swipe down and up gesture on the touch screen.

Constant Value: 8 (0x00000008)

public static final int GESTURE_SWIPE_LEFT

Added in API level 16

The user has performed a swipe left gesture on the touch screen.

Constant Value: 3 (0x00000003)

public static final int GESTURE_SWIPE_LEFT_AND_DOWN

Added in API level 16

The user has performed a left and down gesture on the touch screen.

Constant Value: 10 (0x0000000a)

public static final int GESTURE_SWIPE_LEFT_AND_RIGHT

Added in API level 16

The user has performed a swipe left and right gesture on the touch screen.

Constant Value: 5 (0x00000005)

public static final int GESTURE_SWIPE_LEFT_AND_UP

Added in API level 16

The user has performed a left and up gesture on the touch screen.

Constant Value: 9 (0x00000009)

public static final int GESTURE_SWIPE_RIGHT

Added in API level 16

The user has performed a swipe right gesture on the touch screen.

Constant Value: 4 (0x00000004)

public static final int GESTURE_SWIPE_RIGHT_AND_DOWN

Added in API level 16

The user has performed a right and down gesture on the touch screen.

Constant Value: 12 (0x0000000c)

public static final int GESTURE_SWIPE_RIGHT_AND_LEFT

Added in API level 16

The user has performed a swipe right and left gesture on the touch screen.

Constant Value: 6 (0x00000006)

public static final int GESTURE_SWIPE_RIGHT_AND_UP

Added in API level 16

The user has performed a right and up gesture on the touch screen.

Constant Value: 11 (0x0000000b)

public static final int GESTURE_SWIPE_UP

Added in API level 16

The user has performed a swipe up gesture on the touch screen.

Constant Value: 1 (0x00000001)

public static final int GESTURE_SWIPE_UP_AND_DOWN

Added in API level 16

The user has performed a swipe up and down gesture on the touch screen.

Constant Value: 7 (0x00000007)

public static final int GESTURE_SWIPE_UP_AND_LEFT

Added in API level 16

The user has performed an up and left gesture on the touch screen.

Constant Value: 13 (0x0000000d)

public static final int GESTURE_SWIPE_UP_AND_RIGHT

Added in API level 16

The user has performed an up and right gesture on the touch screen.

Constant Value: 14 (0x0000000e)

public static final int GLOBAL_ACTION_BACK

Added in API level 16

Action to go back.

Constant Value: 1 (0x00000001)

public static final int GLOBAL_ACTION_HOME

Added in API level 16

Action to go home.

Constant Value: 2 (0x00000002)

public static final int GLOBAL_ACTION_NOTIFICATIONS

Added in API level 16

Action to open the notifications.

Constant Value: 4 (0x00000004)

public static final int GLOBAL_ACTION_QUICK_SETTINGS

Added in API level 17

Action to open the quick settings.

Constant Value: 5 (0x00000005)

public static final int GLOBAL_ACTION_RECENTS

Added in API level 16

Action to open the recent apps.

Constant Value: 3 (0x00000003)

public static final String SERVICE_INTERFACE

Added in API level 4

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

Constant Value: "android.accessibilityservice.AccessibilityService"

public static final String SERVICE_META_DATA

Added in API level 14

Name under which an AccessibilityService component publishes information about itself. This meta-data must reference an XML resource containing an <accessibility-service> tag. This is a a sample XML file configuring an accessibility service:

 <accessibility-service
     android:accessibilityEventTypes="typeViewClicked|typeViewFocused"
     android:packageNames="foo.bar, foo.baz"
     android:accessibilityFeedbackType="feedbackSpoken"
     android:notificationTimeout="100"
     android:accessibilityFlags="flagDefault"
     android:settingsActivity="foo.bar.TestBackActivity"
     android:canRetrieveWindowContent="true"
     android:canRequestTouchExplorationMode="true"
     android:canRequestEnhancedWebAccessibility="true"
     . . .
 />

Constant Value: "android.accessibilityservice"

Public Constructors

public AccessibilityService ()

Added in API level 4

Public Methods

public AccessibilityNodeInfo findFocus (int focus)

Find the view that has the specified focus type. The search is performed across all windows.

Note: In order to access the windows your service has to declare the capability to retrieve window content by setting the AccessibilityService_canRetrieveWindowContent property in its meta-data. For details refer to SERVICE_META_DATA. Also the service has to opt-in to retrieve the interactive windows by setting the FLAG_RETRIEVE_INTERACTIVE_WINDOWS flag.Otherwise, the search will be performed only in the active window.

Parameters
focus The focus to find. One of FOCUS_INPUT or FOCUS_ACCESSIBILITY.
Returns
  • The node info of the focused view or null.

public AccessibilityNodeInfo getRootInActiveWindow ()

Added in API level 16

Gets the root node in the currently active window if this service can retrieve window content. The active window is the one that the user is currently touching or the window with input focus, if the user is not touching any window.

Note: In order to access the root node your service has to declare the capability to retrieve window content by setting the AccessibilityService_canRetrieveWindowContent property in its meta-data. For details refer to SERVICE_META_DATA.

Returns
  • The root node if this service can retrieve window content.

public final AccessibilityServiceInfo getServiceInfo ()

Added in API level 16

Gets the an AccessibilityServiceInfo describing this AccessibilityService. This method is useful if one wants to change some of the dynamically configurable properties at runtime.

Returns
  • The accessibility service info.

public List<AccessibilityWindowInfo> getWindows ()

Gets the windows on the screen. This method returns only the windows that a sighted user can interact with, as opposed to all windows. For example, if there is a modal dialog shown and the user cannot touch anything behind it, then only the modal window will be reported (assuming it is the top one). For convenience the returned windows are ordered in a descending layer order, which is the windows that are higher in the Z-order are reported first.

Note: In order to access the windows your service has to declare the capability to retrieve window content by setting the AccessibilityService_canRetrieveWindowContent property in its meta-data. For details refer to SERVICE_META_DATA. Also the service has to opt-in to retrieve the interactive windows by setting the FLAG_RETRIEVE_INTERACTIVE_WINDOWS flag.

Returns
  • The windows if there are windows and the service is can retrieve them, otherwise an empty list.

public abstract void onAccessibilityEvent (AccessibilityEvent event)

Added in API level 4

Callback for AccessibilityEvents.

Parameters
event An event.

public final IBinder onBind (Intent intent)

Added in API level 4

Implement to return the implementation of the internal accessibility service interface.

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 abstract void onInterrupt ()

Added in API level 4

Callback for interrupting the accessibility feedback.

public final boolean performGlobalAction (int action)

Added in API level 16

Performs a global action. Such an action can be performed at any moment regardless of the current application or user location in that application. For example going back, going home, opening recents, etc.

Parameters
action The action to perform.
Returns
  • Whether the action was successfully performed.

public final void setServiceInfo (AccessibilityServiceInfo info)

Added in API level 4

Sets the AccessibilityServiceInfo that describes this service.

Note: You can call this method any time but the info will be picked up after the system has bound to this service and when this method is called thereafter.

Parameters
info The info.

Protected Methods

protected boolean onGesture (int gestureId)

Added in API level 16

Called by the system when the user performs a specific gesture on the touch screen. Note: To receive gestures an accessibility service must request that the device is in touch exploration mode by setting the FLAG_REQUEST_TOUCH_EXPLORATION_MODE flag.

Parameters
gestureId The unique id of the performed gesture.
Returns
  • Whether the gesture was handled.

protected boolean onKeyEvent (KeyEvent event)

Added in API level 18

Callback that allows an accessibility service to observe the key events before they are passed to the rest of the system. This means that the events are first delivered here before they are passed to the device policy, the input method, or applications.

Note: It is important that key events are handled in such a way that the event stream that would be passed to the rest of the system is well-formed. For example, handling the down event but not the up event and vice versa would generate an inconsistent event stream.

Note: The key events delivered in this method are copies and modifying them will have no effect on the events that will be passed to the system. This method is intended to perform purely filtering functionality.

Parameters
event The event to be processed.
Returns
  • If true then the event will be consumed and not delivered to applications, otherwise it will be delivered as usual.

protected void onServiceConnected ()

Added in API level 4

This method is a part of the AccessibilityService lifecycle and is called after the system has successfully bound to the service. If is convenient to use this method for setting the AccessibilityServiceInfo.