建立及執行 TV 應用程式

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

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

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

如要瞭解如何設計電視應用程式，請參閱「為電視設計」。另請參閱 Android TV GitHub 存放區中的範例應用程式。

決定支援的媒體格式

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

設定電視專案

本節說明如何設定 TV 專案，無論是修改現有的 Android 應用程式，以在 TV 裝置上執行，或是建立新的 TV 應用程式。如果您已有 Android 應用程式，新增 Android TV 支援功能之後，您就能為電視設計使用者介面，同時重複使用現有的應用程式架構。

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

  • 電視活動：在應用程式資訊清單中，宣告要在 TV 裝置上執行的活動。
  • 電視程式庫：選擇是否包含適用於 TV 裝置的一或多個 androidx 程式庫，詳見本指南的另一章節。這些程式庫提供的小工具可用來建立使用者介面。

必要條件

開始建構 TV 應用程式前，請先採取下列步驟：

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

宣告電視活動

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

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

<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 使用者介面中。

TV 應用程式的使用者介面，或現有應用程式的電視部分，必須提供簡單的介面，讓使用者能利用距離 10 英尺遠的遙控器輕鬆瀏覽內容。如果您要修改現有應用程式以便在電視上使用，請不要針對手機和平板電腦使用相同的活動版面配置。如需設計 TV 應用程式的指南，請參閱「為 TV 設計」。

宣告電視裝置支援

請宣告 android.software.leanback 功能，宣告您的應用程式專為 Android TV 建構。

如果應用程式同時在行動裝置和電視上運作，請將 required 屬性值設為 false。如果將 required 屬性值設為 true，Google Play 就只會提供 Android TV OS 您的應用程式。

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

不需要宣告觸控螢幕

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

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

注意：在應用程式資訊清單中，您必須宣告觸控螢幕為非必要操作，如以下程式碼範例所示。否則，您的應用程式就不會顯示在 TV 裝置上的 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>

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

打造適用於 Android TV OS 的應用程式

Jetpack 包含可與電視應用程式搭配使用的 androidx 套件程式庫。

Compose for TV

建議您使用 Compose 建構適用於 Android TV OS 的應用程式。除了核心 Compose 程式庫之外，Compose for TV 程式庫也提供專為大螢幕設計的專屬元件：

請參閱「在 Android TV 上使用 Jetpack Compose」一文，瞭解如何使用 Compose for TV 建構 TV 應用程式。

Leanback UI 工具包

Leanback UI 工具包提供電視裝置的 API 和使用者介面小工具：

瞭解如何在「建構電視播放應用程式」中，使用 Leanback UI 工具包建構 TV 應用程式。

執行 TV 應用程式

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

在實體裝置上執行

請按照以下方式設定電視裝置：

  1. 使用 USB 傳輸線將電視裝置連接至開發機器。如有需要，請參閱裝置製造商提供的說明文件。
  2. 在電視裝置上前往「設定」。
  3. 在「裝置」列中選取「關於」。
  4. 捲動至「Build」並選取「Build」數次，直到畫面上顯示「您已成為開發人員！」訊息。
  5. 返回「設定」。在「Preferences」列中，選取「Developer options」。
  6. 依序選取「偵錯」>「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 應用程式，有助於提高採用率。

如要將 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 應用程式。

下一頁
處理 TV 硬體