From 7515d188ddc6f5b582080b0e712ef9d003c6b85c Mon Sep 17 00:00:00 2001 From: Scott Rowe Date: Tue, 9 Dec 2014 15:51:39 -0800 Subject: docs: Checklist for TV Apps Change-Id: I93b57161b3e519164dab551068411f686d772596 --- .../guide/topics/manifest/uses-feature-element.jd | 28 +-- docs/html/training/training_toc.cs | 6 + docs/html/training/tv/games/index.jd | 23 ++- docs/html/training/tv/publishing/checklist.jd | 207 +++++++++++++++++++++ docs/html/training/tv/start/hardware.jd | 44 ++++- docs/html/training/tv/start/layouts.jd | 15 ++ docs/html/training/tv/start/start.jd | 36 +++- 7 files changed, 327 insertions(+), 32 deletions(-) create mode 100644 docs/html/training/tv/publishing/checklist.jd (limited to 'docs') diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index a716bf8..b040898 100644 --- 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 -
+
- -

Google Play Filtering

+ +

Google Play Filtering

Google Play uses the <uses-feature> - 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.

By specifying the features that your application requires, @@ -98,7 +98,7 @@ application requires.

Declared <uses-feature> 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 <uses-feature> 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.

@@ -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.

- +
attributes:
@@ -352,7 +352,7 @@ not offer a camera.

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 <uses-feature> element and include an +in a <uses-feature> element and include an android:required="false" attribute. For example, to disable filtering derived from the CAMERA permission, you would declare the feature as shown below.

@@ -560,7 +560,7 @@ is sensitive to delays or lag in sound input or output. - Camera + Camera android.hardware.camera 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. Television android.hardware.type.television The application is designed for a television user experience. - 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 + 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. @@ -880,9 +880,9 @@ in a separate <uses-feature> element.

- + - + @@ -965,7 +965,7 @@ filtering based on the CAMERA permission, you would add this 
<uses-feature android:name="android.hardware.camera" android:required="false" />
FeatureAttribute ValueAttribute Value Description
- + diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 00eca7c..082f5ff 100644 --- 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 + +
  • + + TV Apps Checklist +
    • diff --git a/docs/html/training/tv/games/index.jd b/docs/html/training/tv/games/index.jd index 371e9e9..7a3365d 100644 --- a/docs/html/training/tv/games/index.jd +++ b/docs/html/training/tv/games/index.jd @@ -142,6 +142,11 @@ page.article=true

    +

    Use appropriate buttons

    + +

    Not all game controllers provide Start, Search, or Menu buttons. Be sure your UI does not depend +upon the use of these buttons.

    +

    Handle multiple controllers

    @@ -276,7 +281,7 @@ It includes a white controller on black background and a black controller on whi

    Saving

    - We highly recommend using Play Services Saved Games 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.

    +

    Exit

    + +

    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.

    +

    Web

    - 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.

    Note: You can use the {@link android.webkit.WebView} class for logins to services like Google+ and Facebook.

    + +

    Networking

    + +

    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.

    diff --git a/docs/html/training/tv/publishing/checklist.jd b/docs/html/training/tv/publishing/checklist.jd new file mode 100644 index 0000000..865a89b --- /dev/null +++ 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 + + + +

    + 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. +

    + +

    + 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 Games section. +

    + +

    + For criteria that qualify an Android TV app on Google Play, see + TV App Quality. +

    + +

    TV Form Factor Support

    + +

    These checklist items apply to Games and Apps.

    + +
      + +
    1. + Identify the main TV activity with the {@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} + filter in the manifest. +

      See Declare a TV Activity.

      +
      2. + +
    2. + Provide a home screen banner for each language supported by your app +
        +
      • Launcher app banner measures 320x180 px
        • +
      • Banner resource is located in the {@code drawables/xhdpi} directory
        • +
      • Banner image includes localized text to identify the app.
        • +
      +

      See Provide a home screen banner.

      +
      3. + +
    3. + Eliminate requirements for unsupported hardware in your app. +

      See Declaring hardware requirements for TV.

      +
      4. + +
    4. + Ensure permissions do not imply hardware requirements +

      See Declaring permissions that imply hardware features.

      +
      5. + +
    + + +

    User Interface Design

    + +

    These checklist items apply to Games and Apps.

    + +
      + +
    1. + Provide appropriate layout resources for landscape mode. +

      See Build Basic TV Layouts.

      +
      2. + +
    2. + Ensure that text and controls are large enough to be visible from a distance. +

      See Build Useable Text and Controls.

      +
      3. + +
    3. + Provide high-resolution bitmaps and icons for HDTV screens. +

      See Manage Layout Resources for TV.

      +
      4. + +
    4. + Make sure your icons and logo conform to Android TV specifications. +

      See Manage Layout Resources for TV.

      +
      5. + +
    5. + Allow for overscan in your layout. +

      See Overscan.

      +
      6. + +
    6. + Make every UI element work with both D-pad and game controllers. +

      See Creating Navigation + and Handling Controllers.

      +
      7. + +
    7. + Change the background image as users browse through content. +

      See Update the Background.

      +
      8. + +
    8. + Customize the background color to match your branding in Leanback fragments. +

      See Customize the Card View.

      +
      9. + +
    9. + Ensure that your UI does not require a touch screen. +

      See Touch screen and + Declare touch screen not + required.

      +
      10. + +
    10. + Follow guidelines for effective advertising. +

      See Provide Effective Advertising.

      +
      11. + +
    + + +

    Search and Content Discovery

    + +

    These checklist items apply to Games and Apps.

    + +
      + +
    1. + Provide search results from your app in the Android TV global search box. +

      See Provide Data.

      +
      2. + +
    2. + Provide TV-specific data fields for search. +

      See Identify Columns.

      +
      3. + +
    3. + Make sure your app presents discovered content in a details screen that lets the user start watching + the content immediately. +

      See Display Your App in the + Details Screen.

      +
      4. + +
    4. + Put relevant, actionable content and categories on the main screen, making it easy to discover content. +

      See Recommending TV Content.

      +
      5. + +
    + + +

    Games

    + +

    These checklist items apply to Games.

    + +
      + +
    1. + Show your game on the home screen with the {@code isGame} flag in the manifest. +

      See Show your game on the home screen.

      +
      2. + +
    2. + Make sure game controller support does not depend upon the Start, Select, or Menu buttons (not all + controllers have these). +

      See Input Devices.

      +
      3. + +
    3. + Use a generic gamepad graphic (without specific controller branding) to show game button mappings. +

      See Show controller instructions.

      +
      4. + +
    4. + Check for both ethernet and WiFi connectivity. +

      See Networking.

      +
      5. + +
    5. + Provide users with a clean exit. +

      See Exit.

      +
      6. + + +
    diff --git a/docs/html/training/tv/start/hardware.jd b/docs/html/training/tv/start/hardware.jd index b25a0dd..57651e6 100644 --- 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 @@ -89,6 +88,10 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION) + + + + @@ -97,6 +100,10 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION) + + + + @@ -105,11 +112,26 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION) - + + + + +
    Category This Permission... Implies This Feature Requirement {@code android.hardware.touchscreen}
    Touchscreen emulator{@code android.hardware.faketouch}
    Telephony {@code android.hardware.telephony}
    {@code android.hardware.camera}
    Bluetooth{@code android.hardware.bluetooth}
    Near Field Communications (NFC) {@code android.hardware.nfc}
    {@code android.hardware.location.gps}
    MicrophoneMicrophone [1] {@code android.hardware.microphone}
    Sensors{@code android.hardware.sensor}
    +

    + [1] Some TV controllers have a microphone, which is + not the same as the microphone hardware feature described here. The controller microphone is fully + supported. +

    + +

    + See the + Features Reference for a complete list of features, subfeatures, and their descriptors. +

    +

    Declaring hardware requirements for TV

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

    Note: Some features have subfeatures like {@code android.hardware.camera.front}, + as described in the + Feature Reference. Be sure to mark as {@code required="false"} any subfeatures also used in + your app.

    +

    All apps intended for use on TV devices must declare that the touch screen feature is not required as described in Get Started with @@ -207,7 +240,7 @@ if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_TELEVISION)

    - 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 {@code uses-feature} guide. If your app requests one of the features listed above, include a {@code uses-feature} @@ -246,7 +279,8 @@ if (getPackageManager().hasSystemFeature("android.hardware.touchscreen")) {

    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.

    diff --git a/docs/html/training/tv/start/layouts.jd b/docs/html/training/tv/start/layouts.jd index a390702..177ea7a 100644 --- a/docs/html/training/tv/start/layouts.jd +++ b/docs/html/training/tv/start/layouts.jd @@ -16,6 +16,7 @@ trainingnavtop=true

  • Manage Layout Resources for TV
  • Avoid Layout Anti-Patterns
  • Handle Large Bitmaps
    • +
  • Provide Effective Advertising

    • You should also read

      @@ -258,3 +259,17 @@ trainingnavtop=true For more information on getting the best performance when working with images, see Displaying Bitmaps Efficiently.

      + +

      Provide Effective Advertising

      + +

      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.

      + +

      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.

      + +

      + Note: You can use the {@link android.webkit.WebView} class for logins to + services like Google+ and Facebook. +

      \ No newline at end of file diff --git a/docs/html/training/tv/start/start.jd b/docs/html/training/tv/start/start.jd index e3b92c6..2766e90 100644 --- 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.

      +

      Declare Leanback support

      + +

      + 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. +

      + +
      +<manifest>
+    <uses-feature android:name="android.software.leanback"
+        android:required="false" />
+    ...
+</manifest>
+

      Declare touchscreen not required

      @@ -158,8 +173,8 @@ startpage=true 
       <manifest>
-    <uses-feature android:name="android.hardware.touchscreen"
-              android:required="false" />
+    <uses-feature android:name="android.hardware.touchscreen"
+              android:required="false" />
     ...
 </manifest>
      @@ -173,9 +188,9 @@ startpage=true

      - 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: 

      @@ -263,9 +278,10 @@ startpage=true
     TV apps that play videos and music, and let users browse for the content they want.
   
   
    1. 
-    Surfacing Content on TV - 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.
+    Helping Users Find Your Content on TV -
+    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.
   
      2. 
   
    2. 
     Games for TV - TV devices are a great
-- 
cgit v1.1