| page.title=Get Started with TV Apps |
| page.tags="leanback","recyclerview","launcher" |
| |
| trainingnavtop=true |
| startpage=true |
| |
| @jd:body |
| |
| <div id="tb-wrapper"> |
| <div id="tb"> |
| <h2>This lesson teaches you how to</h2> |
| <ol> |
| <li><a href="#media">Determine Media Format Support</a></li> |
| <li><a href="#dev-project">Setup a TV Project</a></li> |
| <li><a href="#tv-libraries">Add TV Support Libraries</a></li> |
| <li><a href="#build-it">Build TV Apps</a></li> |
| <li><a href="#run">Run TV Apps</a></li> |
| </ol> |
| <h2>You should also read</h2> |
| <ol> |
| <li><a href="{@docRoot}design/tv/index.html"> |
| TV Design</a></li> |
| <li><a href="{@docRoot}training/tv/start/layouts.html"> |
| Building TV Layouts</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p> |
| TV apps use the same structure as those for phones and tablets. This similarity means you can |
| modify your existing apps to also run on TV devices or create new apps based on what you already |
| know about building apps for Android. |
| </p> |
| |
| <p class="note"> |
| <strong>Important:</strong> There are specific requirements your app must meet to |
| qualify as an Android TV app on Google Play. For more information, see the requirements listed |
| in <a href="{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a>. |
| </p> |
| |
| <p> |
| This lesson describes how to prepare your development environment for building TV apps, and the |
| minimum required changes to enable an app to run on TV devices. |
| </p> |
| |
| <h2 id="media">Determine Media Format Support</h2> |
| |
| <p>See the following documentation for information about the codecs, protocols, and formats |
| supported by Android TV.</p> |
| |
| <ul> |
| <li><a href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a></li> |
| <li><a class="external-link" href="https://source.android.com/devices/drm.html">DRM</a></li> |
| <li><code><a href="{@docRoot}reference/android/drm/package-summary.html">android.drm</a></code></li> |
| <li><a href="{@docRoot}guide/topics/media/exoplayer.html">ExoPlayer</a></li> |
| <li>{@link android.media.MediaPlayer android.media.MediaPlayer}</li> |
| </ul> |
| |
| <h2 id="dev-project">Set up a TV Project</h2> |
| |
| <p> |
| This section discusses how to modify an existing app to run on TV devices, or create a new one. |
| These are the main components you must use to create an app that runs on TV devices: |
| </p> |
| |
| <ul> |
| <li><strong>Activity for TV</strong> (Required) - In your application manifest, |
| declare an activity that is intended to run on TV devices.</li> |
| <li><strong>TV Support Libraries</strong> (Optional) - There are several |
| <a href="#tv-libraries">Support Libraries</a> |
| available for TV devices that provide widgets for building user interfaces.</li> |
| </ul> |
| |
| |
| <h3 id="prerequisites">Prerequisites</h3> |
| |
| <p>Before you begin building apps for TV, you must:</p> |
| |
| <ul> |
| <li><strong><a href="{@docRoot}sdk/installing/adding-packages.html#GetTools"> |
| Update your SDK tools to version 24.0.0 or higher</a></strong> |
| <br> |
| The updated SDK tools enable you to build and test apps for TV. |
| </li> |
| <li><strong><a href="{@docRoot}sdk/installing/adding-packages.html#GetTools"> |
| Update your SDK with Android 5.0 (API 21) or higher</a></strong> |
| <br> |
| The updated platform version provides new APIs for TV apps. |
| </li> |
| <li><strong><a href="{@docRoot}sdk/installing/create-project.html"> |
| Create or update your app project</a></strong> |
| <br> |
| In order to access new APIs for TV devices, you must create a project or modify an existing |
| project that targets Android 5.0 (API level 21) or higher. |
| </li> |
| </ul> |
| |
| |
| <h3 id="tv-activity">Declare a TV Activity</h3> |
| |
| <p>An application intended to run on TV devices must declare a launcher activity for TV |
| in its manifest using a {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent filter. |
| This filter identifies your app as being enabled for TV, and is required for your app to be |
| considered a TV app in Google Play. Declaring this intent also identifies which activity |
| in your app to launch when a user selects its icon on the TV home screen.</p> |
| |
| <p>The following code snippet shows how to include this intent filter in your manifest:</p> |
| |
| <pre> |
| <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.<strong>TvActivity</strong>" |
| android:label="@string/app_name" |
| android:theme="@style/Theme.Leanback"> |
| |
| <intent-filter> |
| <action android:name="android.intent.action.MAIN" /> |
| <category android:name="<strong>android.intent.category.LEANBACK_LAUNCHER</strong>" /> |
| </intent-filter> |
| |
| </activity> |
| </application> |
| </pre> |
| |
| <p> |
| The second activity manifest entry in this example specifies that activity as the one to |
| launch on a TV device. |
| </p> |
| |
| <p class="caution"> |
| <strong>Caution:</strong> If you do not include the |
| {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent filter in |
| your app, it is not visible to users running the Google Play store on TV devices. Also, if your |
| app does not have this filter when you load it onto a TV device using developer tools, the app |
| does not appear in the TV user interface. |
| </p> |
| |
| <p> |
| If you are modifying an existing app for use on TV, your app should not use the same |
| activity layout for TV that it does for phones and tablets. The user interface of your TV app (or |
| TV portion of your existing app) should provide a simpler interface that can be easily navigated |
| using a remote control from a couch. For guidelines on designing an app for TV, see the <a href= |
| "{@docRoot}design/tv/index.html">TV Design</a> guide. For more information on the minimum |
| implementation requirements for interface layouts on TV, see <a href= |
| "{@docRoot}training/tv/start/layouts.html">Building TV Layouts</a>. |
| </p> |
| |
| <h3 id="leanback-req">Declare Leanback support</h3> |
| |
| <p> |
| Declare that your app uses the Leanback user interface required by Android TV. If you are developing |
| an app that runs on mobile (phones, wearables, tablets, etc.) as well as Android TV, set the |
| {@code required} attribute value to {@code false}. If you set the {@code required} attribute value |
| to {@code true}, your app will run only on devices that use the Leanback UI. |
| </p> |
| |
| <pre> |
| <manifest> |
| <uses-feature android:name="android.software.leanback" |
| android:required="false" /> |
| ... |
| </manifest> |
| </pre> |
| |
| <h3 id="no-touchscreen">Declare touchscreen not required</h3> |
| |
| <p> |
| Applications that are intended to run on TV devices do not rely on touch screens for input. In |
| order to make this clear, the manifest of your TV app must declare that a the {@code |
| android.hardware.touchscreen} feature is not required. This setting identifies your app as being |
| able to work on a TV device, and is required for your app to be considered a TV app in Google |
| Play. The following code example shows how to include this manifest declaration: |
| </p> |
| |
| <pre> |
| <manifest> |
| <uses-feature android:name="android.hardware.touchscreen" |
| android:required="false" /> |
| ... |
| </manifest> |
| </pre> |
| |
| <p class="caution"> |
| <strong>Caution:</strong> You must declare that a touch screen is not required in your app |
| manifest, as shown this example code, or your app cannot appear in the Google Play store on TV |
| devices. |
| </p> |
| |
| <h3 id="banner">Provide a home screen banner</h3> |
| |
| <p> |
| An application must provide a home screen banner for each localization if it includes a Leanback |
| launcher intent filter. The banner is the app launch point that appears on the home screen in the |
| apps and games rows. Desribe the banner in the manifest as follows: |
| </p> |
| |
| <pre> |
| <application |
| ... |
| android:banner="@drawable/banner" > |
| |
| ... |
| </application> |
| </pre> |
| |
| <p> |
| Use the <a href="{@docRoot}guide/topics/manifest/application-element.html#banner">{@code android:banner}</a> |
| attribute with the <a href="{@docRoot}guide/topics/manifest/application.html"><code><application></code></a> |
| tag to supply a default banner for all application activities, or with the |
| <a href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> |
| tag to supply a banner for a specific activity. |
| </p> |
| |
| <p> |
| See <a href="{@docRoot}design/tv/patterns.html#banner">Banners</a> in the UI Patterns for TV |
| design guide. |
| </p> |
| |
| <h3 id="transition-color">Change the launcher color</h3> |
| |
| <p>When a TV app launches, the system displays an animation that resembles an expanding, filled |
| circle. To customize the color of this animation, set the <code>android:colorPrimary</code> |
| attribute of your TV app or activity to a specific color. You should also set two additional |
| transition overlap attributes to <code>true</code>, as shown in the following snippet from a |
| theme resource XML file:</p> |
| |
| <pre> |
| <resources> |
| <style ... > |
| <item name="android:colorPrimary">@color/primary</item> |
| <item name="android:windowAllowReturnTransitionOverlap">true</item> |
| <item name="android:windowAllowEnterTransitionOverlap">true</item> |
| </style> |
| </resources> |
| </pre> |
| |
| <p>For more information about working with themes and styles, see |
| <a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p> |
| |
| <h2 id="tv-libraries">Add TV Support Libraries</h3> |
| |
| <p> |
| The Android SDK includes support libraries that are intended for use with TV apps. These |
| libraries provide APIs and user interface widgets for use on TV devices. The libraries are |
| located in the {@code <sdk>/extras/android/support/} directory. Here is a list of the |
| libraries and their general purpose: |
| </p> |
| |
| <ul> |
| <li><a href="{@docRoot}tools/support-library/features.html#v17-leanback"> |
| <strong>v17 leanback library</strong></a> - Provides user interface widgets for TV apps, |
| particularly for apps that do media playback. |
| </li> |
| <li><a href="{@docRoot}tools/support-library/features.html#v7-recyclerview"> |
| <strong>v7 recyclerview library</strong></a> - Provides classes for managing display of long |
| lists in a memory efficient manner. Several classes in the v17 leanback library depend on the |
| classes in this library. |
| </li> |
| <li><a href="{@docRoot}tools/support-library/features.html#v7-cardview"> |
| <strong>v7 cardview library</strong></a> - Provides user interface widgets for displaying |
| information cards, such as media item pictures and descriptions. |
| </li> |
| </ul> |
| |
| <p class="note"> |
| <strong>Note:</strong> You are not required to use these support libraries for your TV app. |
| However, we strongly recommend using them, particularly for apps that provide a media catalog |
| browsing interface. |
| </p> |
| |
| <p> |
| If you decide to use the v17 leanback library for your app, you should note that it is dependent |
| on the <a href="{@docRoot}tools/support-library/features.html#v4">v4 support library</a>. This |
| means that apps that use the leanback support library should include all of these support |
| libraries: |
| </p> |
| |
| <ul> |
| <li>v4 support library</li> |
| <li>v7 recyclerview support library</li> |
| <li>v17 leanback support library</li> |
| </ul> |
| |
| <p> |
| The v17 leanback library contains resources, which require you to take specific steps to include |
| it in app projects. For instructions on importing a support library with resources, see |
| <a href="{@docRoot}tools/support-library/setup.html#libs-with-res">Support Library Setup</a>. |
| </p> |
| |
| |
| <h2 id="build-it">Build TV Apps</h2> |
| |
| <p>After you have completed the steps described above, it's time to start building apps for |
| the big screen! Check out these additional topics to help you build your app for TV: |
| |
| <ul> |
| <li> |
| <a href="{@docRoot}training/tv/playback/index.html">Building TV Playback Apps</a> - TVs are |
| built to entertain, so Android provides a set of user interface tools and widgets for building |
| TV apps that play videos and music, and let users browse for the content they want. |
| </li> |
| <li> |
| <a href="{@docRoot}training/tv/discovery/index.html">Helping Users Find Your Content on TV</a> - |
| With all the content choices at users' fingertips, helping them find content they enjoy is almost |
| as important as providing that content. This training discusses how to surface your content on |
| TV devices. |
| </li> |
| <li> |
| <a href="{@docRoot}training/tv/games/index.html">Building TV Games</a> - TV devices are a great |
| platform for games. See this topic for information on building great game experiences for TV. |
| </li> |
| <li> |
| <a href="{@docRoot}training/tv/tif/index.html">Building Live TV Apps</a> - Present your video |
| content in a linear, "broadcast TV" style with channels and programs that your users can access |
| through a program guide as well as the channel up/down buttons. |
| </li> |
| |
| </ul> |
| |
| |
| <h2 id="run">Run TV Apps</h2> |
| |
| <p> |
| Running your app is an important part of the development process. The AVD Manager in the Android |
| SDK provides the device definitions that allow you to create virtual TV devices for running and |
| testing your applications. |
| </p> |
| |
| <p>To create an virtual TV device:</p> |
| |
| <ol> |
| <li>Start the AVD Manager. For more information, see the |
| <a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a> help.</li> |
| <li>In the AVD Manager dialog, click the <strong>Device Definitions</strong> tab.</li> |
| <li>Select one of the Android TV device definitions and click <strong>Create AVD</strong>.</li> |
| <li>Select the emulator options and click <strong>OK</strong> to create the AVD. |
| <p class="note"> |
| <strong>Note:</strong> For best performance of the TV emulator device, enable the <strong>Use |
| Host GPU</strong> option and, where supported, use virtual device acceleration. For |
| more information on hardware acceleration of the emulator, see |
| <a href="{@docRoot}tools/devices/emulator.html#acceleration">Using the Emulator</a>. |
| </p> |
| </li> |
| </ol> |
| |
| <p>To test your application on the virtual TV device:</p> |
| |
| <ol> |
| <li>Compile your TV application in your development environment.</li> |
| <li>Run the application from your development environment and choose the TV virtual device as |
| the target.</li> |
| </ol> |
| |
| <p> |
| For more information about using emulators see, <a href="{@docRoot}tools/devices/emulator.html"> |
| Using the Emulator</a>. For more information on deploying apps from Android Studio to virtual |
| devices, see <a href="{@docRoot}sdk/installing/studio-debug.html">Debugging with Android |
| Studio</a>. |
| </p> |