Crea il tuo servizio di accessibilità

Un servizio di accessibilità è un'app che migliora l'interfaccia utente per assistere gli utenti con disabilità o che potrebbero temporaneamente non essere in grado di interagire completamente con un dispositivo. Ad esempio, gli utenti che guidano, hanno cura di un bambino o partecipano a una festa molto rumorosa potrebbero aver bisogno di feedback aggiuntivi o alternativi sull'interfaccia.

Android fornisce servizi di accessibilità standard, tra cui TalkBack, e gli sviluppatori possono creare e distribuire i propri servizi. Questo documento illustra le nozioni di base per la creazione di un servizio di accessibilità.

Nota: la tua app deve utilizzare i servizi di accessibilità a livello di piattaforma solo per aiutare gli utenti con disabilità a interagire con l'app.

Un servizio di accessibilità può essere integrato in una normale app o creato come progetto Android autonomo. I passaggi per creare il servizio sono gli stessi in entrambe le situazioni.

Crea il tuo servizio di accessibilità

All'interno del progetto, crea un corso che espanda AccessibilityService:

Kotlin

package com.example.android.apis.accessibility

import android.accessibilityservice.AccessibilityService
import android.view.accessibility.AccessibilityEvent

class MyAccessibilityService : AccessibilityService() {
...
    override fun onInterrupt() {}

    override fun onAccessibilityEvent(event: AccessibilityEvent?) {}
...
}

Java

package com.example.android.apis.accessibility;

import android.accessibilityservice.AccessibilityService;
import android.view.accessibility.AccessibilityEvent;

public class MyAccessibilityService extends AccessibilityService {
...
    @Override
    public void onAccessibilityEvent(AccessibilityEvent event) {
    }

    @Override
    public void onInterrupt() {
    }

...
}

Se crei un nuovo progetto per questo Service e non prevedi di associare un'app, puoi rimuovere la classe Activity iniziale dalla fonte.

Dichiarazioni e autorizzazioni del file manifest

Le app che forniscono servizi di accessibilità devono includere dichiarazioni specifiche nei file manifest delle app per essere trattate come servizi di accessibilità dal sistema Android. Questa sezione spiega le impostazioni obbligatorie e facoltative per i servizi di accessibilità.

Dichiarazione relativa al servizio di accessibilità

Affinché la tua app venga considerata come un servizio di accessibilità, includi un elemento service, anziché l'elemento activity, nell'elemento application nel file manifest. Inoltre, all'interno dell'elemento service, includi un filtro per intent del servizio di accessibilità. Il file manifest deve inoltre proteggere il servizio aggiungendo l'autorizzazione BIND_ACCESSIBILITY_SERVICE per garantire che solo il sistema possa eseguire l'associazione al servizio. Ecco un esempio:

  <application>
    <service android:name=".MyAccessibilityService"
        android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"
        android:label="@string/accessibility_service_label">
      <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
      </intent-filter>
    </service>
  </application>

Configurazione del servizio di accessibilità

I servizi di accessibilità devono fornire una configurazione che specifichi i tipi di eventi di accessibilità gestiti dal servizio e informazioni aggiuntive sul servizio. La configurazione di un servizio di accessibilità è contenuta nella classe AccessibilityServiceInfo. Il tuo servizio può creare e impostare una configurazione utilizzando un'istanza di questa classe e setServiceInfo() in fase di runtime. Tuttavia, non tutte le opzioni di configurazione sono disponibili utilizzando questo metodo.

Puoi includere un elemento <meta-data> nel file manifest con un riferimento a un file di configurazione, che ti consente di impostare la gamma completa di opzioni per il tuo servizio di accessibilità, come mostrato nell'esempio seguente:

<service android:name=".MyAccessibilityService">
  ...
  <meta-data
    android:name="android.accessibilityservice"
    android:resource="@xml/accessibility_service_config" />
</service>

Questo elemento <meta-data> fa riferimento a un file XML che crei nella directory delle risorse dell'app: <project_dir>/res/xml/accessibility_service_config.xml>. Il codice seguente mostra un esempio dei contenuti del file di configurazione del servizio:

<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"
/>

Per ulteriori informazioni sugli attributi XML che possono essere utilizzati nel file di configurazione del servizio di accessibilità, consulta la seguente documentazione di riferimento:

• android:description
• android:packageNames
• android:accessibilityEventTypes
• android:accessibilityFlags
• android:accessibilityFeedbackType
• android:notificationTimeout
• android:canRetrieveWindowContent
• android:settingsActivity

Per ulteriori informazioni sulle impostazioni di configurazione che possono essere impostate dinamicamente in fase di runtime, consulta la documentazione di riferimento di AccessibilityServiceInfo.

Configurare il servizio di accessibilità

Considera quanto segue quando imposti le variabili di configurazione per il servizio di accessibilità per indicare al sistema come e quando eseguire:

• A quali tipi di eventi vuoi che risponda?
• Il servizio deve essere attivo per tutte le app o solo per i nomi di pacchetto specifici?
• Quali tipi di feedback diversi utilizza?

Hai due opzioni per impostare queste variabili. L'opzione compatibile con le versioni precedenti è impostarle nel codice utilizzando setServiceInfo(android.accessibilityservice.AccessibilityServiceInfo) A questo scopo, sostituisci il metodo onServiceConnected() e configura lì il tuo servizio, come mostrato nell'esempio seguente:

Kotlin

override fun onServiceConnected() {
    info.apply {
        // Set the type of events that this service wants to listen to. Others
        // aren't passed to this service.
        eventTypes = AccessibilityEvent.TYPE_VIEW_CLICKED or AccessibilityEvent.TYPE_VIEW_FOCUSED

        // If you only want this service to work with specific apps, set their
        // package names here. Otherwise, when the service is activated, it
        // listens to events from all apps.
        packageNames = arrayOf("com.example.android.myFirstApp", "com.example.android.mySecondApp")

        // Set the type of feedback your service provides.
        feedbackType = AccessibilityServiceInfo.FEEDBACK_SPOKEN

        // Default services are invoked only if no package-specific services are
        // present for the type of AccessibilityEvent generated. This service is
        // app-specific, so the flag isn't necessary. For a general-purpose
        // service, consider setting the DEFAULT flag.

        // flags = AccessibilityServiceInfo.DEFAULT;

        notificationTimeout = 100
    }

    this.serviceInfo = info

}

Java

@Override
public void onServiceConnected() {
    // Set the type of events that this service wants to listen to. Others
    // aren't passed to this service.
    info.eventTypes = AccessibilityEvent.TYPE_VIEW_CLICKED |
            AccessibilityEvent.TYPE_VIEW_FOCUSED;

    // If you only want this service to work with specific apps, set their
    // package names here. Otherwise, when the service is activated, it listens
    // to events from all apps.
    info.packageNames = new String[]
            {"com.example.android.myFirstApp", "com.example.android.mySecondApp"};

    // Set the type of feedback your service provides.
    info.feedbackType = AccessibilityServiceInfo.FEEDBACK_SPOKEN;

    // Default services are invoked only if no package-specific services are
    // present for the type of AccessibilityEvent generated. This service is
    // app-specific, so the flag isn't necessary. For a general-purpose service,
    // consider setting the DEFAULT flag.

    // info.flags = AccessibilityServiceInfo.DEFAULT;

    info.notificationTimeout = 100;

    this.setServiceInfo(info);

}

La seconda opzione consiste nel configurare il servizio utilizzando un file XML. Alcune opzioni di configurazione, ad esempio canRetrieveWindowContent, sono disponibili solo se il servizio viene configurato utilizzando XML. Le opzioni di configurazione dell'esempio precedente hanno il seguente aspetto quando vengono definite utilizzando XML:

<accessibility-service
     android:accessibilityEventTypes="typeViewClicked|typeViewFocused"
     android:packageNames="com.example.android.myFirstApp, com.example.android.mySecondApp"
     android:accessibilityFeedbackType="feedbackSpoken"
     android:notificationTimeout="100"
     android:settingsActivity="com.example.android.apis.accessibility.TestBackActivity"
     android:canRetrieveWindowContent="true"
/>

Se utilizzi XML, fallo riferimento nel file manifest aggiungendo un tag <meta-data> alla dichiarazione del servizio che rimandi al file XML. Se archivi il file XML in res/xml/serviceconfig.xml, il nuovo tag avrà il seguente aspetto:

<service android:name=".MyAccessibilityService">
     <intent-filter>
         <action android:name="android.accessibilityservice.AccessibilityService" />
     </intent-filter>
     <meta-data android:name="android.accessibilityservice"
     android:resource="@xml/serviceconfig" />
</service>

Metodi del servizio di accessibilità

Un servizio di accessibilità deve estendere la classe AccessibilityService e sostituire i seguenti metodi di questa classe. Questi metodi sono presentati nell'ordine in cui il sistema Android li chiama: dall'avvio del servizio (onServiceConnected()), all'esecuzione (onAccessibilityEvent(), onInterrupt()) fino all'arresto del servizio (onUnbind()).

• onServiceConnected(): (facoltativo) il sistema chiama questo metodo quando si connette al servizio di accessibilità. Utilizza questo metodo per eseguire passaggi di configurazione una tantum per il tuo servizio, inclusa la connessione ai servizi di sistema per il feedback degli utenti, come la gestione audio o la vibrazione del dispositivo. Se vuoi impostare la configurazione del tuo servizio in fase di runtime o apportare modifiche una tantum, questa è una posizione pratica per chiamare setServiceInfo().

• onAccessibilityEvent(): (obbligatorio) il sistema richiama questo metodo quando rileva un AccessibilityEvent che corrisponde ai parametri di filtro degli eventi specificati dal servizio di accessibilità, ad esempio quando l'utente tocca un pulsante o si concentra su un controllo dell'interfaccia utente in un'app per cui il servizio di accessibilità fornisce feedback. Quando il sistema chiama questo metodo, trasmette il valore AccessibilityEvent associato, che il servizio può quindi interpretare e utilizzare per fornire feedback all'utente. Questo metodo può essere chiamato molte volte durante il ciclo di vita del tuo servizio.

• onInterrupt(): (obbligatorio) il sistema chiama questo metodo quando vuole interrompere il feedback fornito dal servizio, solitamente in risposta a un'azione dell'utente, ad esempio lo spostamento dello stato attivo su un controllo diverso. Questo metodo può essere chiamato molte volte durante il ciclo di vita del servizio.

• onUnbind(): (facoltativo) il sistema chiama questo metodo quando sta per arrestare il servizio di accessibilità. Utilizza questo metodo per eseguire procedure di arresto una tantum, inclusa la rimozione dell'allocazione dei servizi di sistema di feedback degli utenti, come il gestore audio o la vibrazione del dispositivo.

Questi metodi di callback forniscono la struttura di base del servizio di accessibilità. Puoi decidere come elaborare i dati forniti dal sistema Android sotto forma di oggetti AccessibilityEvent e fornire feedback all'utente. Per ulteriori informazioni su come ottenere informazioni da un evento di accessibilità, vedi Trovare i dettagli di un evento.

Registrati agli eventi di accessibilità

Una delle funzioni più importanti dei parametri di configurazione del servizio di accessibilità consente di specificare i tipi di eventi di accessibilità che il servizio può gestire. Specificare queste informazioni consente ai servizi di accessibilità di cooperare tra loro e ti offre la flessibilità di gestire solo tipi di eventi specifici di app specifiche. Il filtro eventi può includere i seguenti criteri:

• Nomi dei pacchetti: specifica i nomi dei pacchetti delle app di cui devono essere gestiti gli eventi di accessibilità da gestire. Se questo parametro viene omesso, il servizio di accessibilità viene considerato disponibile per gli eventi di accessibilità del servizio per qualsiasi app. Puoi impostare questo parametro nei file di configurazione del servizio di accessibilità con l'attributo android:packageNames come elenco separato da virgole o utilizzare il membro AccessibilityServiceInfo.packageNames.

• Tipi di evento: specifica i tipi di eventi di accessibilità che il servizio deve gestire. Puoi impostare questo parametro nei file di configurazione del servizio di accessibilità con l'attributo android:accessibilityEventTypes sotto forma di elenco separato dal carattere |, ad esempio accessibilityEventTypes="typeViewClicked|typeViewFocused". In alternativa, puoi impostarlo utilizzando il membro AccessibilityServiceInfo.eventTypes.

Quando configuri il servizio di accessibilità, considera attentamente gli eventi che il servizio può gestire e registrati solo a questi eventi. Poiché gli utenti possono attivare più di un servizio di accessibilità alla volta, il servizio non deve consumare eventi che non è in grado di gestire. Ricorda che altri servizi potrebbero gestire questi eventi per migliorare l'esperienza utente.

Volume Accessibilità

I dispositivi con Android 8.0 (livello API 26) e versioni successive includono la categoria del volume STREAM_ACCESSIBILITY, che consente di controllare il volume dell'uscita audio del servizio di accessibilità indipendentemente dagli altri suoni sul dispositivo.

I servizi di accessibilità possono utilizzare questo tipo di stream impostando l'opzione FLAG_ENABLE_ACCESSIBILITY_VOLUME. Puoi quindi modificare il volume audio di accessibilità del dispositivo chiamando il metodo adjustStreamVolume() sull'istanza di AudioManager del dispositivo.

Il seguente snippet di codice mostra in che modo un servizio di accessibilità può utilizzare la categoria di volume STREAM_ACCESSIBILITY:

Kotlin

import android.media.AudioManager.*

class MyAccessibilityService : AccessibilityService() {

    private val audioManager = getSystemService(AUDIO_SERVICE) as AudioManager

    override fun onAccessibilityEvent(accessibilityEvent: AccessibilityEvent) {
        if (accessibilityEvent.source.text == "Increase volume") {
            audioManager.adjustStreamVolume(AudioManager.STREAM_ACCESSIBILITY, ADJUST_RAISE, 0)
        }
    }
}

Java

import static android.media.AudioManager.*;

public class MyAccessibilityService extends AccessibilityService {
    private AudioManager audioManager =
            (AudioManager) getSystemService(AUDIO_SERVICE);

    @Override
    public void onAccessibilityEvent(AccessibilityEvent accessibilityEvent) {
        AccessibilityNodeInfo interactedNodeInfo =
                accessibilityEvent.getSource();
        if (interactedNodeInfo.getText().equals("Increase volume")) {
            audioManager.adjustStreamVolume(AudioManager.STREAM_ACCESSIBILITY,
                ADJUST_RAISE, 0);
        }
    }
}

Per ulteriori informazioni, guarda il video della sessione Novità sull'accessibilità Android di Google I/O 2017, che inizia alle 06:35.

Scorciatoia Accessibilità

Sui dispositivi con Android 8.0 (livello API 26) e versioni successive, gli utenti possono attivare e disattivare il servizio di accessibilità preferito da qualsiasi schermata tenendo premuti entrambi i tasti del volume contemporaneamente. Anche se questa scorciatoia attiva e disattiva TalkBack per impostazione predefinita, gli utenti possono configurare il pulsante in modo da attivare e disattivare qualsiasi servizio installato sul dispositivo.

Affinché gli utenti possano accedere a un determinato servizio di accessibilità dalla scorciatoia di accessibilità, il servizio deve richiedere la funzione in fase di runtime.

Per ulteriori informazioni, guarda il video della sessione Novità sull'accessibilità Android di Google I/O 2017, che inizia alle 13:25.

Pulsante Accessibilità

Sui dispositivi che utilizzano un'area di navigazione sottoposta a rendering software e con Android 8.0 (livello API 26) o versioni successive, il lato destro della barra di navigazione include un pulsante Accessibilità. Quando gli utenti premeno questo pulsante, possono richiamare uno dei vari servizi e funzioni di accessibilità abilitate, a seconda dei contenuti attualmente mostrati sullo schermo.

Per consentire agli utenti di richiamare un determinato servizio di accessibilità utilizzando il pulsante di accessibilità, il servizio deve aggiungere il flag FLAG_REQUEST_ACCESSIBILITY_BUTTON nell'attributo android:accessibilityFlags di un oggetto AccessibilityServiceInfo. Il servizio può quindi registrare i callback utilizzando registerAccessibilityButtonCallback().

Nota: questa funzionalità è disponibile solo sui dispositivi che forniscono un'area di navigazione con rendering software. I servizi devono sempre utilizzare isAccessibilityButtonAvailable() e rispondere ai cambiamenti in base alla disponibilità del pulsante Accessibilità implementando onAvailabilityChanged(). In questo modo, gli utenti possono sempre accedere alla funzionalità del servizio, anche se il pulsante di accessibilità non è supportato o non è disponibile.

Il seguente snippet di codice mostra come configurare un servizio di accessibilità per rispondere all'utente che preme il pulsante Accessibilità:

Kotlin

private var mAccessibilityButtonController: AccessibilityButtonController? = null
private var accessibilityButtonCallback:
        AccessibilityButtonController.AccessibilityButtonCallback? = null
private var mIsAccessibilityButtonAvailable: Boolean = false

override fun onServiceConnected() {
    mAccessibilityButtonController = accessibilityButtonController
    mIsAccessibilityButtonAvailable =
            mAccessibilityButtonController?.isAccessibilityButtonAvailable ?: false

    if (!mIsAccessibilityButtonAvailable) return

    serviceInfo = serviceInfo.apply {
        flags = flags or AccessibilityServiceInfo.FLAG_REQUEST_ACCESSIBILITY_BUTTON
    }

    accessibilityButtonCallback =
        object : AccessibilityButtonController.AccessibilityButtonCallback() {
            override fun onClicked(controller: AccessibilityButtonController) {
                Log.d("MY_APP_TAG", "Accessibility button pressed!")

                // Add custom logic for a service to react to the
                // accessibility button being pressed.
            }

            override fun onAvailabilityChanged(
                    controller: AccessibilityButtonController,
                    available: Boolean
            ) {
                if (controller == mAccessibilityButtonController) {
                    mIsAccessibilityButtonAvailable = available
                }
            }
    }

    accessibilityButtonCallback?.also {
        mAccessibilityButtonController?.registerAccessibilityButtonCallback(it, null)
    }
}

Java

private AccessibilityButtonController accessibilityButtonController;
private AccessibilityButtonController
        .AccessibilityButtonCallback accessibilityButtonCallback;
private boolean mIsAccessibilityButtonAvailable;

@Override
protected void onServiceConnected() {
    accessibilityButtonController = getAccessibilityButtonController();
    mIsAccessibilityButtonAvailable =
            accessibilityButtonController.isAccessibilityButtonAvailable();

    if (!mIsAccessibilityButtonAvailable) {
        return;
    }

    AccessibilityServiceInfo serviceInfo = getServiceInfo();
    serviceInfo.flags
            |= AccessibilityServiceInfo.FLAG_REQUEST_ACCESSIBILITY_BUTTON;
    setServiceInfo(serviceInfo);

    accessibilityButtonCallback =
        new AccessibilityButtonController.AccessibilityButtonCallback() {
            @Override
            public void onClicked(AccessibilityButtonController controller) {
                Log.d("MY_APP_TAG", "Accessibility button pressed!");

                // Add custom logic for a service to react to the
                // accessibility button being pressed.
            }

            @Override
            public void onAvailabilityChanged(
              AccessibilityButtonController controller, boolean available) {
                if (controller.equals(accessibilityButtonController)) {
                    mIsAccessibilityButtonAvailable = available;
                }
            }
        };

    if (accessibilityButtonCallback != null) {
        accessibilityButtonController.registerAccessibilityButtonCallback(
                accessibilityButtonCallback, null);
    }
}

Per ulteriori informazioni, guarda il video della sessione Novità sull'accessibilità Android di Google I/O 2017, che inizia alle 16:28.

Gesti con sensore di impronte

I servizi di accessibilità sui dispositivi con Android 8.0 (livello API 26) o versioni successive possono rispondere agli scorrimenti direzionali (su, giù, sinistra e destra) lungo il sensore di impronte digitali di un dispositivo. Per configurare un servizio per ricevere callback su queste interazioni, completa la seguente sequenza:

1. Dichiara l'autorizzazione USE_BIOMETRIC e la funzionalità di CAPABILITY_CAN_REQUEST_FINGERPRINT_GESTURES.
2. Imposta il flag FLAG_REQUEST_FINGERPRINT_GESTURES nell'attributo android:accessibilityFlags.
3. Registrati per le richiamate utilizzando registerFingerprintGestureCallback().

Nota: consenti agli utenti di disattivare il supporto dei gesti con impronta da parte di un servizio di accessibilità. Anche se più servizi di accessibilità possono ascoltare contemporaneamente i gesti delle impronte, ciò causa un conflitto tra i servizi.

Tieni presente che non tutti i dispositivi includono sensori di impronte digitali. Per capire se un dispositivo supporta il sensore, utilizza il metodo isHardwareDetected(). Anche su un dispositivo che include un sensore di impronte digitali, il servizio non può utilizzare il sensore quando è in uso per l'autenticazione. Per identificare quando il sensore è disponibile, chiama il metodo isGestureDetectionAvailable() e implementa il callback di onGestureDetectionAvailabilityChanged().

Lo snippet di codice riportato di seguito mostra un esempio di utilizzo dei gesti con l'impronta per spostarsi sul tabellone di gioco virtuale:

// AndroidManifest.xml
<manifest ... >
    <uses-permission android:name="android.permission.USE_FINGERPRINT" />
    ...
    <application>
        <service android:name="com.example.MyFingerprintGestureService" ... >
            <meta-data
                android:name="android.accessibilityservice"
                android:resource="@xml/myfingerprintgestureservice" />
        </service>
    </application>
</manifest>

// myfingerprintgestureservice.xml
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:accessibilityFlags=" ... |flagRequestFingerprintGestures"
    android:canRequestFingerprintGestures="true"
    ... />

Kotlin

// MyFingerprintGestureService.kt
import android.accessibilityservice.FingerprintGestureController.*

class MyFingerprintGestureService : AccessibilityService() {

    private var gestureController: FingerprintGestureController? = null
    private var fingerprintGestureCallback:
            FingerprintGestureController.FingerprintGestureCallback? = null
    private var mIsGestureDetectionAvailable: Boolean = false

    override fun onCreate() {
        gestureController = fingerprintGestureController
        mIsGestureDetectionAvailable = gestureController?.isGestureDetectionAvailable ?: false
    }

    override fun onServiceConnected() {
        if (mFingerprintGestureCallback != null || !mIsGestureDetectionAvailable) return

        fingerprintGestureCallback =
                object : FingerprintGestureController.FingerprintGestureCallback() {
                    override fun onGestureDetected(gesture: Int) {
                        when (gesture) {
                            FINGERPRINT_GESTURE_SWIPE_DOWN -> moveGameCursorDown()
                            FINGERPRINT_GESTURE_SWIPE_LEFT -> moveGameCursorLeft()
                            FINGERPRINT_GESTURE_SWIPE_RIGHT -> moveGameCursorRight()
                            FINGERPRINT_GESTURE_SWIPE_UP -> moveGameCursorUp()
                            else -> Log.e(MY_APP_TAG, "Error: Unknown gesture type detected!")
                        }
                    }

                    override fun onGestureDetectionAvailabilityChanged(available: Boolean) {
                        mIsGestureDetectionAvailable = available
                    }
                }

        fingerprintGestureCallback?.also {
            gestureController?.registerFingerprintGestureCallback(it, null)
        }
    }
}

Java

// MyFingerprintGestureService.java
import static android.accessibilityservice.FingerprintGestureController.*;

public class MyFingerprintGestureService extends AccessibilityService {
    private FingerprintGestureController gestureController;
    private FingerprintGestureController
            .FingerprintGestureCallback fingerprintGestureCallback;
    private boolean mIsGestureDetectionAvailable;

    @Override
    public void onCreate() {
        gestureController = getFingerprintGestureController();
        mIsGestureDetectionAvailable =
                gestureController.isGestureDetectionAvailable();
    }

    @Override
    protected void onServiceConnected() {
        if (fingerprintGestureCallback != null
                || !mIsGestureDetectionAvailable) {
            return;
        }

        fingerprintGestureCallback =
               new FingerprintGestureController.FingerprintGestureCallback() {
            @Override
            public void onGestureDetected(int gesture) {
                switch (gesture) {
                    case FINGERPRINT_GESTURE_SWIPE_DOWN:
                        moveGameCursorDown();
                        break;
                    case FINGERPRINT_GESTURE_SWIPE_LEFT:
                        moveGameCursorLeft();
                        break;
                    case FINGERPRINT_GESTURE_SWIPE_RIGHT:
                        moveGameCursorRight();
                        break;
                    case FINGERPRINT_GESTURE_SWIPE_UP:
                        moveGameCursorUp();
                        break;
                    default:
                        Log.e(MY_APP_TAG,
                                  "Error: Unknown gesture type detected!");
                        break;
                }
            }

            @Override
            public void onGestureDetectionAvailabilityChanged(boolean available) {
                mIsGestureDetectionAvailable = available;
            }
        };

        if (fingerprintGestureCallback != null) {
            gestureController.registerFingerprintGestureCallback(
                    fingerprintGestureCallback, null);
        }
    }
}

Per ulteriori informazioni, guarda il video della sessione Novità sull'accessibilità Android di Google I/O 2017, che inizia alle 09:03.

Sintesi vocale multilingue

A partire da Android 8.0 (livello API 26), il servizio di sintesi vocale (TTS) di Android può identificare e pronunciare frasi in più lingue all'interno di un singolo blocco di testo. Per abilitare questa funzionalità di cambio automatico della lingua in un servizio di accessibilità, aggrega tutte le stringhe negli oggetti LocaleSpan, come mostrato nel seguente snippet di codice:

Kotlin

val localeWrappedTextView = findViewById<TextView>(R.id.my_french_greeting_text).apply {
    text = wrapTextInLocaleSpan("Bonjour!", Locale.FRANCE)
}

private fun wrapTextInLocaleSpan(originalText: CharSequence, loc: Locale): SpannableStringBuilder {
    return SpannableStringBuilder(originalText).apply {
        setSpan(LocaleSpan(loc), 0, originalText.length - 1, 0)
    }
}

Java

TextView localeWrappedTextView = findViewById(R.id.my_french_greeting_text);
localeWrappedTextView.setText(wrapTextInLocaleSpan("Bonjour!", Locale.FRANCE));

private SpannableStringBuilder wrapTextInLocaleSpan(
        CharSequence originalText, Locale loc) {
    SpannableStringBuilder myLocaleBuilder =
            new SpannableStringBuilder(originalText);
    myLocaleBuilder.setSpan(new LocaleSpan(loc), 0,
            originalText.length() - 1, 0);
    return myLocaleBuilder;
}

Per ulteriori informazioni, guarda il video della sessione Novità sull'accessibilità Android di Google I/O 2017, che inizia alle 10:59.

Agire per conto degli utenti

A partire dal 2011, i servizi di accessibilità possono agire per conto degli utenti, ad esempio modificando l'elemento attivo dell'input e selezionando (attivando) gli elementi dell'interfaccia utente. Nel 2012, l'intervallo di azioni si è ampliato per includere elenchi di scorrimento e l'interazione con i campi di testo. I servizi di accessibilità possono anche eseguire azioni globali, ad esempio accedere alla schermata Home, premere il pulsante Indietro e aprire la schermata delle notifiche e l'elenco delle app recenti. Dal 2012, Android include l'attenzione all'accessibilità, che rende tutti gli elementi visibili selezionabili da un servizio di accessibilità.

Queste funzionalità consentono agli sviluppatori di servizi di accessibilità di creare modalità di navigazione alternative, ad esempio la navigazione tramite gesti, e offrono agli utenti con disabilità un maggiore controllo dei dispositivi basati su Android.

Ascolta i gesti

I servizi di accessibilità possono ascoltare gesti specifici e rispondere agendo per conto di un utente. Questa funzione richiede che il servizio di accessibilità richieda l'attivazione della funzione Esplora al tocco. Il tuo servizio può richiedere questa attivazione impostando il membro flags dell'istanza AccessibilityServiceInfo del servizio su FLAG_REQUEST_TOUCH_EXPLORATION_MODE, come mostrato nell'esempio seguente.

Kotlin

class MyAccessibilityService : AccessibilityService() {

    override fun onCreate() {
        serviceInfo.flags = AccessibilityServiceInfo.FLAG_REQUEST_TOUCH_EXPLORATION_MODE
    }
    ...
}

Java

public class MyAccessibilityService extends AccessibilityService {
    @Override
    public void onCreate() {
        getServiceInfo().flags = AccessibilityServiceInfo.FLAG_REQUEST_TOUCH_EXPLORATION_MODE;
    }
    ...
}

Dopo che il servizio richiede l'attivazione di Esplora al tocco, l'utente deve attivare la funzionalità, se non è già attiva. Quando questa funzionalità è attiva, il servizio riceve notifica dei gesti di accessibilità tramite il metodo di callback onGesture() del servizio e può rispondere agendo per conto dell'utente.

Gesti continui

I dispositivi con Android 8.0 (livello API 26) supportano i gesti continui o i gesti programmatici contenenti più di un oggetto Path.

Quando specifichi una sequenza di tratti, puoi indicare che appartengono allo stesso gesto programmatico utilizzando l'argomento finale willContinue nel costruttore GestureDescription.StrokeDescription, come mostrato nel seguente snippet di codice:

Kotlin

// Simulates an L-shaped drag path: 200 pixels right, then 200 pixels down.
private fun doRightThenDownDrag() {
    val dragRightPath = Path().apply {
        moveTo(200f, 200f)
        lineTo(400f, 200f)
    }
    val dragRightDuration = 500L // 0.5 second

    // The starting point of the second path must match
    // the ending point of the first path.
    val dragDownPath = Path().apply {
        moveTo(400f, 200f)
        lineTo(400f, 400f)
    }
    val dragDownDuration = 500L
    val rightThenDownDrag = GestureDescription.StrokeDescription(
            dragRightPath,
            0L,
            dragRightDuration,
            true
    ).apply {
        continueStroke(dragDownPath, dragRightDuration, dragDownDuration, false)
    }
}

Java

// Simulates an L-shaped drag path: 200 pixels right, then 200 pixels down.
private void doRightThenDownDrag() {
    Path dragRightPath = new Path();
    dragRightPath.moveTo(200, 200);
    dragRightPath.lineTo(400, 200);
    long dragRightDuration = 500L; // 0.5 second

    // The starting point of the second path must match
    // the ending point of the first path.
    Path dragDownPath = new Path();
    dragDownPath.moveTo(400, 200);
    dragDownPath.lineTo(400, 400);
    long dragDownDuration = 500L;
    GestureDescription.StrokeDescription rightThenDownDrag =
            new GestureDescription.StrokeDescription(dragRightPath, 0L,
            dragRightDuration, true);
    rightThenDownDrag.continueStroke(dragDownPath, dragRightDuration,
            dragDownDuration, false);
}

Per ulteriori informazioni, guarda il video della sessione Novità sull'accessibilità Android di Google I/O 2017, che inizia alle 15:47.

Usa le azioni di accessibilità

I servizi di accessibilità possono agire per conto degli utenti per semplificare le interazioni con le app e aumentare la produttività. La possibilità dei servizi di accessibilità di eseguire azioni è stata aggiunta nel 2011 e notevolmente ampliata nel 2012.

Per agire per conto degli utenti, il servizio di accessibilità deve registrarsi per ricevere eventi dalle app e richiedere l'autorizzazione per visualizzare i contenuti delle app impostando android:canRetrieveWindowContent su true nel file di configurazione del servizio. Quando il servizio riceve eventi, può recuperare l'oggetto AccessibilityNodeInfo dall'evento utilizzando getSource(). Con l'oggetto AccessibilityNodeInfo, il servizio può quindi esplorare la gerarchia delle visualizzazioni per determinare quale azione intraprendere e agire per l'utente utilizzando performAction().

Kotlin

class MyAccessibilityService : AccessibilityService() {

    override fun onAccessibilityEvent(event: AccessibilityEvent) {
        // Get the source node of the event.
        event.source?.apply {

            // Use the event and node information to determine what action to
            // take.

            // Act on behalf of the user.
            performAction(AccessibilityNodeInfo.ACTION_SCROLL_FORWARD)

            // Recycle the nodeInfo object.
            recycle()
        }
    }
    ...
}

Java

public class MyAccessibilityService extends AccessibilityService {

    @Override
    public void onAccessibilityEvent(AccessibilityEvent event) {
        // Get the source node of the event.
        AccessibilityNodeInfo nodeInfo = event.getSource();

        // Use the event and node information to determine what action to take.

        // Act on behalf of the user.
        nodeInfo.performAction(AccessibilityNodeInfo.ACTION_SCROLL_FORWARD);

        // Recycle the nodeInfo object.
        nodeInfo.recycle();
    }
    ...
}

Il metodo performAction() consente al servizio di eseguire operazioni all'interno di un'app. Se il servizio deve eseguire un'azione globale, ad esempio accedere alla schermata Home, toccare il pulsante Indietro o aprire la schermata delle notifiche o l'elenco delle app recenti, utilizza il metodo performGlobalAction().

Utilizza i tipi di impostazione dello stato attivo

Nel 2012, Android ha introdotto un obiettivo dell'interfaccia utente chiamato focus per l'accessibilità. I servizi di accessibilità possono utilizzare questa impostazione per selezionare qualsiasi elemento dell'interfaccia utente visibile e intervenire su di esso. Questo tipo di stato attivo è diverso da input, che determina quale elemento dell'interfaccia utente sullo schermo riceve input quando un utente digita i caratteri, preme Invio su una tastiera o preme il pulsante centrale di un D-pad.

È possibile che un elemento di un'interfaccia utente abbia lo stato attivo per l'input, mentre un altro elemento per l'accessibilità. Lo scopo dell'accessibilità è fornire ai servizi di accessibilità un metodo di interazione con gli elementi visibili su uno schermo, indipendentemente dal fatto che l'elemento possa essere impostato o meno per l'input dal punto di vista del sistema. Per assicurarti che il servizio di accessibilità interagisca correttamente con gli elementi di input delle app, segui le linee guida per il test dell'accessibilità di un'app al fine di testare il servizio durante l'utilizzo di un'app tipica.

Nota: i servizi di accessibilità che utilizzano lo stato attivo per l'accessibilità sono responsabili della sincronizzazione dell'elemento attivo dell'input quando un elemento supporta questo tipo di impostazione. I servizi che non sincronizzano lo stato attivo degli input con lo stato attivo di accessibilità rischiano di causare problemi nelle app che prevedono che lo stato degli input si trovi in una località specifica quando vengono intraprese determinate azioni.

Un servizio di accessibilità può determinare quale elemento dell'interfaccia utente ha come priorità di input o di accessibilità utilizzando il metodo AccessibilityNodeInfo.findFocus(). Puoi anche cercare elementi che possono essere selezionati con lo stato attivo dell'input utilizzando il metodo focusSearch(). Infine, il servizio di accessibilità può impostare il focus dell'accessibilità utilizzando il metodo performAction(AccessibilityNodeInfo.ACTION_SET_ACCESSIBILITY_FOCUS).

Raccogliere informazioni

I servizi di accessibilità utilizzano metodi standard per raccogliere e rappresentare le unità chiave delle informazioni fornite dagli utenti, come dettagli degli eventi, testo e numeri.

Ottieni dettagli sulle modifiche alle finestre

Android 9 (livello API 28) e versioni successive consentono alle app di tenere traccia degli aggiornamenti delle finestre quando un'app ridisegna più finestre contemporaneamente. Quando si verifica un evento TYPE_WINDOWS_CHANGED, utilizza l'API getWindowChanges() per determinare come cambiano le finestre. Durante un aggiornamento multi-finestra, ogni finestra produce il proprio insieme di eventi. Il metodo getSource() restituisce la vista principale della finestra associata a ogni evento.

Se un'app definisce i titoli del riquadro Accessibilità per i relativi oggetti View, il servizio può riconoscere quando la UI dell'app viene aggiornata. Quando si verifica un evento TYPE_WINDOW_STATE_CHANGED, utilizza i tipi restituiti da getContentChangeTypes() per determinare come cambia la finestra. Ad esempio, il framework può rilevare quando un riquadro ha un nuovo titolo o scompare.

Visualizza i dettagli dell'evento

Android fornisce ai servizi di accessibilità informazioni sull'interazione dell'interfaccia utente tramite gli oggetti AccessibilityEvent. Nelle versioni precedenti di Android, le informazioni disponibili in un evento di accessibilità, pur fornendo dettagli significativi sul controllo dell'interfaccia utente selezionati dagli utenti, offrivano informazioni contestuali limitate. In molti casi, queste informazioni di contesto mancanti potrebbero essere fondamentali per comprendere il significato del controllo selezionato.

Un esempio di interfaccia in cui il contesto è fondamentale è un calendario o una pianificazione giornaliera. Se l'utente seleziona una fascia oraria delle 16:00 in un elenco di giorni da lunedì a venerdì e il servizio di accessibilità annuncia"16:00", ma non annuncia il nome del giorno della settimana, del giorno del mese o del mese, il feedback risultante è confuso. In questo caso, il contesto di un controllo dell'interfaccia utente è fondamentale per un utente che vuole pianificare una riunione.

Dal 2011, Android amplia in modo significativo la quantità di informazioni che un servizio di accessibilità è in grado di ottenere su un'interazione con l'interfaccia utente componendo eventi di accessibilità in base alla gerarchia delle visualizzazioni. Una gerarchia delle viste è l'insieme di componenti dell'interfaccia utente che contengono il componente (i relativi elementi principali) e gli elementi dell'interfaccia utente che potrebbero essere contenuti da quel componente (i relativi elementi secondari). In questo modo, Android può fornire maggiori dettagli sugli eventi di accessibilità, consentendo ai servizi di accessibilità di fornire feedback più utili agli utenti.

Un servizio di accessibilità riceve informazioni su un evento dell'interfaccia utente tramite un AccessibilityEvent passato dal sistema al metodo di callback onAccessibilityEvent() del servizio. Questo oggetto fornisce dettagli sull'evento, tra cui il tipo di oggetto su cui si agisce, il testo descrittivo e altri dettagli.

Importante: la possibilità di esaminare la gerarchia delle visualizzazioni da un AccessibilityEvent espone potenzialmente le informazioni private dell'utente al tuo servizio di accessibilità. Per questo motivo, il servizio deve richiedere questo livello di accesso tramite il file XML di configurazione del servizio di accessibilità mediante l'inclusione dell'attributo canRetrieveWindowContent e l'impostazione su true. Se non includi questa impostazione nel file XML di configurazione del servizio, le chiamate a getSource() non riusciranno.

• AccessibilityEvent.getRecordCount() e getRecord(int): questi metodi consentono di recuperare l'insieme di oggetti AccessibilityRecord che contribuiscono al AccessibilityEvent passato dal sistema. Questo livello di dettaglio fornisce maggiore contesto per l'evento che attiva il servizio di accessibilità.

• AccessibilityRecord.getSource(): questo metodo restituisce un oggetto AccessibilityNodeInfo. Questo oggetto consente di richiedere la gerarchia del layout di visualizzazione (principali e secondari) del componente che ha dato origine all'evento di accessibilità. Questa funzionalità consente a un servizio di accessibilità di esaminare l'intero contesto di un evento, inclusi i contenuti e lo stato di eventuali viste o viste secondarie.

Nota: getSource(), AccessibilityNodeInfo.getChild() e getParent() restituiscono solo oggetti di visualizzazione considerati importanti per l'accessibilità, ovvero viste che disegnano contenuti o rispondono alle azioni dell'utente. Se il tuo servizio richiede tutte le viste, può richiederle impostando il membro flags dell'istanza AccessibilityServiceInfo del servizio su FLAG_INCLUDE_NOT_IMPORTANT_VIEWS.

La piattaforma Android consente a un AccessibilityService di eseguire query sulla gerarchia delle visualizzazioni, raccogliendo informazioni sul componente dell'interfaccia utente che genera un evento, nonché sui relativi elementi principali e secondari. Per farlo, imposta la seguente riga nella configurazione XML:

android:canRetrieveWindowContent="true"

Dopodiché, recupera un oggetto AccessibilityNodeInfo utilizzando getSource(). Questa chiamata restituisce un oggetto solo se la finestra da cui ha origine l'evento è ancora la finestra attiva. In caso contrario, viene restituito un valore nullo, quindi comportati di conseguenza.

Nell'esempio seguente, il codice esegue le seguenti operazioni quando viene ricevuto un evento:

1. Cattura immediatamente l'elemento principale della vista da cui ha avuto origine l'evento.
2. In questa visualizzazione cerca un'etichetta e una casella di controllo come viste secondarie.
3. Se le trova, crea una stringa da segnalare all'utente, indicando l'etichetta e se è stata selezionata.

Se in qualsiasi momento viene restituito un valore nullo mentre attraversa la gerarchia di visualizzazione, il metodo si arrende in modo discreto.

Kotlin

// Alternative onAccessibilityEvent that uses AccessibilityNodeInfo.

override fun onAccessibilityEvent(event: AccessibilityEvent) {

    val source: AccessibilityNodeInfo = event.source ?: return

    // Grab the parent of the view that fires the event.
    val rowNode: AccessibilityNodeInfo = getListItemNodeInfo(source) ?: return

    // Using this parent, get references to both child nodes, the label, and the
    // checkbox.
    val taskLabel: CharSequence = rowNode.getChild(0)?.text ?: run {
        rowNode.recycle()
        return
    }

    val isComplete: Boolean = rowNode.getChild(1)?.isChecked ?: run {
        rowNode.recycle()
        return
    }

    // Determine what the task is and whether it's complete based on the text
    // inside the label, and the state of the checkbox.
    if (rowNode.childCount < 2 || !rowNode.getChild(1).isCheckable) {
        rowNode.recycle()
        return
    }

    val completeStr: String = if (isComplete) {
        getString(R.string.checked)
    } else {
        getString(R.string.not_checked)
    }
    val reportStr = "$taskLabel$completeStr"
    speakToUser(reportStr)
}

Java

// Alternative onAccessibilityEvent that uses AccessibilityNodeInfo.

@Override
public void onAccessibilityEvent(AccessibilityEvent event) {

    AccessibilityNodeInfo source = event.getSource();
    if (source == null) {
        return;
    }

    // Grab the parent of the view that fires the event.
    AccessibilityNodeInfo rowNode = getListItemNodeInfo(source);
    if (rowNode == null) {
        return;
    }

    // Using this parent, get references to both child nodes, the label, and the
    // checkbox.
    AccessibilityNodeInfo labelNode = rowNode.getChild(0);
    if (labelNode == null) {
        rowNode.recycle();
        return;
    }

    AccessibilityNodeInfo completeNode = rowNode.getChild(1);
    if (completeNode == null) {
        rowNode.recycle();
        return;
    }

    // Determine what the task is and whether it's complete based on the text
    // inside the label, and the state of the checkbox.
    if (rowNode.getChildCount() < 2 || !rowNode.getChild(1).isCheckable()) {
        rowNode.recycle();
        return;
    }

    CharSequence taskLabel = labelNode.getText();
    final boolean isComplete = completeNode.isChecked();
    String completeStr = null;

    if (isComplete) {
        completeStr = getString(R.string.checked);
    } else {
        completeStr = getString(R.string.not_checked);
    }
    String reportStr = taskLabel + completeStr;
    speakToUser(reportStr);
}

Ora hai a disposizione un servizio di accessibilità completo e funzionante. Prova a configurare la modalità di interazione con l'utente aggiungendo il motore di sintesi vocale di Android o utilizzando un Vibrator per fornire feedback aptico.

Elabora testo

I dispositivi con Android 8.0 (livello API 26) e versioni successive includono diverse funzionalità di elaborazione del testo che semplificano l'identificazione e il funzionamento di specifiche unità di testo sullo schermo da parte dei servizi di accessibilità.

Descrizioni comandi

Android 9 (livello API 28) introduce diverse funzionalità che consentono di accedere alle descrizioni comando nella UI di un'app. Usa getTooltipText() per leggere il testo di una descrizione comando e usa ACTION_SHOW_TOOLTIP e ACTION_HIDE_TOOLTIP per indicare alle istanze di View di mostrare o nascondere le relative descrizioni comando.

Testo suggerimento

A partire dal 2017, Android include diversi metodi per interagire con il testo suggerito di un oggetto basato su testo:

• I metodi isShowingHintText() e setShowingHintText() indicano e stabiliscono rispettivamente se il contenuto testuale attuale del nodo rappresenta il testo del suggerimento del nodo.
• getHintText() consente di accedere al testo del suggerimento stesso. Anche se un oggetto non mostra testo del suggerimento, la chiamata a getHintText() ha esito positivo.

Posizioni dei caratteri di testo sullo schermo

Sui dispositivi con Android 8.0 (livello API 26) e versioni successive, i servizi di accessibilità possono determinare le coordinate dello schermo per il riquadro di delimitazione di ogni carattere visibile all'interno di un widget TextView. I servizi trovano queste coordinate chiamando refreshWithExtraData(), passando EXTRA_DATA_TEXT_CHARACTER_LOCATION_KEY come primo argomento e un oggetto Bundle come secondo argomento. Durante l'esecuzione del metodo, il sistema compila l'argomento Bundle con un array partibile di oggetti Rect. Ogni oggetto Rect rappresenta il riquadro di delimitazione di un determinato carattere.

Valori di intervallo unilaterali standardizzati

Alcuni oggetti AccessibilityNodeInfo utilizzano un'istanza di AccessibilityNodeInfo.RangeInfo per indicare che un elemento UI può assumere un intervallo di valori. Quando crei un intervallo utilizzando RangeInfo.obtain() o quando recuperi i valori estremi dell'intervallo utilizzando getMin() e getMax(), tieni presente che i dispositivi con Android 8.0 (livello API 26) e versioni successive rappresentano intervalli unilaterali in modo standardizzato:

• Per gli intervalli senza valore minimo, Float.NEGATIVE_INFINITY rappresenta il valore minimo.
• Per gli intervalli senza valore massimo, Float.POSITIVE_INFINITY rappresenta il valore massimo.

Rispondere agli eventi di accessibilità

Ora che il servizio è configurato per eseguire e ascoltare gli eventi, scrivi il codice in modo che sappia cosa fare quando arriva un AccessibilityEvent. Per prima cosa, esegui l'override del metodo onAccessibilityEvent(AccessibilityEvent). In questo metodo, utilizza getEventType() per determinare il tipo di evento e getContentDescription() per estrarre eventuale testo dell'etichetta associato alla vista che attiva l'evento:

Kotlin

override fun onAccessibilityEvent(event: AccessibilityEvent) {
    var eventText: String = when (event.eventType) {
        AccessibilityEvent.TYPE_VIEW_CLICKED -> "Clicked: "
        AccessibilityEvent.TYPE_VIEW_FOCUSED -> "Focused: "
        else -> ""
    }

    eventText += event.contentDescription

    // Do something nifty with this text, like speak the composed string back to
    // the user.
    speakToUser(eventText)
    ...
}

Java

@Override
public void onAccessibilityEvent(AccessibilityEvent event) {
    final int eventType = event.getEventType();
    String eventText = null;
    switch(eventType) {
        case AccessibilityEvent.TYPE_VIEW_CLICKED:
            eventText = "Clicked: ";
            break;
        case AccessibilityEvent.TYPE_VIEW_FOCUSED:
            eventText = "Focused: ";
            break;
    }

    eventText = eventText + event.getContentDescription();

    // Do something nifty with this text, like speak the composed string back to
    // the user.
    speakToUser(eventText);
    ...
}

Risorse aggiuntive

Per saperne di più, consulta le seguenti risorse:

Guide

• Crea app accessibili

Codelab

• Sviluppare un servizio di accessibilità per Android