Building an Android TV app: Part 1

During my past internship as an Android Intern I was asked to build an Android TV app. As many developers would do, I started by looking up the sample guides and existing apps for code snippets and inspirations. The main problem I faced during the internship was how hard it is to“imitate” some things found on Google apps.

That is why I decided to write this guide. During this guide I will be how to copy designs seen in many TV apps that are not as clear on how to accomplish it from the guides and sample code without diving into the Leanback library code itself.

During this series of tutorials, I will show how to build a TMDB (The Movie Database) client to browse movies.

Check out the app on the PlayStore:

I will assume that you already know how to create an Android studio project and understand the basics of Android development. This tutorial will focus on explaining the Android TV framework and not Android itself.

On the first part of the tutorial we will focus on creating the home page of the app.

The home page is composed of a BrowseFragment from the Leanback library which is divided into 4 main components:

  • HeadersFragment: The left side of the fragment that holds the headers for a set of Rows or Pages.
  • TitleView: The top right corner of the screen. This can be used with a badge image or a String title. It can be also customized through a custom view.
  • SearchOrb: The SearchOrb on the top left corner of the screen can have it’s color customized and will show when a SearchListener is attached to the fragment.
  • RowsFragment: The main component of the fragment. It will hold a set of rows. The titles of the rows will automatically be used by the HeadersFragment.

Getting Started

Head to and download the Skeleton branch. That will be the starting point for the rest of this tutorial. It has the basic classes for part 1 of this project already created and set up.

Note: The Application will use Dagger 2 for the Dependency injection, Retrofit 2 for the data retrieval and RxJava to manage the network calls and a lot of other common Android libraries. Check out the dependencies in the build.gradle file in order to learn more about the libraries included in the skeleton project. The skeleton project already has all of the network calls, dependencies and models set up, so the main focus of this guide is the TV framework itself.

Note 2: The app requires an API Key from TMDB. You can get a free key from in about 5 minutes.

Note 3: The app doesn’t run at first because there are a few things missing on the manifest, but that will be fixed on step 1.

Step 1: Setting up the TV manifest

I could have this part on the Skeleton project already ready, but I wanted to point out some details necessary for any TV project. Usually some of this stuff gets done automatically for you when you create an app with a new TV Activity.

Open up AndroidManifest.xml and add the following:

The manifest should now look somewhat similar to this:

The app should now compile, but just a blank screen will appear. In the next steps we will be adding content to the app.

Step 2: Adding the API key

Open the file and add your API key.

The file should look like this:

Step 3: Creating the MovieCardView

The MovieCardView will be in charge of displaying a single movie in the screen. We could potentially have reused one of the predefined ones by the Leanback Library, but for the purposes of this tutorial we will be creating a custom one to understand the framework better.

The MovieCardView extends BaseCardView provided by the Leanback Library. The skeleton project also contains a BindableCardView class to avoid repeating the same thing for every class that extends BaseCardView.

Step 4: Creating the MoviePresenter

The next step is to make a MoviePresenter in order to tell the ArrayObjectAdapter how to render Movie objects.

As you can see, the presenter is very simple in this case. All we needed to do here was create a new Presenter.ViewHolder with the MovieCardView we created earlier. We could also add some type safety and check if the item is a instance of Movie and if the View is a instance of MovieCardView, but we can ignore it for now as we know that all the ViewHolders will have a MovieCardView and a Movie as an object.

Step 5: Setting up the Main BrowseFragment.

In this step we will set up the Adapter of the BrowseFragment. Open the MainFragment. Most of the code we will be adding is inside the createRows() and onActivityCreated() method, that is where we will setup the adapters for the fragment.

We should add the following:
(Read the comments in the code for more info)

Note: Check out the bindMovies() method to understand how the response is added to the RowsAdapter set to the fragment.

Now you should be able to Run the project and see a list of rows with movies from TMDB.

It now looks somewhat like this:

If you compare to the previous screenshot we see that we are missing the cool background art from each movie. We will fix that on the next step.

Note: If nothing appears, please check if you added the right API key from TMDB in the file.

Step 6: Adding the background

There are two interfaces that allow us to interact with the cards in the rows.

  • OnItemViewClickedListener: Handles when a user clicks on a card
  • OnItemViewSelectedListener: Handles when user hovers on a card.

For the purpose of changing the background of the page we will use the second one.

The 1st step is to add the interface in the MainFragment and implement the required method onItemSelected

Open and add the following:

Now run the project again and try moving through the cards. The background for each item should change to a backdrop image provided by TMDB.

It should now look somewhat like this:

Background changes as we move through the movies

Congrats! You have your first TV app to show the newest movies on TMDB. For now it doesn’t do much as we can only see the poster of the movies.

On Part 2 of the tutorial, we will be creating a details page for the movie and implement the OnItemViewClickedListener to handle clicks on the cards.

The full code for Part 1 can be found in the Part 1 branch of this project. The Github repository also has screenshots of the full app!

Thanks for reading, if you liked it don’t forget to click o the hearth to help more people find it!

Check out Part 2 to lear how to show details of a movie using a DetailsFragment!