Gestire i controller TV

I dispositivi TV richiedono un dispositivo hardware secondario per interagire con le app: un telecomando di base, un telecomando con puntatore o un controller di gioco. Per offrire un'esperienza utente coerente, la tua app deve supportare l'input del D-pad, gestire i controller che vanno offline e supportare l'input di più tipi di controller, inclusi i telecomandi con puntatore.

Controlli minimi del D-pad

Il controller predefinito per un dispositivo TV è un D-pad. In generale, la tua app deve essere utilizzabile da un telecomando che ha solo i tasti Su, Giù, Sinistra, Destra, Seleziona, Indietro e Home. Se la tua app è un gioco che in genere richiede un controller di gioco con controlli aggiuntivi, prova a supportare il gameplay solo con questi controlli del D-pad. In caso contrario, avvisa l'utente che è necessario un controller e consentigli di uscire dal gioco in modo controllato utilizzando il controller D-pad.

Per maggiori informazioni sulla navigazione con i controller D-pad per i dispositivi TV, vedi Navigazione TV.

Gestire le disconnessioni del controller

I controller per la TV sono spesso dispositivi Bluetooth, che potrebbero tentare di risparmiare energia entrando periodicamente in modalità sospensione e disconnettendosi dal dispositivo TV. Ciò significa che un'app potrebbe essere interrotta o riavviata se non è configurata per gestire questi eventi di riconnessione. Questi eventi possono verificarsi in una delle seguenti circostanze:

• Durante la riproduzione di un video di diversi minuti, il D-pad o il controller potrebbe entrare in modalità sospensione, disconnettersi dal dispositivo TV e riconnettersi in un secondo momento.
• Durante il gioco, un nuovo giocatore potrebbe unirsi alla partita utilizzando un controller di gioco che non è ancora connesso.
• Durante il gioco, un giocatore potrebbe uscire dal gioco e disconnettere un controller.

Qualsiasi attività dell'app TV soggetta a eventi di disconnessione e riconnessione deve essere configurata per gestire gli eventi di riconnessione nel manifest dell'app. Il seguente esempio di codice mostra come abilitare un'attività per gestire le modifiche alla configurazione, inclusa la connessione, la disconnessione o la riconnessione di una tastiera o di un dispositivo di navigazione:

<activity
  android:name="com.example.android.TvActivity"
  android:label="@string/app_name"
  android:configChanges="keyboard|keyboardHidden|navigation"
  android:theme="@style/Theme.Leanback">

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
  </intent-filter>
  ...
</activity>

Questa modifica alla configurazione consente all'app di continuare a essere eseguita durante un evento di riconnessione anziché essere riavviata dal framework Android, il che non è una buona esperienza utente.

Gestire le variazioni di input del D-pad

Gli utenti di dispositivi TV potrebbero utilizzare più di un tipo di controller con la TV. Ad esempio, un utente potrebbe avere un controller D-pad di base, un telecomando con puntatore o un controller di gioco. I codici chiave forniti da un controller di gioco quando viene utilizzato per le funzioni del D-pad potrebbero variare rispetto ai codici chiave inviati da un D-pad di base.

Gestisci le variazioni nell'input del D-pad in modo che l'utente non debba cambiare controller per utilizzare la tua app. Per maggiori informazioni sulla gestione delle variazioni dell'input, vedi Elaborare l'input del D-pad.

Supportare i telecomandi con puntatore

Alcuni dispositivi TV supportano i telecomandi con puntatore, come i mouse aerei o i telecomandi con tasti direzionali sensibili al tocco (trackpad). Il supporto dei telecomandi con puntatore consente agli utenti di interagire con la tua app utilizzando i gesti di punta e clicca, passaggio del mouse, scorrimento e trascinamento, offrendo un'esperienza più fluida su hardware compatibile e mantenendo la piena compatibilità con il D-pad.

Dichiarare il supporto del telecomando con puntatore nel manifest

Per indicare che la tua app è navigabile con l'input da tocco e puntatore, configura il file manifest dell'app con i metadati android.software.leanback.supports_touch impostati su true:

<manifest ...>
    <!-- Signal whether the app is adaptive or built just for TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true|false" />
    <!-- Ensure the app can be installed on conventional TVs -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <!-- Signal whether the app supports pointer remotes -->
    <meta-data
        android:name="android.software.leanback.supports_touch"
        android:value="true" />
    <application ...>
        ...
    </application>
</manifest>

Supportano le interazioni di clic, passaggio del mouse e scorrimento

Quando supporti i telecomandi con puntatore, assicurati che i componenti dell'interfaccia utente rispondano in modo appropriato all'input del cursore e al tocco nelle seguenti interazioni:

• Clic e selezione:tutti gli elementi dell'interfaccia utente selezionabili e su cui è possibile spostare il cursore devono essere cliccabili con il telecomando con puntatore, in modo da corrispondere al comportamento della selezione con il D-pad (KEYCODE_DPAD_CENTER).
  • Jetpack Compose: utilizza i modificatori Modifier.clickable() o pointerInput. Per maggiori dettagli, vedi Tocca e tieni premuto.
  • Visualizzazioni:gestisci gli eventi di clic sulle visualizzazioni. Per maggiori dettagli, vedi la Panoramica degli eventi di input.
• Stati di passaggio del mouse visivi:forniscono un chiaro effetto visivo di passaggio del mouse per indicare quando il cursore del puntatore è posizionato sopra un elemento selezionabile.
  • Jetpack Compose:utilizza Modifier.hoverable() o osserva gli stati di passaggio del mouse utilizzando un InteractionSource. Per maggiori dettagli, vedi Gestire le interazioni degli utenti.
  • Visualizzazioni:definisci gli stati al passaggio del mouse utilizzando elementi grafici state-list con android:state_hovered="true".
• Scorrimento con scorrimento rapido:lo scorrimento orizzontale e verticale attivato da un gesto di scorrimento rapido su un pulsante D-pad centrale sensibile al tocco deve funzionare senza problemi su tutti i contenuti scorrevoli.
• Scorrimento tramite trascinamento:gli utenti devono essere in grado di trascinare per scorrere verticalmente (verso l'alto e verso il basso) o orizzontalmente (verso sinistra e destra) nei contenitori scorrevoli.
  • Jetpack Compose:i contenitori scorrevoli standard supportano lo scorrimento con il puntatore e il tocco per impostazione predefinita. Per le implementazioni personalizzate, vedi Input del puntatore in Compose.
  • Visualizzazioni:le visualizzazioni standard scorrevoli supportano lo scorrimento tramite tocco per impostazione predefinita. Per la gestione personalizzata dell'input, vedi Tocco e input.
• Scorrimento della riproduzione dei contenuti multimediali:durante la riproduzione di contenuti multimediali (come programmi TV e film), gli utenti devono essere in grado di interagire con la barra di avanzamento della riproduzione (barra di ricerca) puntando e facendo clic per passare a un timestamp passato o futuro, nonché trascinando (scorrendo) lungo la barra di avanzamento per cercare un momento specifico.

Gestire gli eventi dei pulsanti

Quando l'utente fa clic su un pulsante di un controller, la tua app riceve un evento con un KeyEvent. Il comportamento previsto per il pulsante potrebbe essere un evento multimediale, come riproduzione, pausa o interruzione, oppure un evento di tipo TV, come selezione o navigazione. Per offrire una buona esperienza utente, assegna un comportamento coerente ai pulsanti del controller.

Eventi dell'interfaccia utente TV

Assegna il comportamento della UI TV ai pulsanti che generano tipi KeyEvent come mostrato nella tabella seguente:

Eventi multimediali

Quando l'utente guarda contenuti multimediali, assegna un comportamento ai pulsanti che generano tipi di KeyEvent come mostrato nella tabella seguente. Se la tua app controlla un MediaSession, utilizza un MediaControllerAdapter per chiamare uno dei metodi MediaControllerCompat.TransportControls mostrati nella tabella. Tieni presente che i pulsanti di selezione fungono da pulsanti di riproduzione o pausa in questo contesto.

Fornire un comportamento appropriato del pulsante Indietro

Il pulsante Indietro non deve mai fungere da pulsante di attivazione/disattivazione. Ad esempio, non utilizzarlo per aprire e chiudere un menu. Utilizzalo solo per navigare all'indietro, in stile breadcrumb, nelle schermate precedenti in cui è stato il player.

Poiché il pulsante Indietro esegue solo la navigazione lineare all'indietro, puoi utilizzarlo per uscire da un menu in-app aperto da un altro pulsante e tornare all'app. La pressione consecutiva del pulsante Indietro deve sempre portare alla schermata Home di Android TV. Ad esempio: gioco > schermata di pausa del gioco > schermata principale del gioco > schermata Home di Android TV o riproduzione di un programma TV > schermata principale dell'app TV

Schermata Home di Android TV.

Per saperne di più sulla progettazione per la navigazione, vedi Progettare la navigazione Indietro e Su. Per informazioni sull'implementazione, consulta la sezione Fornire una navigazione a ritroso corretta.

Gestire i controller per i giochi

Quando crei giochi per Android TV, progetta il tuo sistema di controllo in modo che funzioni sia con i telecomandi TV standard sia con i controller di gioco dedicati.

Supportare i controlli del D-pad

Pianifica lo schema di controllo intorno a un controllo D-pad, poiché questo set di controlli è quello predefinito per i dispositivi Android TV. Il giocatore deve essere in grado di utilizzare un D-pad per tutti gli aspetti del gioco, non solo per controllare il gameplay principale, ma anche per navigare nei menu e negli annunci. Per questo motivo, assicurati che il gioco per Android TV non faccia riferimento a un'interfaccia touch con frasi come "Tocca qui per continuare".

Il modo in cui modelli l'interazione del giocatore con il controller può essere fondamentale per ottenere un'ottima esperienza utente. Prendi in esame queste best practice:

• Comunica in anticipo i requisiti del controller:utilizza la descrizione di Google Play per comunicare al giocatore eventuali aspettative sui controller. Se un gioco è più adatto a un gamepad con joystick rispetto a uno con solo un D-pad, specificalo. Un giocatore che utilizza un controller non adatto a un gioco potrebbe avere un'esperienza negativa e dare al tuo gioco una valutazione scadente.
• Utilizza una mappatura dei pulsanti coerente:una mappatura dei pulsanti intuitiva è fondamentale per una buona esperienza utente. Ad esempio, rispetta le convenzioni accettate utilizzando il tasto A per accettare e il tasto B per annullare. Puoi anche offrire flessibilità consentendo all'utente di rimappare i pulsanti. Per saperne di più sulla mappatura dei pulsanti, vedi Gestire le azioni del controller.
• Rileva le funzionalità del controller e regolale di conseguenza:esegui una query sul controller per conoscere le sue funzionalità e ottimizzare la corrispondenza tra controller e gioco. Ad esempio, potresti voler far sterzare un oggetto a un giocatore agitando il controller in aria, ma se il controller di un giocatore non dispone dell'hardware dell'accelerometro e del giroscopio, l'agitazione non funziona. Esegui una query sul controller e, se il rilevamento del movimento non è supportato, passa a uno schema di controllo alternativo disponibile. Per saperne di più sull'interrogazione delle funzionalità del controller, consulta Supportare i controller in tutte le versioni di Android.

Utilizzare i pulsanti appropriati

Non tutti i controller di gioco forniscono i pulsanti Start, Ricerca o Menu. Assicurati che la tua UI non dipenda dall'uso di questi pulsanti.

Gestire più controller

Quando più giocatori giocano a un gioco, ognuno con il proprio controller, è importante mappare ogni coppia giocatore-controller. Per informazioni su come implementare l'identificazione del numero di controller, consulta getControllerNumber().

Gestire le disconnessioni del controller

Quando un controller viene disconnesso durante il gioco, metti in pausa la partita e mostra una finestra di dialogo che chiede al giocatore disconnesso di ricollegare il controller.

Inoltre, fornisci suggerimenti per la risoluzione dei problemi nella finestra di dialogo. Ad esempio, chiedi al lettore di "Controlla la connessione Bluetooth". Per maggiori informazioni sull'implementazione del supporto dei dispositivi di input, vedi Gestire le azioni del controller e la panoramica del Bluetooth.

Mostra istruzioni del controller

Se il tuo gioco fornisce istruzioni visive per il controllo del gioco, utilizza un'immagine del controller priva di branding e includi solo pulsanti compatibili con Android.

Per visualizzare immagini di esempio di un controller compatibile con Android, scarica il modello di gamepad per Android TV (ZIP). Include un controller bianco su uno sfondo nero e un controller nero su uno sfondo bianco, mostrati nella figura 1, come file PNG e come file Adobe® Illustrator®.