直接前往內容

最常造訪的網頁

最近瀏覽的網頁

navigation

Displaying Content in Recommendations Channels

The Android TV home screen, or simply the home screen, provides a UI that displays recommended content as a table of channels and programs. Each row is a channel. A channel contains cards for every program available on that channel:

TV home screen

This document demonstrates how to add channels and programs to the home screen, update content, handle user actions, and provide the best experience for your users. (If you'd like to dig deeper into the API, try the home screen codelab and watch the I/O 2017 Android TV session.)

Note: Recommendations channels are only available in Android 8.0 (API level 26) and later. You must use them to supply recommendations for apps running in Android 8.0 (API level 26) and later. To supply recommendations for apps running on earlier versions of Android, your app must use the recommendations row instead.

The home screen UI

Apps can create new channels, add, remove, and update the programs in a channel, and control the order of programs in a channel. For example an app can create a channel called "What's New" and show cards for newly available programs.

Apps cannot control the order in which channels appear in the home screen. When your app creates a new channel, the home screen adds it to the bottom of the channel list. The user can reorder, hide, and show channels.

The Watch Next channel

The Watch Next channel is the second row that appears in the home screen, after the apps row. The system creates and maintains this channel. Your app can add programs to the Watch Next channel: programs that the user marked as interesting, stopped watching in the middle, or that are related to the content the user is watching (like the next episode in a series or next season of a show).

The Watch Next channel has some constraints: Your app cannot move, remove, or hide the Watch Next channel's row.

App channels

The channels that your app creates all follow this life cycle:

  1. User discovers a channel in your app and requests to add it to the home screen.
  2. App creates the channel and adds it to the TvProvider (at this point the channel is not visible).
  3. App asks the system to display the channel.
  4. System asks user to approve the new channel.
  5. New channel appears in the last row of the home screen.

The default channel

Your app can offer any number of channels for the user to add to the home screen. The user usually has to select and approve each channel before it appears in the home screen. Every app has the option of creating one default channel. The default channel is special because it automatically appears in the home screen; the user does not have to explicitly request it.

Prerequisites

The Android TV home screen uses Android's TvProvider APIs to manage the channels and programs that your app creates. To access the provider's data, add the following permissions to your app's manifest:

<uses-permission android:name="com.android.providers.tv.permission.READ_EPG_DATA" />
<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

The TvProvider support library makes it easier to use the provider. Add it to the dependencies in your build.gradle file:

compile 'com.android.support:support-tv-provider:27.0.0'

To work with channels and programs, be sure to include these support library imports in your program:

import android.support.media.tv.Channel;
import android.support.media.tv.TvContractCompat;
import android.support.media.tv.ChannelLogoUtils;
import android.support.media.tv.PreviewProgram;
import android.support.media.tv.WatchNextProgram;

Channels

The first channel your app creates becomes its default channel. The default channel automatically appears in the home screen. All other channels you create must be selected and accepted by the user before they can appear in the home screen.

Creating a channel

Your app should ask the system to show newly added channels only when it is running in the foreground. This prevents your app from displaying a dialog requesting approval to add your channel while the user is running a different app. If you try to add a channel while running in the background, the activity's onActivityResult() method returns the status code RESULT_CANCELED.

To create a channel, follow these steps:

  1. Create a channel builder and set its attributes:

    Channel.Builder builder = new Channel.Builder();
    // Every channel you create must have the type `TYPE_PREVIEW`
    builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
           .setDisplayName("Channel Name")
           .setAppLinkIntentUri(uri);
    

    The channel type must be TYPE_PREVIEW. Add more attributes as required.

  2. Insert the channel into the provider:

    Uri channelUri = context.getContentResolver().insert(
      TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());
    

    You need to save the channel ID in order to add programs to the channel later. Extract the channel ID from the returned URI:

    long channelId = ContentUris.parseId(channelUri);
    

  3. You must add a logo for your channel. Use a Uri or Bitmap:

    // Choose one or the other
    storeChannelLogo(Context context, long channelId, Uri logoUri); // also works if logoUri is a URL
    storeChannelLogo(Context context, long channelId, Bitmap logo);
    

    The logo icon should be 80dp x 80dp, and it must be opaque. It is displayed under a circular mask:

    TV home screen icon mask

  4. Create the default channel (optional):

    When your app creates its first channel, you can make it the default channel so it appears in the home screen immediately without any user action:

    TvContractCompat.requestChannelBrowsable(context, channelId);
    

    Any other channels you create aren't visible until the user explicitly selects them.

Updating a channel

Updating channels is very similar to creating them.

Use another Channel.Builder to set the attributes that need to change.

Use the ContentResolver to update the channel. Use the channel ID that you saved when the channel was originally added:

context.getContentResolver().update(TvContractCompat.buildChannelUri(channelId),
    builder.build().toContentValues(), null, null);

To update a channel's logo, use storeChannelLogo().

Deleting a channel

context.getContentResolver().delete(TvContractCompat.buildChannelUri(channelId), null, null);

Programs

Adding programs to an app channel

Create a PreviewProgram.Builder and set its attributes:

PreviewProgram.Builder builder = new PreviewProgram.Builder();
builder.setChannelId(channelId)  
       .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
       .setTitle("Title")
       .setDescription("Program description")
       .setPosterArtUri(uri)
       .setIntentUri(uri)
       .setInternalProviderId(appProgramId);

Add more attributes depending on the type of program. (To see the attributes available for each type of program, refer to the tables below.)

Insert the program into the provider:

Uri programUri = context.getContentResolver().insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
      builder.build().toContentValues());

Retrieve the program ID for later reference:

long programId = ContentUris.parseId(programUri);

Adding programs to the Watch Next channel

Inserting programs into the Watch Next channel is the same as inserting programs into your own channel.

There are four types of programs; select the appropriate type:

TypeNotes
WATCH_NEXT_TYPE_CONTINUEThe user stopped while watching content.
WATCH_NEXT_TYPE_NEXTThe next available program in a series the user is watching is available. For example, if the user is watching episode 3 of a series, the app can suggest that they watch episode 4 next.
WATCH_NEXT_TYPE_NEWNew content that clearly follows what the user is watching is now available. For example, the user is watching episode number 5 from a series and episode 6 becomes available for watching.
WATCH_NEXT_TYPE_WATCHLISTInserted by the system or the app when the user saves a program.

Use a WatchNextProgram.Builder:

WatchNextProgram.Builder builder = new WatchNextProgram.Builder();
builder.setType(TvContractCompat.WatchNextPrograms.TYPE_CLIP)
       .setWatchNextType(TvContractCompat.WatchNextPrograms.WATCH_NEXT_TYPE_CONTINUE)
       .setLastEngagementTimeUtcMillis(time)
       .setTitle("Title")
       .setDescription("Program description")
       .setPosterArtUri(uri)
       .setIntentUri(uri)
       .setInternalProviderId(appProgramId);

Uri watchNextProgramUri = context.getContentResolver()
        .insert(TvContractCompat.WatchNextPrograms.CONTENT_URI, builder.build().toContentValues());

Use TvContractCompat.buildWatchNextProgramUri(long watchNextProgramId) to create the Uri you need to update a Watch Next program.

When the user adds a program to the Watch Next channel, the system copies the program to the row. It sends the intent TvContractCompat.ACTION_PREVIEW_PROGRAM_ADDED_TO_WATCH_NEXT to notify the app that the program has been added. The intent includes two extras: the program ID that was copied and the program ID created for the program in the Watch Next channel.

Updating a program

You can change a program's information. For example, you may want to update the rental price for a the movie, or update a progress bar showing how much of a program the user has watched.

Use a PreviewProgram.Builder to set the attributes you need to change, then call getContentResolver().update to update the program. Specify the program ID that you saved when the program was originally added:

context.getContentResolver().update(TvContractCompat.buildPreviewProgramUri(programId),
    builder.build().toContentValues(), null, null);

Deleting a program

context.getContentResolver().delete(TvContractCompat.buildPreviewProgramUri(programId), null, null);

Handling user actions

Your app can help users discover content by providing a UI to display and add channels. Your app should also handle interactions with your channels after they appear in the home screen.

Discovering and adding channels

Your app can provide a UI element that lets the user select and add its channels (for example, a button that asks to add the channel). After the user requests a specific channel, execute this code to get the user's permission to add it to the home screen UI:

Intent intent = new Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE);
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId);
try {
   activity.startActivityForResult(intent, 0);
} catch (ActivityNotFoundException e) {
  // handle error
}

The system displays a dialog asking the user to approve the channel. Handle the result of the request in the onActivityResult method of your activity (Activity.RESULT_CANCELED or Activity.RESULT_OK).

Android TV home screen events

When the user interacts with the programs/channels published by the app, the home screen sends intents to the app:

Make sure to create intent filters for all the Uris that the home screen sends for user interactions; for example:

<receiver
   android:name=".WatchNextProgramRemoved"
   android:enabled="true"
   android:exported="true">
   <intent-filter>
       <action android:name="android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED" />
   </intent-filter>
</receiver>

Best practices

Attributes

This section describes the channel and program attributes separately.

Channel attributes

You must specify these attributes for every channel:

Attribute Notes
TYPE set to TYPE_PREVIEW.
DISPLAY_NAME set to the name of the channel.
APP_LINK_INTENT_URI When the user selects the channel's logo the system sends an intent to start an activity that presents content relevant to the channel. Set this attribute to the Uri used in the intent filter for that activity.

In addition, a channel also has six fields reserved for internal app usage. These fields can be used to store keys or other values that can help the app map the channel to its internal data structure:

Program attributes

See the individual pages for the attributes for each type of program:

Sample Code

To learn more about building apps that interact with the home screen and add channels and programs to the Android TV home screen, see our home screen codelab and github sample.

本網站使用 Cookie 儲存你在此指定的語言和顯示選項偏好設定。

掌握有關 Android 開發人員的最新消息和實用訣竅,協助你製作最受歡迎的 Google Play 內容。

* 必填欄位

訂閱成功!

在 WeChat 上追蹤 Google Developers

你要以瀏覽這個網站嗎?

你要求以顯示這個網頁,但你為此網站指定的語言偏好設定為

是否要變更語言偏好設定並改用瀏覽網站?稍後如要變更語言偏好設定,請利用位在每個網頁最下方的語言選單來調整設定。

你的 API 層級必須達 以上才能存取這個級別

本說明文件已隱藏,因為你為該文件選取的 API 層級為 。使用左側導覽列上方的選取工具即可變更說明文件的 API 層級。

如需進一步瞭解如何為應用程式指定 API 層級的相關資訊,請參閱 Supporting Different Platform Versions (支援不同的平台版本) (英文)。

Take a short survey?
Help us improve the Android developer experience. (April 2018 — Developer Survey)