TV 앱 시작하기

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

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

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

TV 앱 디자인에 관한 자세한 내용은 TV용 디자인을 참고하세요. Android TV GitHub 저장소의 샘플 앱도 참고하세요.

미디어 형식 지원 결정

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

• 지원되는 미디어 형식
• DRM
• android.drm
• ExoPlayer
• android.media.MediaPlayer

TV 프로젝트 설정

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

참고: 휴대기기와 TV 기기를 모두 지원하는 단일 앱이 있는 것이 좋습니다. 휴대기기와 TV 기기에 별도의 앱이 필요한 경우 여러 APK 지원을 사용하여 Google Play에서 동일한 등록정보로 여러 앱을 게시할 수 있습니다. 자세한 정보는 다중 APK 지원을 참고하세요.

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 레이아웃 빌드를 참고하세요.

TV 기기 지원 선언

android.software.leanback 기능을 선언하여 앱이 Android TV용으로 빌드되었음을 선언합니다.

앱이 모바일과 TV 모두에서 실행되는 경우 required 속성 값을 false로 설정합니다. required 속성 값을 true로 설정하면 Google Play에서 Android TV OS에서만 앱을 사용할 수 있도록 합니다.

<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 TV 앱은 다른 모든 Android 앱과 마찬가지로 홈 화면 아이콘을 제공해야 합니다. 앱의 효과적인 시작점과 세부 애셋 요구사항을 설정하는 방법에 관한 권장사항은 Android TV 앱 아이콘 및 배너 가이드라인을 참조하세요.

홈 화면 배너

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

배너의 경우 320x180픽셀 크기의 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>

테마 및 스타일 작업에 관한 자세한 내용은 스타일 및 테마를 참고하세요.

Android TV OS용 앱 빌드

대부분의 AndroidX 라이브러리는 Android TV와 함께 사용할 수 있습니다. 수명 주기 인식 UI 데이터를 관리하려면 ViewModel와 같은 아키텍처 구성요소를 사용하고, 모바일에서와 마찬가지로 로컬 SQLite 데이터베이스와 통합하려면 Room를 사용하세요.

대부분의 AndroidX 라이브러리는 Android TV를 지원합니다. TV 앱은 모바일 앱과 동일한 아키텍처 구성요소를 사용할 수 있습니다. 폼 팩터 간에 구성요소를 공유할 수도 있으므로 TV 앱의 프레젠테이션 로직만 전문화하면 됩니다.

TV용 Compose

Jetpack Compose를 사용하여 TV OS UI를 빌드합니다. Compose는 UI 개발을 위한 최신 Android 권장사항입니다. TV용 Compose 라이브러리는 핵심 Compose 라이브러리와 함께 대형 화면용으로 특별히 설계된 전용 구성요소를 제공합니다.

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

Android TV에서 Jetpack Compose 사용에서 TV용 Compose를 사용하여 TV 앱을 빌드하는 방법을 알아보세요.

Leanback UI 도구 키트 (권장하지 않음)

Leanback UI 툴킷은 지금까지 Android 뷰와 프래그먼트를 사용하는 TV 기기 전용의 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

Leanback UI 도구 키트 사용에서 Leanback UI 도구 키트를 사용하여 TV 앱을 빌드하는 방법을 알아보세요.

TV 앱 실행

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

실제 기기에서 실행

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

1. USB 케이블을 사용하여 TV 기기를 개발 시스템에 연결합니다. 필요한 경우 기기 제조업체에서 제공한 문서를 참조하세요.
2. TV 기기에서 설정으로 이동합니다.
3. 기기 행에서 정보를 선택합니다.
4. Build로 스크롤하고 '개발자가 되셨습니다.' 메시지가 표시될 때까지 Build를 여러 번 선택합니다.
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 앱 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 앱을 준비하기 위한 다음 단계를 확인하세요.