Joe Fernandez | d86a2f5 | 2014-09-11 09:52:07 -0700 | [diff] [blame] | 1 | page.title=Get Started with TV Apps |
| 2 | page.tags="leanback","recyclerview","launcher" |
| 3 | |
| 4 | trainingnavtop=true |
| 5 | startpage=true |
| 6 | |
| 7 | @jd:body |
| 8 | |
| 9 | <div id="tb-wrapper"> |
| 10 | <div id="tb"> |
| 11 | <h2>This lesson teaches you how to</h2> |
| 12 | <ol> |
| 13 | <li><a href="#dev-project">Setup a TV Project</a></li> |
| 14 | <li><a href="#build-it">Build TV Apps</a></li> |
| 15 | <li><a href="#run">Run TV Apps</a></li> |
| 16 | </ol> |
| 17 | <h2>You should also read</h2> |
| 18 | <ol> |
| 19 | <li><a href="{@docRoot}design/tv/index.html"> |
| 20 | TV Design</a></li> |
| 21 | <li><a href="{@docRoot}training/tv/start/layouts.html"> |
| 22 | Building TV Layouts</a></li> |
| 23 | </ol> |
| 24 | </div> |
| 25 | </div> |
| 26 | |
| 27 | <p> |
| 28 | TV apps use the same structure as those for phones and tablets. This similarity means you can |
| 29 | modify your existing apps to also run on TV devices or create new apps based on what you already |
| 30 | know about building apps for Android. |
| 31 | </p> |
| 32 | |
| 33 | <p class="note"> |
Joe Fernandez | cd2445a | 2014-10-07 22:55:44 -0700 | [diff] [blame] | 34 | <strong>Important:</strong> There are specific requirements your app must meet to |
Joe Fernandez | d86a2f5 | 2014-09-11 09:52:07 -0700 | [diff] [blame] | 35 | qualify as an Android TV app on Google Play. For more information, see the requirements listed |
| 36 | in <a href="{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a>. |
| 37 | </p> |
| 38 | |
| 39 | <p> |
| 40 | This lesson describes how to prepare your development environment for building TV apps, and the |
| 41 | minimum required changes to enable an app to run on TV devices. |
| 42 | </p> |
| 43 | |
| 44 | |
| 45 | <h2 id="dev-project">Set up a TV Project</h2> |
| 46 | |
| 47 | <p> |
| 48 | This section discusses how to modify an existing app to run on TV devices, or create a new one. |
| 49 | These are the main components you must use to create an app that runs on TV devices: |
| 50 | </p> |
| 51 | |
| 52 | <ul> |
| 53 | <li><strong>Activity for TV</strong> (Required) - In your application manifest, |
| 54 | declare an activity that is intended to run on TV devices.</li> |
| 55 | <li><strong>TV Support Libraries</strong> (Optional) - There are several |
| 56 | <a href="#tv-libraries">Support Libraries</a> |
| 57 | available for TV devices that provide widgets for building user interfaces.</li> |
| 58 | </ul> |
| 59 | |
| 60 | |
| 61 | <h3 id="prerequisites">Prerequisites</h3> |
| 62 | |
| 63 | <p>Before you begin building apps for TV, you must:</p> |
| 64 | |
| 65 | <ul> |
| 66 | <li><strong><a href="{@docRoot}sdk/installing/adding-packages.html#GetTools"> |
| 67 | Update your SDK tools to version 24.0.0 or higher</a></strong> |
| 68 | <br> |
| 69 | The updated SDK tools enable you to build and test apps for TV. |
| 70 | </li> |
| 71 | <li><strong><a href="{@docRoot}sdk/installing/adding-packages.html#GetTools"> |
| 72 | Update your SDK with Android 5.0 (API 21) or higher</a></strong> |
| 73 | <br> |
| 74 | The updated platform version provides new APIs for TV apps. |
| 75 | </li> |
| 76 | <li><strong><a href="{@docRoot}sdk/installing/create-project.html"> |
| 77 | Create or update your app project</a></strong> |
| 78 | <br> |
| 79 | In order to access new APIs for TV devices, you must create a project or modify an existing |
| 80 | project that targets Android 5.0 (API level 21) or higher. |
| 81 | </li> |
| 82 | </ul> |
| 83 | |
| 84 | |
| 85 | <h3 id="tv-activity">Declare a TV Activity</h3> |
| 86 | |
| 87 | <p>An application intended to run on TV devices must declare a launcher activity for TV |
| 88 | in its manifest using a {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent filter. |
| 89 | This filter identifies your app as being enabled for TV, allowing it to be considered a TV app |
| 90 | in Google Play. Declaring this intent also identifies which activity |
| 91 | in your app to launch when a user selects its icon on the TV home screen.</p> |
| 92 | |
| 93 | <p class="caution"> |
| 94 | <strong>Caution:</strong> If you do not include the {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent filter in |
| 95 | your app, it is not visible to users running the Google Play store on TV devices. Also, if your |
| 96 | app does not have this filter when you load it onto a TV device using developer tools, the app |
| 97 | does not appear in the TV user interface. |
| 98 | </p> |
| 99 | |
| 100 | <p>The following code snippet shows how to include this intent filter in your manifest:</p> |
| 101 | |
| 102 | <pre> |
| 103 | <application> |
| 104 | ... |
| 105 | <activity |
| 106 | android:name="com.example.android.MainActivity" |
| 107 | android:label="@string/app_name" > |
| 108 | |
| 109 | <intent-filter> |
| 110 | <action android:name="android.intent.action.MAIN" /> |
| 111 | <category android:name="android.intent.category.LAUNCHER" /> |
| 112 | </intent-filter> |
| 113 | </activity> |
| 114 | |
| 115 | <activity |
| 116 | android:name="com.example.android.<strong>TvActivity</strong>" |
| 117 | android:label="@string/app_name" |
| 118 | android:theme="@style/Theme.Leanback"> |
| 119 | |
| 120 | <intent-filter> |
| 121 | <action android:name="android.intent.action.MAIN" /> |
| 122 | <category android:name="<strong>android.intent.category.LEANBACK_LAUNCHER</strong>" /> |
| 123 | </intent-filter> |
| 124 | |
| 125 | </activity> |
| 126 | </application> |
| 127 | </pre> |
| 128 | |
| 129 | <p> |
| 130 | The second activity manifest entry in this example specifies that activity as the one to |
| 131 | launch on a TV device. |
| 132 | </p> |
| 133 | |
| 134 | <p> |
| 135 | If you are modifying an existing app for use on TV, your app should not use the same |
| 136 | activity layout for TV that it does for phones and tablets. The user interface of your TV app (or |
| 137 | TV portion of your existing app) should provide a simpler interface that can be easily navigated |
| 138 | using a remote control from a couch. For guidelines on designing an app for TV, see the <a href= |
| 139 | "{@docRoot}design/tv/index.html">TV Design</a> guide. For more information on the minimum |
| 140 | implementation requirements for interface layouts on TV, see <a href= |
| 141 | "{@docRoot}training/tv/start/layouts.html">Building TV Layouts</a>. |
| 142 | </p> |
| 143 | |
| 144 | |
| 145 | <h3 id="tv-libraries">Add TV support libraries</h3> |
| 146 | |
| 147 | <p> |
| 148 | The Android SDK includes support libraries that are intended for use with TV apps. These |
| 149 | libraries provide APIs and user interface widgets for use on TV devices. The libraries are |
| 150 | located in the {@code <sdk>/extras/android/support/} directory. Here is a list of the |
| 151 | libraries and their general purpose: |
| 152 | </p> |
| 153 | |
| 154 | <ul> |
| 155 | <li><a href="{@docRoot}tools/support-library/features.html#v17-leanback"> |
| 156 | <strong>v17 leanback library</strong></a> - Provides user interface widgets for TV apps, |
| 157 | particularly for apps that do media playback. |
| 158 | </li> |
| 159 | <li><a href="{@docRoot}tools/support-library/features.html#v7-recyclerview"> |
| 160 | <strong>v7 recyclerview library</strong></a> - Provides classes for managing display of long |
| 161 | lists in a memory efficient manner. Several classes in the v17 leanback library depend on the |
| 162 | classes in this library. |
| 163 | </li> |
| 164 | <li><a href="{@docRoot}tools/support-library/features.html#v7-cardview"> |
| 165 | <strong>v7 cardview library</strong></a> - Provides user interface widgets for displaying |
| 166 | information cards, such as media item pictures and descriptions. |
| 167 | </li> |
| 168 | </ul> |
| 169 | |
| 170 | <p class="note"> |
| 171 | <strong>Note:</strong> You are not required to use these support libraries for your TV app. |
| 172 | However, we strongly recommend using them, particularly for apps that provide a media catalog |
| 173 | browsing interface. |
| 174 | </p> |
| 175 | |
| 176 | <p> |
| 177 | If you decide to use the v17 leanback library for your app, you should note that it is dependent |
| 178 | on the <a href="{@docRoot}tools/support-library/features.html#v4">v4 support library</a>. This |
| 179 | means that apps that use the leanback support library should include all of these support |
| 180 | libraries: |
| 181 | </p> |
| 182 | |
| 183 | <ul> |
| 184 | <li>v4 support library</li> |
| 185 | <li>v7 recyclerview support library</li> |
| 186 | <li>v17 leanback support library</li> |
| 187 | </ul> |
| 188 | |
| 189 | <p> |
| 190 | The v17 leanback library contains resources, which require you to take specific steps to include |
| 191 | it in app projects. For instructions on importing a support library with resources, see |
| 192 | <a href="{@docRoot}tools/support-library/setup.html#libs-with-res">Support Library Setup</a>. |
| 193 | </p> |
| 194 | |
| 195 | |
| 196 | <h2 id="build-it">Build TV Apps</h2> |
| 197 | |
| 198 | <p>After you have completed the steps described above, it's time to start building apps for |
| 199 | the big screen! Check out these additional topics to help you build your app for TV: |
| 200 | |
| 201 | <ul> |
| 202 | <li> |
| 203 | <a href="{@docRoot}training/tv/playback/index.html">Building TV Playback Apps</a> - TVs are |
| 204 | built to entertain, so Android provides a set of user interface tools and widgets for building |
| 205 | TV apps that play videos and music, and let users browse for the content they want. |
| 206 | </li> |
| 207 | <li> |
| 208 | <a href="{@docRoot}training/tv/search/index.html">Surfacing Content on TV</a> - With all the |
| 209 | content choices at users' fingertips, helping them find content they enjoy is almost as important |
| 210 | as providing that content. This training discusses how to surface your content on TV devices. |
| 211 | </li> |
| 212 | <li> |
| 213 | <a href="{@docRoot}training/tv/games/index.html">Games for TV</a> - TV devices are a great |
| 214 | platform for games. See this topic for information on building great game experiences for TV. |
| 215 | </li> |
| 216 | </ul> |
| 217 | |
| 218 | |
| 219 | <h2 id="run">Run TV Apps</h2> |
| 220 | |
| 221 | <p> |
| 222 | Running your app is an important part of the development process. The AVD Manager in the Android |
| 223 | SDK provides the device definitions that allow you to create virtual TV devices for running and |
| 224 | testing your applications. |
| 225 | </p> |
| 226 | |
| 227 | <p>To create an virtual TV device:</p> |
| 228 | |
| 229 | <ol> |
| 230 | <li>Start the AVD Manager. For more information, see the |
| 231 | <a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a> help.</li> |
| 232 | <li>In the AVD Manager dialog, click the <strong>Device Definitions</strong> tab.</li> |
| 233 | <li>Select one of the Android TV device definitions and click <strong>Create AVD</strong>.</li> |
| 234 | <li>Select the emulator options and click <strong>OK</strong> to create the AVD. |
| 235 | <p class="note"> |
| 236 | <strong>Note:</strong> For best performance of the TV emulator device, enable the <strong>Use |
| 237 | Host GPU</strong> option and, where supported, use virtual device acceleration. For |
| 238 | more information on hardware acceleration of the emulator, see |
| 239 | <a href="{@docRoot}tools/devices/emulator.html#acceleration">Using the Emulator</a>. |
| 240 | </p> |
| 241 | </li> |
| 242 | </ol> |
| 243 | |
| 244 | <p>To test your application on the virtual TV device:</p> |
| 245 | |
| 246 | <ol> |
| 247 | <li>Compile your TV application in your development environment.</li> |
| 248 | <li>Run the application from your development environment and choose the TV virtual device as |
| 249 | the target.</li> |
| 250 | </ol> |
| 251 | |
| 252 | <p> |
| 253 | For more information about using emulators see, <a href="{@docRoot}tools/devices/emulator.html"> |
| 254 | Using the Emulator</a>. For more information on deploying apps from Android Studio to virtual |
| 255 | devices, see <a href="{@docRoot}sdk/installing/studio-debug.html">Debugging with Android |
| 256 | Studio</a>. For more information about deploying apps to emulators from Eclipse with ADT, see |
| 257 | <a href="{@docRoot}tools/building/building-eclipse.html">Building and Running from Eclipse with |
| 258 | ADT</a>. |
| 259 | </p> |