How nice would it be to display your app content before the user thinks about opening it? Guess what? This is possible with the Channels API!

In this post, we will go through a step-by-step guide with some helpful insights on creating and publishing your app’s Preview Channels to the Android TV home screen and how to handle user interaction with your channels. Make sure to check out the sample app with all the concepts of this post.

dependencies {
    ...
    implementation 'androidx.tvprovider:tvprovider:1.1.0-alpha01'
}

Note: We will cover the queryChannels() function later. For now, assume that it returns all channels of your app.

After building the channel, we need to use the ContentResolver to insert or update it on the database which is used by the system to get information about the channels.

Publishing a channel

As mentioned, creating a channel is not enough to make it visible on the home screen. We need to ask for the user’s permission to publish the channel. The code for this is very straightforward:

This will prompt the user with a dialog asking to add the channel to the TV home screen.

The default channel

To create the default channel, we will use a BroadcastReceiver usually triggered once your app is installed. In rare cases, it can be triggered only on the first app launch. Add the following to your AndroidManifest.xml

And here’s how we can implement the BroadcastReceiver:

💡 Tip: Notice the call to Channel.setInternalProviderId() function. This is a way to set the id your app uses to identify the channel. As the channel id needs to be unique among all the installed apps, it is generated by the database, and we can’t change it. That’s why we have the setInternalProviderId() API to store your app’s internal id for that channel.

To test your BroadcastReceiver implementation, you can trigger its Intent via adb with the following code:

adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \
    your.package.name/.YourReceiverName

Querying channel information

To manage the app channels, we usually need to query for their data to decide what information needs to change, what programs we need to add or remove, and what shouldn’t be touched.

There are a few ways and APIs to help us with that. If you want complete control and access to all your channel data, use the ContentResolver API and query the channels database for the exact information you need. If you only need to read the basics about your channel, you can use the PreviewChannelHelper API.

PreviewChannelHelper

With PreviewChannelHelper, you have out-of-the-box implementations of the most common CRUD operations with channels and programs. It is an abstraction layer on top of the low-level operations that can be performed with the ContentResolver. Take a look at the documentation for the available functions.

When reading channel data with the PreviewChannelHelper, you can only read the columns listed on the PreviewChannelHelper.Columns.PROJECTION array which are:

A channel has plenty more attributes than this. Take a look at the getProjection() function in its source code to see all the existing attributes.

A very useful attribute is the Channels.COLUMN_BROWSABLE, which indicates if the channel is already published or not. With that, you can show or hide a button to remove the channel from the TV home screen from inside your app. To query that value from the database though, you must use the ContentProvider.

💡 Tip: To avoid frustrations and lost time debugging things like a channel property value not making sense, e.g., a channel that is already published having the Channel.isBrowsable property being false, be aware that the PreviewChannelHelper fills the Channel instance variables with the result of the query from the PROJECTION shown above, which has very limited information. In other words, properties not listed on the projection will have the field default value (false for booleans, 0 for numbers, and so on…)

ContentProvider

Using the ContentProvider APIs gives you full control of the data you want to query. If you want, for example, to query all attributes from a channel you can do the following:

💡 Tip: Check the implementations of PreviewChannelHelper functions and adjust them for your needs.

Creating or Updating a Program

In the same way we manage channels, managing programs is very similar. Look at how we can create or update an existing program and add it to a channel.

💡 Tip: Notice the call to PreviewProgram.Builder.setInternalProviderId() function. It follows the same logic as the channel builder by providing a way to store the app internal content id into a program.

⚠️ Attention: TheContentProvider CRUD operations are I/O operations. To have the best performance on your app, make sure you are running these operations outside the main thread.

To wrap up the program management section, check out the implementation of the getChannelPrograms() function.

Handling User Actions on programs and channels

Handling user actions is basically handling App Links. When the user clicks on a channel or program, an Intent will be sent to your app with the URI provided on the channel/program creation. After that, it’s basically navigating to that piece of content on your app.

Start by adding an <intent-filter> to an <activity> on your app’s AndroidManifest.xml like the following:

And add some code to handle the Intent on your Activity or Fragment for example:

That’s another wrap!

If you got to this point, thank you for reading this post! I’m sure you’re striving to build (or already built) an awesome app for your users!

Follow me to be notified about the next posts. You can also reach me on Twitter with questions or suggestions at @admqueiroga

Additional resources:

1. Make sure to surf through the official and amazing documentation on channels. There’s a lot of knowledge in there.
2. Check out the channels codelab.
3. Check the App-Links documentation.
4. Take a look at the sample app I used to learn and get inspiration for this post

See you soon!

This article was previously published on proandroiddev.com