TV アプリを作成して実行する

テレビアプリは、スマートフォンやタブレット向けのアプリと同じ構造を使用します。この類似性により、既存のアプリを修正してテレビ デバイスでも実行できるようにしたり、Android 向けアプリのビルドに関する既存の知識に基づいて新しいアプリを作成したりできます。

重要: Google Play で Android TV アプリとして提供するには、アプリが特定の要件を満たしている必要があります。詳しくは、TV アプリの品質に記載されている要件をご覧ください。

このガイドでは、テレビアプリをビルドするための開発環境を準備する方法と、テレビデバイスでアプリを実行できるようにするために必要な最小限の変更について説明します。

テレビ向けアプリの設計については、テレビ向けに設計するをご覧ください。Android TV GitHub リポジトリにあるサンプルアプリもご覧ください。

メディア形式のサポートについて判断する

Android TV でサポートされているコーデック、プロトコル、形式については、次のドキュメントをご覧ください。

• サポートされているメディア形式
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

TV プロジェクトをセットアップする

このセクションでは、既存の Android アプリをテレビデバイスで実行できるように変更する場合と、新しい TV アプリを作成する場合の、テレビ プロジェクトの設定方法について説明します。既存の Android アプリがある場合は、Android TV のサポートを追加することで、既存のアプリ アーキテクチャを再利用しながら、テレビ用のユーザー インターフェースを設計できます。

テレビデバイスで実行されるアプリを作成する際に使用する主なコンポーネントは次の 2 つです。

• テレビ用アクティビティ: アプリケーション マニフェストで、テレビデバイスで実行することを目的としたアクティビティを宣言します。
• TV ライブラリ: 必要に応じて、このガイドの別のセクションに記載されている、TV デバイスで利用可能な androidx ライブラリを 1 つ以上含めます。これらのライブラリは、ユーザー インターフェースを構築するためのウィジェットを提供します。

前提条件

テレビ用アプリのビルドを開始する前に、次の手順を行う必要があります。

• SDK ツールをバージョン 24.0.0 以降に更新します。
  更新された SDK ツールを使用すると、テレビ用のアプリをビルドしてテストできます。
• Android 5.0（API 21）以降で SDK を更新します。
  更新されたプラットフォーム バージョンでは、TV アプリ用の新しい API が提供されます。
• アプリ プロジェクトを作成または更新します。
  TV デバイス用の新しい API にアクセスするには、Android 5.0（API レベル 21）以上をターゲットとするプロジェクトを作成するか、既存のプロジェクトを変更します。

TV のアクティビティを宣言する

TV デバイスで実行されるアプリは、マニフェスト内で 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>

この例の 2 番目のアクティビティ マニフェスト エントリは、テレビ デバイスで起動するアクティビティであることを指定しています。

注意: CATEGORY_LEANBACK_LAUNCHER インテント フィルタをアプリに含めないと、テレビ デバイスで Google Play を実行しているユーザーにはアプリが表示されません。また、デベロッパー ツールを使用してテレビ デバイスにアプリを読み込むときに、アプリにこのフィルタがない場合、アプリはテレビのユーザー インターフェースに表示されません。

テレビアプリのユーザー インターフェース、または既存のアプリのテレビ部分では、10 フィート離れた場所からリモコンを使用して直感的に操作できる必要があります。テレビで使用するために既存のアプリを変更する場合は、スマートフォンやタブレットで使用しているアクティビティ レイアウトをテレビで使用しないでください。テレビ向けアプリの設計に関するガイドラインについては、テレビ向けに設計するをご覧ください。

テレビ デバイスのサポートを宣言する

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>

タッチスクリーンの不要を宣言する

テレビ デバイスで実行されることを想定したアプリは、入力にタッチスクリーンを使用しません。これを明確にするため、テレビアプリのマニフェストで android.hardware.touchscreen 機能が必須でないことを宣言する必要があります。この設定により、アプリがテレビ デバイスで動作可能であることが識別されます。この設定は、アプリが Google Play で 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 以降では、SplashScreen プラットフォーム API を使用して作成されたカスタム スプラッシュ画面アニメーションは、Android TV アプリではサポートされていません。

TV アプリが起動すると、システムは拡大する塗りつぶされた円のようなアニメーションを表示します。このアニメーションの色をカスタマイズするには、テレビアプリまたはアクティビティの android:colorPrimary 属性を特定の色に設定します。また、テーマ リソース XML ファイルの次のスニペットに示すように、2 つのトランジション オーバーラップ属性を true に設定します。

<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>
create.xml

テーマとスタイルの操作について詳しくは、スタイルとテーマをご覧ください。

Android TV OS 用アプリを作成する

Jetpack には、TV アプリで使用する androidx パッケージ ライブラリが含まれています。

テレビ向け Compose

Android TV OS 向けのアプリを作成するには、Compose を使用することをおすすめします。コア Compose ライブラリに加えて、Compose for TV ライブラリには、大画面用に特別に設計された専用コンポーネントが用意されています。

• androidx.tv.foundation
• androidx.tv.material

Compose for TV を使用して TV アプリを作成する方法については、Android TV で Jetpack Compose を使用するをご覧ください。

Leanback UI ツールキット

Leanback UI ツールキットは、テレビ デバイス用の API とユーザー インターフェース ウィジェットを提供します。

• androidx.leanback.app
• androidx.leanback.database
• androidx.leanback.graphics
• androidx.leanback.media
• androidx.leanback.preference
• androidx.leanback.system
• androidx.leanback.widget
• androidx.leanback.widget.picker

TV 再生アプリを作成するで、Leanback UI ツールキットを使用して TV アプリを作成する方法を確認してください。

TV アプリを実行する

アプリの実行は開発プロセスの重要部分です。USB デバッグをサポートするように構成されたテレビ デバイスでアプリを実行するか、仮想テレビ デバイスを使用できます。

実機で実行する

次のように TV デバイスを設定します。

1. USB ケーブルを使って TV デバイスを開発用 PC に接続します。必要に応じて、デバイス メーカーが提供するドキュメントを参照してください。
2. TV デバイスで、[Settings] に移動します。
3. [デバイス] 行で [デバイス情報] を選択します。
4. [ビルド] までスクロールし、「デベロッパーになりました」というメッセージが表示されるまで [ビルド] を数回選択します。
5. [設定] に戻ります。[設定] 行で [開発者向けオプション] を選択します。
6. [Debugging > USB debugging] を選択し、[On] を選択します。
7. TV のホーム画面に戻ります。

TV デバイスでアプリケーションをテストするには:

1. Android Studio でプロジェクトを選択し、ツールバーの [Run] をクリックします。
2. [Select Deployment Target] ウィンドウで、テレビ デバイスを選択して [OK] をクリックします。

仮想デバイス上で実行する

Android SDK の AVD Manager には、アプリケーションの実行とテスト用の仮想 TV デバイスを作成できるデバイス定義が用意されています。

仮想 TV デバイスを作成するには:

1. AVD Manager を起動します。詳しくは、仮想デバイスを作成して管理するをご覧ください。
2. [AVD Manager] ダイアログで [Device Definitions] タブをクリックします。
3. Android TV のいずれかのデバイス定義を選択し、[Create AVD] をクリックします。
4. エミュレータ オプションを選択し、[OK] をクリックして AVD を作成します。

   注: テレビ エミュレータ デバイスのパフォーマンスを最大限に引き出すには、x86 エミュレータを使用し、[ホスト GPU を使用] オプションを有効にします。また、仮想デバイス アクセラレーションが利用可能な場合はそれも使用します。エミュレータのハードウェア アクセラレーションについて詳しくは、Android Emulator のハードウェア アクセラレーションを設定するをご覧ください。

仮想 TV デバイス上でアプリをテストするには:

1. Android Studio でプロジェクトを選択し、ツールバーの [Run] をクリックします。
2. [Select Deployment Target] ウィンドウで、仮想テレビ デバイスを選択して [OK] をクリックします。

エミュレータの使用について詳しくは、 Android Emulator 上でアプリを実行するをご覧ください。Android Studio から仮想デバイスにアプリをデプロイする方法について詳しくは、アプリをデバッグするをご覧ください。

TV アプリを Instant エクスペリエンスとして実行できるようにする

Instant エクスペリエンスを使用すると、ユーザーはテレビアプリをインストールせずに試すことができるため、アプリの導入を促進できます。

Android TV デバイスまたはエミュレータで Instant App として実行するように TV アプリを設定するには、まず手順に沿ってInstant 対応 App Bundle を作成します。

次に、テレビアプリの 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 アプリが Instant エクスペリエンスとして実行されるように構成されました。

公開に向けて TV アプリを準備する

テレビアプリを公開、配信するための次のステップについては、テレビアプリのチェックリストをご覧ください。