Gestire i controller TV

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, 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 per un dispositivo TV è un D-pad. In generale, la tua app deve essere utilizzabile da un telecomando che abbia 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 del D-pad. In caso contrario, avvisa l'utente che è necessario un controller e consenti di uscire dal gioco in modo corretto utilizzando il controller D-pad.

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

Gestire le disconnessioni del controller

I controller per TV sono spesso dispositivi Bluetooth che potrebbero tentare di risparmiare energia entrando periodicamente in 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 dal dispositivo TV e riconnettersi in un secondo momento.
• Durante il gameplay, un nuovo giocatore potrebbe unirsi al gioco utilizzando un controller di gioco che non è già connesso.
• Durante il gameplay, un giocatore potrebbe uscire dal gioco e disconnettere un controller di gioco.

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 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 durante un evento di riconnessione , anziché essere riavviata dal framework Android, il che non è una buona esperienza utente.

Gestire le varianti 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 ai codici chiave inviati da un D-pad di base.

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

Gestire gli eventi dei pulsanti

Quando l'utente fa clic su un pulsante di un controller, l'app riceve un evento con un KeyEvent. Il comportamento previsto per il pulsante potrebbe essere un evento multimediale, come Riproduci, Metti in pausa o Interrompi, oppure potrebbe essere 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 dell'interfaccia utente TV ai pulsanti che generano tipi KeyEvent come mostrato nella tabella seguente:

Eventi multimediali

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

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

Fornire un comportamento appropriato del pulsante Indietro

Il pulsante Indietro non deve mai fungere da 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 si trovava il giocatore.

Poiché il pulsante Indietro esegue solo la navigazione lineare all'indietro, puoi utilizzare lo 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: gameplay > schermata di pausa del gioco > schermata principale del gioco > schermata Home di Android TV o riproduzione di programmi TV > schermata principale dell'app TV > schermata Home di Android TV.

Per ulteriori informazioni sulla progettazione per la navigazione, consulta Progettare la navigazione Indietro e Su. Per informazioni sull'implementazione, consulta Fornire una navigazione a ritroso corretta.

Gestire i controller per i giochi

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 tuo gioco per Android TV non faccia riferimento a un'interfaccia touch con un linguaggio come "Tocca qui per continuare."

Il modo in cui il giocatore interagisce con il controller può essere fondamentale per ottenere un'esperienza utente ottimale. 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 un joystick rispetto a uno con solo un D-pad, rendilo chiaro. Un giocatore che utilizza un controller non adatto a un gioco potrebbe avere un'esperienza negativa 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 convenzioni accettate utilizzando il pulsante A per accettare e il pulsante B per annullare. Puoi anche offrire flessibilità sotto forma di rimappabilità. Per ulteriori informazioni sulla mappatura dei pulsanti, consulta Gestire le azioni del controller.
• Rileva le funzionalità del controller e regolale di conseguenza: esegui una query sul controller in merito alle sue funzionalità per 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 di hardware per accelerometro e 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 ulteriori informazioni sull'esecuzione di query sulle 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, Cerca o Menu. Assicurati che l'interfaccia utente non dipenda dall'utilizzo 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 del controller, consulta getControllerNumber().

Gestire le disconnessioni del controller

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

Inoltre, offri suggerimenti per la risoluzione dei problemi nella finestra di dialogo. Ad esempio, chiedi al giocatore di "Controllare la connessione Bluetooth". Per ulteriori informazioni sull'implementazione del supporto dei dispositivi di input, consulta Gestire le azioni del controller e la panoramica di Bluetooth.

Mostrare le istruzioni del controller

Se il tuo gioco fornisce istruzioni visive per i controlli di gioco, utilizza un' immagine del controller priva di branding e includi solo i 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, mostrati nella Figura 1, come file PNG e come file Adobe® Illustrator®.