If you are building an app for Amazon Fire TV, it is good practice to implement the navigation and interaction of your app UI with the remote control. This can be achieved in multiple ways, but the key concept is to map the controls of the movement and interactions inside your apps to the D-Pad and buttons present on the Fire TV remote. The Fire TV documentation on UX best practices covers this basic aspects of app navigation and input.
With Fire TV expanding to automotive, it’s important to now add touch interactions to Fire TV apps on top of the D-Pad navigation. Customers will both be able to use remote controls, and touch on these devices.
In this tutorial we will see how to modify Android-based Fire TV apps designed for D-Pad to add touch interaction and how to provide a good touch-based UX.
The tutorial will cover 5 key steps:
Sample App - Github Repository:
As you follow through the steps of this tutorial, you can also download/clone from GitHub the Fire TV Sample App – Touch and D-Pad: https://github.com/amzn/firetv-sample-touch-app
This Sample App is a companion to this tutorial as it integrates all the code shown below and allows you to quickly see it in action. You can then also use it as a starting reference when editing or creating your app.
Step 1: Understanding UI Directional Navigation and focus with D-Pad
Android-based applications for Fire TV should follow clear platform-level patterns for remote-based navigation. Since Fire OS is built on top of Android, it follows the same layout and design patterns as standard Android apps.
In order to map app UI navigation automatically to the remote D-Pad, and specify in what order the different Android Views should be navigated by the customer, we need to use Android’s Directional Navigation (see Android’s documentation here). This is a best practice, and if your Android application doesn’t follow this pattern, it’s important to apply the following changes as this impacts how the Touch behaviour connects to the D-Pad behaviour.
The Directional Navigation requires us to specify for each “focusable” view what is the next or previous view that needs to be selected. This will allow the system to automatically map what is the next view that will be focused on when a user presses the navigation buttons on their remote D-Pad (Up, Down, Left, Right).
This is achieved by adding to our layout XML files views the following tags:
android:nextFocusDown, android:nextFocusRight, android:nextFocusLeft, android:nextFocusUp
\followed by the id of the view we want the app to select next based on the order.
So for example
<TextView android:id="@+id/Item1"
android:nextFocusRight="@+id/Item2"/>
Step 2: Applying Directional Navigation to TV apps layouts
Before we apply touch interactions to our Fire TV app, we need to make sure that we create a consistent Directional Navigation experience between D-pad and touch navigation.
This is quite simple for basic apps interfaces, but Media and Entertainment TV Apps interfaces can be quite complex, as more often than not they need to display dynamic content. Hence, most views might be generated at runtime.
In order to achieve this, most developers use Android Views that can easily hold dynamic content. A good example of this is the RecyclerView. The RecyclerView is a component which allows dynamic content to be parsed from an adapter. RecyclerView is efficient and it implements one of the standard Android patterns: the ViewHolder.
However, since the content of a RecyclerView is dynamic, we need to make sure that the navigation between the views which are generated inside RecyclerViews is correct.
In order to demonstrate this, we created a simple application which simulates the standard implementation of a TV interface. This application has two main UI components:
On the left you can see the menuLayout in black, and on the right the rowsLayout in grey.
While this is an oversimplification for the sake of this tutorial, as your app might have more complex nesting for its views, this represents the skeleton of a dynamic Media/TV App UI.
What you want to do now is to define how the directional navigation works on this layout.
The first thing that we want to make sure of is that we can actually move from our categories menu to the content rows. So what we do is to set nextFocusRight to the first row RecyclerView for our LinearLayout:
<LinearLayout
android:id="@+id/menuLayout"
[...]
android:nextFocusRight="@id/rowRecyclerView1">
This way, once the user clicks on the right button, it will automatically move the focus to the first RecyclerView on the right.
Another thing that we need to do is to set up how the navigation between the items of the RecyclerView itself works. Since the views of a RecyclerView are created dynamically at runtime, it is not practical to manually set the direction of navigation on each individual view; it cannot be achieved using the XML layout anyway. Instead, in order to do this, we need to use a very specific tag on the RecyclerView called descendantFocusability:
<androidx.recyclerview.widget.RecyclerView
android:id="@+id/recyclerViewMenu"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:descendantFocusability="afterDescendants" />
By setting descendantFocusability to afterDescendants we ensure that automatically, once the views are dynamically generated, the RecyclerView itself provides focus to the items inside the RecyclerView (in this case, it gives focus to the categories defined inside the RecyclerView menu).
Note - It is important to apply this to all our RecyclerViews, as this automatically defines the relationship between the items. The great news is that we don't have to manually define the relationship between each item because Android automatically takes care of that for us as a framework level feature.
We need to apply this to all the RecyclerViews in our right side layout as well.We need to define the Directional Navigation between each one of the RecyclerView (for sake of simplicity, in our example we defined 4 rows through 4 dedicated RecyclerView)
At the end, our RecyclerViews should look like this:
<androidx.recyclerview.widget.RecyclerView
android:id="@+id/rowRecyclerView1"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:descendantFocusability="afterDescendants"
android:nextFocusDown="@id/rowRecyclerView2" />
<androidx.recyclerview.widget.RecyclerView
android:id="@+id/rowRecyclerView2"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:descendantFocusability="afterDescendants"
android:nextFocusDown="@id/recyclerView3" />
<androidx.recyclerview.widget.RecyclerView
android:id="@+id/rowRecyclerView3"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:descendantFocusability="afterDescendants"
android:nextFocusDown="@id/rowRecyclerView4" />
<androidx.recyclerview.widget.RecyclerView
android:id="@+id/rowRecyclerView4"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:descendantFocusability="afterDescendants"/>
Notice how the last RecyclerView, rowRecyclerView4, doesn't have the next Focus down target. The reason for that is there is no further RecyclerView to navigate to.
Once we complete this step, we now have a fully navigable UI using the D-Pad. We can now look into how to properly touch-enable our interface by modifying the content of our RecyclerViews.
You can see how the UI is fully navigable using the remote even though the views are generated dynamically.
Step 3: Adding touch interactions for clicks: OnClickListeners
The next step is to add touch interactions when the user clicks on an item. Luckily for us, Android was built for touch in mind. To add click actions to our applications UI, we can use standard Android components which will allow us to cover both the D-Pad interaction and the touch interaction.
The best and easiest way to implement click actions or touch actions on a view is to use the standard Android OnClickListener. OnClickListener allows both touch clicks and d-pad button clicks to be performed on a view. onClickListener triggers a method called onClick() where you can execute any desired operation.
Note - If you have implemented the click action on your or D-Pad based UI in any other way, you might need to add the OnClickListener on top of any custom implementation you have. This is to ensure D-Pad clicks and touch clicks both execute the desired operation.
While on a D-Pad style navigation the size of the view is not important, , it is very relevant for touch interactions. Therefore, it's better to use larger views and areas in our UI to provide a good user experience.
In our simple application we are going to apply the OnClickListener to the layout itself and not to the views inside of the layout. This could be achieved also by expanding the internal views to fill the entire layout area and apply the OnClickListener to the individual views like TextView or ImageView, however applying it to the entire layout it's a simple solution that allows us to fulfil our goal and doesn't require to change the look and feel of the UI at all.
The views are dynamic and created by the RecyclerViews, so we need to apply individual on click listeners to each one of the created elements of each RecyclerView.We do this by modifying the code for the RecyclerView adaptors, getting a reference to the layout of each individual item of the RecyclerView and applying the onClickListener in the onBindViewHolder() method of the adapter:
public class MenuItemsAdapter extends RecyclerView.Adapter<MenuItemsAdapter.ViewHolder> {
private String[] localDataSet;
/**
* Provide a reference to the type of views that you are using
* (custom ViewHolder).
*/
public class ViewHolder extends RecyclerView.ViewHolder {
private final TextView textView;
private final ConstraintLayout menuConstraintLayout;
public ViewHolder(View view) {
super(view);
// Define click listener for the ViewHolder's View
textView = (TextView) view.findViewById(R.id.textView);
menuConstraintLayout = view.findViewById(R.id.menuconstraintLayout);
}
public TextView getTextView() {
return textView;
}
public ConstraintLayout getMenuConstraintLayout() {
return menuConstraintLayout;
}
}
/**
* Initialize the dataset of the Adapter.
*
* @param dataSet String[] containing the data to populate views to be used
* by RecyclerView.
*/
public MenuItemsAdapter(String[] dataSet) {
localDataSet = dataSet;
}
// Create new views (invoked by the layout manager)
@Override
public ViewHolder onCreateViewHolder(ViewGroup viewGroup, int viewType) {
// Create a new view, which defines the UI of the list item
View view = LayoutInflater.from(viewGroup.getContext())
.inflate(R.layout.menulayout, viewGroup, false);
return new ViewHolder(view);
}
// Replace the contents of a view (invoked by the layout manager)
@Override
public void onBindViewHolder(ViewHolder viewHolder, final int position) {
// Get element from your dataset at this position and replace the
// contents of the view with that element
viewHolder.getTextView().setText(localDataSet[position]);
viewHolder.getMenuConstraintLayout().setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
//In this sample app we are just logging the Click,
//but here you could for example open a new Activity or select
//a specific Category
Log.e("Click ", "Clicked "+localDataSet[position]);
}
});
}
// Return the size of your dataset (invoked by the layout manager)
@Override
public int getItemCount() {
return localDataSet.length;
}
}
In order to show if an item is focused on or clicked, it's important to use backgrounds and drawables that contain the different states in which a specific view can find itself.
This is easily achieved using a selector drawable, which can contain multiple states like focused and pressed (clicked)
Menuselectordrawable.xml (used as background for our Menu Layout)
<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_pressed="true"
android:drawable="@android:color/holo_blue_bright" /> <!-- pressed -->
<item android:state_focused="true"
android:drawable="@android:color/holo_orange_light" /> <!-- focused -->
<item android:state_hovered="true"
android:drawable="@android:color/holo_green_light" /> <!-- hovered -->
<item android:drawable="@android:color/background_dark" /> <!-- default -->
</selector>
In the menulayout.xml
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:id="@+id/menuconstraintLayout"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/menuselectordrawable"
android:focusable="true"
android:focusableInTouchMode="true">
At this point, all of our UI views are clickable and will show a different background color when clicked on (blue) and when focused on (orange)
You can see the onClickListeners being correctly triggered via the remote control.
Step 4: Managing view focus between D-Pad and touch interactions
The next step is to build a consistent experience between the d-pad and touch interactions. This means making sure that the directional navigation works consistently if we are using a remote or if we are interacting using touch.
As we mentioned above, Android was built with touchscreen and touch interactions in mind. This means that the underlying layer managing our apps UI and views is mostly touch-enabled already.
In Android, most of the views are visible and focusable by default. Actually, views inherit a parameter called focusable, which by default is set to “auto”, meaning that is up to the platform itself to determine if this view should be focusable or not. Views like Buttons, TextView, EditText are focusable by default as those are main UI components, while layouts and layout inflators are usually not automatically focusable by default, as they are usually used just to define the UI structure.
In order to make our app fully touch-enabled, we need to make sure that the most important views in our app are focusable, and also we need to make sure that they can be focused on when the customer uses touch.
For this reason, we are going to edit two parameters in our views: focusable and focusableInTouchMode.
Going back to our sample app, we created two new separate layouts which are used to populate the individual items inside the “Categories” RecyclerView and the “rows” RecyclerView.
We need to make sure that:
We do this by setting both focusable and focusableInTouchMode to true.
menuLayout.xml (defines the individual content of the Categories on the left, which contains only a TextView)
<androidx.constraintlayout.widget.ConstraintLayout
[...]
android:id="@+id/menuconstraintLayout"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/menuselectordrawable"
android:focusable="true"
android:focusableInTouchMode="true">
<TextView
android:id="@+id/textView"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
[...] />
cardLayout.xml (defines the individual content of the Movies rows on the right. Each card contains a ImageView and a TextView)
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
[...]
android:id="@+id/cardconstraintLayout"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:background="@drawable/selectordrawable"
android:focusable="true"
android:focusableInTouchMode="true"
>
<ImageView
android:id="@+id/imageView"
android:layout_width="150dp"
android:layout_height="100dp"
[...] />
<TextView
android:id="@+id/textView"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
[...] />
</androidx.constraintlayout.widget.ConstraintLayout>
By doing this, we ensure that if the user touches the UI or if they navigate through the d-pad controllers, in both cases the right UI element will be focused on. See clip below for a demonstration.
In this clip you can see how the views are correctly clicked and focused on using touch interaction.
Step 5: Additional best practices and testing Touch on Fire TV
After completing the steps above, we will have successful touch-enabled the most important components of our app UI.
There are additional simple steps to ensure that we are providing a great user experience for both touch and d-pad navigation:
How can you test Touch on Fire TV devices without a touchscreen?
The easiest solution is to connect a wireless mouse to your Fire TV. Mouse on Android simulates touch interaction. You can do this by:
Download and test the Fire TV Sample App for Touch and D-Pad
Remember to download the Fire TV Sample App – Touch and D-Pad at https://github.com/amzn/firetv-sample-touch-app. This app includes all the code you have seen above and is a great starting point for optimizing your Android-based Fire TV app for Touch.
Conclusion
This tutorial gave you a practical first overview on how to touch enable your Fire TV application.
For more details on these please check out our documentation: