docs/html/training/tv/start/start.jd

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="#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="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>
&lt;application
  android:banner="&#64;drawable/banner" &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 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>
&lt;manifest&gt;
    &lt;uses-feature android:name="android.software.leanback"
        android:required="false" /&gt;
    ...
&lt;/manifest&gt;
</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>
&lt;manifest&gt;
    &lt;uses-feature android:name="android.hardware.touchscreen"
              android:required="false" /&gt;
    ...
&lt;/manifest&gt;
</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>
&lt;application
    ...
    android:banner="&#64;drawable/banner" &gt;

    ...
&lt;/application&gt;
</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>&lt;application&gt;</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>&lt;activity&gt;</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>

<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 &lt;sdk&gt;/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">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>