Gestire i controller TV

I dispositivi TV richiedono un dispositivo hardware secondario per interagire con le app: un controller remoto di base o un controller di gioco. Di conseguenza, l'app deve supportare l'input del d-pad. Inoltre, la tua app potrebbe dover gestire i controller che vanno offline e l'input da più di un tipo di controller.

Questa guida illustra i requisiti per la gestione dei controller per i dispositivi TV.

Controlli minimi del D-pad

Il controller predefinito di una TV è un D-pad. In generale, l'app deve poter essere utilizzata da un telecomando dotato solo di pulsanti su, giù, sinistra, destra, selezione, 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 D-pad. In caso contrario, avvisa l'utente che è necessario un controller e consentigli di uscire dal gioco utilizzando il controller D-pad.

Per maggiori informazioni sulla gestione della navigazione con il controller D-pad per i dispositivi TV, consulta la sezione Navigazione sulla TV.

Gestire le disconnessioni del controller

I controller per la TV sono spesso dispositivi Bluetooth che potrebbero tentare di risparmiare energia passando periodicamente in modalità di sospensione e scollegandosi 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 che dura diversi minuti, un D-pad o un controller di gioco potrebbe attivare la modalità di sospensione, disconnettersi dalla TV e riconnettersi in un secondo momento.
  • Durante il gameplay, un nuovo giocatore potrebbe partecipare al gioco utilizzando un controller di gioco non ancora collegato.
  • Durante il gameplay, un giocatore potrebbe abbandonare il gioco e scollegare un controller di gioco.

Qualsiasi attività dell'app TV soggetta a eventi di disconnessione e riconnessione deve essere configurata in modo da gestire gli eventi di riconnessione nel file manifest dell'app. Il seguente esempio di codice mostra come abilitare un'attività per gestire le modifiche alla configurazione, incluse le connessioni, la disconnessione e 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 eseguire un evento di riconnessione anziché essere riavviata dal framework Android, il che non offre un'esperienza utente positiva.

Gestire le variazioni di input del D-pad

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

Gestisci le variazioni dell'input del D-pad in modo che l'utente non debba cambiare controller per gestire l'app. Per ulteriori informazioni sulla gestione delle variazioni di input, consulta la pagina Elaborare l'input del D-pad.

Gestire gli eventi dei pulsanti

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

Eventi UI TV

Assegna il comportamento dell'UI TV ai pulsanti che generano i tipi KeyEvent, come mostrato nella seguente tabella:

KeyEventComportamento
KEYCODE_BUTTON_B, KEYCODE_BACKIndietro
KEYCODE_BUTTON_SELECT, KEYCODE_BUTTON_A, KEYCODE_ENTER, KEYCODE_DPAD_CENTER e KEYCODE_NUMPAD_ENTERSelezione
KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT e KEYCODE_DPAD_RIGHTNavigazione

Eventi multimediali

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

KeyEventChiamata TransportControlsComportamento
BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER e KEYCODE_NUMPAD_ENTER play()Gioca
BUTTON_START, BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER e KEYCODE_NUMPAD_ENTER pause()Mettere in pausa
BUTTON_R1skipToNext()Vai al successivo
BUTTON_L1skipToPrevious()Passa ai contenuti precedenti
DPAD_RIGHT, BUTTON_R2, AXIS_RTRIGGER e AXIS_THROTTLEfastForward()Avanti veloce
DPAD_LEFT, BUTTON_L2, AXIS_LTRIGGER e AXIS_BRAKErewind()Indietro
N/Astop()Interrompi

Nota:quando utilizzi un MediaSession, non sostituire la gestione dei pulsanti specifici dei contenuti multimediali, come KEYCODE_MEDIA_PLAY o KEYCODE_MEDIA_PAUSE. Il sistema attiva automaticamente il metodo MediaSession.Callback appropriato.

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 retrocedere, in stile breadcrumb, nelle schermate precedenti in cui è stato eseguito il player.

Poiché il pulsante Indietro esegue soltanto una navigazione a ritroso lineare, puoi usarlo per lasciare un menu in-app aperto con un pulsante diverso e tornare all'app. La pressione continua del pulsante Indietro deve sempre indirizzare alla schermata Home di Android TV. Ad esempio: gameplay > schermata 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 maggiori informazioni sulla progettazione della navigazione, consulta l'articolo Progettare la navigazione posteriore e superiore. Per scoprire di più sull'implementazione, consulta la sezione Fornire una navigazione indietro corretta.

Gestisci i controller per i giochi

Supporta i controlli del D-pad

Pianifica lo schema di controllo attorno a un controllo D-pad, dato che questo set di controlli è l'impostazione predefinita 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 di base, ma anche per navigare tra i menu e gli annunci. Per questo motivo, assicurati che il tuo gioco Android TV non faccia riferimento a un'interfaccia touch con linguaggio come "Tocca qui per continuare".

Il modo in cui definisci l'interazione del giocatore con il controller può essere fondamentale per ottenere un'esperienza utente ottimale. Tieni in considerazione le seguenti best practice:

  • Comunica in anticipo i requisiti del controller: usa la descrizione di Google Play per comunicare al giocatore eventuali aspettative in merito ai controller. Se un gioco è più adatto a un gamepad con joystick rispetto a uno con solo D-pad, indicalo chiaramente. Un giocatore che utilizza un controller non adatto per un gioco potrebbe avere un'esperienza negativa e assegnare una valutazione negativa al gioco.
  • Utilizza una mappatura dei pulsanti coerente: una mappatura intuitiva dei pulsanti è fondamentale per una buona esperienza utente. Ad esempio, rispetta le dogane accettate utilizzando il pulsante A per accettare e il pulsante B per annullare. Puoi anche offrire flessibilità sotto forma di rimappabilità. Per maggiori informazioni sulla mappatura dei pulsanti, consulta Gestire le azioni del controller.
  • Rileva le funzionalità del controller e apporta le modifiche necessarie: chiedi al controller le sue funzionalità per ottimizzare la corrispondenza tra controller e gioco. Ad esempio, si potrebbe voler guidare un oggetto sventolando il controller in aria, ma se il controller di un player è privo dell'accelerometro e dell'hardware del giroscopio, agitare non funziona. Interroga il controller e, se il rilevamento dei movimenti non è supportato, passa a uno schema di controllo alternativo disponibile. Per ulteriori informazioni sull'esecuzione di query sulle funzionalità del controller, vedi Supportare i controller in tutte le versioni di Android.

Usa i pulsanti appropriati

Non tutti i controller di gioco dispongono di pulsanti Start, Ricerca o Menu. Assicurati che l'interfaccia utente non dipenda dall'uso di questi pulsanti.

Gestire più controller

Quando più giocatori giocano, 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 scollegato durante il gameplay, metti in pausa il gioco e mostra una finestra di dialogo che chiede al giocatore disconnesso di ricollegare il controller.

Inoltre, nella finestra di dialogo fornisci suggerimenti per la risoluzione dei problemi. Ad esempio, puoi impostare il player "Controlla la connessione Bluetooth". Per ulteriori informazioni sull'implementazione del supporto dei dispositivi di input, consulta Gestire le azioni del controller e Panoramica del Bluetooth.

Mostra le istruzioni del controller

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

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

Figura 1. Esempio di istruzioni per il controller utilizzando il modello per Gamepad per Android TV.