docs/html/preview/tv/start/index.jd

page.title=Get Started with TV Apps
page.tags="leanback","recyclerview","launcher"

@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#prerequisites">Prerequisites</a></li>
    <li><a href="#dev-project">Setup a TV Project</a>
      <ul>
        <li><a href="#tv-activity">Create a TV Activity</a></li>
        <li><a href="#tv-libraries">Add TV Support Libraries</a></li>
      </ul>
    </li>
    <li><a href="#build-it">Build TV Apps</a></li>
    <li><a href="#run">Run TV Apps</a></li>

  </ol>
</div>
</div>

<p>This guide describes how to prepare your development environment and projects for building
  TV apps, including updating your existing app to run on TV devices.</p>


<h2 id="prerequisites">Prerequisites</h2>

<p>Before you begin setting up to build apps for TV, you must:</p>

<ul>
  <li><strong><a href="{@docRoot}preview/setup-sdk.html">
    Set up the Preview SDK</a></strong>
    <br>
    The preview SDK provides the developer tools needed to build and test apps for TV.
  </li>
  <li><strong><a href="{@docRoot}preview/setup-sdk.html#project">
    Create a Preview SDK Project</a></strong>
    <br>
    In order to access new APIs for TV devices, you must create a project that targets the preview
    release level or modify an existing project to target the preview release.
  </li>
</ul>


<h2 id="dev-project">Set up a TV Project</h2>

<p>TV apps use the same structure as those for phones and tablets. This 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. This section discusses how to modify an existing app, or create a
  new one, to run on TV devices.</p>

<p>These are the main steps to creating an app that runs on TV devices. Only the first
  is required:</p>

<ul>
  <li><strong>Activity for TV</strong> - (Required) In your application manifest, you must
    declare an activity that is intended to run on TV devices.</li>
  <li><strong>TV Support Libraries</strong> - (Optional) There are several Support Libraries
    available for TV devices that provide widgets for building user interfaces.</li>
</ul>


<h3 id="tv-activity">Create 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 {@code android.intent.category.LEANBACK_LAUNCHER} intent filter.
  This filter identifies your app as being built for TV, enabling it to be displayed in the
  Google Play store app running on TV devices. Declaring this intent also identifies which activity
  in your app should be launched when a user selects its icon on the TV home screen.</p>

<p class="caution">
  <strong>Caution:</strong> If you do not include the {@code 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>
&lt;application&gt;
  ...
  &lt;activity
    android:name=&quot;com.example.android.MainActivity&quot;
    android:label=&quot;@string/app_name&quot; &gt;

    &lt;intent-filter&gt;
      &lt;action android:name=&quot;android.intent.action.MAIN&quot; /&gt;
      &lt;category android:name=&quot;android.intent.category.LAUNCHER&quot; /&gt;
    &lt;/intent-filter&gt;
  &lt;/activity&gt;

  &lt;activity
    android:name=&quot;com.example.android.<strong>TvActivity</strong>&quot;
    android:label=&quot;&#64;string/app_name&quot;
    android:theme=&quot;&#64;style/Theme.Leanback&quot;&gt;

    &lt;intent-filter&gt;
      &lt;action android:name=&quot;android.intent.action.MAIN&quot; /&gt;
      &lt;category android:name="<strong>android.intent.category.LEANBACK_LAUNCHER</strong>" /&gt;
    &lt;/intent-filter&gt;

  &lt;/activity&gt;
&lt;/application&gt;
</pre>

<p>The second activity manifest entry in the example above specifies that activity as
  the main one when your app launches on an TV device.</p>

<p>If you have an existing app that you are modifying for TV use, 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 instructions on
  developing a user interface appropriate to TV, see the
  <a href="{@docRoot}preview/tv/ui/index.html">TV User Interface</a> guide.
</p>


<h3 id="tv-libraries">Add TV Support Libraries</h3>

<p>The Preview 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 &lt;sdk&gt;/extras/android/support/} directory where you installed the
  Preview SDK. Here is a list of the libraries and their general purpose:</p>

<ul>
  <li><strong>v17 leanback library</strong> - Provides user interface widgets for TV, including
    {@code BrowseFragment}, {@code DetailsFragment}, and {@code SearchFragment}.
    <ul>
      <li>SDK location: {@code &lt;sdk&gt;/extras/android/support/v17/leanback}</li>
      <li>Gradle dependency: {@code com.android.support:leanback-v17:20.0.+}</li>
      <li>Contains resources: Yes</li>
    </ul>
  </li>
  <li><strong>v7 recyclerview library</strong> - 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.
    <ul>
      <li>SDK location: {@code &lt;sdk&gt;/extras/android/support/v7/recyclerview}</li>
      <li>Gradle dependency: {@code com.android.support:recyclerview-v7:20.0.+}</li>
      <li>Contains resources: No</li>
    </ul>
  </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>v17 leanback support library</li>
  <li>v7 recyclerview support library</li>
  <li>v4 support library</li>
</ul>

<p>The v17 leanback library contain resources, which requires
  you to take specific steps to include it in app projects. For instructions on
  importing a support library with resources, see
  <a href="http://developer.android.com/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}preview/tv/ui/index.html">User Interface</a> - The user interface of
    TV devices is different from those of other Android devices. See this topic to find out how
    to build TV user interfaces and to learn about the widgets provided to simplify that task.
  </li>
  <li><a href="{@docRoot}preview/tv/games/index.html">Games for TV</a> - TV devices are great
    platforms for games. See this topic for information on building great game experiences for
    TV.</li>
  <li><a href="{@docRoot}preview/tv/start/hardware-features.html">Hardware features</a> - TV
    devices do not contain hardware features normally found on other Android devices. See this
    topic for information on unsupported hardware features and what to do about them.
  </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 allows 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, such as
    <strong>Large Android TV</strong>, 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 CPU platform image that supports hardware 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 about deploying apps to emulators from
Eclipse with ADT, see <a href="{@docRoot}http://developer.android.com/tools/building/building-eclipse.html">
Building and Running from Eclipse with ADT</a>.</p>