- Manifest Declarations and Permissions
- AccessibilityService Methods
- Getting Event Details
- Example Code
An accessibility service is an application that provides user interface enhancements to assist users with disabilities, or who may temporarily be unable to fully interact with a device. For example, users who are driving, taking care of a young child or attending a very loud party might need additional or alternative interface feedback.
Android provides standard accessibility services, including TalkBack, and developers can create and distribute their own services. This document explains the basics of building an accessibility service.
The ability for you to build and deploy accessibility services was introduced with Android 1.6 (API Level 4) and received significant improvements with Android 4.0 (API Level 14). The Android Support Library was also updated with the release of Android 4.0 to provide support for these enhanced accessibility features back to Android 1.6. Developers aiming for widely compatible accessibility services are encouraged to use the Support Library and develop for the more advanced accessibility features introduced in Android 4.0.
Manifest Declarations and Permissions
Applications that provide accessibility services must include specific declarations in their application manifests in order to be treated as an accessibility service by an Android system. This section explains the required and optional settings for accessibility services.
Accessibility service declaration
In order to be treated as an accessibility service, your application must include the
service element (rather than the
activity element) within the
element in its manifest. In addition, within the
service element, you must also include an
accessibility service intent filter, as shown in the following sample:
<application> <service android:name=".MyAccessibilityService" android:label="@string/accessibility_service_label"> <intent-filter> <action android:name="android.accessibilityservice.AccessibilityService" /> </intent-filter> </service> </application>
These declarations are required for all accessibility services deployed on Android 1.6 (API Level 4) or higher.
Accessibility service configuration
Accessibility services must also provide a configuration which specifies the types of
accessibility events that the service handles and additional information about the service. The
configuration of an accessibility service is contained in the
AccessibilityServiceInfo class. Your service can build and set a
configuration using an instance of this class and
setServiceInfo() at runtime.
However, not all configuration options are available using this method.
Beginning with Android 4.0, you can include a
<meta-data> element in your manifest
with a reference to a configuration file, which allows you to set the full range of options for
your accessibility service, as shown in the following example:
<service android:name=".MyAccessibilityService"> ... <meta-data android:name="android.accessibilityservice" android:resource="@xml/accessibility_service_config" /> </service>
This meta-data element refers to an XML file that you create in your application’s resource
<project_dir>/res/xml/accessibility_service_config.xml). The following code
shows example contents for the service configuration file:
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android" android:description="@string/accessibility_service_description" android:packageNames="com.example.android.apis" android:accessibilityEventTypes="typeAllMask" android:accessibilityFlags="flagDefault" android:accessibilityFeedbackType="feedbackSpoken" android:notificationTimeout="100" android:canRetrieveWindowContent="true" android:settingsActivity="com.example.android.accessibility.ServiceSettingsActivity" />
One of the most important functions of the accessibility service configuration parameters is to allow you to specify what types of accessibility events your service can handle. Being able to specify this information enables accessibility services to cooperate with each other, and allows you as a developer the flexibility to handle only specific events types from specific applications. The event filtering can include the following criteria:
- Package Names - Specify the package names of applications whose accessibility
events you want your service to handle. If this parameter is omitted, your accessibility service is
considered available to service accessibility events for any application. This parameter can be set
in the accessibility service configuration files with the
android:packageNamesattribute as a comma-separated list, or set using the
- Event Types - Specify the types of accessibility events you want your service
to handle. This parameter can be set in the accessibility service configuration files with the
android:accessibilityEventTypesattribute as a comma-separated list, or set using the
For more information about the XML attributes which can be used in the accessibility service configuration file, follow these links to the reference documentation:
For more information about which configuration settings can be dynamically set at runtime, see
AccessibilityServiceInfo reference documentation.
An application that provides accessibility service must extend the
AccessibilityService class and override the following methods from
that class. These methods are presented in the order in which they are called by the Android system,
from when the service is started
while it is running (
onInterrupt()) to when it is
shut down (
onServiceConnected()- (optional) This system calls this method when it successfully connects to your accessibility service. Use this method to do any one-time setup steps for your service, including connecting to user feedback system services, such as the audio manager or device vibrator. If you want to set the configuration of your service at runtime or make one-time adjustments, this is a convenient location from which to call
onAccessibilityEvent()- (required) This method is called back by the system when it detects an
AccessibilityEventthat matches the event filtering parameters specified by your accessibility service. For example, when the user clicks a button or focuses on a user interface control in an application for which your accessibility service is providing feedback. When this happens, the system calls this method of your service with the associated
AccessibilityEvent, which you can then interpret and provide feedback to the user. This method may be called many times over the lifecycle of your service.
onInterrupt()- (required) This method is called when the system wants to interrupt the feedback your service is providing, usually in response to a user taking action, such as moving focus to a different user interface control than the one for which you are currently providing feedback. This method may be called many times over the lifecycle of your service.
onUnbind()- (optional) This method is called when the system is about to shutdown the accessibility service. Use this method to do any one-time shutdown procedures, including de-allocating user feedback system services, such as the audio manager or device vibrator.
These callback methods provide the basic structure for your accessibility service. It is up to
you to decide on how to process data provided by the Android system in the form of
AccessibilityEvent objects and provide feedback to the user.
Getting Event Details
The Android system provides information to accessibility services about the user interface
AccessibilityEvent objects. Prior to Android
4.0, the information available in an accessibility event, while providing a significant amount of
detail about a user interface control selected by the user, typically provided limited contextual
information. In many cases, this missing context information might be critical to understanding the
meaning of the selected control.
A typical example of an interface where context is of critical importance is a calendar or day planner. If a user selects a 4:00 PM time slot in a Monday to Friday day list and the accessibility service announces “4 PM”, but fails to indicate this is a Friday a Monday, the month or day, this is hardly ideal feedback for the user. In this case, the context of a user interface control is of critical importance to a user who wants to schedule a meeting.
Android 4.0 significantly extends the amount of information that an accessibility service can obtain about an user interface interaction by composing accessibility events based on the view hierarchy. A view hierarchy is the set of user interface components that contain the component (its parents) and the user interface elements that may be contained by that component (its children). In this way, the Android system can provide much richer detail about accessibility events, allowing accessibility services to provide more useful feedback to users.
An accessibility service gets information about an user interface event through an
AccessibilityEvent passed by the system to the service’s
onAccessibilityEvent() callback method. This object provides details about the event, including the
type of object being acted upon, its descriptive text and other details. Starting in Android 4.0
(and supported in previous releases through the
AccessibilityEventCompat object in the Support Library), you
can obtain additional information about the event using these calls:
getRecord(int)- These methods allow you to retrieve the set of
AccessibilityRecordobjects which contributed to the
AccessibilityEventpassed to you by the system, which can provide more context for your accessibility service.
AccessibilityEvent.getSource()- This method returns an
AccessibilityNodeInfoobject. This object allows you to request the parents and children of the component that originated the accessibility event and investigate their contents and state in order to provide
Important: The ability to investigate the full view hierarchy from an
AccessibilityEventpotentially exposes private user information to your accessibility service. For this reason, your service must request this level of access through the accessibility service configuration XML file, by including the
canRetrieveWindowContentattribute and setting it to
true. If you do not include this setting in your service configuration xml file, calls to
The API Demo project contains two samples which can be used as a starting point for generating
- This service is based on the original implementation of
AccessibilityServiceand can be used as a base for developing basic accessibility services that are compatible with Android 1.6 (API Level 4) and higher.
- This service is based on the enhanced accessibility APIs introduced in Android 4.0 (API Level
14). However, you can use the Android Support
Libary to substitute classes introduced in later API levels (e.g.,
AccessibilityNodeInfo) with equivalent support package classes (e.g.,
AccessibilityNodeInfoCompat) to make this example work with API versions back to Android 1.6 (API Level 4).