建立及執行 TV 應用程式

電視應用程式的結構與手機和平板電腦應用程式相同。這表示您可以修改現有應用程式，讓應用程式也能在電視裝置上執行，或是根據您已知的 Android 應用程式建構方式，建立新的應用程式。

重要事項：應用程式必須符合特定條件，才能在 Google Play 上成為 Android TV 應用程式。詳情請參閱「TV 應用程式品質」一文列出的規定。

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

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

判斷媒體格式支援情形

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

設定電視專案

本節將說明如何設定 TV 專案，無論您是修改現有的 Android 應用程式，使其能在 TV 裝置上執行，還是建立新的 TV 應用程式，都適用於本節內容。如果您有現有的 Android 應用程式，只要新增 Android TV 支援，就能為 TV 設計使用者介面，同時重複使用現有的應用程式架構。

建立可在電視裝置上執行的應用程式時，主要會用到下列兩個元件：

  • 電視專用活動：在應用程式資訊清單中，宣告將在電視裝置上執行的活動。
  • TV 程式庫：您可以選擇加入一或多個適用於 TV 裝置的 androidx 程式庫，這些程式庫列於本指南的另一個章節。這些程式庫提供的小工具可用於建構使用者介面。

必要條件

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

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

宣告電視活動

如要在電視裝置上執行應用程式，必須在資訊清單中宣告電視的啟動器活動。這項作業會使用 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 的使用者就看不到該應用程式。此外，如果您使用開發人員工具將應用程式載入電視裝置，但應用程式沒有這個篩選器，應用程式就不會顯示在電視使用者介面中。

電視應用程式的使用者介面 (或現有應用程式的電視部分) 必須提供直覺式導覽功能，讓使用者在 10 英尺外也能使用遙控器操作。如果您要修改現有應用程式，以便在電視上使用，請勿在電視上使用與手機和平板電腦相同的活動版面配置。如需設計 TV 應用程式的指南，請參閱「為 TV 設計」。

宣告支援電視裝置

宣告 android.software.leanback 功能，聲明您的應用程式是為 Android TV 打造。

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

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

宣告不需要觸控螢幕

在電視裝置上執行的應用程式不會依賴觸控螢幕輸入內容。 為明確指出這點，電視應用程式的資訊清單必須宣告 android.hardware.touchscreen 功能為非必要。這項設定會將應用程式識別為可在電視裝置上運作，且應用程式必須具備這項設定，Google Play 才會將其視為 TV 應用程式。以下程式碼範例說明如何加入這項資訊清單宣告：

<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> 標記搭配使用，則可為特定活動提供橫幅。

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

變更啟動器顏色

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

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

<resources>
    <style name="MyTheme">
      <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 套件程式庫，可用於 TV 應用程式。

Compose for TV

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

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

Leanback UI 工具包

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

請參閱「打造 TV 播放應用程式」，瞭解如何使用 Leanback UI 工具包建構 TV 應用程式。

執行 TV 應用程式

執行應用程式是開發程序的重要環節。您可以在設定為支援 USB 偵錯的電視裝置上執行應用程式，也可以使用虛擬電視裝置。

在實體裝置上執行

請按照下列步驟設定電視裝置：

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

如要在電視裝置上測試應用程式，請按照下列步驟操作：

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

在虛擬裝置上執行

Android SDK 中的 AVD 管理工具提供裝置定義，可讓您建立虛擬電視裝置，用於執行及測試應用程式。

如要建立虛擬電視裝置，請按照下列步驟操作：

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

    注意：如要讓電視模擬器裝置發揮最佳效能，請使用 x86 模擬器，並啟用「使用主機 GPU」選項。此外，請盡可能使用虛擬裝置加速功能。如要進一步瞭解模擬器的硬體加速功能，請參閱「設定 Android Emulator 的硬體加速功能」。

如要在虛擬電視裝置上測試應用程式，請按照下列步驟操作：

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

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

啟用電視應用程式，以免安裝體驗的形式執行

免安裝體驗可讓使用者不必安裝就能試用電視應用程式，有助於提高採用率。

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

接著，在電視應用程式的 intent-filterMainActivity 中，確認 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 硬體