主屏幕上的频道

Android TV 主屏幕提供了一个界面,该界面以频道和节目表格的形式显示推荐内容。每行对应一个频道。频道包含该频道上每个可用节目的卡片:

Android TV 主屏幕
Android TV 主屏幕

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

主屏幕界面

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

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

“接下来观看”频道

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

应用频道

应用创建的所有渠道都遵循以下生命周期:

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

如需使用频道和节目,请务必在您的程序中添加以下支持库导入:

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。根据需要添加更多属性。

    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)

  2. 将频道插入提供程序:

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

  3. 您需要保存频道 ID,以便稍后向频道添加节目。从返回的 URI 中提取频道 ID:

    var channelId = ContentUris.parseId(channelUri)

  4. 您必须为频道添加徽标。请使用 Uri 或 Bitmap。徽标图标应为 80dp x 80dp,且必须不透明。它显示在圆形遮罩下:

    TV 主屏幕图标遮罩

    // Choose one or the other.
    storeChannelLogo(context, channelId, logoUri) // also works if logoUri is a URL.
    storeChannelLogo(context, channelId, logo)

  5. 创建默认频道(可选):当您的应用创建其第一个频道时,您可以将其设为默认频道,以便它立即显示在主屏幕上,而无需用户执行任何操作。您创建的任何其他频道在用户明确选择之前都不会显示。

    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:

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

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

删除频道

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

计划

节目是频道中显示的各个内容卡片。您可以将节目发布到应用的自定义频道和系统管理的“接下来观看”频道。

向应用频道中添加节目

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

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

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

将节目插入提供程序:

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

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

val programId = ContentUris.parseId(programUri)

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

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

更新节目

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

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

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

删除节目

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

处理用户操作

您的应用可以提供一个界面来显示和添加频道,从而帮助用户发现内容。您的应用还应处理与频道在主屏幕中显示后的互动。

发现并添加频道

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

在用户请求特定频道后,执行以下代码以获取用户将其添加到主屏幕界面的权限:

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
}

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

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_PROGRAMS 的 BroadcastReceiver 应为未经身份验证的用户推荐频道内容。例如,您的应用可以先显示最佳内容或当前热门内容。用户登录后,该应用可以显示个性化内容。这是应用在用户登录前向其追加销售的绝佳机会。
  • 当您的应用不在前台运行,而您需要更新频道或节目时,请使用 JobScheduler 安排工作(请参阅 JobScheduler 和 JobService)。
  • 如果您的应用行为不当(例如,持续向提供程序发送垃圾数据),系统可能会撤消应用的提供程序权限。请务必使用 try-catch 子句封装访问提供程序的代码,以处理安全异常。
  • 在更新节目和频道之前,请向提供方查询您需要更新的数据并协调数据。例如,无需更新用户想要从界面中移除的节目。使用后台作业,在查询现有数据并请求批准频道后,将数据插入或更新到提供程序中。您可以在应用启动时以及应用需要更新其数据时运行此作业。

context.contentResolver
    .query(
        TvContractCompat.buildChannelUri(channelId),
        null, null, null, null
    ).use({
            cursor ->
        if (cursor != null && cursor.moveToNext()) {
            val 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。

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

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

节目属性

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

示例代码

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