I dispositivi TV richiedono un dispositivo hardware secondario per interagire con le app: un telecomando di base o un controller di gioco. Pertanto, la tua app deve supportare l'input del d-pad. Inoltre, l'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 D-pad
Il controller predefinito per un dispositivo TV è un D-pad. In generale, l'app deve essere azionabile da un telecomando con solo i pulsanti 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 D-pad. In caso contrario, avvisa l'utente che è necessario un controller e consentigli di uscire dal gioco agevolmente utilizzando il controller D-pad.
Per maggiori informazioni sulla navigazione con i controller D-pad per i dispositivi TV, vedi Navigazione TV.
Maniglia il controller si disconnette
Spesso i controller per la TV sono dispositivi Bluetooth, che potrebbero tentare di risparmiare energia attivando periodicamente la modalità di 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, un D-pad o un controller di gioco potrebbe entrare in 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 uscire dal gioco e scollegare un controller di gioco.
Qualsiasi attività nelle 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 consentire a un'attività di 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 tramite un evento di riconnessione, invece di essere riavviata dal framework Android, che non rappresenta 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 chiave forniti da un controller di gioco quando viene utilizzato per le funzioni del D-pad potrebbero variare rispetto a quelli 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 utilizzare l'app. Per ulteriori informazioni sulla gestione delle variazioni di input, vedi Elaborare l'input del d-pad.
Gestisci gli eventi del pulsante
Quando l'utente fa clic su un pulsante su un controller, la tua app riceve un evento con
KeyEvent. Il comportamento
previsto del pulsante può essere un evento multimediale, come riproduzione, pausa o interruzione, oppure un evento di tipo TV, come
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'interfaccia utente TV ai pulsanti che generano i tipi KeyEvent
come illustrato nella seguente tabella:
KeyEvent | Comportamento |
|---|---|
KEYCODE_BUTTON_B, KEYCODE_BACK | Indietro |
KEYCODE_BUTTON_SELECT, KEYCODE_BUTTON_A, KEYCODE_ENTER, KEYCODE_DPAD_CENTER e KEYCODE_NUMPAD_ENTER | Selezione |
KEYCODE_DPAD_UP, KEYCODE_DPAD_DOWN, KEYCODE_DPAD_LEFT e KEYCODE_DPAD_RIGHT | Navigazione |
Eventi multimediali
Quando l'utente sta guardando contenuti multimediali, assegna un comportamento ai pulsanti che generano i tipi KeyEvent come mostrato nella tabella seguente. 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
funzionano come pulsanti di riproduzione o pausa.
KeyEvent | Chiamata TransportControls | Comportamento |
|---|---|---|
BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER e KEYCODE_NUMPAD_ENTER |
play() | Riproduci |
BUTTON_START, BUTTON_SELECT, BUTTON_A, ENTER, DPAD_CENTER e KEYCODE_NUMPAD_ENTER |
pause() | Metti in pausa |
BUTTON_R1 | skipToNext() | Vai al successivo |
BUTTON_L1 | skipToPrevious() | Passa ai contenuti precedenti |
DPAD_RIGHT, BUTTON_R2, AXIS_RTRIGGER e AXIS_THROTTLE | fastForward() | Fast forward |
DPAD_LEFT, BUTTON_L2, AXIS_LTRIGGER e AXIS_BRAKE | rewind() | Indietro |
| N/A | stop() | Interrompi |
Nota:quando utilizzi un MediaSession, non eseguire l'override della gestione dei pulsanti specifici dei contenuti multimediali, come KEYCODE_MEDIA_PLAY o KEYCODE_MEDIA_PAUSE.
Il sistema attiva automaticamente il metodo MediaSession.Callback appropriato.
Fornire il 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 andare indietro, in stile breadcrumb, tra le schermate precedenti in cui si trovava il player.
Poiché il pulsante Indietro esegue solo una navigazione lineare a ritroso, puoi utilizzarlo per uscire da un menu in-app aperto da un pulsante diverso e tornare all'app. Se premi consecutivamente il pulsante Indietro alla fine, alla fine il pulsante deve sempre portare alla schermata Home di Android TV. Ad esempio: gameplay > 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 ulteriori informazioni sulla progettazione per la navigazione, vedi Progettazione della navigazione di riserva. Per scoprire di più sull'implementazione, consulta Offrire una navigazione a ritroso corretta.
Gestisci i controller per i giochi
Supporto dei controlli del D-pad
Pianifica lo schema di controllo in base a un controllo D-pad, poiché questo insieme è l'impostazione predefinita per i dispositivi Android TV. Il giocatore deve essere in grado di usare un D-pad per tutti gli aspetti del gioco, non solo per il controllo del gameplay principale, ma anche per la navigazione nei menu e per gli annunci. Per questo motivo, assicurati che il tuo gioco Android TV non faccia riferimento a un'interfaccia touch con linguaggio del tipo "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. Prendi in esame queste best practice:
- Comunica in anticipo i requisiti dei 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 un joystick anziché a uno con solo D-pad, specificalo chiaramente. Un giocatore che utilizza un controller non adatto per un gioco potrebbe avere un'esperienza scadente e dare al tuo gioco una valutazione negativa.
- Utilizza una mappatura dei pulsanti coerente: una mappatura dei pulsanti intuitiva è 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 la pagina su come gestire le azioni del controller.
- Rileva le funzionalità del controller e regolale di conseguenza: esegui una query sul controller per verificare le sue funzionalità per ottimizzare la corrispondenza tra controller e gioco. Ad esempio, potresti voler chiedere a un giocatore di sterzare un oggetto muovendo il controller in aria, ma se il controller di un giocatore non dispone di accelerometro e giroscopio hardware, la mano non funziona. Esegui una query sul controller e, se il rilevamento dei movimenti non è supportato, passa a uno schema di controllo alternativo disponibile. Per maggiori informazioni sull'esecuzione di query sulle funzionalità dei controller, vedi Supportare i controller nelle versioni di Android.
Usa i pulsanti appropriati
Non tutti i controller di gioco offrono i pulsanti Start, Cerca o Menu. Assicurati che la tua UI non dipenda dall'uso di questi pulsanti.
Gestire più controller
Quando più giocatori stanno giocando, ognuno con il proprio controller, è importante mappare ogni coppia giocatore-controller. Per informazioni su come implementare l'identificazione
del numero controller, consulta
getControllerNumber().
Maniglia il controller si disconnette
Quando un controller viene disconnesso durante il gameplay, mettilo in pausa 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, di' al player "Controlla la connessione Bluetooth". Per maggiori informazioni sull'implementazione del supporto dei dispositivi di input, consulta Gestire le azioni del controller e la panoramica sul Bluetooth.
Mostra istruzioni per il controller
Se il gioco fornisce istruzioni visive per il controllo del gioco, usa 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 ZIP (ZIP) per Android TV Gamepad. Include un controller bianco su sfondo nero e un controller nero su uno sfondo bianco (mostrato nella figura 1) come file PNG e come file Adobe® Illustrator®.
Figura 1. Esempi di istruzioni per il controller usando il modello per Gamepad di Android TV.