TV 앱 시작하기

TV 앱은 스마트폰 및 태블릿용 앱과 동일한 구조를 사용합니다. 이러한 유사성이 있으므로 TV 기기에서도 실행되도록 기존 앱을 수정하거나 Android용 앱 빌드에 관해 이미 알고 있는 지식을 바탕으로 새로운 앱을 만들 수 있습니다.

중요: 앱이 Google Play에서 Android TV 앱으로 승인받으려면 특정 요구사항을 충족해야 합니다. 자세한 내용은 TV 앱 품질에 나열된 요구사항을 참조하세요.

이 가이드에서는 TV 앱을 빌드하기 위한 개발 환경을 준비하는 방법과 앱을 TV 기기에서 실행하는 데 필요한 최소한의 변경사항을 설명합니다.

TV용 앱 디자인에 관한 자세한 내용은 TV용 앱 디자인TV 레이아웃 빌드를 참고하세요. 샘플 TV 앱을 검토하려면 Android TV GitHub 저장소에서 Android Leanback 샘플 앱을 참고하세요.

미디어 형식 지원 결정

Android TV에서 지원하는 코덱, 프로토콜, 형식에 관한 자세한 내용은 다음 문서를 참고하세요.

TV 프로젝트 설정

이 섹션에서는 TV 기기에서 실행되도록 기존 Android 앱을 수정하거나 새 TV 앱을 만드는 등 TV 프로젝트를 설정하는 방법을 설명합니다. 기존 Android 앱이 있는 경우 Android TV 지원을 추가하면 기존 앱 아키텍처를 재사용하면서 TV용 사용자 인터페이스를 디자인할 수 있습니다.

TV 기기에서 실행되는 앱을 만들 때 사용하는 두 가지 주요 구성요소가 있습니다.

  • TV 활동: 애플리케이션 매니페스트에서 TV 기기에서 실행할 활동을 선언합니다.
  • TV 라이브러리: 선택적으로 TV 기기에 사용할 수 있는 androidx 라이브러리를 하나 이상 포함합니다. 이 라이브러리는 이 가이드의 다른 섹션에 나열되어 있습니다. 이러한 라이브러리는 사용자 인터페이스 빌드를 위한 위젯을 제공합니다.

기본 요건

TV용 앱을 빌드하기 전에 다음 단계를 따라야 합니다.

  • 버전 24.0.0 이상으로 SDK 도구를 업데이트합니다.
    업데이트된 SDK 도구를 사용하면 TV용 앱을 빌드하고 테스트할 수 있습니다.
  • SDK를 Android 5.0 (API 21) 이상으로 업데이트합니다.
    업데이트된 플랫폼 버전에서는 TV 앱용 새로운 API를 제공합니다.
  • 앱 프로젝트를 만들거나 업데이트합니다.
    TV 기기용 새 API에 액세스하려면 프로젝트를 만들거나 Android 5.0 (API 수준 21) 이상을 타겟팅하는 기존 프로젝트를 수정하세요.

TV 활동 선언

TV 기기에서 실행되도록 개발하는 애플리케이션은 매니페스트에서 TV의 런처 활동을 선언해야 합니다. 이를 위해 CATEGORY_LEANBACK_LAUNCHER 인텐트 필터를 사용합니다. 이 필터는 앱이 TV용으로 사용 설정되었음을 식별하고 Google Play에서 TV 앱으로 식별하도록 허용합니다. 사용자가 TV 홈 화면에서 앱을 선택하면 이 인텐트는 실행할 활동을 식별합니다.

다음 코드 스니펫은 manifest에서 인텐트 필터를 포함하는 방법을 보여줍니다.

<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>

이 예의 두 번째 활동 매니페스트 항목은 TV 기기에서 실행할 활동임을 지정합니다.

주의: 앱에 CATEGORY_LEANBACK_LAUNCHER 인텐트 필터를 포함하지 않으면 TV 기기에서 Google Play를 실행하는 사용자에게 앱이 표시되지 않습니다. 또한 개발자 도구를 사용하여 TV 기기에 앱을 로드할 때 앱에 이 필터가 없으면 앱이 TV 사용자 인터페이스에 표시되지 않습니다.

TV 앱의 사용자 인터페이스 또는 기존 앱의 TV 부분에서는 3m 떨어진 곳에서 리모컨을 사용하여 쉽게 탐색할 수 있는 간단한 인터페이스를 제공해야 합니다. TV에서 사용하도록 기존 앱을 수정하는 경우 스마트폰 및 태블릿에서 사용하는 것과 동일한 활동 레이아웃을 TV에 사용하지 마세요. TV용 앱 디자인에 관한 가이드라인은 TV용 앱 디자인을 참조하세요. TV 인터페이스 레이아웃의 최소 구현 요구사항에 관한 자세한 내용은 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>

터치스크린이 필수가 아니라고 선언

TV 기기에서 실행되도록 설계된 애플리케이션은 터치스크린을 사용하여 입력을 받지 않습니다. 이를 명확히 하려면 TV 앱의 매니페스트에서 android.hardware.touchscreen 기능이 필요하지 않음을 선언해야 합니다. 이 설정은 앱이 TV 기기에서 작동하는 것으로 식별되며, Google Play에서 앱이 TV 앱으로 간주되려면 이 설정이 필요합니다. 다음 코드 예시는 이 manifest 선언을 포함하는 방법을 보여줍니다.

<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 앱과 마찬가지로 Android TV 앱은 홈 화면 아이콘을 제공해야 합니다. 앱을 위한 적절한 시작점과 자세한 저작물 요구사항을 결정하기 위한 권장사항은 Android TV 앱 아이콘 및 배너 가이드라인을 참고하세요.

android:banner 속성을 <application> 태그와 함께 사용하여 모든 애플리케이션 활동에 기본 배너를 제공하거나, <activity> 태그와 함께 사용하여 특정 활동의 배너를 제공합니다.

배너에는 크기가 320 x 180px인 xhdpi 리소스를 사용하세요. 텍스트는 이미지에 포함되어야 합니다. 앱을 두 개 이상의 언어로 제공하는 경우 지원되는 언어별로 텍스트와 함께 별도의 버전의 배너를 제공해야 합니다.

런처 색상 변경

주의: Android 12 이상에서는 SplashScreen 플랫폼 API를 사용하여 빌드된 맞춤 스플래시 화면 애니메이션이 Android TV 앱에서 지원되지 않습니다.

TV 앱이 실행되면 완전히 채워진 원 모양의 애니메이션이 표시됩니다. 이 애니메이션의 색상을 맞춤설정하려면 TV 앱 또는 활동의 android:colorPrimary 속성을 특정 색상으로 설정합니다. 또한, 테마 리소스 XML 파일에서 다음 스니펫과 같이 두 개의 전환 중복 속성을 true로 설정합니다.

<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에는 TV 앱에 사용할 androidx 패키지가 포함되어 있습니다. 이러한 라이브러리는 TV 기기용 API와 사용자 인터페이스 위젯을 제공합니다.

TV 앱 빌드

앞에서 나열된 단계를 완료했다면 이제 대형 화면용 앱 빌드를 시작할 차례입니다. 다음 추가 주제를 살펴보면 TV용 앱 빌드에 도움이 될 것입니다.

  • TV 재생 앱 빌드: TV는 엔터테인먼트를 제공하기 위해 만들어졌으므로 Android는 동영상과 음악을 재생하고 사용자가 원하는 콘텐츠를 탐색할 수 있는 TV 앱을 빌드하기 위한 일련의 사용자 인터페이스 도구와 위젯을 제공합니다.
  • 사용자가 Android TV에서 콘텐츠를 찾도록 지원: 사용자는 모든 콘텐츠를 손쉽게 선택할 수 있으므로 사용자가 즐기는 콘텐츠를 찾도록 지원하는 것은 콘텐츠를 제공하는 것만큼이나 중요합니다. 이 가이드에서는 TV 기기에 콘텐츠를 표시하는 방법을 설명합니다.
  • TV 게임 빌드: TV 기기는 게임하기에 좋은 플랫폼입니다. TV에서 우수한 게임 환경을 빌드하는 방법에 관한 정보는 이 주제를 참조하세요.
  • TV 입력 서비스 빌드: 동영상 콘텐츠를 선형 '지상파 TV' 스타일로 보여줄 수 있습니다. 여기에는 사용자가 프로그램 가이드 및 채널 위/아래 버튼을 통해 액세스할 수 있는 채널과 프로그램이 포함됩니다.

TV 앱 실행

앱 실행은 개발 과정에서 중요한 부분입니다. USB 디버깅을 지원하도록 구성된 TV 기기에서 앱을 실행하거나 가상 TV 기기를 사용할 수 있습니다.

실제 기기에서 실행

다음 단계에 따라 TV 기기를 설정합니다.

  1. USB 케이블을 사용하여 TV 기기를 개발 시스템에 연결합니다. 필요한 경우 기기 제조업체에서 제공한 문서를 참조하세요.
  2. TV 기기에서 설정으로 이동합니다.
  3. 기기 행에서 정보를 선택합니다.
  4. 빌드까지 아래로 스크롤한 다음 '개발자가 되셨습니다.' 메시지가 표시될 때까지 여러 번 빌드를 선택합니다.
  5. '설정'으로 돌아갑니다. 환경설정 행에서 개발자 옵션을 선택합니다.
  6. 디버깅 > USB 디버깅을 선택하고 설정을 선택합니다.
  7. TV 홈 화면으로 돌아갑니다.

TV 기기에서 애플리케이션을 테스트하려면 다음과 같이 합니다.

  1. Android 스튜디오에서 프로젝트를 선택하고 툴바에서 Run 을 클릭합니다.
  2. Select Deployment Target 창에서 TV 기기를 선택하고 OK를 클릭합니다.

가상 기기에서 실행

Android SDK의 AVD Manager는 애플리케이션 실행과 테스트를 위한 가상 TV 기기를 만들 수 있는 기기 정의를 제공합니다.

가상 TV 기기를 만들려면 다음과 같이 합니다.

  1. AVD Manager를 시작합니다. 자세한 내용은 가상 기기 만들기 및 관리를 참고하세요.
  2. AVD Manager 대화상자에서 기기 정의 탭을 클릭합니다.
  3. Android TV 기기 정의 중 하나를 선택하고 AVD 만들기를 클릭합니다.
  4. 에뮬레이터 옵션을 선택하고 OK를 클릭하여 AVD를 만듭니다.

    참고: TV 에뮬레이터 기기가 최고의 성능을 발휘하게 하려면 x86 에뮬레이터를 사용하고 호스트 GPU 사용 옵션을 사용 설정합니다. 또한 사용할 수 있는 경우 가상 기기 가속을 사용합니다. 에뮬레이터의 하드웨어 가속에 관한 자세한 내용은 Android Emulator의 하드웨어 가속 구성을 참고하세요.

가상 TV 기기에서 애플리케이션을 테스트하려면 다음과 같이 합니다.

  1. Android 스튜디오에서 프로젝트를 선택하고 툴바에서 Run 을 클릭합니다.
  2. Select Deployment Target 창에서 가상 TV 기기를 선택하고 OK를 클릭합니다.

에뮬레이터 사용에 관한 자세한 내용은 Android Emulator에서 앱 실행을 참고하세요. Android 스튜디오에서 가상 기기로 앱을 배포하는 방법에 관한 자세한 내용은 앱 디버그를 참고하세요.

TV 앱을 인스턴트 환경으로 실행하도록 사용 설정

인스턴트 환경을 통해 사용자는 TV 앱을 쉽게 사용해 볼 수 있으며 채택률을 높일 수 있습니다.

Android TV 기기 또는 에뮬레이터에서 인스턴트 앱으로 실행되도록 TV 앱을 설정하려면 먼저 안내에 따라 인스턴트 지원 App Bundle을 만듭니다.

다음으로 TV 앱 MainActivityintent-filter에서 LAUNCHERLEANBACK_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 앱을 게시 및 배포할 수 있도록 다음 단계를 검토합니다.