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 per videogiochi. Per offrire un'esperienza utente coerente, l'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, l'app deve essere utilizzabile da un telecomando che dispone solo dei 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 normalmente utilizzando il controller D-pad.

Per saperne di più sulla navigazione con i controller D-pad per i dispositivi TV, consulta Navigazione TV.

Gestisci le disconnessioni del controller

I controller per la 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 partecipare al gioco utilizzando un controller non ancora connesso.
• Durante il gameplay, un giocatore potrebbe abbandonare il gioco e scollegare 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, tra cui 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 funzionare durante un evento di riconnessione, anziché essere riavviata dal framework Android, il che non è un'esperienza utente ottimale.

Gestisci 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 un controller D-pad di base, un telecomando con puntatore o un controller per videogiochi. I codici tasto forniti da un controller per videogiochi quando viene utilizzato per le funzioni del D-pad potrebbero variare rispetto ai codici tasto 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 ulteriori informazioni sulla gestione delle variazioni di input, consulta Elabora l'input del D-pad.

Supporto dei telecomandi con puntatore

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

Dichiara il supporto del telecomando puntatore nel manifest

Per indicare che la tua app è navigabile con input puntatore e tocco, configura il manifest dell'app con android.software.leanback.supports_touch <property> impostato su true all'interno dell'elemento <application> (o all'interno di singoli elementi <activity> per configurare il supporto per attività):

<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" />
    <application ...>
        <!-- Signal whether the app supports pointer remotes -->
        <property
            android:name="android.software.leanback.supports_touch"
            android:value="true" />
        ...
    </application>
</manifest>

Supportano le interazioni di clic, passaggio del mouse e scorrimento

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

• Clic e selezione: tutti gli elementi UI attivabili e selezionabili 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 premi.
  • Visualizzazioni: gestisci gli eventi di clic sulle visualizzazioni. Per maggiori dettagli, consulta la panoramica degli eventi di input.
• Stati di passaggio del mouse visivi: fornisci un chiaro effetto visivo di passaggio del mouse per indicare quando il cursore del puntatore è posizionato su un elemento selezionabile.
  • Jetpack Compose: utilizza Modifier.hoverable() o osserva gli stati di passaggio del mouse utilizzando un InteractionSource. Per maggiori dettagli, consulta Gestire le interazioni degli utenti.
  • Visualizzazioni: definisci gli stati di passaggio del mouse utilizzando disegnabili con elenco di stati con android:state_hovered="true".
• Scorrimento con scorrimento e scorrimento rapido: lo scorrimento orizzontale e verticale attivato da un gesto di scorrimento o 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 verso destra) i contenitori scorrevoli.
  • Jetpack Compose: i container scorrevoli standard supportano lo scorrimento con puntatore e tocco per impostazione predefinita. Per le implementazioni personalizzate, consulta Input del puntatore in Compose.
  • Visualizzazioni: le visualizzazioni scorrevoli standard supportano lo scorrimento touch per impostazione predefinita. Per la gestione personalizzata degli input, consulta Tocco e input.
• Trascinamento della riproduzione di contenuti multimediali: durante la riproduzione di contenuti multimediali (ad esempio programmi TV e film), gli utenti devono poter interagire con la barra di avanzamento della riproduzione (barra di scorrimento) indicando e facendo clic per passare a un timestamp passato o futuro, nonché trascinando lungo la barra di avanzamento per cercare un momento specifico.

Gestisci 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 un'esperienza utente positiva, assegna un comportamento coerente ai pulsanti del controller.

Eventi UI TV

Assegna il comportamento della UI della TV ai pulsanti che generano i 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 in questo contesto i pulsanti di selezione fungono da pulsanti di riproduzione o pausa.

Fornisci un comportamento appropriato per il pulsante Indietro

Il pulsante Indietro non deve mai fungere da pulsante di attivazione/disattivazione. Ad esempio, non utilizzarlo sia per aprire che per chiudere un menu. Utilizzalo solo per tornare indietro, in stile breadcrumb, attraverso le schermate precedenti visitate dal giocatore.

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: 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 saperne di più sulla progettazione della navigazione, consulta Progettazione della navigazione Indietro e Su. Per scoprire di più sull'implementazione, consulta Fornire una navigazione a ritroso corretta.

Gestisci i controller per i giochi

Quando crei giochi per Android TV, progetta lo schema di controllo in modo che funzioni sia con i telecomandi TV standard sia con i controller per videogiochi dedicati.

Supporto dei controlli del D-pad

Pianifica lo schema di controllo attorno a un controllo D-pad, poiché 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 principale, ma anche per navigare nei menu di navigazione 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 modelli l'interazione del giocatore con il controller può essere fondamentale per offrire 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, specificalo chiaramente. Un giocatore che utilizza un controller non adatto per un gioco potrebbe avere un'esperienza scadente e dare una valutazione negativa al tuo gioco.
• Utilizza una mappatura dei pulsanti coerente: una mappatura dei pulsanti intuitiva è fondamentale per una buona esperienza utente. Ad esempio, rispetta le consuetudini accettate utilizzando il pulsante A per accettare e il pulsante B per annullare. Puoi anche offrire flessibilità consentendo all'utente di rimappare i pulsanti. Per saperne di più sulla mappatura dei pulsanti, consulta Gestisci le azioni del controller.
• Rileva le funzionalità del controller e regola di conseguenza: esegui una query sul controller per conoscere le sue funzionalità e ottimizzare l'abbinamento tra controller e gioco. Ad esempio, potresti voler consentire a un giocatore di guidare un oggetto agitando il controller in aria, ma se il controller del giocatore non dispone di accelerometro e giroscopio, l'azione non funziona. Esegui una query sul controller e, se il rilevamento dei movimenti non è supportato, passa a uno schema di controllo alternativo disponibile. Per saperne di più sull'esecuzione di query sulle funzionalità del controller, consulta Supporta i controller nelle versioni di Android.

Utilizza i pulsanti appropriati

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

Gestisci 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().

Gestisci le disconnessioni del controller

Quando un controller viene scollegato durante il gameplay, metti in pausa il gioco e mostra una finestra di dialogo che invita il giocatore scollegato a ricollegare il controller.

Inoltre, offri suggerimenti per la risoluzione dei problemi nella finestra di dialogo. Ad esempio, di' al giocatore: "Controlla la connessione Bluetooth". Per saperne di più sull'implementazione del supporto dei dispositivi di input, consulta Gestisci le azioni del controller e la panoramica di Bluetooth.

Mostra 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 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 uno sfondo nero e un controller nero su uno sfondo bianco, mostrati nella figura 1, come file PNG e come file Adobe® Illustrator®.