開始使用 TV 應用程式

TV 應用程式採用的結構與手機和平板電腦應用程式相同。這種相似之處表示您可以修改現有應用程式，使其一併在 TV 裝置上執行，或是根據建構 Android 應用程式的既有知識建立新的應用程式。

重要事項：您的應用程式必須符合特定需求，才能成為 Google Play 的 Android TV 應用程式。詳情請參閱 TV 應用程式品質指南中所列的規定。

本指南說明如何準備開發環境來建構 TV 應用程式，以及讓應用程式可在 TV 裝置上執行的最低必要變更。

如需設計電視應用程式的相關資訊，請參閱「為電視設計」和「打造 TV 版面配置」。如要查看範例電視應用程式，請參閱 Android TV GitHub 存放區中的 Android Leanback 範例應用程式。

決定媒體格式支援

請參閱下列說明文件，瞭解 Android TV 支援的轉碼器、通訊協定和格式：

設定電視專案

本節說明如何設定 TV 專案，無論是要修改現有 Android 應用程式以在 TV 裝置上執行，還是建立新的 TV 應用程式，都可以透過新增 Android TV 支援功能，利用現有的應用程式架構設計電視的使用者介面。

建立在 TV 裝置上執行的應用程式時，需要使用以下兩個主要元件：

  • 電視活動：在應用程式資訊清單中，宣告預計在 TV 裝置上執行的活動。
  • TV 程式庫：您可以視需要加入一或多個適用於電視裝置的 androidx 程式庫，詳情請參閱本指南的其他章節。這些程式庫提供用於建構使用者介面的小工具。

必要條件

開始建構電視應用程式前，請先完成下列步驟：

  • 將 SDK 工具更新至 24.0.0 以上版本。
    新版 SDK 工具可讓您建構及測試電視專用應用程式。
  • 更新 SDK 至 Android 5.0 (API 21) 以上版本。
    更新平台版本為電視應用程式提供新的 API。
  • 建立或更新應用程式專案。
    如要存取電視裝置的新 API，請建立專案或修改指定 Android 5.0 (API 級別 21) 以上版本的現有專案。

宣告電視活動

要在 TV 裝置上執行的應用程式，必須在資訊清單中宣告電視的啟動器活動。系統會使用 CATEGORY_LEANBACK_LAUNCHER 意圖篩選器執行此操作。此篩選器會將您的應用程式視為已啟用電視，並讓 Google Play 將其識別為電視應用程式。當使用者在電視主畫面上選取您的應用程式時，這項意圖會識別要啟動哪個活動。

下列程式碼片段說明如何將這個意圖篩選器納入資訊清單：

<application
  android:banner="@drawable/banner" >
  ...
  <activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
  </activity>

  <activity
    android:name="com.example.android.TvActivity"
    android:label="@string/app_name"
    android:theme="@style/Theme.Leanback">

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>

  </activity>
</application>

這個範例中的第二個活動資訊清單項目會指定這是要在電視裝置上啟動的活動。

注意：如果您未在應用程式中加入 CATEGORY_LEANBACK_LAUNCHER 意圖篩選器，透過 TV 裝置執行 Google Play 的使用者就不會看到這個篩選器。此外，如果您使用開發人員工具將應用程式載入電視裝置時沒有這個篩選器，則電視使用者介面就不會顯示該應用程式。

TV 應用程式的使用者介面或現有應用程式的電視部分，必須提供簡單的介面，讓使用者在 10 英尺遠處也能輕鬆操作。如要修改現有應用程式以便用於電視，請勿針對手機和平板電腦使用與電視相同的活動版面配置。如需電視應用程式設計指南，請參閱「在電視上設計應用程式」。如要進一步瞭解電視介面版面配置的基本實作要求，請參閱「建構 TV 版面配置」。

宣告 Leanback 支援

宣告應用程式會使用 Android TV 所需的 Leanback 使用者介面。如果應用程式同時在行動裝置和 Android TV 上執行，請將 required 屬性值設為 false。如果將 required 屬性值設為 true，應用程式只能在使用 Leanback UI 的裝置上執行。

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

無須宣告觸控螢幕

可在電視裝置上執行的應用程式，不需要以觸控螢幕輸入。為此，電視應用程式的資訊清單必須宣告 android.hardware.touchscreen 功能非必要功能。這項設定會將應用程式視為可以在 TV 裝置上運作，而 Google Play 必須將您的應用程式視為電視應用程式。以下程式碼範例說明如何加入這個資訊清單宣告：

<manifest>
    <uses-feature android:name="android.hardware.touchscreen"
              android:required="false" />
    ...
</manifest>

注意：您必須在應用程式資訊清單中，宣告不需要觸控螢幕，如以下範例程式碼所示。否則，您的應用程式不會顯示在 Google Play 電視裝置上。

提供主畫面圖示和橫幅

Android TV 應用程式必須提供每個本地化版本的主畫面圖示和橫幅圖片。視 Android TV 裝置而定，圖示或橫幅會用來當做應用程式啟動點，顯示在應用程式和遊戲列的主畫面中。

如要在應用程式中加入這些內容，請在資訊清單中描述圖示和橫幅，如下所示： 

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

主畫面圖示

Android TV 應用程式和其他 Android 應用程式一樣，必須提供主畫面圖示。如需瞭解如何為應用程式獲得出色推出點的最佳做法，以及詳細的資產規定，請參閱 Android TV 應用程式圖示和橫幅規範。

使用 android:banner 屬性與 <application> 標記，可提供所有應用程式活動的預設橫幅，而與 <activity> 標記搭配使用，為特定活動提供橫幅。

橫幅請使用大小為 320 x 180 像素的 xhdpi 資源。圖片必須包含文字。如果您的應用程式有多個語言版本，則必須為每個支援的語言提供不同的橫幅版本。

變更啟動器顏色

注意：在 Android 12 以上版本中，使用 SplashScreen 平台 API 建構的自訂啟動畫面動畫不適用於 Android TV 應用程式。

當電視應用程式啟動時，系統會顯示類似展開的填滿圓圈的動畫。如要自訂這個動畫的顏色，請將電視應用程式或活動的 android:colorPrimary 屬性設為特定顏色。此外，請將兩個轉場重疊屬性設為 true，如以下主題資源 XML 檔案中的程式碼片段：

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

如要進一步瞭解如何使用主題和樣式，請參閱「樣式和主題」。

新增 TV 媒體庫

Jetpack 包含可用於電視應用程式的 androidx 套件程式庫。這些程式庫為電視裝置提供 API 和使用者介面小工具：

打造 TV 應用程式

完成上述步驟後，即可開始建構大螢幕應用程式！歡迎查看下列其他主題，瞭解如何建構電視專用應用程式：

  • 打造電視播放應用程式：電視為娛樂使用者打造而成，因此 Android 提供一組使用者介面工具和小工具，可讓您建構會播放影片和音樂的電視應用程式，讓使用者能夠瀏覽自己想要的內容。
  • 協助使用者在 Android TV 上找到您的內容： 使用者可動手執行所有內容選項，協助他們找到喜愛的內容，幾乎與提供這些內容一樣重要。本指南將說明如何在 TV 裝置上顯示您的內容。
  • 打造電玩遊戲：電視裝置是遊戲的絕佳平台。如要瞭解如何為電視打造絕佳的遊戲體驗，請參閱這個主題。
  • 打造電視輸入服務：以線性的「廣播電視」風格呈現您的影片內容，讓使用者可透過節目指南和向上/向下按鈕存取頻道和節目。

執行 TV 應用程式

執行應用程式是開發過程中相當重要的一環。您可以在支援 USB 偵錯功能的電視裝置上執行應用程式，或使用虛擬電視裝置。

在實體裝置上執行

設定電視裝置的步驟如下：

  1. 使用 USB 傳輸線將電視裝置連接到開發機器。如有需要，請參閱裝置製造商提供的說明文件。
  2. 在電視裝置上前往「設定」。
  3. 在「裝置」列中，選取「關於」。
  4. 向下捲動至「Build」並多次選取「Build」數次，直到畫面上顯示「開發人員設定已啟用！」訊息。
  5. 返回「設定」。在「Preferences」列中，選取「Developer options」。
  6. 依序選取「Debugging」>「USB 偵錯」，然後選取「開啟」。
  7. 返回電視主畫面。

如何在電視裝置上測試應用程式：

  1. 在 Android Studio 中選取專案，然後按一下工具列中的「Run」圖示 。
  2. 在「Select Deployment Target」視窗中，選取電視裝置，然後按一下「OK」。

在虛擬裝置上執行

Android SDK 中的 AVD Manager 提供裝置定義，讓您建立用來執行及測試應用程式的虛擬電視裝置。

如何建立虛擬電視裝置：

  1. 啟動 AVD Manager。詳情請參閱「建立及管理虛擬裝置」。
  2. 在 AVD Manager 對話方塊中，按一下「Device Definitions」(裝置定義) 分頁標籤。
  3. 選取其中一個 Android TV 裝置定義，然後按一下「建立 AVD」。
  4. 選取模擬器選項，然後按一下「OK」建立 AVD。

    注意：為獲得最佳電視模擬器裝置效能，請使用 x86 模擬器並啟用「Use Host GPU」選項。如果有的話，也請用虛擬裝置加速功能。如要進一步瞭解模擬器的硬體加速功能，請參閱「設定 Android Emulator 的硬體加速功能」一文。

如何在虛擬電視裝置上測試應用程式：

  1. 在 Android Studio 中選取專案，然後按一下工具列中的「Run」圖示 。
  2. 在「Select Deployment Target」視窗中，選取虛擬電視裝置，然後按一下「OK」。

如要進一步瞭解如何使用模擬器，請參閱「 在 Android Emulator 上執行應用程式」。如要進一步瞭解如何從 Android Studio 將應用程式部署至虛擬裝置，請參閱「對應用程式進行偵錯」。

讓 TV 應用程式當做免安裝體驗執行

免安裝體驗可讓使用者輕鬆試用您的 TV 應用程式，有助於提高採用率。

如要將電視應用程式設為在 Android TV 裝置或模擬器上以免安裝應用程式形式執行，請先按照操作說明建立免安裝即用應用程式套件。

接著，在電視應用程式 MainActivity 的 intent-filter 中，確認 LAUNCHER 和 LEANBACK_LAUNCHER 都已在 AndroidManifest.xml 中宣告：

<activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
      <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
  </activity>

TV 應用程式現已設定成免安裝體驗。

準備要發布的 TV 應用程式

請參閱 TV 應用程式檢查清單，瞭解接下來的步驟，以發布及發布 TV 應用程式。

下一頁
AndroidX TV 媒體庫