am 37425662: am 26994aa7: Merge "docs: Checklist for TV Apps" into lmp-docs

* commit '37425662d3b2a17a8d2cb495d650f1e115dccabe': docs: Checklist for TV Apps
2015-01-06 04:57:25 +00:00
parent a9a514331c 37425662d3
commit ea0137ef54
7 changed files with 327 additions and 32 deletions
--- a/docs/html/guide/topics/manifest/uses-feature-element.jd
+++ b/docs/html/guide/topics/manifest/uses-feature-element.jd
@@ -27,12 +27,12 @@ page.tags=filtering,features,google play filters,permissions
 </div>
 </div>

- <div class="sidebox-wrapper"> 
+ <div class="sidebox-wrapper">
 <div class="sidebox">
-    <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> 
-    <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> 
+    <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;">
+    <p style="color:#669999;padding-top:1em;">Google Play Filtering</p>
    <p style="padding-top:1em;">Google Play uses the <code>&lt;uses-feature&gt;</code>
-    elements declared in your app manifest to filter your app from devices 
+    elements declared in your app manifest to filter your app from devices
    that do not meet it's hardware and software feature requirements. </p>

 <p style="margin-top:1em;">By specifying the features that your application requires,
@@ -98,7 +98,7 @@ application requires.</p>
 <p>Declared <code>&lt;uses-feature></code> elements are informational only, meaning
 that the Android system itself does not check for matching feature support on
 the device before installing an application. However, other services
-(such as Google Play) or applications may check your application's 
+(such as Google Play) or applications may check your application's
 <code>&lt;uses-feature></code> declarations as part of handling or interacting
 with your application. For this reason, it's very important that you declare all of
 the features (from the list below) that your application uses. </p>
@@ -124,7 +124,7 @@ permission grants your application access to the appropriate hardware and
 software, while declaring the features used by your application ensures proper
 device compatibility.</p>

-</dd> 
+</dd>


 <dt>attributes:</dt>
@@ -352,7 +352,7 @@ not offer a camera.</p>

 <p>If you don't want Google Play to filter based on a specific implied
 feature, you can disable that behavior. To do so, declare the feature explicitly
-in a <code>&lt;uses-feature&gt;</code> element and include an 
+in a <code>&lt;uses-feature&gt;</code> element and include an
 <code>android:required="false"</code> attribute. For example, to disable
 filtering derived from the <code>CAMERA</code> permission, you would declare
 the feature as shown below.</p>
@@ -560,7 +560,7 @@ is sensitive to delays or lag in sound input or output.</td>
       <td></td>
    </tr>
    <tr>
-       <td rowspan="5">Camera</td>
+       <td rowspan="6">Camera</td>
       <td><code>android.hardware.camera</code></td>
       <td>The application uses the device's camera. If the device supports
           multiple cameras, the application uses the camera that facing
@@ -741,9 +741,9 @@ device.</td>
  <td>Television</td>
  <td><code>android.hardware.type.television</code></td>
  <td>The application is designed for a television user experience.</td>
-  <td>This feature defines "television" to be a typical living room television experience: 
-  displayed on a big screen, where the user is sitting far away and the dominant form of 
-  input is something like a d-pad, and generally not through touch or a 
+  <td>This feature defines "television" to be a typical living room television experience:
+  displayed on a big screen, where the user is sitting far away and the dominant form of
+  input is something like a d-pad, and generally not through touch or a
  mouse/pointer-device.</td>
 </tr>

@@ -880,9 +880,9 @@ in a separate <code>&lt;uses-feature&gt;</code> element. </p>


  <table>
-<tr> 
+<tr>
  <th>Feature</th>
-  <th>Attribute Value</th> 
+  <th>Attribute Value</th>
  <th>Description</th>
 </tr>
 <tr>
@@ -965,7 +965,7 @@ filtering based on the <code>CAMERA</code> permission, you would add this
 <pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre>

 <table id="permissions-features" >
-  <tr> 
+  <tr>
    <th>Category</th>
    <th>This Permission...</th>
    <th>Implies This Feature Requirement</th>
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -978,6 +978,12 @@ include the action bar on devices running Android 2.1 or higher."
           description="How to build Live TV apps.">
           Building Live TV Apps</a>
      </li>
+
+      <li>
+        <a href="<?cs var:toroot ?>training/tv/publishing/checklist.html"
+           description="An itemized list of requirements for TV apps.">
+           TV Apps Checklist</a>
+      </li>
    </ul>
  </li>
  <!-- End: Building for TV -->
--- a/docs/html/training/tv/games/index.jd
+++ b/docs/html/training/tv/games/index.jd
@@ -142,6 +142,11 @@ page.article=true
 </p>


+<h3 id="button-independence">Use appropriate buttons</h3>
+
+<p>Not all game controllers provide Start, Search, or Menu buttons. Be sure your UI does not depend
+upon the use of these buttons.</p>
+
 <h3 id="multiple-controllers">Handle multiple controllers</h3>

 <p>
@@ -276,7 +281,7 @@ It includes a white controller on black background and a black controller on whi
 <h3 id="saving">Saving</h3>

 <p>
-  We highly recommend using Play Services <a href=
+  Use Google Play Services <a href=
  "https://developers.google.com/games/services/common/concepts/savedgames">Saved Games</a> to store
  your game save. Your game should bind game saves to a specific Google account, so as to be
  uniquely identifiable even across devices: Whether the player is using a handset or a TV, the
@@ -301,15 +306,27 @@ It includes a white controller on black background and a black controller on whi
  site.
 </p>

+<h3 id="exit">Exit</h3>
+
+<p>Provide a consistent and obvious UI element that lets the user exit the game gracefully. This
+element should be accessible with the D-pad navigation buttons. Do this instead of relying on the
+Home button to provide an exit, as that is not consistent nor reliable across different controllers.</p>
+

 <h2 id="web">Web</h2>

 <p>
-  We discourage enabling web browsing in games for Android TV. The television set is not
-  well-suited for browsing, either in terms of display or control scheme.
+  Do not enable web browsing in games for Android TV. Android TV does not support a web browser.
 </p>

 <p class="note">
  <strong>Note:</strong> You can use the {@link android.webkit.WebView} class for logins to
  services like Google+ and Facebook.
 </p>
+
+<h2 id="networking">Networking</h2>
+
+<p>Games frequently need greater bandwidth to provide optimum performance, and many users prefer
+ethernet to WiFi to provide that performance. Your app should check for both WiFi and ethernet
+connections. If your app is for TV only, you do not need to check for 3G/LTE service as you would
+for a mobile app.</p>
--- a/docs/html/training/tv/publishing/checklist.jd
+++ b/docs/html/training/tv/publishing/checklist.jd
@@ -0,0 +1,207 @@
+page.title=TV Apps Checklist
+page.tags="tv", "checklist"
+page.article=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+  <h2>Checklist sections</h2>
+  <ul>
+    <li><a href="#leanback">TV Form Factor Support</a></li>
+    <li><a href="#design">User Interface Design</a></li>
+    <li><a href="#discovery">Search and Content Discovery</a></li>
+    <li><a href="#games">Games</a></li>
+  </ul>
+  <h2>You should also read</h2>
+  <ul>
+    <li><a href="{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a></li>
+    <li><a href="http://android-developers.blogspot.com/2014/10/material-design-on-android-checklist.html">
+      Material Design on Android Checklist</a></li>
+    <li><a href="{@docRoot}distribute/tools/launch-checklist.html">
+      Launch Checklist</a></li>
+  </ul>
+</div>
+</div>
+
+<p>
+  Users enjoy the TV app experience when it is consistent, logical, and predictable.
+  They should be able to navigate within your app and throughout Android TV without getting lost or
+  having to "reset" the UI and start over. Users appreciate clear, colorful, and functional interfaces
+  that make the experience magical. With these ideas in mind, you can create an app that fits nicely
+  in Android TV and performs as users expect.
+</p>
+
+<p>
+  This checklist covers the main aspects of development for both apps and games and provides
+  guidelines to ensure that your app provides the best possible experience. Additional considerations
+  for games only are covered in the <em>Games</em> section.
+</p>
+
+<p>
+  For criteria that qualify an Android TV app on Google Play, see
+  <a href="{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a>.
+</p>
+
+<h2 id="leanback">TV Form Factor Support</h2>
+
+<p>These checklist items apply to <strong>Games</strong> and <strong>Apps</strong>.</p>
+
+<ol>
+
+<li>
+  Identify the main TV activity with the {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER}
+  filter in the manifest.
+  <p>See <a href="{@docRoot}training/tv/start/start.html#tv-activity">Declare a TV Activity</a>.</p>
+</li>
+
+<li>
+  Provide a home screen banner for each language supported by your app
+  <ul>
+    <li>Launcher app banner measures 320x180 px</li>
+    <li>Banner resource is located in the {@code drawables/xhdpi} directory</li>
+    <li>Banner image includes localized text to identify the app.</li>
+  </ul>
+  <p>See <a href="{@docRoot}training/tv/start/start.html#banner">Provide a home screen banner</a>.</p>
+</li>
+
+<li>
+  Eliminate requirements for unsupported hardware in your app.
+  <p>See <a href="training/tv/start/hardware.html#declare-hardware-requirements">Declaring hardware requirements for TV</a>.</p>
+</li>
+
+<li>
+  Ensure permissions do not imply hardware requirements
+  <p>See <a href="training/tv/start/hardware.html#hardware-permissions">Declaring permissions that imply hardware features</a>.</p>
+</li>
+
+</ol>
+
+
+<h2 id="design">User Interface Design</h2>
+
+<p>These checklist items apply to <strong>Games</strong> and <strong>Apps</strong>.</p>
+
+<ol>
+
+<li>
+  Provide appropriate layout resources for landscape mode.
+  <p>See <a href="{@docRoot}training/tv/start/layouts.html#structure">Build Basic TV Layouts</a>.</p>
+</li>
+
+<li>
+  Ensure that text and controls are large enough to be visible from a distance.
+  <p>See <a href="{@docRoot}training/tv/start/layouts.html#visibility">Build Useable Text and Controls</a>.</p>
+</li>
+
+<li>
+  Provide high-resolution bitmaps and icons for HDTV screens.
+  <p>See <a href="{@docRoot}training/tv/start/layouts.html#density-resources">Manage Layout Resources for TV</a>.</p>
+</li>
+
+<li>
+  Make sure your icons and logo conform to Android TV specifications.
+  <p>See <a href="{@docRoot}design/tv/patterns.html#icons">Manage Layout Resources for TV</a>.</p>
+</li>
+
+<li>
+  Allow for overscan in your layout.
+  <p>See <a href="{@docRoot}training/tv/start/layouts.html#overscan">Overscan</a>.</p>
+</li>
+
+<li>
+  Make every UI element work with both D-pad and game controllers.
+  <p>See <a href="{@docRoot}training/tv/start/navigation.html">Creating Navigation</a>
+    and <a href="{@docRoot}training/tv/start/hardware.html#controllers">Handling Controllers</a>.</p>
+</li>
+
+<li>
+  Change the background image as users browse through content.
+  <p>See <a href="{@docRoot}training/tv/playback/browse.html#background">Update the Background</a>.</p>
+</li>
+
+<li>
+  Customize the background color to match your branding in Leanback fragments.
+  <p>See <a href="{@docRoot}training/tv/playback/card.html#background">Customize the Card View</a>.</p>
+</li>
+
+<li>
+  Ensure that your UI does not require a touch screen.
+  <p>See <a href="{@docRoot}training/tv/start/hardware.html#no-touchscreen">Touch screen</a> and
+    <a href="{@docRoot}training/tv/start/start.html#no-touchscreen">Declare touch screen not
+    required</a>.</p>
+</li>
+
+<li>
+  Follow guidelines for effective advertising.
+  <p>See <a href="{@docRoot}training/tv/start/layouts.html#advertising">Provide Effective Advertising</a>.</p>
+</li>
+
+</ol>
+
+
+<h2 id="discovery">Search and Content Discovery</h2>
+
+<p>These checklist items apply to <strong>Games</strong> and <strong>Apps</strong>.</p>
+
+<ol>
+
+<li>
+  Provide search results from your app in the Android TV global search box.
+  <p>See <a href="{@docRoot}training/tv/discovery/searchable.html#provide">Provide Data</a>.</p>
+</li>
+
+<li>
+  Provide TV-specific data fields for search.
+  <p>See <a href="{@docRoot}training/tv/discovery/searchable.html#columns">Identify Columns</a>.</p>
+</li>
+
+<li>
+  Make sure your app presents discovered content in a details screen that lets the user start watching
+  the content immediately.
+  <p>See <a href="{@docRoot}training/tv/discovery/searchable.html#details">Display Your App in the
+    Details Screen</a>.</p>
+</li>
+
+<li>
+  Put relevant, actionable content and categories on the main screen, making it easy to discover content.
+  <p>See <a href="{@docRoot}training/tv/discovery/recommendations.html">Recommending TV Content</a>.</p>
+</li>
+
+</ol>
+
+
+<h2 id="games">Games</h2>
+
+<p>These checklist items apply to <strong>Games</strong>.</p>
+
+<ol>
+
+<li>
+  Show your game on the home screen with the {@code isGame} flag in the manifest.
+  <p>See <a href="{@docRoot}training/tv/games/index.html#Launcher">Show your game on the home screen</a>.</p>
+</li>
+
+<li>
+  Make sure game controller support does not depend upon the Start, Select, or Menu buttons (not all
+  controllers have these).
+  <p>See <a href="{@docRoot}training/tv/games/index.html#control">Input Devices</a>.</p>
+</li>
+
+<li>
+  Use a generic gamepad graphic (without specific controller branding) to show game button mappings.
+  <p>See <a href="{@docRoot}training/tv/games/index.html#ControllerHelp">Show controller instructions</a>.</p>
+</li>
+
+<li>
+  Check for both ethernet and WiFi connectivity.
+  <p>See <a href="{@docRoot}training/tv/games/index.html#networking">Networking</a>.</p>
+</li>
+
+<li>
+  Provide users with a clean exit.
+  <p>See <a href="{@docRoot}training/tv/games/index.html#exit">Exit</a>.</p>
+</li>
+
+
+</ol>
--- a/docs/html/training/tv/start/hardware.jd
+++ b/docs/html/training/tv/start/hardware.jd
@@ -1,6 +1,5 @@
 page.title=Handling TV Hardware
-page.tags=tv
-helpoutsWidget=true
+page.tags="unsupported"
 trainingnavtop=true

@jd:body
@@ -88,6 +87,10 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)
    <td>Touchscreen</td>
    <td>{@code android.hardware.touchscreen}</td>
  </tr>
+  <tr>
+    <td>Touchscreen emulator</td>
+    <td>{@code android.hardware.faketouch}</td>
+  </tr>
  <tr>
    <td>Telephony</td>
    <td>{@code android.hardware.telephony}</td>
@@ -96,6 +99,10 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)
    <td>Camera</td>
    <td>{@code android.hardware.camera}</td>
  </tr>
+  <tr>
+    <td>Bluetooth</td>
+    <td>{@code android.hardware.bluetooth}</td>
+  </tr>
  <tr>
    <td>Near Field Communications (NFC)</td>
    <td>{@code android.hardware.nfc}</td>
@@ -105,11 +112,26 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)
    <td>{@code android.hardware.location.gps}</td>
  </tr>
  <tr>
-    <td>Microphone</td>
+    <td>Microphone <sup><a href="#cont-mic">[1]</a></sup></td>
    <td>{@code android.hardware.microphone}</td>
  </tr>
+  <tr>
+    <td>Sensors</td>
+    <td>{@code android.hardware.sensor}</td>
+  </tr>
 </table>

+<p id="cont-mic" class="note">
+  <strong>[1]</strong> Some TV controllers have a microphone, which is
+  not the same as the microphone hardware feature described here. The controller microphone is fully
+  supported.
+</p>
+
+<p>
+  See the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#features-reference">
+  Features Reference</a> for a complete list of features, subfeatures, and their descriptors.
+</p>
+

 <h3 id="declare-hardware-requirements">Declaring hardware requirements for TV</h3>

@@ -131,18 +153,29 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)
 <pre>
 &lt;uses-feature android:name="android.hardware.touchscreen"
        android:required="false"/&gt;
+&lt;uses-feature android:name="android.hardware.faketouch"
+        android:required="false"/&gt;
 &lt;uses-feature android:name="android.hardware.telephony"
        android:required="false"/&gt;
 &lt;uses-feature android:name="android.hardware.camera"
        android:required="false"/&gt;
+&lt;uses-feature android:name="android.hardware.bluetooth"
+        android:required="false"/&gt;
 &lt;uses-feature android:name="android.hardware.nfc"
        android:required="false"/&gt;
 &lt;uses-feature android:name="android.hardware.gps"
        android:required="false"/&gt;
 &lt;uses-feature android:name="android.hardware.microphone"
        android:required="false"/&gt;
+&lt;uses-feature android:name="android.hardware.sensor"
+        android:required="false"/&gt;
 </pre>

+<p class="note"><strong>Note:</strong> Some features have subfeatures like {@code android.hardware.camera.front},
+  as described in the <a href="guide/topics/manifest/uses-feature-element.html#features-reference">
+  Feature Reference</a>. Be sure to mark as {@code required="false"} any subfeatures also used in
+  your app.</p>
+
 <p>
  All apps intended for use on TV devices must declare that the touch screen feature is not required
  as described in <a href="{@docRoot}training/tv/start/start.html#no-touchscreen">Get Started with
@@ -207,7 +240,7 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)
 </table>

 <p>
-  For a complete list of permission requests that imply a hardware feature requirement, see
+  For a complete list of permission requests that imply a hardware feature requirement, see the
  <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features">{@code
  uses-feature}</a> guide. If your app requests one of the features listed above, include a
  <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code uses-feature}</a>
@@ -246,7 +279,8 @@ if (getPackageManager().hasSystemFeature("android.hardware.touchscreen")) {
 <p>
  Since most TVs do not have touch screens, Android does not support touch screen interaction for
  TV devices. Furthermore, using a touch screen is not consistent with a viewing environment where
-  the user is seated 10 feet away from the display.
+  the user is seated 10 feet away from the display. Make sure that your UI elements and text do not
+  require or imply the use of a touchscreen.
 </p>

 <p>
--- a/docs/html/training/tv/start/layouts.jd
+++ b/docs/html/training/tv/start/layouts.jd
@@ -16,6 +16,7 @@ trainingnavtop=true
    <li><a href="#density-resources">Manage Layout Resources for TV</a></li>
    <li><a href="#anti-patterns">Avoid Layout Anti-Patterns</a></li>
    <li><a href="#large-bitmaps">Handle Large Bitmaps</a></li>
+    <li><a href="#advertising">Provide Effective Advertising</a></li>
  </ol>
  <h2>You should also read</h2>
  <ol>
@@ -258,3 +259,17 @@ trainingnavtop=true
  For more information on getting the best performance when working with images, see
  <a href="{@docRoot}training/displaying-bitmaps/index.html">Displaying Bitmaps Efficiently</a>.
 </p>
+
+<h2 id="advertising">Provide Effective Advertising</h2>
+
+<p>Advertising on Android TV must always be full-screen. Ads must not appear alongside or over
+content. The user must be able to dismiss an advertisement with the D-pad controller. Video ads must
+be dismissible within 30 seconds of their start time.</p>
+
+<p>Android TV does not provide a web browser. Your ads must not attempt to launch a web browser or
+redirect to the Google Play Store.</p>
+
+<p class="note">
+  <strong>Note:</strong> You can use the {@link android.webkit.WebView} class for logins to
+  services like Google+ and Facebook.
+</p>
--- a/docs/html/training/tv/start/start.jd
+++ b/docs/html/training/tv/start/start.jd
@@ -1,6 +1,5 @@
 page.title=Get Started with TV Apps
-page.tags=tv, leanback, recyclerview
-helpoutsWidget=true
+page.tags="leanback","recyclerview","launcher"

 trainingnavtop=true
 startpage=true
@@ -145,6 +144,22 @@ startpage=true
  "{@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>

@@ -158,8 +173,8 @@ startpage=true

 <pre>
 &lt;manifest&gt;
-    <strong>&lt;uses-feature android:name="android.hardware.touchscreen"
-              android:required="false" /&gt;</strong>
+    &lt;uses-feature android:name="android.hardware.touchscreen"
+              android:required="false" /&gt;
    ...
 &lt;/manifest&gt;
 </pre>
@@ -173,9 +188,9 @@ startpage=true
 <h3 id="banner">Provide a home screen banner</h3>

 <p>
-  An application must provide a home screen banner 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:
+  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>
@@ -263,9 +278,10 @@ startpage=true
    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.
+    <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