主屏幕上的频道

Android TV 主屏幕(或简称“主屏幕”)提供了一个以“频道”和“节目”表格的形式显示推荐内容的界面。每行对应一个频道。而每个频道中则包含一些卡片,每个卡片对应着该频道上提供的一个节目:

TV 主屏幕

本文档介绍了如何向主屏幕添加频道和节目、更新内容、处理用户操作,以及为用户提供最佳体验。(如果您想更深入地了解该 API,请尝试学习主屏幕 Codelab 并观看 2017 年 I/O 大会 Android TV 专题演讲。)

注意:推荐频道仅适用于 Android 8.0(API 级别 26)及更高版本。您必须使用它们为在 Android 8.0(API 级别 26)及更高版本中运行的应用提供建议。如需为在较低版本的 Android 上运行的应用提供推荐,您的应用必须改用“推荐”行

主屏幕界面

应用可以创建新频道,在频道中添加、移除和更新节目,以及控制频道中节目的顺序。 例如,应用可以创建一个名为“新内容”的频道,并显示新推出节目的卡片。

应用无法控制频道在主屏幕上显示的顺序。在您的应用创建新频道后,主屏幕会将其添加到频道列表末尾。用户可以重新排列频道顺序,也可以隐藏或显示频道。

“接下来观看”频道

“接下来观看”频道是主屏幕上显示的第二行,位于应用行之后。此频道由系统创建和维护。您的应用可以向“接下来观看”频道添加节目。如需了解详情,请参阅向“接下来观看”频道添加节目

应用频道

您的应用创建的频道均遵循以下流程:

  1. 用户在您的应用中发现频道并请求将其添加到主屏幕中。
  2. 应用创建相应频道,并将其添加到 TvProvider(此时,该频道不会显示)。
  3. 应用要求系统显示该频道。
  4. 系统要求用户批准这个新频道。
  5. 新频道显示在主屏幕上的最后一行中。

默认频道

您的应用可以提供任意数量的频道供用户添加到主屏幕。通常,用户必须先选择并批准每个频道,频道才会显示在主屏幕中。每个应用都可以创建一个默认频道。默认频道比较特殊,因为它会自动显示在主屏幕中;用户无需明确请求该频道。

前提条件

Android TV 主屏幕使用 Android 的 TvProvider API 来管理应用创建的频道和节目。要访问此提供程序的数据,请将以下权限添加到应用清单中:

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

借助 TvProvider 支持库,您可以更轻松地使用此提供程序。请将其添加到 build.gradle 文件的依赖项中:

Groovy

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

implementation("androidx.tvprovider:tvprovider:1.0.0")

如需处理频道和节目,请确保将这些支持库导入到您的程序中:

Kotlin

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

Java

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;

频道

您的应用创建的第一个频道会成为它的默认频道。默认频道会自动显示在主屏幕上,而您创建的所有其他频道,则只有在用户选择并接受之后才会显示在主屏幕上。

创建频道

应用只有在前台运行时才可要求系统显示新添加的频道。这样可以防止您的应用在用户运行其他应用时显示请求批准添加频道的对话框。如果您尝试在后台运行时添加频道,则相应 Activity 的 onActivityResult() 方法会返回状态代码 RESULT_CANCELED

如需创建频道,请按以下步骤操作:

  1. 创建频道 builder 并设置其属性。请注意,渠道类型必须是 TYPE_PREVIEW。根据需要添加更多属性

    Kotlin

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

    Java

    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);
    
  2. 将频道插入提供程序:

    Kotlin

    var channelUri = context.contentResolver.insert(
            TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues())
    

    Java

    Uri channelUri = context.getContentResolver().insert(
            TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());
    
  3. 您需要保存频道 ID,以便稍后向频道添加节目。从返回的 URI 中提取频道 ID:

    Kotlin

    var channelId = ContentUris.parseId(channelUri)
    

    Java

    long channelId = ContentUris.parseId(channelUri);
    
  4. 您必须为频道添加徽标。请使用 UriBitmap。徽标图标应为 80dp x 80dp,并且必须不透明。它显示在圆形蒙版下方:

    TV 主屏幕图标遮罩

    Kotlin

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

    Java

    // 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);
    
  5. 创建默认频道(可选):当应用创建第一个频道时,您可以将其设为默认频道,使其立即显示在主屏幕中,而无需用户执行任何操作。您创建的所有其他频道在用户明确选择之前都不可见。

    Kotlin

    TvContractCompat.requestChannelBrowsable(context, channelId)
    

    Java

    TvContractCompat.requestChannelBrowsable(context, channelId);
    

  6. 让默认频道在应用打开之前就显示出来。如需实现此行为,您可以添加一个 BroadcastReceiver,监听应用安装后主屏幕发送的 android.media.tv.action.INITIALIZE_PROGRAMS 操作:
    <receiver
      android:name=".RunOnInstallReceiver"
      android:exported="true">
        <intent-filter>
          <action android:name="android.media.tv.action.INITIALIZE_PROGRAMS" />
          <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </receiver>
    
    在开发期间旁加载应用时,您可以通过 adb 触发 intent 来测试此步骤,其中 your.package.name/.YourReceiverName 是应用的 BroadcastReceiver

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

    在极少数情况下,您的应用可能会在用户启动应用的同时收到广播。请确保您的代码不会尝试多次添加默认频道。

更新频道

更新频道的过程与创建频道非常相似。

请使用另一个 Channel.Builder 来设置需要更改的属性。

请使用 ContentResolver 来更新频道。请使用最初添加频道时保存的频道 ID:

Kotlin

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

Java

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

如需更新频道徽标,请使用 storeChannelLogo()

删除频道

Kotlin

context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)

Java

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

计划

向应用频道中添加节目

创建 PreviewProgram.Builder 并设置其属性:

Kotlin

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

Java

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);

根据节目类型添加更多属性。(如需查看每种类型的节目可用的属性,请参阅下面的表格。)

将节目插入提供程序:

Kotlin

var programUri = context.contentResolver.insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
        builder.build().toContentValues())

Java

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

提取节目 ID 以供日后引用:

Kotlin

val programId = ContentUris.parseId(programUri)

Java

long programId = ContentUris.parseId(programUri);

向“接下来观看”频道添加节目

如需向“接下来观看”频道插入节目,请参阅向“接下来观看”频道添加节目

更新节目

您可以更新节目信息。例如,您可能要更新电影的租借价格,或更新显示用户观看进度的进度条。

使用 PreviewProgram.Builder 设置需要更改的属性,然后调用 getContentResolver().update 来更新节目。指定您在最初添加节目时保存的节目 ID:

Kotlin

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

Java

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

删除节目

Kotlin

context.contentResolver
        .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)

Java

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

处理用户操作

您的应用可以提供用于显示和添加频道的界面,帮助用户发现内容。在频道显示在主屏幕上之后,您的应用还需处理用户与这些频道的交互。

发现并添加频道

您的应用可以提供一个界面元素,供用户选择并添加应用的频道(例如,要求添加频道的按钮)。

在用户请求特定频道后,请执行此代码,请求用户同意将该频道添加到主屏幕界面中:

Kotlin

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

Java

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
}

系统会显示一个对话框,要求用户批准频道。 请在 Activity(Activity.RESULT_CANCELEDActivity.RESULT_OK)的 onActivityResult 方法中处理请求结果。

Android TV 主屏幕事件

当用户与应用发布的节目/频道互动时,主屏幕会向应用发送 intent:

  • 当用户选择某个频道的徽标后,主屏幕会将存储在该频道的 APP_LINK_INTENT_URI 属性中的 Uri 发送给应用。此时,应用应启动其主界面或与所选频道相关的视图。
  • 当用户选择某个节目后,主屏幕会将存储在该节目的 INTENT_URI 属性中的 Uri 发送给应用。此时,应用应播放所选的内容。
  • 用户可以表示其对某个节目不再感兴趣,想要从主屏幕界面中移除该节目。系统会从界面中移除该节目,并将该节目的 ID 以及一个 Intent(android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED 或 android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED)一起发送给拥有该节目的应用。应用应该从提供程序中移除该节目,并且不能重新插入该节目。

请务必针对主屏幕为用户互动发送的所有 Uris 创建 intent 过滤器;例如:

<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>

最佳实践

  • 许多 TV 应用都会要求用户登录。在这种情况下,监听 android.media.tv.action.INITIALIZE_PROGRAMSBroadcastReceiver 应该向未经身份验证的用户建议频道内容。例如,您的应用最初可以显示最精彩的内容或当前热门的内容。在用户登录后,它可以显示个性化内容。这也是应用在用户登录前进行追加销售的绝佳机会。
  • 当您的应用不在前台且您需要更新频道或节目时,请使用 JobScheduler 调度工作(请参阅 JobSchedulerJobService)。
  • 如果您的应用行为异常(例如:持续向提供程序发送数据垃圾),系统可能会撤消应用的提供程序权限。请务必使用 try-catch 子句封装用于访问提供程序的代码,以处理安全异常。
  • 在更新节目和频道之前,请向提供程序查询您需要更新和协调数据的数据。例如,无需更新用户想要从界面中移除的节目。使用后台作业,在查询现有数据并请求批准您的频道后,将数据插入/更新提供程序。您可以在应用启动时以及每当应用需要更新其数据时运行此作业。

    Kotlin

    context.contentResolver
      .query(
          TvContractCompat.buildChannelUri(channelId),
              null, null, null, null).use({
                  cursor-> if (cursor != null and cursor.moveToNext()) {
                               val channel = Channel.fromCursor(cursor)
                               if (channel.isBrowsable()) {
                                   //update channel's programs
                               }
                           }
              })
    

    Java

    try (Cursor cursor = context.getContentResolver()
          .query(
              TvContractCompat.buildChannelUri(channelId),
              null,
              null,
              null,
              null)) {
                  if (cursor != null && cursor.moveToNext()) {
                      Channel channel = Channel.fromCursor(cursor);
                      if (channel.isBrowsable()) {
                          //update channel's programs
                      }
                  }
              }
    
  • 针对所有图片(徽标、图标、内容图片)使用不同的 URI。更新图片时请务必使用不同的 URI。系统会缓存所有图片。如果您在更改图片时未更改 URI,系统会继续显示旧图片。

  • 请注意,不能使用 WHERE 语句;如果使用 WHERE 语句调用提供程序,系统将会抛出安全异常。

属性

本部分将分别介绍频道属性和节目属性。

频道属性

您必须为每个频道指定以下属性:

属性 备注
TYPE 设为 TYPE_PREVIEW
DISPLAY_NAME 设置为频道名称。
APP_LINK_INTENT_URI 在用户选择频道徽标后,系统会发送 Intent 以启动提供与频道相关的内容的 Activity。请将此属性设为该 Activity 的 intent 过滤器中使用的 URI。

此外,频道还预留了 6 个字段供内部应用使用。这些字段可用于存储键或其他值,以帮助应用将频道映射到其内部数据结构:

  • INTERNAL_PROVIDER_ID
  • INTERNAL_PROVIDER_DATA
  • INTERNAL_PROVIDER_FLAG1
  • INTERNAL_PROVIDER_FLAG2
  • INTERNAL_PROVIDER_FLAG3
  • INTERNAL_PROVIDER_FLAG4

节目属性

请参阅每种节目类型所对应的属性的说明页面:

示例代码

如需详细了解如何构建能够与 Android TV 主屏幕交互并向主屏幕添加频道和节目的应用,请参阅我们的主屏幕 Codelab