| 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="#dev-project">Setup a TV Project</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="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, allowing it 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 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>The following code snippet shows how to include this intent filter in your manifest:</p> |
| |
| <pre> |
| <application> |
| ... |
| <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> |
| 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="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/search/index.html">Surfacing 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">Games for TV</a> - TV devices are a great |
| platform for games. See this topic for information on building great game experiences for TV. |
| </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>. For more information about deploying apps to emulators from Eclipse with ADT, see |
| <a href="{@docRoot}tools/building/building-eclipse.html">Building and Running from Eclipse with |
| ADT</a>. |
| </p> |