建立及執行 TV 應用程式

TV 應用程式採用的結構與手機和平板電腦的應用程式相同。這種相似之處可讓您 修改現有應用程式，同時在 TV 裝置上執行，或根據現有應用程式建立新的應用程式 瞭解如何打造 Android 應用程式

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

本指南說明如何準備開發環境，以便建構 TV 應用程式，並 讓應用程式在 TV 裝置上執行。

如要瞭解如何設計電視應用程式，請參閱設計 電視。另請參閱 Android TV GitHub 存放區。

決定支援的媒體格式

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

設定電視專案

本節會說明如何設定電視專案，無論您在 修改現有的 Android 應用程式，使其能夠在 TV 裝置上執行或建立 新的 TV 應用程式。如果已有 Android 應用程式，那麼新增 Android TV 支援後，您就能設計應用程式 並重複使用現有的應用程式架構。

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

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

必要條件

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

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

宣告電視活動

要在 TV 裝置上執行的應用程式必須宣告電視的啟動器活動 。使用 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 應用程式的使用者介面，或現有應用程式的電視部分，必須提供易於瀏覽的簡易介面 使用距離 10 英尺遠的遙控器如果您要修改現有的應用程式來在電視上使用，請勿使用相同的應用程式 針對手機和平板電腦所使用的電視活動版面配置。如需為 TV 設計應用程式的指南，請參閱為 TV 設計應用程式。

宣告電視裝置支援

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

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

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

不需要宣告觸控螢幕

在電視裝置上執行的應用程式不必透過觸控螢幕輸入。 為了清楚起見，電視應用程式資訊清單必須宣告 android.hardware.touchscreen 功能為非必要功能。這項設定會將您的應用程式識別為 只能在電視裝置上閱讀，而且您的應用程式必須設為 Google 的 TV 應用程式。 遊玩、以下程式碼範例說明如何加入這份資訊清單宣告： 

<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 以上版本中，使用 Android TV 應用程式不支援 SplashScreen 平台 API。

當 TV 應用程式啟動時，系統會顯示類似可展開的動畫 社交圈。如要自訂此動畫的顏色，請設定 android:colorPrimary 新增至 TV 應用程式或活動的特定顏色。此外，設定兩個 將重疊屬性轉換至 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 中選取專案，然後按一下 跑步 。
  2. 在「Select Deployment Target」視窗中 選取電視裝置，然後按一下「OK」。

在虛擬裝置上執行

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

如何建立虛擬電視裝置：

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

    注意：為了獲得最佳電視模擬器裝置效能，請使用 x86 模擬器 並啟用「Use Host GPU」選項。也可在其他地方使用虛擬裝置加速功能 廣告。如要進一步瞭解模擬器硬體加速功能，請參閱 設定硬體加速 Android Emulator。

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

  1. 在 Android Studio 中選取專案，然後按一下 跑步 。
  2. 在「Select Deployment Target」視窗中 選取虛擬電視裝置，然後按一下「OK」。

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

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

免安裝應用程式 試用您的 TV 應用程式，有助於提高採用率。

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

接著，在 TV 應用程式的 intent-filter 中 MainActivity，請確認 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 硬體