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"> 34 <strong>Important:</strong> There are specific requirements your app must meet to 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> 260