diff options
Diffstat (limited to 'docs')
52 files changed, 1379 insertions, 337 deletions
diff --git a/docs/html/about/dashboards/index.jd b/docs/html/about/dashboards/index.jd index 808f04a..448dcda 100644 --- a/docs/html/about/dashboards/index.jd +++ b/docs/html/about/dashboards/index.jd @@ -41,13 +41,6 @@ with Android 2.2 and higher. Each snapshot of data represents all the devices th Google Play Store in the prior 7 days.</p> -<div class="note"> -<p><strong>Note:</strong> Beginning in September, 2013, devices running versions older than Android -2.2 do not appear in this data because those devices do not support the new Google Play Store -app. Only the new app is able to measure the number of devices that actively visit Google Play Store -and we believe this measurement best reflects your potential user-base.</p> -</div> - <h2 id="Platform">Platform Versions</h2> @@ -64,7 +57,7 @@ Platform Versions</a>.</p> </div> -<p style="clear:both"><em>Data collected during a 7-day period ending on September 9, 2014. +<p style="clear:both"><em>Data collected during a 7-day period ending on November 3, 2014. <br/>Any versions with less than 0.1% distribution are not shown.</em> </p> @@ -95,7 +88,7 @@ Screens</a>.</p> </div> -<p style="clear:both"><em>Data collected during a 7-day period ending on September 9, 2014. +<p style="clear:both"><em>Data collected during a 7-day period ending on November 3, 2014. <br/>Any screen configurations with less than 0.1% distribution are not shown.</em></p> @@ -115,7 +108,7 @@ support for any lower version (for example, support for version 2.0 also implies <img alt="" style="float:right" -src="//chart.googleapis.com/chart?chs=400x250&cht=p&chd=t%3A77.5%2C22.5&chf=bg%2Cs%2C00000000&chl=GL%202.0%7CGL%203.0&chco=c4df9b%2C6fad0c" /> +src="//chart.googleapis.com/chart?chl=GL%202.0%7CGL%203.0&chd=t%3A74.7%2C25.3&chf=bg%2Cs%2C00000000&chco=c4df9b%2C6fad0c&cht=p&chs=400x250" /> <p>To declare which version of OpenGL ES your application requires, you should use the {@code android:glEsVersion} attribute of the <a @@ -133,17 +126,17 @@ uses.</p> </tr> <tr> <td>2.0</td> -<td>77.5%</td> +<td>74.7%</td> </tr> <tr> <td>3.0</td> -<td>22.5%</td> +<td>25.3%</td> </tr> </table> -<p style="clear:both"><em>Data collected during a 7-day period ending on September 9, 2014</em></p> +<p style="clear:both"><em>Data collected during a 7-day period ending on November 3, 2014</em></p> @@ -161,42 +154,42 @@ uses.</p> var VERSION_DATA = [ { - "chart": "//chart.googleapis.com/chart?chco=c4df9b%2C6fad0c&cht=p&chs=500x250&chl=Froyo%7CGingerbread%7CIce%20Cream%20Sandwich%7CJelly%20Bean%7CKitKat&chd=t%3A0.7%2C11.4%2C9.6%2C53.8%2C24.5&chf=bg%2Cs%2C00000000", + "chart": "//chart.googleapis.com/chart?chl=Froyo%7CGingerbread%7CIce%20Cream%20Sandwich%7CJelly%20Bean%7CKitKat&chd=t%3A0.6%2C9.8%2C8.5%2C50.9%2C30.2&chf=bg%2Cs%2C00000000&chco=c4df9b%2C6fad0c&cht=p&chs=500x250", "data": [ { "api": 8, "name": "Froyo", - "perc": "0.7" + "perc": "0.6" }, { "api": 10, "name": "Gingerbread", - "perc": "11.4" + "perc": "9.8" }, { "api": 15, "name": "Ice Cream Sandwich", - "perc": "9.6" + "perc": "8.5" }, { "api": 16, "name": "Jelly Bean", - "perc": "25.1" + "perc": "22.8" }, { "api": 17, "name": "Jelly Bean", - "perc": "20.7" + "perc": "20.8" }, { "api": 18, "name": "Jelly Bean", - "perc": "8.0" + "perc": "7.3" }, { "api": 19, "name": "KitKat", - "perc": "24.5" + "perc": "30.2" } ] } @@ -210,27 +203,27 @@ var SCREEN_DATA = "Large": { "hdpi": "0.6", "ldpi": "0.5", - "mdpi": "4.3", - "tvdpi": "1.7", + "mdpi": "4.5", + "tvdpi": "1.9", "xhdpi": "0.6" }, "Normal": { - "hdpi": "35.7", - "mdpi": "10.6", - "xhdpi": "19.2", - "xxhdpi": "16.2" + "hdpi": "36.6", + "mdpi": "9.9", + "xhdpi": "18.9", + "xxhdpi": "16.0" }, "Small": { - "ldpi": "6.2" + "ldpi": "5.8" }, "Xlarge": { "hdpi": "0.3", - "mdpi": "3.7", - "xhdpi": "0.4" + "mdpi": "3.9", + "xhdpi": "0.5" } }, - "densitychart": "//chart.googleapis.com/chart?chco=c4df9b%2C6fad0c&cht=p&chs=400x250&chl=ldpi%7Cmdpi%7Ctvdpi%7Chdpi%7Cxhdpi%7Cxxhdpi&chd=t%3A6.7%2C18.6%2C1.7%2C36.6%2C20.2%2C16.2&chf=bg%2Cs%2C00000000", - "layoutchart": "//chart.googleapis.com/chart?chco=c4df9b%2C6fad0c&cht=p&chs=400x250&chl=Xlarge%7CLarge%7CNormal%7CSmall&chd=t%3A4.4%2C7.7%2C81.7%2C6.2&chf=bg%2Cs%2C00000000" + "densitychart": "//chart.googleapis.com/chart?chl=ldpi%7Cmdpi%7Ctvdpi%7Chdpi%7Cxhdpi%7Cxxhdpi&chd=t%3A6.3%2C18.3%2C1.9%2C37.5%2C20.0%2C16.0&chf=bg%2Cs%2C00000000&chco=c4df9b%2C6fad0c&cht=p&chs=400x250", + "layoutchart": "//chart.googleapis.com/chart?chl=Xlarge%7CLarge%7CNormal%7CSmall&chd=t%3A4.7%2C8.1%2C81.4%2C5.8&chf=bg%2Cs%2C00000000&chco=c4df9b%2C6fad0c&cht=p&chs=400x250" } ]; @@ -302,6 +295,16 @@ var VERSION_NAMES = "api":19, "link":"<a href='/about/versions/android-4.4.html'>4.4</a>", "codename":"KitKat" + }, + { + "api":20, + "link":"<a href='/about/versions/android-4.4.html'>4.4W</a>", + "codename":"KitKat for Wear" + }, + { + "api":21, + "link":"<a href='/about/versions/android-5.0.html'>4.4</a>", + "codename":"Lollipop" } ]; diff --git a/docs/html/design/tv/index.jd b/docs/html/design/tv/index.jd index 483c24f..d79e279 100644 --- a/docs/html/design/tv/index.jd +++ b/docs/html/design/tv/index.jd @@ -1,4 +1,7 @@ -page.title=Android TV +page.title=Designing for Android TV +page.tags="tv", "leanback","designguidelines" +page.metaDescription=Guidelines to help you create a great leanback experience on Android TV. +page.image=design/tv/images/apps-games-rows.jpg @jd:body @@ -6,12 +9,15 @@ page.title=Android TV experience. It's important to understand how your app is presented in the main user interface and how your app can help users get to the content they want quickly.</p> -<p class="note"> +<p class="caution"> <strong>Important:</strong> There are specific design 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 class="note"><strong>Note:</strong> For information about how to publish your TV apps in Google Play, +see <a href="/distribute/googleplay/tv.html">Distributing to Android TV</a>.</p> + <h2>Home Screen</h2> <p>The Home Screen is the start of the user experience, providing search, content diff --git a/docs/html/design/tv/patterns.jd b/docs/html/design/tv/patterns.jd index 768dcfc..be7ae31 100644 --- a/docs/html/design/tv/patterns.jd +++ b/docs/html/design/tv/patterns.jd @@ -41,6 +41,8 @@ page.title=UI Patterns for TV language, you must provide versions of the banner image for each supported language.</li> </ul> +<p>See <a href="{@docRoot}training/tv/start/start.html#banner">Provide a home screen banner</a> +in Get Started with TV Apps for more information.</p> <h3>Recommendation Icons</h3> diff --git a/docs/html/design/wear/patterns.jd b/docs/html/design/wear/patterns.jd index 30fdc24..e56ac2d 100644 --- a/docs/html/design/wear/patterns.jd +++ b/docs/html/design/wear/patterns.jd @@ -76,6 +76,13 @@ page.title=UI Patterns for Android Wear <li>The cue card can be invoked to continue specifying the action. For example in a messaging application, tapping a “Reply” action button invokes the Cue Card and prompts for voice input. In this case the prompt label (such as “Speak your message…”) and a set of sample voice suggestions can be specified by developers.</li> </ol> +<a class="notice-developers left" href="{@docRoot}training/wearables/ui/confirm.html"> + <div> + <h3>Developer Docs</h3> + <p>Showing Confirmations</p> + </div> +</a> + <h2 id="Continuing" style="clear:both">Continuing activities on phone</h2> @@ -100,6 +107,13 @@ page.title=UI Patterns for Android Wear <p>Good examples of using an action on card include: play and pause music, toggle light switch on and off, navigate to an address, and call a phone number.</p> +<a class="notice-developers left" href="{@docRoot}training/wearables/ui/cards.html"> + <div> + <h3>Developer Docs</h3> + <p>Creating Cards</p> + </div> +</a> + <h2 id="Stacks" style="clear:both">Card stacks</h2> <img src="{@docRoot}design/media/wear/expandable_stacks.png" width="147" height="147" style="float:right;margin:0 0 20px 40px"> @@ -124,6 +138,13 @@ to check-in to.</p> <p>More information about how to use the 2D Picker pattern is provided in the <a href="{@docRoot}design/wear/structure.html#2DPicker">App Structure</a> guide.</p> +<a class="notice-developers left" href="{@docRoot}training/wearables/ui/2d-picker.html"> + <div> + <h3>Developer Docs</h3> + <p>Creating a 2D Picker</p> + </div> +</a> + <h2 id="Voice" style="clear:both">Voice commands</h2> @@ -148,3 +169,10 @@ href="{@docRoot}training/wearables/apps/layouts.html#UiLibrary"><code>WearableLi <p>Of course, it is possible for Android Wear apps to extend themselves beyond the familiarities of these patterns. For a deeper look at the options available, see the <a href="{@docRoot}design/wear/structure.html">App Structure</a> guide.</p> + +<a class="notice-developers left" href="{@docRoot}training/wearables/ui/lists.html"> + <div> + <h3>Developer Docs</h3> + <p>Creating Lists</p> + </div> +</a> diff --git a/docs/html/design/wear/structure.jd b/docs/html/design/wear/structure.jd index b77ccc2..95d5c1a 100644 --- a/docs/html/design/wear/structure.jd +++ b/docs/html/design/wear/structure.jd @@ -84,12 +84,18 @@ margin: 0 10px 20px 20px; <img src="{@docRoot}design/media/wear/1D_picker.png" alt="" width="499px" /> <p class="img-caption">This pattern can be used to present a single vertical list, or a “1D Picker”</p> -<img src="{@docRoot}design/media/wear/2D_picker.png" alt="" width:760px" /> +<img src="{@docRoot}design/media/wear/2D_picker.png" alt="" width="760px" /> <p class="img-caption">It can also be used as a 2D matrix of options, as a way of presenting categorized options.</p> <h3>Actions</h3> +<a class="notice-developers" style="clear:none" href="{@docRoot}training/wearables/ui/2d-picker.html"> + <div> + <h3>Developer Docs</h3> + <p>Creating a 2D Picker</p> + </div> +</a> <p>For actions on each card, use the <a href="{@docRoot}design/wear/patterns.html#Actions">Action cards pattern</a>.</p> <h3>Making it fast</h3> @@ -155,6 +161,6 @@ href="#2DPicker">2D picker</a> is always available.</p> <h3>Manually exiting</h3> <p>Even with logical exit points like these, some cases may exist where the user may want to immediately exit. This may be common in apps that are used for a longer while. In all cases, you should treat long-press as the user's intent to exit, using -<a href="{@docRoot}training/wearables/apps/layouts.html#UiLibrary"><code>DismissOverlayView</code></a>.</p> +<a href="{@docRoot}training/wearables/ui/exit.html"><code>DismissOverlayView</code></a>.</p> diff --git a/docs/html/distribute/essentials/quality/tv.jd b/docs/html/distribute/essentials/quality/tv.jd index b13307e..20018c3 100644 --- a/docs/html/distribute/essentials/quality/tv.jd +++ b/docs/html/distribute/essentials/quality/tv.jd @@ -47,11 +47,9 @@ page.image=/distribute/images/gp-tv-quality.png qualify as an Android TV app on Google Play. </p> -<p class="note"> - <strong>Note:</strong> You will be able to submit TV apps to Google Play with the public release - of Android 5.0 on November 3. Stay tuned for more information about how to submit your TV apps - through the Google Play Developer Console. -</p> +<p class="note"><strong>Note:</strong> For information about how to publish your TV apps in Google Play, +see <a href="{@docRoot}distribute/googleplay/tv.html">Distributing to Android TV</a>.</p> + <div class="headerLine"> diff --git a/docs/html/distribute/googleplay/edu/start.jd b/docs/html/distribute/googleplay/edu/start.jd index 3c3a175..f4c9717 100644 --- a/docs/html/distribute/googleplay/edu/start.jd +++ b/docs/html/distribute/googleplay/edu/start.jd @@ -1,4 +1,4 @@ -page.title=Publish Apps +page.title=Publish Education Apps page.image=/distribute/images/play-education.jpg meta.tags="education", "guidelines", "quality" page.tags="education", "addendum" diff --git a/docs/html/distribute/googleplay/googleplay_toc.cs b/docs/html/distribute/googleplay/googleplay_toc.cs index 45464c7..fc7cd11 100644 --- a/docs/html/distribute/googleplay/googleplay_toc.cs +++ b/docs/html/distribute/googleplay/googleplay_toc.cs @@ -18,6 +18,12 @@ </div> </li> <li class="nav-section"> + <div class="nav-section empty" style="font-weight:normal"><a href="<?cs var:toroot?>distribute/googleplay/tv.html"> + <span class="en">Distributing to <span style="white-space:nowrap">Android TV</span></span> + </a> + </div> + </li> + <li class="nav-section"> <div class="nav-section-header" style="font-weight:normal"><a href="<?cs var:toroot?>distribute/googleplay/edu/about.html"> <span class="en">Google Play for Education</span> </a> diff --git a/docs/html/distribute/googleplay/index.jd b/docs/html/distribute/googleplay/index.jd index a215930..20f07fa 100644 --- a/docs/html/distribute/googleplay/index.jd +++ b/docs/html/distribute/googleplay/index.jd @@ -21,7 +21,7 @@ nonavpage=true data-maxResults="3"> </div> - <h3>Google Play for Education</h3> + <h3>Distribute Your Apps</h3> <div class="resource-widget resource-flow-layout landing col-16" data-query="collection:distribute/gp/gpfelanding" diff --git a/docs/html/distribute/googleplay/tv.jd b/docs/html/distribute/googleplay/tv.jd new file mode 100644 index 0000000..37cbe26 --- /dev/null +++ b/docs/html/distribute/googleplay/tv.jd @@ -0,0 +1,320 @@ +page.title=Distributing to Android TV +page.image=/design/tv/images/atv-home.jpg +meta.tags="tv", "publish", "quality" +page.tags="tv", "publish", "googleplay" +page.metaDescription=Distribute your apps, games, and content to Android TV. + +@jd:body + +<div id="qv-wrapper"><div id="qv"> +<h2>How to Participate</h2> +<ol> +<li><a href="#understand_guidelines">Understand the guidelines</a></li> +<li><a href="#develop_app">Develop a great app for TV</a></li> +<li><a href="#test_app">Test for TV App Quality</a></li> +<li><a href="#opt_in">Opt-in</a></li> +<li><a href="#track_review">Track your review</a></li> +</ol> + +<h2>You Should Also Read</h2> +<ol> +<li><a href="{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a></li> +<li><a href="{@docRoot}distribute/essentials/quality/core.html">Core App Quality</a></li> +</ol> + +</div></div> + +<p> + If you've got a great app or game, Android TV and Google Play can help you + bring it to users right in their living rooms. You'll be able to offer your + apps and games in a storefront experience that’s optimized for TV. You can + extend your new or existing apps for TV and then publish them using familiar + tools and processes in Google Play. +</p> + +<p> + To get started, review the sections in this document to learn how to + distribute your TV apps to users through Google Play. Be sure to read + <a href="{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a> + for information on the usability and quality standards that your apps should + meet. When your app is ready, you can opt-in to publishing in the Android TV + storefront from the Developer Console. +</p> + +<h2 id="how_to_participate"> + How to Participate +</h2> + +<p> + Google Play lets you put your TV apps in front of a new audience of users in + their living rooms. You can develop and publish using your existing Developer + Console account and your current distribution and pricing settings. It's easy + to participate — the sections below outline the process. +</p> + +<div style="float:right;margin:1em 0 1.5em 2em;"> + <img src="{@docRoot}images/gp-tv-process.png"> +</div> + +<h3 id="understand_guidelines"> + 1. Understand guidelines and requirements +</h3> + +<p> + To prepare for a successful launch on Android TV, start by reviewing the + guidelines for creating great app experiences on TV. See the <a href= + "{@docRoot}design/tv/index.html">Android TV design guidelines</a> for ideas + on extending your app for TV and details on design and usability. +</p> + +<p> + As you get started designing your TV experience, make sure to read and + understand the quality criteria for TV apps. The Google Play experience for + Android TV <strong>showcases only apps that are usable on the TV</strong> + — your apps can participate if they meet a set of basic quality + criteria. See <a href="{@docRoot}distribute/essentials/quality/tv.html">TV + App Quality</a> for details. +</p> + +<h3 id="develop_app">2. Develop a great app for TV</h3> + +<p> + A great app for TV is designed for living room use and takes advantage of the + capabilities of Android TV and related input accessories such as game + controllers, D-pads, and remotes. The app is refined to offer a polished, + high-quality experience on large screens and delivers a compelling feature + set for users. +</p> + +<p> + As you consider your TV app, review the <a href= + "{@docRoot}training/tv/start/index.html">developer documentation</a> and + usability guidelines and plan on supporting them to the greatest extent + possible. Make sure to design a great leanback experience for users and build + it with the leanback library included in the SDK. You’ll want to optimize + other parts of your app for the TV use case and it's a good idea to identify + those early in your development process. +</p> + +<p> + In most cases, we recommend delivering your TV experience as part of your + existing app for phones, tablets, and other devices, using the same package + name and store listing. This approach lets users upgrade to your TV experience + seamlessly and also lets you take advantage of the reviews and ratings you’ve + earned in your app for phones and tablets. +</p> + +<p> + You can bundle your TV intents, leanback library, and TV-specific code and + resources as part of a single APK solution for all supported devices. If + necessary, you can use <a href= + "{@docRoot}google/play/publishing/multiple-apks.html">Multiple APK + Support</a> to deliver a custom binary to Android TV devices under the same + package name and store listing that you use for phones and tablets. +</p> + +<p> + Throughout design and development, it's important to have a suitable device + on which to prototype and test your user experience. You should acquire one + or more Android TV devices or emulators and set up your testing environment + as early as possible. The recommended hardware device for testing in the + Android TV environment is Nexus Player, which is <a href= + "http://www.google.com/intl/all/nexus/player/">available from Google Play</a> + and other stores, and you should also acquire a game controller and other TV + input devices. +</p> + +<h3 id="test_app">3. Test for TV App Quality</h3> + +<p> + Your TV apps should be designed to perform well, look great on Android TV, + and offer the best user experience possible. Google Play showcases + high-quality apps for easy discovery by users in Google Play. Here’s how you + can participate and deliver an Android TV app that users will enjoy. +</p> + +<ul> + <li>Meet Core App Quality guidelines + <ul> + <li>Follow <a href="{@docRoot}design/index.html">Android Design + guidelines</a>. Pay special attention to using <a href= + "http://www.google.com/design/spec/material-design/introduction.html">material + design</a> in your app. + </li> + + <li>Test your apps against the <a href= + "{@docRoot}distribute/essentials/quality/core.html">Core App Quality + guidelines</a>. + </li> + </ul> + </li> + <li>Meet <a href="{@docRoot}distribute/essentials/quality/tv.html">TV App + Quality</a> guidelines + <ul> + <li>Follow our best practices for <a href="{@docRoot}training/tv/index.html"> + TV app development</a></li> + <li>Make sure your app meets all of the <a href= + "{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a> criteria</li> + </ul> + </li> + <li>Strive for simplicity and highest usability</li> +</ul> + +<h3 id="opt_in">4. Opt-in to Android TV and publish</h3> + +<p> + When you've built your release-ready APK and tested to ensure that it meets + all of the <a href="{@docRoot}distribute/essentials/quality/tv.html">TV App + Quality</a> guidelines, upload it to the Developer Console. Update your store + listing with TV screenshots and TV banner, and set distribution options as + needed. If you aren't familiar with how to prepare for launch on Google Play, + see the <a href= + "{@docRoot}distribute/googleplay/publish/preparing.html">Launch + Checklist.</a> +</p> + +<p> + Before you can publish to Android TV users, you need to opt-in to Android + TV from the <strong>Pricing and Distribution</strong> section of the + Developer Console. Opt-in means that you want your app to be made available + to Android TV users through Google Play, and that + your app meets <a href="{@docRoot}distribute/essentials/quality/tv.html">TV + App Quality</a> guidelines. +</p> + +<p> + You can opt-in only if your app meets two preliminary quality + criteria that are automatically checked on APK upload: +</p> + +<ul> + <li>Your app manifest must include an intent type of <a href= + "{@docRoot}reference/android/content/Intent.html#ACTION_MAIN"><code>ACTION_MAIN</code></a> + with category <a href= + "{@docRoot}reference/android/content/Intent.html#CATEGORY_LEANBACK_LAUNCHER"> + <code>CATEGORY_LEANBACK_LAUNCHER</code></a>. Learn more <a href= + "{@docRoot}training/tv/start/start.html#tv-activity">here</a>. + </li> + + <li>Your app must declare that it does not require a touchscreen. The + manifest must declare the <code>android.hardware.touchscreen</code> hardware + with <code>android:required="false”</code>. Learn more <a href= + "{@docRoot}training/tv/start/hardware.html#declare-hardware-requirements">here</a>. + </li> +</ul> + +<p> + If your app meets the preliminary criteria, you’ll see an opt-in checkbox for + Android TV, as shown below. If the opt-in checkbox is not enabled, review + your APK to ensure it meets the preliminary criteria. +</p> + +<p> + After you opt-in and save the changes, you can publish your app as usual. + Before making the app available to Android TV users, Google Play submits + your app for review against the <a href= + "{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a> criteria + and notifies you of the result. See the next section for details on how to + track the approval status of your app. +</p> + +<p> + If your app meet <a href="{@docRoot}distribute/essentials/quality/tv.html">TV + App Quality</a> criteria, Google Play makes that app available to Android TV + users. Your app is alsoeligible for higher-visibility featuring in app + collections and promotions. To let users everywhere know that your app is + designed for Android TV, Google Play decorates the app’s store listing with a + TV badge. +</p> + +<p> + Note that opt-in and review do not affect the availability of your app to + other devices in Google Play Store — on phones and tablets, for + example, your app is available as soon as you publish. +</p> + +<p> + Here are the steps to opt-in to Android TV in the Developer Console: +</p> + +<ol> + <li>Make sure your app meets all <a href= + "{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a> criteria + </li> + + <li>Add TV screenshots and banner graphic to the app’s store listing + </li> + + <li>In the <strong>All Applications</strong> page, click the app you want to opt-in. + </li> + + <li>Under <strong>Pricing and Distribution</strong>, scroll down to find <em>Android TV</em> and the + opt-in checkbox. + </li> + + <li>Click the checkbox next to <em>Distribute your app to Android TV</em>. + </li> + + <li>Click <strong>Save</strong> to save your changes. + </li> +</ol> + +<div style="padding-top:1em"> + <img style="border:2px solid #ddd;" src="{@docRoot}images/gp-tv-opt-in.png"> + <p class="caption"> + <strong>Opt-in for TV:</strong> Include your app in Android TV by opting-in from the + Developer Console. + </p> +</div> + +<h3 id="track_review">5. Track your review and approval</h3> + +<p> + If your app meets the technical and quality criteria for Android TV, as described above, + your app will be available for users to enjoy on Android TV. If your app doesn’t meet + the criteria, you’ll receive a <strong>notification email sent to your developer account + address</strong>, with a summary of the areas that you need to address. When you’ve made + the necessary adjustments, you can upload a new version of your app to the Developer + Console. +</p> + +<p> + At any time, you can check the review and approval status of your app in the + Developer Console, under <em>Android TV</em> in the app's <strong>Pricing and Distribution</strong> + page. +</p> + +<p> + There are three approval states: +</p> + +<ul> + <li> + <em>Pending</em> — Your app was sent for review and the review is not yet + complete. + </li> + + <li> + <em>Approved</em> — Your app was reviewed and approved. The app will be + made available directly to Android TV users. + </li> + + <li> + <em>Not approved</em> — Your app was reviewed and not approved. Check the + notification email for information about why the app was not approved. You + can address any issues and opt-in and publish again to initiate another + review. + </li> +</ul> + +<p>To understand how your apps are evaluated, please see the <a href= +"{@docRoot}distribute/essentials/quality/tv.html">TV App Quality</a> document. </p> + + + <h3>Related resources</h3> + + <div class="resource-widget resource-flow-layout col-16" + data-query="collection:tvlanding" + data-cardSizes="9x6, 6x3x2" + data-maxResults="6"> + </div> diff --git a/docs/html/distribute/tools/promote/badges.jd b/docs/html/distribute/tools/promote/badges.jd index 4bea8be..eb09333 100644 --- a/docs/html/distribute/tools/promote/badges.jd +++ b/docs/html/distribute/tools/promote/badges.jd @@ -66,7 +66,7 @@ div.button-row input { var APP_LANGS = ['it','pt-br','pt-pt','nl','ko','ja','fr','es','es-419','en','de']; // variables for creating 'try it out' demo button -var imagePath = "{@docRoot}images/brand/" +var imagePath = "https://developer.android.com/images/brand/" var linkStart = "<a href=\"https://play.google.com/store/"; var imageStart = "\">\n" + " <img alt=\""; @@ -99,7 +99,7 @@ function buildButton(form) { $("#button-preview").html(linkStart + "apps/details?id=" + packageName + imageStart + altText + imageSrc + selectedValue + imageEnd); - + // Send the event to Analytics ga('send', 'event', 'Distribute', 'Create Google Play Badge', 'Package ' + selectedValue); } else if (form["publisher"].value != "Example, Inc.") { @@ -111,7 +111,7 @@ function buildButton(form) { $("#button-preview").html(linkStart + "search?q=pub:" + publisherName + imageStart + altText + imageSrc + selectedValue + imageEnd); - + // Send the event to Analytics ga('send', 'event', 'Distribute', 'Create Google Play Badge', 'Publisher ' + selectedValue); } else { @@ -159,7 +159,7 @@ function clearLabel(id, example) { /** Switch the badge urls for selected language */ function changeBadgeLang() { var lang = $('#locale option:selected').val(); - + // check if we have the 'app' badge for this lang and show notice if not $("div.button-row.error").remove(); // remove any existing instance of error message if ($.inArray(lang,APP_LANGS) == -1) { @@ -173,7 +173,7 @@ function changeBadgeLang() { } else { $("div.button-row.app").show(); // show the 'app' badge row } - + $('.button-row img').each(function() { var id = $(this).parent().attr('for'); var imgName = lang + $('input#'+id).attr('value') + '.png'; @@ -356,7 +356,7 @@ alt="Get it on Google Play (large)" /></label> style="font-family:monospace;background-color:#efefef;padding:5px;display:none;margin-bottom:1em"> </textarea > -<p>Try it out:</p> +<p>Test your badge:</p> <div id="button-preview" style="margin-top:1em"></div> </div> diff --git a/docs/html/google/gcm/adv.jd b/docs/html/google/gcm/adv.jd index 245467f..95497e3 100644 --- a/docs/html/google/gcm/adv.jd +++ b/docs/html/google/gcm/adv.jd @@ -261,7 +261,7 @@ is either a "send-to-sync" (collapsible) message or a "message wi payload" (non-collapsible message). These concepts are described in more detail in the following sections.</p> -<h3 id="s2s"><strong>Send-to-sync messages</strong></h3> +<h3 id="s2s">Send-to-sync messages</h3> <p>A send-to-sync (collapsible) message is often a "tickle" that tells a mobile application to sync data from the server. For example, suppose you have @@ -288,6 +288,7 @@ and B4, and so on. If you exceed this number GCM will only keep 4 collapse keys, guarantees about which ones they will be.</p> <h3 id="payload">Messages with payload</h3> + <p>Unlike a send-to-sync message, every "message with payload" (non-collapsible message) is delivered. The payload the message contains can be up to 4kb. For example, here is a JSON-formatted message in an IM application in diff --git a/docs/html/google/gcm/ccs.jd b/docs/html/google/gcm/ccs.jd index 2faf97f..7db7a74 100644 --- a/docs/html/google/gcm/ccs.jd +++ b/docs/html/google/gcm/ccs.jd @@ -21,7 +21,7 @@ page.title=GCM Cloud Connection Server (XMPP) </li> <li><a href="#upstream">Upstream Messages</a> <ol> - <li><a href="#receipts">Receive return receipts</a></li> + <li><a href="#receipts">Receive delivery receipts</a></li> </ol> </li> <li><a href="#flow">Flow Control</a> </li> @@ -45,11 +45,15 @@ page.title=GCM Cloud Connection Server (XMPP) </div> </div> -<p>The GCM Cloud Connection Server (CCS) is an XMPP endpoint that provides a +<p>The Google Cloud Messaging (GCM) Cloud Connection Server (CCS) is an XMPP endpoint that provides a persistent, asynchronous, bidirectional connection to Google servers. The connection can be used to send and receive messages between your server and your users' GCM-connected devices.</p> +<p class="note"><strong>Note:</strong> The content in this document +applies to <a href="http://developer.chrome.com/apps/cloudMessaging"> +GCM with Chrome apps</a> as well as Android. + <p>You can continue to use the HTTP request mechanism to send messages to GCM servers, side-by-side with CCS which uses XMPP. Some of the benefits of CCS include:</p> @@ -259,22 +263,6 @@ message is "nack". A NACK message contains:</p> </message> </pre> -<p>Quota exceeded:</p> - -<pre><message> - <gcm xmlns="google:mobile:data"> - { - "message_type":"nack", - "message_id":"msgId1", - "from":"APA91bHFOtaQGSwupt5l1og", - "error":"QUOTA_EXCEEDED", - "error_description":"Short-term downstream quota exceeded for this registration id" - } - </gcm> -</message> -</pre> - - <p>The following table lists NACK error codes. Unless otherwise indicated, a NACKed message should not be retried. Unexpected NACK error codes should be treated the same as {@code INTERNAL_SERVER_ERROR}.</p> @@ -312,11 +300,11 @@ message should be immediately retried over another connection.</td> <td>{@code INVALID_JSON}</td> <td>The JSON message payload is not valid.</td> </tr> -<tr> -<td>{@code QUOTA_EXCEEDED}</td> -<td>The rate of messages to a particular registration ID (in other words, to a -sender/device pair) is too high. If you want to retry the message, try using a slower -rate.</td> +<td>{@code DEVICE_MESSAGE_RATE_EXCEEDED}</td> +<td>The rate of messages to a particular device is too high. You should reduce +the number of messages sent to this device and should not immediately retry +sending to this device. This error code replaces {@code QUOTA_EXCEEDED}, +which has been deprecated.</td> </tr> <tr> <td>{@code SERVICE_UNAVAILABLE}</td> @@ -429,15 +417,17 @@ response to the above message:</p> </gcm> </message></pre> -<h3 id="receipts">Receive return receipts</h3> +<h3 id="receipts">Receive delivery receipts</h3> -<p>You can use upstream messaging to get receipt notifications, confirming -that a given message was sent to a device. Your 3rd-party app server receives the receipt -notification from CCS once the message has been sent to the device.</p> +<p>You can use upstream messaging to get delivery receipts (sent from CCS to +your 3rd party app server) when +a device confirms that it received a message sent by CCS.</p> <p>To enable this feature, the message your 3rd-party app server sends to CCS must include a field called <code>"delivery_receipt_requested"</code>. When this field is set to -<code>true</code>, CCS sends a return receipt. Here is an XMPP stanza containing a JSON +<code>true</code>, CCS sends a delivery receipt when a device confirms that it received a particular message.</p> + +<p>Here is an XMPP stanza containing a JSON message with <code>"delivery_receipt_requested"</code> set to <code>true</code>:</p> <pre><message id=""> @@ -457,8 +447,10 @@ message with <code>"delivery_receipt_requested"</code> set to <code>tr </message> </pre> -<p>Here is an example of a receipt notification message that CCS sends back to your 3rd-party -app server:</p> + + +<p>Here is an example of the delivery receipt that CCS sends to tell your 3rd-party +app server that a device received a message that CCS sent it:</p> </p> <pre><message id=""> @@ -483,12 +475,12 @@ app server:</p> <ul> <li>The {@code "message_type"} is set to {@code "receipt"}. <li>The {@code "message_status"} is set to {@code "MESSAGE_SENT_TO_DEVICE"}, - indicating that the message was delivered. Notice that in this case, + indicating that the device received the message. Notice that in this case, {@code "message_status"} is not a field but rather part of the data payload.</li> <li>The receipt message ID consists of the original message ID, but with a -<code>dr:</code> prefix. Your 3rd-party app server must send an ACK back with this ID, +<code>dr2:</code> prefix. Your 3rd-party app server must send an ACK back with this ID, which in this example is {@code dr2:m-1366082849205}.</li> - <li>The original message ID and status are inside the + <li>The original message ID, the device registration ID, and the status are inside the {@code "data"} field.</li> </ul> diff --git a/docs/html/google/gcm/client.jd b/docs/html/google/gcm/client.jd index 20bff10..70109c6 100644 --- a/docs/html/google/gcm/client.jd +++ b/docs/html/google/gcm/client.jd @@ -34,14 +34,14 @@ page.tags=cloud,push,messaging </div> </div> -<p>A GCM client is a GCM-enabled app that runs on an Android device. To write your -client code, we recommend that you use the -<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> -{@code GoogleCloudMessaging}</a> APIs. +<p>A Google Cloud Messaging (GCM) client is a GCM-enabled app that runs on an +Android device. To write your client code, we recommend that you use the +<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html"> +GCM APIs</a>. The client helper library that was offered in previous versions of GCM still works, but it has been superseded by the more efficient -<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> -{@code GoogleCloudMessaging}</a> APIs.</p> +<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html"> +GCM APIs</a>.</p> <p>A full GCM implementation requires both a client implementation and a server implementation. For more @@ -57,8 +57,8 @@ registration ID), and a broadcast receiver to receive messages sent by GCM. <h2 id="play-services">Step 1: Set Up Google Play Services</h2> <p>To write your client application, use the -<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> -{@code GoogleCloudMessaging}</a> API. +<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html"> +GCM APIs</a>. To use this API, you must set up your project to use the Google Play services SDK, as described in <a href="/google/play-services/setup.html">Setup Google Play Services SDK</a>.</p> @@ -159,7 +159,7 @@ could not run properly. </li> <p>Finally, write your application. This section features a sample client application that illustrates how to use the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> -{@code GoogleCloudMessaging}</a> APIs. The sample consists of a main activity +{@code GoogleCloudMessaging}</a> API. The sample consists of a main activity ({@code DemoActivity}), a {@link android.support.v4.content.WakefulBroadcastReceiver} ({@code GcmBroadcastReceiver}), and an {@link android.app.IntentService} ({@code GcmIntentService}). You can find the complete source code for this sample at the @@ -456,7 +456,7 @@ private void storeRegistrationId(Context context, String regId) { <p>When the user clicks the app's <strong>Send</strong> button, the app sends an upstream message using the <a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> -{@code GoogleCloudMessaging}</a> APIs. In order to receive the upstream message, +{@code GoogleCloudMessaging}</a> API. In order to receive the upstream message, your server should be connected to CCS. You can use one of the demo servers in <a href="ccs.html#implement">Implementing an XMPP-based App Server</a> to run the sample and connect to CCS.</p> @@ -652,7 +652,7 @@ your sender ID and API key. <p>To view statistics and any error messages for your GCM applications:</p> <ol> - <li> Go to the <code><a href="http://play.google.com/apps/publish">Developer Console</a></code>.</li> + <li> Go to the <a href="http://play.google.com/apps/publish">Developer Console</a>.</li> <li>Login with your developer account. <p>You will see a page that has a list of all of your apps.</p></li> <li> Click on the "statistics" link next to the app for which you diff --git a/docs/html/google/gcm/gcm.jd b/docs/html/google/gcm/gcm.jd index 19151b9..3d6594d 100644 --- a/docs/html/google/gcm/gcm.jd +++ b/docs/html/google/gcm/gcm.jd @@ -21,7 +21,7 @@ page.title=Overview </div> </div> -<p>Google Cloud Messaging for Android (GCM) is a free service that helps +<p>Google Cloud Messaging (GCM) for Android is a free service that helps developers send data from servers to their Android applications on Android devices, and upstream messages from the user's device back to the cloud. This could be a lightweight message telling the Android application diff --git a/docs/html/google/gcm/gs.jd b/docs/html/google/gcm/gs.jd index ae57b6d..a889624 100644 --- a/docs/html/google/gcm/gs.jd +++ b/docs/html/google/gcm/gs.jd @@ -25,12 +25,12 @@ page.tags=cloud,push,messaging </div> </div> -<p>This document tells you how to get started setting up a GCM -implementation. +<p>This document tells you how to get started setting up a Google Cloud Messaging +(GCM) implementation. Before you begin, make sure to <a href="/google/play-services/setup.html">set up the Google Play Services SDK</a>. You need this SDK to use the -<a href="{@docRoot}reference/com/google/android/gms/gcm/GoogleCloudMessaging.html"> -{@code GoogleCloudMessaging}</a> methods.</p> +<a href="{@docRoot}reference/com/google/android/gms/gcm/package-summary.html"> +GCM APIs</a>.</p> <h2 id="create-proj">Creating a Google API project</h2> <p>To create a Google API project:</p> diff --git a/docs/html/google/gcm/http.jd b/docs/html/google/gcm/http.jd index b8d8659..773acd1 100644 --- a/docs/html/google/gcm/http.jd +++ b/docs/html/google/gcm/http.jd @@ -33,13 +33,16 @@ page.title=GCM HTTP Connection Server </div> </div> -<p>This document describes the GCM HTTP connection server. Connection servers +<p>This document describes the Google Cloud Messaging (GCM) HTTP +connection server. Connection servers are the Google-provided servers that take messages from the 3rd-party application server and sending them to the device.</p> +<p class="note"><strong>Note:</strong> The content in this document +applies to <a href="http://developer.chrome.com/apps/cloudMessaging"> +GCM with Chrome apps</a> as well as Android.</p> - -<p class="note"><strong>Note:</strong> See +<p>See <a href="server.html#params">Implementing GCM Server</a> for a list of all the message parameters and which connection server(s) supports them.</p> @@ -163,7 +166,7 @@ before the request can be retried.</td> </tr> <tr> <td>5xx</td> - <td>Errors in the 500-599 range (such as 500 or 503) indicate that there wa + <td>Errors in the 500-599 range (such as 500 or 503) indicate that there was an internal error in the GCM server while trying to process the request, or that the server is temporarily unavailable (for example, because of timeouts). Sender must retry later, honoring any <code>Retry-After</code> header included in the @@ -416,6 +419,12 @@ A message was addressed to a registration ID whose package name did not match the value passed in the request. Happens when error code is <code>InvalidPackageName</code>. </dd> + +<dt id="big_msg"><strong>Device Message Rate Exceeded</strong></dt> + <dd>The rate of messages to a particular device is too high. You should reduce the number +of messages sent to this device and should not retry sending to this device immediately. +<br/>Happens when error code is <code>DeviceMessageRateExceeded</code>.</dd> + </dl> <h3 id="example-responses">Example responses</h3> diff --git a/docs/html/google/gcm/index.jd b/docs/html/google/gcm/index.jd index 56e0865..af5d741 100644 --- a/docs/html/google/gcm/index.jd +++ b/docs/html/google/gcm/index.jd @@ -13,11 +13,11 @@ header.hide=1 <h1 itemprop="name" style="margin-bottom:0;">Google Cloud Messaging for Android</h1> <p itemprop="description"> - Google Cloud Messaging for Android (GCM) is a service that allows you to send data + Google Cloud Messaging (GCM) for Android is a service that allows you to send data from your server to your users' Android-powered device, and also to receive messages from devices on the same connection. The GCM service handles all aspects of queueing of messages -and delivery to the target Android application running on the target device. GCM is -completely free no matter how big your messaging needs are, and there are no quotas. +and delivery to the target Android application running on the target device, and it is +completely free. </p> </div> diff --git a/docs/html/google/gcm/notifications.jd b/docs/html/google/gcm/notifications.jd index 2815f3d..147b69c 100644 --- a/docs/html/google/gcm/notifications.jd +++ b/docs/html/google/gcm/notifications.jd @@ -83,7 +83,7 @@ message body is JSON.</p> <h2 id="gen-server">Generate a Notification Key on the Server</h2> <p>To generate a notification key on the server, you create a new -create a new <code>notification_key</code> and map it to a +<code>notification_key</code> and map it to a <code>notification_key_name</code>.</p> <p>This example shows how to create a new <code>notification_key</code> for a @@ -268,7 +268,7 @@ notification key operations.</p> <p>When you make a request to create a {@code notification_key} or to add/remove its regIDs, a successful response always returns the <code>notification_key</code>. -his is the {@code notification_key} you will use for sending messages:</p> +Use the returned {@code notification_key} for sending messages:</p> <pre>HTTP status: 200 { diff --git a/docs/html/google/gcm/server.jd b/docs/html/google/gcm/server.jd index e3a6b25..20e2b2e 100644 --- a/docs/html/google/gcm/server.jd +++ b/docs/html/google/gcm/server.jd @@ -37,7 +37,7 @@ page.title=Implementing GCM Server </div> -<p>The server side of GCM consists of 2 components:</p> +<p>The server side of Google Cloud Messaging (GCM) consists of 2 components:</p> <ul> <li>Google-provided <strong>GCM Connection Servers</strong> take messages from a 3rd-party application server and send them to a GCM-enabled @@ -168,36 +168,37 @@ column for information about which connection servers support that particular parameter.</p> <p class="table-caption" id="table1"> - <strong>Table 1.</strong> Message parameters.</p> + <strong>Table 1.</strong> Message Parameters JSON (CCS and HTTP).</p> <table> <tr> - <th>Field</th> + <th>Parameter</th> <th>Description</th> <th>Where Supported</th> </tr> <td><code>to</code></td> -<td>In CCS, used in place of <code>registration_ids</code> to specify the -recipient of a message. Its value must be a registration ID. +<td>In CCS, this parameter is used in place of <code>registration_ids</code> to +specify the recipient of a message. Its value must be a registration ID. The value is a string. Required.</td> <td>CCS</td> </tr> <tr> <td><code>message_id</code></td> -<td>In CCS, uniquely identifies a message in an XMPP connection. The value is a -string that uniquely identifies the associated message. The value is a string. Required.</td> +<td>In CCS, this parameter uniquely identifies a message in an XMPP connection. +The value is a string that uniquely identifies the associated message. Required.</td> <td>CCS</td> </tr> <tr> <td><code>message_type</code></td> -<td>In CCS, indicates a special status message, typically sent by the system. +<td>In CCS, this parameter indicates a special status message, typically sent by the system. However, your app server also uses this parameter to send an 'ack' or 'nack' message back to the CCS connection server. For more discussion of this topic, see <a href="ccs.html">Cloud Connection Server</a>. The value is a string. Optional.</td> <td>CCS</td> <tr> <td><code>registration_ids</code></td> - <td>A string array with the list of devices (registration IDs) receiving the + <td>This parameter specifies a string array containing the list of devices +(registration IDs) receiving the message. It must contain at least 1 and at most 1000 registration IDs. To send a multicast message, you must use JSON. For sending a single message to a single device, you could use a JSON object with just 1 registration id, or plain text @@ -208,12 +209,13 @@ Required.</td> </tr> <tr> <td><code>notification_key</code></td> - <td>A string that maps a single user to multiple registration IDs associated + <td>This parameter specifies a string that maps a single user to multiple +registration IDs associated with that user. This allows a 3rd-party server to send a single message to multiple app instances (typically on multiple devices) owned by a single user. A 3rd-party server can use {@code notification_key} as the target for a message instead of an individual registration ID (or array of registration IDs). The maximum -number of members allowed for a {@code notification_key} is 10. For more discussion +number of members allowed for a {@code notification_key} is 20. For more discussion of this topic, see <a href="notifications.html">User Notifications</a>. Optional. </td> <td style="width:100px">HTTP. This feature is supported in CCS, but you use it by @@ -221,13 +223,14 @@ specifying a notification key in the "to" field.</td> </tr> <tr> <td><code>collapse_key</code></td> - <td>An arbitrary string (such as "Updates Available") that is used + <td>This parameter specifies an arbitrary string (such as +"Updates Available") that is used to collapse a group of like messages when the device is offline, so that only the last message gets sent to the client. This is intended to avoid sending too many messages to the phone when it comes back online. Note that since there is no guarantee of the order in which messages get sent, the "last" message may not actually be the last -message sent by the application server. Collapse keys are also called +message sent by the application server. Messages with collapse keys are also called <a href="#s2s">send-to-sync messages</a>. <br> <strong>Note:</strong> GCM allows a maximum of 4 different collapse keys to be @@ -242,8 +245,9 @@ discussion of this topic. Optional.</td> </tr> <tr> <td><code>data</code></td> - <td>A JSON object whose fields represents the key-value pairs of the message's -payload data. If present, the payload data it will be + <td>This parameter specifies a JSON object whose fields represents the +key-value pairs of the message's +payload data. If present, the payload data will be included in the Intent as application data, with the key being the extra's name. For instance, <code>"data":{"score":"3x1"}</code> would result in an intent extra named <code>score</code> whose value is the string <code>3x1</code>. @@ -253,17 +257,14 @@ recommend using strings, since the values will be converted to strings in the GC server anyway. If you want to include objects or other non-string data types (such as integers or booleans), you have to do the conversion to string yourself. Also note that the key cannot be a reserved word (<code>from</code> or any word -starting with <code>google.</code>). To complicate things slightly, there are -some reserved words (such as <code>collapse_key</code>) that are technically -allowed in payload data. However, if the request also contains the word, the -value in the request will overwrite the value in the payload data. Hence using -words that are defined as field names in this table is not recommended, even in -cases where they are technically allowed. Optional.</td> +starting with <code>google.</code>). Using words defined in this table as field +names (such as <code>collapse_key</code>) could yield unpredictable outcomes and +is not recommended. Optional.</td> <td>CCS, HTTP</td> </tr> <tr> <td><code>delay_while_idle</code></td> - <td>If included, indicates that the message should not be sent immediately + <td>This parameter indicates that the message should not be sent immediately if the device is idle. The server will wait for the device to become active, and then only the last message for each <code>collapse_key</code> value will be sent. The default value is <code>false</code>, and must be a JSON boolean. Optional.</td> @@ -271,26 +272,70 @@ sent. The default value is <code>false</code>, and must be a JSON boolean. Optio </tr> <tr> <td><code>time_to_live</code></td> - <td>How long (in seconds) the message should be kept on GCM storage if the -device is offline. Optional (default time-to-live is 4 weeks, and must be set as + <td>This parameter specifies how long (in seconds) the message should be kept on GCM +storage if the device is offline. Optional (default time-to-live is 4 weeks, and must be set as a JSON number).</td> <td>CCS, HTTP</td> </tr> <tr> <td><code>restricted_package_name</code></td> - <td>A string containing the package name of your application. When set, messages -will only be sent to registration IDs that match the package name. Optional. + <td>This parameter specifies a string containing the package +name of your application. When set, messages +are only sent to registration IDs that match the package name. Optional. </td> <td>HTTP</td> </tr> <tr> <td><code>dry_run</code></td> - <td>If included, allows developers to test their request without actually + <td>This parameter allows developers to test a request without actually sending a message. Optional. The default value is <code>false</code>, and must be a JSON boolean. </td> <td>HTTP</td> </tr> +<tr> + <td><code>delivery_receipt_requested</code></td> + <td>This parameter lets you request confirmation of message delivery. When +this parameter is set to <code>true</code>, CCS sends a +delivery receipt when a device confirms that it received a message sent by CCS. +The default value is <code>false</code>, and must be a JSON boolean. Optional.<br /> +This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> +delivery receipts</a>. +</td> + <td>CCS</td> +</tr> +<tr> + <td><code>message_status</code></td> + <td>This parameter specifies the status of the receipt message. +The parameter appears inside the +<code>"data"</code> field of a +delivery receipt message. Currently the only possible value +is <code>MESSAGE_SENT_TO_DEVICE</code>, which indicates that a device acknowledges +receiving a message sent by CCS.<br /> +This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> +delivery receipts</a>.</td> + <td>CCS</td> +</tr> +<tr> + <td><code>original_message_id</code></td> + <td>The value of this parameter is the ID of the original message that the server sent to +the device. This parameter appears inside the <code>"data"</code> field of a +delivery receipt message. <br /> +This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> +delivery receipts</a>.</td> + <td>CCS</td> +</tr> +<tr> + <td><code>device_registration_id</code></td> + <td>For the purpose of tracking the delivery receipt, this parameter lists +the registration ID of the device to which a given message was sent. This parameter +appears inside the <code>"data"</code> field of a +delivery receipt message. <br /> +This parameter relates to <a href="{@docRoot}google/gcm/ccs.html#receipts"}> +delivery receipts</a>.</td> + <td>CCS</td> +</tr> + </table> <p>If you want to test your request (either JSON or plain text) without delivering @@ -298,21 +343,23 @@ the message to the devices, you can set an optional HTTP or JSON parameter calle <code>dry_run</code> with the value <code>true</code>. The result will be almost identical to running the request without this parameter, except that the message will not be delivered to the devices. Consequently, the response will contain fake -IDs for the message and multicast fields.</p> - -<h3 id="plain-text">Plain text (HTTP only)</h3> +IDs for the message and multicast parameters.</p> -<p>If you are using plain text instead of JSON, the message fields must be set as +<p>If you are using plain text instead of JSON, the message parameters must be set as HTTP parameters sent in the body, and their syntax is slightly different, as -described below: +described in the following table: + +<p class="table-caption" id="table2"> + <strong>Table 2.</strong> Message Parameters Plain Text (HTTP only).</p> <table> <tr> - <th>Field</th> + <th>Parameter</th> <th>Description</th> </tr> <tr> <td><code>registration_id</code></td> - <td>Must contain the registration ID of the single device receiving the message. + <td>This parameter specifies the registration ID of the single device +receiving the message. Required.</td> </tr> <tr> @@ -322,24 +369,23 @@ Required.</td> <tr> <td><code>data.<key></code></td> - <td>Payload data, expressed as parameters prefixed with <code>data.</code> and + <td>This parameter specifies payload data, expressed as parameters +prefixed with <code>data.</code> and suffixed as the key. For instance, a parameter of <code>data.score=3x1</code> would result in an intent extra named <code>score</code> whose value is the string <code>3x1</code>. There is no limit on the number of key/value parameters, though there is a limit on the total size of the message. Also note that the key cannot be a reserved word (<code>from</code> or any word starting with -<code>google.</code>). To complicate things slightly, there are some reserved words -(such as <code>collapse_key</code>) that are technically allowed in payload data. -However, if the request also contains the word, the value in the request will -overwrite the value in the payload data. Hence using words that are defined as -field names in this table is not recommended, even in cases where they are -technically allowed. Optional.</td> +<code>google.</code>). Using words defined in this table as field +names (such as <code>collapse_key</code>) could yield unpredictable outcomes and +is not recommended. Optional.</td> </tr> <tr> <td><code>delay_while_idle</code></td> - <td>Should be represented as <code>1</code> or <code>true</code> for -<code>true</code>, anything else for <code>false</code>. Optional. The default + <td>This parameter specifies whether messages should be delivered when the device +is asleep. A value of <code>1</code> or <code>true</code> indicates +<code>true</code>, and anything else indicates <code>false</code>. Optional. The default value is <code>false</code>.</td> </tr> <tr> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index ade05c9..7374a67 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -9,6 +9,7 @@ parent.link=manifest-intro.html android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"] android:<a href="#autoremrecents">autoRemoveFromRecents</a>=["true" | "false"] + android:<a href="#banner">banner</a>="<i>drawable resource</i>" android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"] android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale", "touchscreen", "keyboard", "keyboardHidden", @@ -153,6 +154,29 @@ automatically removed from the overview screen. This overrides the caller's use "{@code true}" or "{@code false}".</dd> +<dt><a name="banner"></a>{@code android:banner}</dt> +<dd>A <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> +providing an extended graphical banner for its associated item. Use with the +{@code <activity>} tag to supply a default banner for a specific activity, or with the +<a href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> +tag to supply a banner for all application activities. + +<p>The system uses the banner to represent an app in +the Android TV home screen. Since the banner is displayed only in the home screen, it +should only be specified by applications with an activity that handles the +{@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent.</p> + +<p>This attribute must be set as a reference to a drawable resource containing +the image (for example {@code "@drawable/banner"}). There is no default banner. +</p> + +<p> +See <a href="{@docRoot}design/tv/patterns.html#banner"> +Banners</a> in the UI Patterns for TV design guide, and <a href="{@docRoot}training/tv/start/start.html#banner"> +Provide a home screen banner</a> in Get Started with TV Apps for more information. +</p></dd> + + <dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt> <dd>Whether or not all activities will be removed from the task, except for the root activity, whenever it is re-launched from the home screen — diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 33f6bce..8a0e837 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -7,12 +7,14 @@ page.title=<application> <dd><pre class="stx"><application android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] android:<a href="#allowbackup">allowBackup</a>=["true" | "false"] android:<a href="#agent">backupAgent</a>="<i>string</i>" + android:<a href="#banner">banner</a>="<i>drawable resource</i>" android:<a href="#debug">debuggable</a>=["true" | "false"] android:<a href="#desc">description</a>="<i>string resource</i>" android:<a href="#enabled">enabled</a>=["true" | "false"] android:<a href="#code">hasCode</a>=["true" | "false"] android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"] android:<a href="#icon">icon</a>="<i>drawable resource</i>" + android:<a href="#isGame">isGame</a>=["true" | "false"] android:<a href="#killrst">killAfterRestore</a>=["true" | "false"] android:<a href="#largeHeap">largeHeap</a>=["true" | "false"] android:<a href="#label">label</a>="<i>string resource</i>" @@ -48,13 +50,13 @@ page.title=<application> <dt>description:</dt> <dd itemprop="description">The declaration of the application. This element contains subelements -that declare each of the application's components and has attributes -that can affect all the components. Many of these attributes (such as -{@code icon}, {@code label}, {@code permission}, {@code process}, -{@code taskAffinity}, and {@code allowTaskReparenting}) set default values +that declare each of the application's components and has attributes +that can affect all the components. Many of these attributes (such as +{@code icon}, {@code label}, {@code permission}, {@code process}, +{@code taskAffinity}, and {@code allowTaskReparenting}) set default values for corresponding attributes of the component elements. Others (such as -{@code debuggable}, {@code enabled}, {@code description}, and -{@code allowClearUserData}) set values for the application as a whole and +{@code debuggable}, {@code enabled}, {@code description}, and +{@code allowClearUserData}) set values for the application as a whole and cannot be overridden by the components.</dd> @@ -65,18 +67,18 @@ cannot be overridden by the components.</dd> <dd><dl class="attr"> <dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> -<dd>Whether or not activities that the application defines can move from -the task that started them to the task they have an affinity for when that task -is next brought to the front — {@code "true"} if they can move, and -{@code "false"} if they must remain with the task where they started. +<dd>Whether or not activities that the application defines can move from +the task that started them to the task they have an affinity for when that task +is next brought to the front — {@code "true"} if they can move, and +{@code "false"} if they must remain with the task where they started. The default value is {@code "false"}. <p> -The -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element has its own +The +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +element has its own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -attribute that can override the value set here. See that attribute for more +attribute that can override the value set here. See that attribute for more information. </p></dd> @@ -92,46 +94,68 @@ The default value of this attribute is true.</dd> <dt><a name="agent"></a>{@code android:backupAgent}</dt> <dd>The name of the class that implement's the application's backup agent, a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be -a fully qualified class name (such as, {@code "com.example.project.MyBackupAgent"}). -However, as a shorthand, if the first character of the name is a period -(for example, {@code ".MyBackupAgent"}), it is appended to the -package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> +a fully qualified class name (such as, {@code "com.example.project.MyBackupAgent"}). +However, as a shorthand, if the first character of the name is a period +(for example, {@code ".MyBackupAgent"}), it is appended to the +package name specified in the +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p> There is no default. The name must be specified. </p></dd> +<dt><a name="banner"></a>{@code android:banner}</dt> +<dd>A <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> +providing an extended graphical banner for its associated item. Use with the +{@code <application>} tag to supply a default banner for all application activities, or with the +<a href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> +tag to supply a banner for a specific activity. + +<p>The system uses the banner to represent an app in +the Android TV home screen. Since the banner is displayed only in the home screen, it +should only be specified by applications with an activity that handles the +{@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent.</p> + +<p>This attribute must be set as a reference to a drawable resource containing +the image (for example {@code "@drawable/banner"}). There is no default banner. +</p> + +<p> +See <a href="{@docRoot}design/tv/patterns.html#banner"> +Banners</a> in the UI Patterns for TV design guide, and <a href="{@docRoot}training/tv/start/start.html#banner"> +Provide a home screen banner</a> in Get Started with TV Apps for more information. +</p></dd> + <dt><a name="debug"></a>{@code android:debuggable}</dt> -<dd>Whether or not the application can be debugged, even when running +<dd>Whether or not the application can be debugged, even when running on a device in user mode — {@code "true"} if it can be, and {@code "false"} -if not. The default value is {@code "false"}.</dd> +if not. The default value is {@code "false"}.</dd> <dt><a name="desc"></a>{@code android:description}</dt> <dd>User-readable text about the application, longer and more descriptive than the application label. The value must be set as a reference to a string resource. Unlike the label, it cannot be a raw string. There is no default value.</dd> <dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the Android system can instantiate components of -the application — {@code "true"} if it can, and {@code "false"} -if not. If the value is {@code "true"}, each component's -{@code enabled} attribute determines whether that component is enabled -or not. If the value is {@code "false"}, it overrides the +<dd>Whether or not the Android system can instantiate components of +the application — {@code "true"} if it can, and {@code "false"} +if not. If the value is {@code "true"}, each component's +{@code enabled} attribute determines whether that component is enabled +or not. If the value is {@code "false"}, it overrides the component-specific values; all components are disabled. <p> The default value is {@code "true"}. -</p></dd> +</p></dd> <dt><a name="code"></a>{@code android:hasCode}</dt> -<dd>Whether or not the application contains any code — {@code "true"} -if it does, and {@code "false"} if not. When the value is {@code "false"}, -the system does not try to load any application code when launching components. +<dd>Whether or not the application contains any code — {@code "true"} +if it does, and {@code "false"} if not. When the value is {@code "false"}, +the system does not try to load any application code when launching components. The default value is {@code "true"}. <p> An application would not have any code of its own only if it's using nothing -but built-in component classes, such as an activity that uses the {@link +but built-in component classes, such as an activity that uses the {@link android.app.AliasActivity} class, a rare occurrence.</p> </dd> @@ -140,7 +164,7 @@ android.app.AliasActivity} class, a rare occurrence.</p> activities and views in this application — {@code "true"} if it should be enabled, and {@code "false"} if not. The default value is {@code "true"} if you've set either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> -or <a +or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to {@code "14"} or higher; otherwise, it's {@code "false"}. @@ -161,20 +185,26 @@ make use of the renderer without errors.</p> </dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon for the application as whole, and the default icon for -each of the application's components. See the individual -{@code icon} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +<dd>An icon for the application as whole, and the default icon for +each of the application's components. See the individual +{@code icon} attributes for +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. <p> This attribute must be set as a reference to a drawable resource containing -the image (for example {@code "@drawable/icon"}). There is no default icon. +the image (for example {@code "@drawable/icon"}). There is no default icon. </p></dd> +<dt><a name="isGame"></a>{@code android:isGame}</dt> +<dd>Whether or not the application is a game. The system may group together applications classifed +as games or display them separately from other applications. + +<p>The default is {@code false}.</p></dd> + <dt><a name="killrst"></a>{@code android:killAfterRestore}</dt> <dd>Whether the application in question should be terminated after its settings have been restored during a full-system restore operation. @@ -202,65 +232,65 @@ because some devices are constrained by their total available memory.</p> </dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the application as a whole, and a default -label for each of the application's components. See the individual -{@code label} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +<dd>A user-readable label for the application as a whole, and a default +label for each of the application's components. See the individual +{@code label} attributes for +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> <dt><a name="logo"></a>{@code android:logo}</dt> <dd>A logo for the application as whole, and the default logo for activities. <p>This attribute must be set as a reference to a drawable resource containing -the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> +the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> <dt><a name="space"></a>{@code android:manageSpaceActivity}</dt> -<dd>The fully qualified name of an Activity subclass that the system -can launch to let users manage the memory occupied by the application -on the device. The activity should also be declared with an +<dd>The fully qualified name of an Activity subclass that the system +can launch to let users manage the memory occupied by the application +on the device. The activity should also be declared with an <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element. </dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The fully qualified name of an {@link android.app.Application} -subclass implemented for the application. When the application process -is started, this class is instantiated before any of the application's -components. +<dd>The fully qualified name of an {@link android.app.Application} +subclass implemented for the application. When the application process +is started, this class is instantiated before any of the application's +components. <p> The subclass is optional; most applications won't need one. -In the absence of a subclass, Android uses an instance of the base +In the absence of a subclass, Android uses an instance of the base Application class. </p></dd> <dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have in order to interact -with the application. This attribute is a convenient way to set a -permission that applies to all of the application's components. It can -be overwritten by setting the {@code permission} attributes of individual +<dd>The name of a permission that clients must have in order to interact +with the application. This attribute is a convenient way to set a +permission that applies to all of the application's components. It can +be overwritten by setting the {@code permission} attributes of individual components. <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and another document, +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> +section in the introduction and another document, <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. </p></dd> <dt><a name="persistent"></a>{@code android:persistent}</dt> -<dd>Whether or not the application should remain running at all times — -{@code "true"} if it should, and {@code "false"} if not. The default value -is {@code "false"}. Applications should not normally set this flag; +<dd>Whether or not the application should remain running at all times — +{@code "true"} if it should, and {@code "false"} if not. The default value +is {@code "false"}. Applications should not normally set this flag; persistence mode is intended only for certain system applications.</dd> <dt><a name="proc"></a>{@code android:process}</dt> @@ -282,9 +312,9 @@ user ID and be signed with the same certificate. </p> <p> -If the name assigned to this attribute begins with a colon (':'), a new +If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is created when it's needed. -If the process name begins with a lowercase character, a global process +If the process name begins with a lowercase character, a global process of that name is created. A global process can be shared with other applications, reducing resource usage. </p></dd> @@ -307,7 +337,7 @@ incompatible. <em>Use with caution!</em> If your app requires an {@link android.accounts.Account}, the value for this attribute must correspond to the account authenticator type used by your app (as defined by {@link android.accounts.AuthenticatorDescription}), -such as "com.google". +such as "com.google". <p>The default value is null and indicates that the application can work <em>without</em> any accounts. @@ -369,13 +399,13 @@ direction associated to the user's Locale choice (your layouts will always be le <dt><a name="aff"></a>{@code android:taskAffinity}</dt> <dd>An affinity name that applies to all activities within the application, except for those that set a different affinity with their own -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> attributes. See that attribute for more information. <p> -By default, all activities within an application share the same -affinity. The name of that affinity is the same as the package name -set by the +By default, all activities within an application share the same +affinity. The name of that affinity is the same as the package name +set by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. </p></dd> @@ -389,7 +419,7 @@ only through adb.</dd> <dt><a name="theme"></a>{@code android:theme}</dt> <dd>A reference to a style resource defining a default theme for all activities in the application. Individual activities can override -the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> +the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> attributes. For more information, see the <a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide. </dd> diff --git a/docs/html/images/games/game-controller-buttons_2x_crop.png b/docs/html/images/games/game-controller-buttons_2x_crop.png Binary files differnew file mode 100644 index 0000000..54dc2fa --- /dev/null +++ b/docs/html/images/games/game-controller-buttons_2x_crop.png diff --git a/docs/html/images/gp-tv-opt-in.png b/docs/html/images/gp-tv-opt-in.png Binary files differnew file mode 100644 index 0000000..a815818 --- /dev/null +++ b/docs/html/images/gp-tv-opt-in.png diff --git a/docs/html/images/gp-tv-process.png b/docs/html/images/gp-tv-process.png Binary files differnew file mode 100644 index 0000000..a530777 --- /dev/null +++ b/docs/html/images/gp-tv-process.png diff --git a/docs/html/images/tools/studio-build-variant.png b/docs/html/images/tools/studio-build-variant.png Binary files differnew file mode 100644 index 0000000..a400ad4 --- /dev/null +++ b/docs/html/images/tools/studio-build-variant.png diff --git a/docs/html/images/ui/notifications/heads-up.png b/docs/html/images/ui/notifications/heads-up.png Binary files differindex 42fbbcd..75cc95e 100644 --- a/docs/html/images/ui/notifications/heads-up.png +++ b/docs/html/images/ui/notifications/heads-up.png diff --git a/docs/html/jd_collections.js b/docs/html/jd_collections.js index 08c0090..d63580e 100644 --- a/docs/html/jd_collections.js +++ b/docs/html/jd_collections.js @@ -57,8 +57,8 @@ var RESOURCE_COLLECTIONS = { }, "distribute/gp/gpfelanding": { "resources": [ + "distribute/googleplay/tv.html", "distribute/googleplay/edu/about.html", - "distribute/googleplay/edu/start.html", "distribute/googleplay/edu/videos.html" ] }, @@ -773,6 +773,14 @@ var RESOURCE_COLLECTIONS = { "https://support.google.com/googleplay/answer/2651410" ] }, + "tvlanding": { + "title": "", + "resources": [ + "tv/index.html", + "design/tv/index.html", + "training/tv/index.html" + ] + }, "distribute/stories/games": { "title": "", "resources": [ diff --git a/docs/html/sdk/installing/adding-packages.jd b/docs/html/sdk/installing/adding-packages.jd index 22d055c..b8d8925 100644 --- a/docs/html/sdk/installing/adding-packages.jd +++ b/docs/html/sdk/installing/adding-packages.jd @@ -1,6 +1,6 @@ page.title=Adding SDK Packages -page.tags=studio, sdk tools, eclipse adt, sdk manager, google play services, support library +page.tags=sdk manager helpoutsWidget=true @jd:body diff --git a/docs/html/sdk/installing/index.jd b/docs/html/sdk/installing/index.jd index 6a99952..68f4eb7 100644 --- a/docs/html/sdk/installing/index.jd +++ b/docs/html/sdk/installing/index.jd @@ -1,6 +1,6 @@ page.title=Installing the Android SDK -page.tags=studio, sdk tools, eclipse adt +page.tags=sdk tools helpoutsWidget=true @jd:body @@ -74,9 +74,9 @@ Continue: Adding SDK Packages</a></p> <!-- ################ STUDIO ##################### --> <div id="studio" heading="Installing Android Studio" style="display:none"> -<p>Android Studio provides everything you need to start developing apps, including -the Android SDK tools and the Android Studio IDE (powered by IntelliJ) to -streamline your Android app development.</p> +<p>Android Studio provides the tools you need to start developing apps, including +the Android Studio IDE (powered by IntelliJ) and guides you to install +the Android SDK tools to streamline your Android app development.</p> <p>If you didn't download Android Studio, go <a href="{@docRoot}sdk/installing/studio.html" ><b>download Android Studio now</b></a>, or switch to the @@ -103,8 +103,9 @@ style="float:right;font-size:13px"><a href='' onclick='showAll();return false;' <p><b>To set up Android Studio on Windows:</b></p> <ol> - <li>Launch the downloaded EXE file, {@code android-studio-bundle-<version>.exe}.</li> - <li>Follow the setup wizard to install Android Studio. + <li>Unzip the file, {@code android-studio-ide-<version>-windows.zip} and launch the + <code>studio.exe</code> file.</li> + <li>Follow the setup wizard to install Android Studio and the SDK Tools. <p>On some Windows systems, the launcher script does not find where Java is installed. If you encounter this problem, @@ -119,11 +120,10 @@ style="float:right;font-size:13px"><a href='' onclick='showAll();return false;' </ol> -<p>The individual tools and -other SDK packages are saved within the Android Studio application directory. -If you need to access the tools directly, use a terminal to navigate into the application and locate -the {@code sdk/} directory. For example:</p> -<p><code>\Users\<user>\AppData\Local\Android\android-studio\sdk\</code></p> +<p>The individual tools and other SDK packages are saved outside the Android Studio application +directory. If you need to access the tools directly, use a terminal to navigate to the location +where they are installed. For example:</p> +<p><code>\Users\<user>\sdk\</code></p> @@ -134,7 +134,7 @@ the {@code sdk/} directory. For example:</p> <p><b>To set up Android Studio on Mac OSX:</b></p> <ol> - <li>Open the downloaded DMG file, {@code android-studio-bundle-<version>.dmg}.</li> + <li>Unzip the downloaded zip file, {@code android-studio-ide-<version>-mac.zip}.</li> <li>Drag and drop Android Studio into the Applications folder. <p> Depending on your security settings, when you attempt to open Android Studio, you might @@ -143,13 +143,13 @@ the {@code sdk/} directory. For example:</p> <strong>Allow applications downloaded from</strong>, select <strong>Anywhere</strong>. Then open Android Studio again.</p> </li> + <li>Follow the links to install the SDK outside of the Android Studio directories.</li> </ol> -<p>The individual tools and -other SDK packages are saved within the Android Studio application directory. -If you need access the tools directly, use a terminal to navigate into the application and locate -the {@code sdk/} directory. For example:</p> -<p><code>/Applications/Android\ Studio.app/sdk/</code></p> +<p>The individual tools and other SDK packages are saved outside the Android Studio application +directory. If you need access the tools directly, use a terminal to navigate into the location +where they are installed. For example:</p> +<p><code>/Applications/sdk/</code></p> </div><!-- end mac --> @@ -160,13 +160,14 @@ the {@code sdk/} directory. For example:</p> <p><b>To set up Android Studio on Linux:</b></p> <ol> - <li>Unpack the downloaded Tar file, {@code android-studio-bundle-<version>.tgz}, into an appropriate - location for your applications. + <li>Unpack the downloaded Tar file, {@code android-studio-ide-<version>-linux.zip}, into an + appropriate location for your applications. <li>To launch Android Studio, navigate to the {@code android-studio/bin/} directory in a terminal and execute {@code studio.sh}. <p>You may want to add {@code android-studio/bin/} to your PATH environmental variable so that you can start Android Studio from any directory.</p> </li> + <li>Follow the links to install the SDK outside of the Android Studio directories.</li> </ol> </div><!-- end linux --> @@ -217,11 +218,12 @@ style="float:right;font-size:13px"><a href='' onclick='showAll();return false;' <p>Your download package is an executable file that starts an installer. The installer checks your machine for required tools, such as the proper Java SE Development Kit (JDK) and installs it if necessary. - The installer then saves the Android SDK Tools into a default location (or you can specify the location).</p> + The installer then saves the Android SDK Tools to a specified the location outside of the Android + Studio directories.</p> <ol> <li>Double-click the executable ({@code .exe} file) to start the install.</li> -<li>Make a note of the name and location in which it saves the SDK on your system—you will need to +<li>Make a note of the name and location where you save the SDK on your system—you will need to refer to the SDK directory later when using the SDK tools from the command line.</li> <li>Once the installation completes, the installer starts the Android SDK Manager. @@ -237,8 +239,8 @@ the SDK tools from the command line.</li> <p><b>To get started on Mac OSX:</b></p> <p>Unpack the ZIP file you've downloaded. By default, it's unpacked -into a directory named <code>android-sdk-mac_x86</code>. Move it to an appropriate location on your machine, -such as a "Development" directory in your home directory.</p> +into a directory named <code>android-sdk-mac_x86</code>. Move it to an appropriate location on your +machine, such as a "Development" directory in your home directory.</p> <p>Make a note of the name and location of the SDK directory on your system—you will need to refer to the SDK directory later when using @@ -253,9 +255,8 @@ the SDK tools from the command line.</p> <p><b>To get started on Linux:</b></p> -<p>Unpack the {@code .tgz} file you've downloaded. By default, the SDK files are unpacked -into a directory named <code>android-sdk-linux_x86</code>. Move it to an appropriate location on your machine, -such as a "Development" directory in your home directory.</p> +<p>Unpack the {@code .zip} file you've downloaded. The SDK files are download separately to a +user-specified directory. </p> <p>Make a note of the name and location of the SDK directory on your system—you will need to refer to the SDK directory later when using diff --git a/docs/html/sdk/installing/studio.jd b/docs/html/sdk/installing/studio.jd index b0567e7..6991dea 100644 --- a/docs/html/sdk/installing/studio.jd +++ b/docs/html/sdk/installing/studio.jd @@ -194,12 +194,12 @@ This is the Android Software Development Kit License Agreement href="" style="display:none;width:368px;margin:0 auto;display:block;font-size:18px" ></a> <div style="margin:20px 0 0 0"> -<p style="margin-bottom:8px">This download includes:</p> +<p style="margin-bottom:8px">This installation includes:</p> <ul style="margin-bottom:20px"> -<li>Android Studio Beta</li> -<li>All the Android SDK Tools to design, test, and debug your app</li> -<li>A version of the Android platform to compile your app</li> -<li>A version of the Android system image to run your app in the emulator</li> + <li>Android Studio Beta</li> + <li>All the Android SDK Tools to design, test, and debug your app</li> + <li>A version of the Android platform to compile your app</li> + <li>A version of the Android system image to run your app in the emulator</li> </ul> </div> @@ -244,43 +244,41 @@ download (or continue to use) <th>Platform</th> <th>Package</th> <th>Size</th> - <th>MD5 Checksum</th> + <th>SHA Sum</th> </tr> <tr> <td>Windows</td> <td> <a onclick="return onDownload(this)" id="win-studio" - href="https://dl.google.com/android/studio/install/0.8.6/android-studio-bundle-135.1339820-windows.exe"> - android-studio-bundle-135.1339820-windows.exe + href="https://dl.google.com/dl/android/studio/ide-zips/0.8.14/android-studio-ide-135.1538390-windows.zip">android-studio-ide-135.1538390-windows.zip </a> </td> - <td>379497130 bytes</td> - <td>024e002b8c8fa7dcd2ff69fd69e06e56</td> + <td>177343814 bytes</td> + <td>b533480200ba893616c73b32477e66ebb357a1b3</td> </tr> <tr> <td><nobr>Mac OS X</nobr></td> <td> <a onclick="return onDownload(this)" id="mac-studio" - href="https://dl.google.com/android/studio/install/0.8.6/android-studio-bundle-135.1339820-mac.dmg"> - android-studio-bundle-135.1339820-mac.dmg + href="https://dl.google.com/dl/android/studio/ide-zips/0.8.14/android-studio-ide-135.1538390-mac.zip"> + android-studio-ide-135.1538390-mac.zip </a> </td> - <td>368507143 bytes</td> - <td>4143f2aa556634eae91701965d88899b</td> + <td>176745627 bytes</td> + <td>4070e6f6a44d042266f46f1f2f9ca3448ac23f8cd</td> </tr> <tr> <td>Linux</td> <td> <a onclick="return onDownload(this)" id="linux-studio" - href="https://dl.google.com/android/studio/install/0.8.6/android-studio-bundle-135.1339820-linux.tgz"> - android-studio-bundle-135.1339820-linux.tgz + href="https://dl.google.com/dl/android/studio/ide-zips/0.8.14/android-studio-ide-135.1538390-linux.zip">android-studio-ide-135.1538390-linux.zip </a> </td> - <td>417631443 bytes</td> - <td>fa403762ecd0a5da87acbeff485f81cc</td> + <td>176358193 bytes</td> + <td>718356b49254f6c4e55c64b99164d311995205dd</td> </tr> </table> @@ -301,44 +299,48 @@ download (or continue to use) <tr> <td> <ul> - <li>Microsoft Windows 8, 7, Vista, 2003, or XP (32 or 64 bit)</li> - <li>1 GB of RAM minimum, 2 GB recommended</li> - <li>400 MB of disk space</li> - <li>At least 1 GB of additional disk space for the Android SDK, emulator system images, and caches</li> + <li>Microsoft Windows 8/7/Vista/2003 (32 or 64 bit)</li> + <li>2 GB RAM minimum, 4 GB RAM recommended</li> + <li>400 MB disk space </li> + <li>At least 1 GB for Android SDK, emulator system images, and caches</li> <li>1280x800 minimum screen resolution</li> - <li>Java Development Kit (JDK) 6 or higher</li> + <li>Java Development Kit (JDK) 7 or higher</li> + <li>(Optional for accelerated emulator: Intel processor with support for Intel VT-x, Intel + EM64T (Intel 64), and Execute Disable (XD) Bit functionality)</li> </ul> </td> <td> <ul> <li>Mac OS X 10.8.5 or higher, up to 10.9 (Mavericks)</li> - <li>1 GB of RAM minimum, 2 GB recommended</li> - <li>400 MB of disk space</li> - <li>At least 1 GB of additional disk space for the Android SDK, emulator system images, and caches</li> + <li>2 GB RAM minimum, 4 GB RAM recommended</li> + <li>400 MB disk space</li> + <li>At least 1 GB for Android SDK, emulator system images, and caches</li> <li>1280x800 minimum screen resolution</li> - <li>Java Runtime Environment (JRE) 6 *</li> - <li>Java Development Kit (JDK) 6 or JDK 7</li> + <li>Java Runtime Environment (JRE) 6</li> + <li>Java Development Kit (JDK) 7 or higher + <p>On Mac OS, run Android Studio with Java Runtime Environment (JRE) 6 for optimized font + rendering. You can then configure your project to use Java Development Kit (JDK) JDK 7.</p></li> + <li>(Optional for accelerated emulator: Intel processor with support for Intel VT-x, Intel + EM64T (Intel 64), and Execute Disable (XD) Bit functionality)</li> </ul> -<p>* On Mac OS, run Android Studio with Java Runtime Environment (JRE) 6 for optimized font -rendering. You can then configure your project to use Java Development Kit (JDK) 6 or JDK 7.</p> + </td> <td> <ul> - <li>64-bit distribution capable of running 32-bit applications</li> + <li>GNOME or KDE desktop.</li> + <li>Tested on Ubuntu 12.04, Precise Pangolin (64-bit distribution capable of running 32-bit + applications)</li> <li>GNU C Library (glibc) 2.11 or later is required.</li> - <li>Tested on Ubuntu 12.04, Precise Pangolin</li> - <li>GNOME or KDE desktop</li> - <li>1 GB of RAM minimum, 2 GB recommended</li> - <li>400 MB of disk space</li> - <li>At least 1 GB of additional disk space for the Android SDK, emulator system images, and caches</li> + <li>2 GB RAM minimum, 4 GB RAM recommended</li> + <li>400 MB disk space</li> + <li>At least 1 GB for Android SDK, emulator system images, and caches</li> <li>1280x800 minimum screen resolution</li> - <li>Oracle Java Development Kit (JDK) 6 or JDK 7</li> + <li>Java Development Kit (JDK) 7 or higher</li> </ul> </td> </tr> </table> -<p class="note"><strong>Note:</strong> Java Development Kit (JDK) 7 is required if you're targeting -the Android L Developer Preview.</p> +<p class="note"><strong>Note:</strong> The full SDK/NDK requires 13 GB of disk space.</p> </div><!-- end pax --> @@ -425,7 +427,7 @@ installation.</p> <p><strong>Caution:</strong> Replacing your existing installation of Android Studio will remove any additional SDK packages you've installed, such as target platforms, system images, and sample apps. To preserve these, copy them from your current -SDK directory under Android Studio to a temporary location +SDK directory to a temporary location before installing the update. Then move them back once the update is complete. If you fail to copy these packages, then you can instead download them again through the Android SDK Manager.</p> @@ -453,6 +455,17 @@ style="vertical-align:bottom;margin:0;height:19px" /> in the toolbar.</p> <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" + alt=""/>Android Studio v0.8.14</a> <em>(October 2014)</em> + </p> + + <div class="toggle-content-toggleme"> + <p>See <a href="http://tools.android.com/recent">tools.android.com</a> for a full list of changes.</p> + </div> +</div> + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt=""/>Android Studio v0.8.6</a> <em>(August 2014)</em> </p> @@ -650,7 +663,7 @@ for possible resolutions to known issues: <a href="http://tools.android.com/know if (os) { /* set up primary ACE download button */ $('#download-ide-button').show(); - $('#download-ide-button').append("Download Android Studio Beta <span class='small'>v0.8.6</span>" + $('#download-ide-button').append("Download Android Studio Beta <span class='small'>v0.8.14</span>" + "<br/> <span class='small'>with the Android SDK for " + os + "</span>"); $('#download-ide-button').click(function() {return onDownload(this,true);}).attr('href', bundlename); diff --git a/docs/html/tools/building/multidex.jd b/docs/html/tools/building/multidex.jd new file mode 100644 index 0000000..49cde8c --- /dev/null +++ b/docs/html/tools/building/multidex.jd @@ -0,0 +1,458 @@ +page.title=Building Apps with Over 65K Methods +page.tags="65536","references","max","65k","dex","64k","multidex","multi-dex","methods"</p> + +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#about"> + About the 65K Reference Limit</a> + <ol> + <li><a href="#mdex-pre-l">Multidex support prior to Android 5.0</a></li> + <li><a href="#mdex-on-l">Multidex support for Android 5.0 and higher</a></li> + </ol> + </li> + <li><a href="#avoid"> + Avoiding the 65K Limit</a></li> + <li><a href="#mdex-gradle"> + Configuring Your App for Multidex with Gradle</a> + <ol> + <li><a href="#limitations"> + Limitations of the multidex support library</a></li> + </ol> + </li> + <li><a href="#dev-build"> + Optimizing Multidex Development Builds</a> + <ol> + <li><a href="#variants-studio"> + Using Build Variants in Android Studio</a></li> + </ol> + </li> + <li><a href="#testing"> + Testing Multidex Apps</a></li> + </ol> + + <h2>See Also</h2> + <ol> + <li><a href="{@docRoot}tools/help/proguard.html">ProGuard</a> + </li> + </ol> + </div> +</div> + + +<p> + As the Android platform has continued to grow, so has the size of Android apps. When your + application and the libraries it references reach a certain size, you encounter build errors that + indicate your app has reached a limit of the Android app build architecture. Earlier versions of + the build system report this error as follows: +</p> + +<pre> +Conversion to Dalvik format failed: +Unable to execute dex: method ID not in [0, 0xffff]: 65536 +</pre> + +<p> + More recent versions of the Android build system display a different error, which is an + indication of the same problem: +</p> + +<pre> +trouble writing output: +Too many field references: 131000; max is 65536. +You may try using --multi-dex option. +</pre> + +<p> + Both these error conditions display a common number: 65,536. This number is significant in that + it represents the total number of references that can be invoked by the code within a single + Dalvik Executable (dex) bytecode file. If you have built an Android app and received this error, + then congratulations, you have a lot of code! This document explains how to move past this + limitation and continue building your app. +</p> + +<p class="note"> + <strong>Note:</strong> The guidance provided in this document supersedes the guidance given in + the Android Developers blog post <a href= + "http://android-developers.blogspot.com/2011/07/custom-class-loading-in-dalvik.html">Custom Class + Loading in Dalvik</a>. +</p> + + +<h2 id="about">About the 65K Reference Limit</h2> + +<p> + Android application (APK) files contain executable bytecode files in the form of <a href= + "https://source.android.com/devices/tech/dalvik/">Dalvik</a> Executable (DEX) files, which + contain the compiled code used to run your app. The Dalvik Executable specification limits the + total number of methods that can be referenced within a single DEX file to 65,536, including + Android framework methods, library methods, and methods in your own code. Getting past this limit + requires that you configure your app build process to generate more than one DEX file, known as a + <em>multidex</em> configuration. +</p> + + +<h3 id="mdex-pre-l">Multidex support prior to Android 5.0</h3> + +<p> + Versions of the platform prior to Android 5.0 use the Dalvik runtime for executing app code. By + default, Dalvik limits apps to a single classes.dex bytecode file per APK. In order to get around + this limitation, you can use the <a href="{@docRoot}tools/support-library/features.html#multidex"> + multidex support library</a>, which becomes part of the primary DEX file of your app and then + manages access to the additional DEX files and the code they contain. +</p> + + +<h3 id="mdex-on-l">Multidex support for Android 5.0 and higher</h3> + +<p> + Android 5.0 and higher uses a runtime called ART which natively supports loading multiple dex + files from application APK files. ART performs pre-compilation at application install time which + scans for classes(..N).dex files and compiles them into a single .oat file for execution by the + Android device. For more information on the Android 5.0 runtime, see <a href= + "https://source.android.com/devices/tech/dalvik/art.html">Introducing ART</a>. +</p> + + +<h2 id="avoid">Avoiding the 65K Limit</h2> + +<p> + Before configuring your app to enable use of 65K or more method references, you should take steps + to reduce the total number of references called by your app code, including methods defined by + your app code or included libraries. The following strategies can help you avoid hitting the dex + reference limit: +</p> + +<ul> + <li> + <strong>Review your app's direct and transitive dependencies</strong> - Ensure any large library + dependency you include in your app is used in a manner that outweighs the amount of code + being added to the application. A common anti-pattern is to include a very large library + because a few utility methods were useful. Reducing your app code dependencies can often help + you avoid the dex reference limit. + </li> + <li> + <strong>Remove unused code with ProGuard</strong> - Configure the <a href= + "{@docRoot}tools/help/proguard.html">ProGuard</a> settings for your app to run ProGuard and + ensure you have shrinking enabled for release builds. Enabling shrinking ensures you + are not shipping unused code with your APKs. + </li> +</ul> + + +<p> + Using these techniques can help you avoid the build configuration changes required to enable more + method references in your app. These steps can also decrease the size of your APKs, which is + particularly important for markets where bandwidth costs are high. +</p> + + +<h2 id="mdex-gradle">Configuring Your App for Multidex with Gradle</h2> + +<p> + The Android plugin for Gradle available in Android SDK Build Tools 21.1 and higher supports + multidex as part of your build configuration. Make sure you update the Android SDK Build Tools + tools and the Android Support Repository to the latest version using the <a href= + "{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> before attempting to configure your app + for multidex. +</p> + +<p> + Setting up your app development project to use a multidex configuration requires that you make a + few modifications to your app development project. In particular you need to perform the + following steps: +</p> + +<ul> + <li>Change your Gradle build configuration to enable multidex</li> + <li>Modify your manifest to reference the {@link android.support.multidex.MultiDexApplication} + class</li> +</ul> + +<p> + Modify your app Gradle build file configuration to include the support library and enable + multidex output, as shown in the following Gradle build file snippet: +</p> + +<pre> +android { + compileSdkVersion 21 + buildToolsVersion "21.1.0" + + defaultConfig { + ... + minSdkVersion 14 + targetSdkVersion 21 + ... + + // Enabling multidex support. + multiDexEnabled true + } + ... +} + +dependencies { + compile 'com.android.support:multidex:1.0.0' +} +</pre> + +<p class="note"> + <strong>Note:</strong> You can specify the <code>multiDexEnabled</code> setting in the + <code>defaultConfig,</code> <code>buildType</code>, or <code>productFlavor</code> sections of + your Gradle build file. +</p> + + +<p> + In your manifest add the {@link android.support.multidex.MultiDexApplication} class from the + multidex support library to the application element. +</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.android.multidex.myapplication"> + <application + ... + android:name="android.support.multidex.MultiDexApplication"> + ... + </application> +</manifest> +</pre> + +<p> + When these configuration settings are added to an app, the Android build tools construct a + primary dex (classes.dex) and supporting (classes2.dex, classes3.dex) as needed. The build system + will then package them into an APK file for distribution. +</p> + +<p class="note"> + <strong>Note:</strong> If your app uses extends the {@link android.app.Application} class, you + can override the attachBaseContext() method and call MultiDex.install(this) to enable multidex. + For more information, see the {@link android.support.multidex.MultiDexApplication} reference + documentation. +</p> + +<h3 id="limitations">Limitations of the multidex support library</h3> + +<p> + The multidex support library has some known limitations that you should be aware of and test for + when you incorporate it into your app build configuration: +</p> + +<ul> + <li>The installation of .dex files during startup onto a device's data partition is complex and + can result in Application Not Responding (ANR) errors if the secondary dex files are large. In + this case, you should apply code shrinking techniques with ProGuard to minimize the size of dex + files and remove unused portions of code. + </li> + + <li>Applications that use multidex may not start on devices that run versions of the platform + earlier than Android 4.0 (API level 14) due to a Dalvik linearAlloc bug (Issue <a href= + "http://b.android.com/22586">22586</a>). If you are targeting API levels earlier than 14, make + sure to perform testing with these versions of the platform as your application can have issues + at startup or when particular groups of classes are loaded. Code shrinking can reduce or possibly + eliminate these potential issues. + </li> + + <li>Applications using a multidex configuration that make very large memory allocation + requests may crash during run time due to a Dalvik linearAlloc limit (Issue <a href= + "http://b.android.com/78035">78035</a>). The allocation limit was increased in Android 4.0 (API + level 14), but apps may still run into this limit on Android versions prior to + Android 5.0 (API level 21). + </li> + + <li>There are complex requirements regarding what classes are needed in the primary dex file when + executing in the Dalvik runtime. The Android build tooling updates handle the Android + requirements, but it is possible that other included libraries have additional dependency + requirements including the use of introspection or invocation of Java methods from native code. + Some libraries may not be able to be used until the multidex build tools are updated to allow you + to specify classes that must be included in the primary dex file. + </li> +</ul> + + +<h2 id="dev-build">Optimizing Multidex Development Builds</h2> + +<p> + A multidex configuration requires significantly increased build processing time because the build + system must make complex decisions about what classes must be included in the primary DEX file + and what classes can be included in secondary DEX files. This means that routine builds performed + as part of the development process with multidex typically take longer and can potentially slow + your development process. +</p> + +<p> + In order to mitigate the typically longer build times for multidex output, you should create two + variations on your build output using the Android plugin for Gradle + <a href="http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Product-flavors"> + {@code productFlavors}</a>: a development flavor and a production flavor. +</p> + +<p> + For the development flavor, set a minimum SDK version of 21. This setting generates multidex + output much faster using the ART-supported format. For the release flavor, set a minimum SDK + version which matches your actual minimum support level. This setting generates a multidex APK + that is compatible with more devices, but takes longer to build. +</p> + +<p> + The following build configuration sample demonstrates the how to set up these flavors in a Gradle + build file: +</p> + +<pre> +android { + productFlavors { + // Define separate dev and prod product flavors. + dev { + // dev utilizes minSDKVersion = 21 to allow the Android gradle plugin + // to pre-dex each module and produce an APK that can be tested on + // Android Lollipop without time consuming dex merging processes. + minSdkVersion 21 + } + prod { + // The actual minSdkVersion for the application. + minSdkVersion 14 + } + } + ... + buildTypes { + release { + runProguard true + proguardFiles getDefaultProguardFile('proguard-android.txt'), + 'proguard-rules.pro' + } + } +} +dependencies { + compile 'com.android.support:multidex:1.0.0' +} +</pre> + +<p> + After you have completed this configuration change, you can use the <code>devDebug</code> variant + of your app, which combines the attributes of the <code>dev</code> productFlavor and the + <code>debug</code> buildType. Using this target creates a debug app with proguard disabled, + multidex enabled, and minSdkVersion set to Android API level 21. These settings cause the Android + gradle plugin to do the following: +</p> + +<ol> + <li>Build each module of the application (including dependencies) as separate dex files. This is + commonly referred to as pre-dexing. + </li> + + <li>Include each dex file in the APK without modification. + </li> + + <li>Most importantly, the module dex files will not be combined, and so the long-running + calculation to determine the contents of the primary dex file is avoided. + </li> +</ol> + +<p> + These settings result in fast, incremental builds, because only the dex files of modified modules + are recomputed and repackaged into the APK file. The APK that results from these builds can be + used to test on Android 5.0 devices only. However, by implementing the configuration as a flavor, + you preserve the ability to perform normal builds with the release-appropriate minimum SDK level + and proguard settings. +</p> + +<p> + You can also build the other variants, including a <code>prodDebug</code> variant + build, which takes longer to build, but can be used for testing outside of development. + Within the configuration shown, the <code>prodRelease</code> variant would be the final testing + and release version. If you are executing gradle tasks from the command line, you can use + standard commands with <code>DevDebug</code> appended to the end (such as <code>./gradlew + installDevDebug</code>). For more information about using flavors with Gradle tasks, see the + <a href="http://tools.android.com/tech-docs/new-build-system/user-guide">Gradle Plugin User + Guide</a>. +</p> + +<p> + <strong>Tip:</strong> You can also provide a custom manifest, or a custom application class for each + flavor, allowing you to use the support library MultiDexApplication class, or calling + MultiDex.install() only for the variants that need it. +</p> + + +<h3 id="variants-studio">Using Build Variants in Android Studio</h3> + +<p> + Build variants can be very useful for managing the build process when using multidex. Android + Studio allows you to select these build variants in the user interface. +</p> + +<p> + To have Android Studio build the "devDebug" variant of your app: +</p> + +<ol> + <li>Open the <em>Build Variants</em> window from the left-sidebar. The option is located next to + <em>Favorites</em>. + </li> + + <li>Click the name of the build variant to select a different variant, as shown in Figure 1. + </li> +</ol> + +<img src="{@docRoot}images/tools/studio-build-variant.png" alt="" height="XXX" id="figure1"> +<p class="img-caption"> + <strong>Figure 1.</strong> Screen shot of the Android Studio left panel showing a build variant. +</p> + +<p class="note"> + <strong>Note</strong>: The option to open this window is only available after you have + successfully synchronized Android Studio with your Gradle build file using the <strong>Tools > + Android > Sync Project with Gradle Files</strong> command. +</p> + + +<h2 id="testing">Testing Multidex Apps</h2> + +<p> + Testing apps that use multidex configuration require some additional steps and configuration. + Since the location of code for classes is not within a single DEX file, instrumentation tests do + not run properly unless configured for multidex. +</p> + +<p> + When testing a multidex app with instrumentation tests, use + <a href="{@docRoot}reference/com/android/test/runner/MultiDexTestRunner.html"> + MultiDexTestRunner</a> from the multidex testing support library. The following sample + {@code build.gradle} file, demonstrates how to configure your build to use this test runner: +</p> + +<pre> +android { + defaultConfig { + ... + testInstrumentationRunner "android.support.multidex.MultiDexTestRunner" + } +} + +dependencies { + androidTestCompile 'com.android.support:multidex-instrumentation:1.0.0' +} +</pre> + +<p> + You may use the instrumentation test runner class directly or extend it to fit your testing + needs. Alternatively, you can override onCreate in existing instrumentations like this: +</p> + +<pre> +public void onCreate(Bundle arguments) { + MultiDex.install(getTargetContext()); + super.onCreate(arguments); + ... +} +</pre> + +<p class="note"> + <strong>Note:</strong> Use of multidex for creating a test APK is not currently supported. +</p>
\ No newline at end of file diff --git a/docs/html/tools/revisions/build-tools.jd b/docs/html/tools/revisions/build-tools.jd index 6f07755..ec88efc 100644 --- a/docs/html/tools/revisions/build-tools.jd +++ b/docs/html/tools/revisions/build-tools.jd @@ -77,6 +77,18 @@ listing in the Android SDK Manager.</p> <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" + alt=""/>Build Tools, Revision 21.1</a> <em>(October 2014)</em> + </p> + <div class="toggle-content-toggleme"> + <p>Added multidex file support for APKs and Jack suppport to address the 64K method reference + limit.</p> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt=""/>Build Tools, Revision 21.0.2</a> <em>(October 2014)</em> </p> <div class="toggle-content-toggleme"> diff --git a/docs/html/tools/revisions/platforms.jd b/docs/html/tools/revisions/platforms.jd index 85b9c5e..ef8575a 100644 --- a/docs/html/tools/revisions/platforms.jd +++ b/docs/html/tools/revisions/platforms.jd @@ -88,7 +88,7 @@ class="toggle-content-img" alt="" />Revision 2</a> <em>(October 2014)</em> <div class="toggle-content-toggleme"> - <p>Added location APIs support for Wear.</p> + <p>Updated the rendering library. </p> <p>Dependencies:</p> <ul> diff --git a/docs/html/tools/support-library/features.jd b/docs/html/tools/support-library/features.jd index 44c5045..3ebfc89 100644 --- a/docs/html/tools/support-library/features.jd +++ b/docs/html/tools/support-library/features.jd @@ -8,6 +8,7 @@ page.title=Support Library Features <h2>In this document</h2> <ol> <li><a href="#v4">v4 Support Library</a></li> + <li><a href="#multidex">Multidex Support Library</a></li> <li><a href="#v7">v7 Support Libraries</a> <ol> <li><a href="#v7-appcompat">v7 appcompat library</a></li> @@ -145,6 +146,34 @@ com.android.support:support-v4:21.0.+ <p>This dependency notation specifies the release version 21.0.0 or higher.</p> +<h2 id="multidex">Multidex Support Library</h2> + +<p> + This library provides support for building apps with multiple Dalvik Executable (DEX) files. + Apps that reference more than 65536 methods are required to use multidex configurations. For + more information about using multidex, see <a href="{@docRoot}tools/building/multidex.html"> + Building Apps with Over 65K Methods</a>. +</p> + +<p> + This library is located in the {@code <sdk>/extras/android/support/multidex/} directory + after you download the Android Support Libraries. The library does not contain user interface + resources. To include it in your application project, follow the instructions for <a href= + "{@docRoot}tools/support-library/setup.html#libs-without-res">Adding libraries without + resources</a>. +</p> + +<p> + The Gradle build script dependency identifier for this library is as follows: +</p> + +<pre> +com.android.support:multidex:1.0.+ +</pre> + +<p>This dependency notation specifies the release version 1.0.0 or higher.</p> + + <h2 id="v7">v7 Support Libraries</h2> <p>There are several libraries designed to be used with Android 2.1 (API level 7) and higher. diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 8eb9cbf..ac33185 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -66,10 +66,17 @@ <li class="nav-section"> - <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/building/index.html"><span class="en">Building and Running</span></a></div> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>tools/building/index.html"> + <span class="en">Building and Running</span></a> + </div> <ul> - <li><a href="<?cs var:toroot ?>tools/building/building-eclipse.html"><span class="en">From Eclipse with ADT</span></a></li> - <li><a href="<?cs var:toroot ?>tools/building/building-cmdline.html"><span class="en">From the Command Line</span></a></li> + <li><a href="<?cs var:toroot ?>tools/building/building-eclipse.html"> + <span class="en">From Eclipse with ADT</span></a></li> + <li><a href="<?cs var:toroot ?>tools/building/building-cmdline.html"> + <span class="en">From the Command Line</span></a></li> + <li><a href="<?cs var:toroot ?>tools/building/multidex.html"> + <span class="en">Apps Over 65K Methods</span></a></li> </ul> </li> diff --git a/docs/html/training/basics/firstapp/building-ui.jd b/docs/html/training/basics/firstapp/building-ui.jd index c082642..0430cdd 100644 --- a/docs/html/training/basics/firstapp/building-ui.jd +++ b/docs/html/training/basics/firstapp/building-ui.jd @@ -1,7 +1,7 @@ page.title=Building a Simple User Interface trainingnavtop=true -page.tags=ui, views, layouts, widgets, string resources +page.tags=ui helpoutsWidget=true @jd:body diff --git a/docs/html/training/basics/firstapp/creating-project.jd b/docs/html/training/basics/firstapp/creating-project.jd index 418eb68..2e06103 100644 --- a/docs/html/training/basics/firstapp/creating-project.jd +++ b/docs/html/training/basics/firstapp/creating-project.jd @@ -1,6 +1,6 @@ page.title=Creating an Android Project -page.tags=eclipse adt, sdk tools, project setup +page.tags=project setup helpoutsWidget=true trainingnavtop=true diff --git a/docs/html/training/basics/firstapp/starting-activity.jd b/docs/html/training/basics/firstapp/starting-activity.jd index f9dcba4..71f66dd 100644 --- a/docs/html/training/basics/firstapp/starting-activity.jd +++ b/docs/html/training/basics/firstapp/starting-activity.jd @@ -4,7 +4,7 @@ parent.link=index.html trainingnavtop=true -page.tags=input events, intents, activity lifecycle +page.tags=intents helpoutsWidget=true @jd:body diff --git a/docs/html/training/tv/discovery/index.jd b/docs/html/training/tv/discovery/index.jd index fbc8c9f..5849149 100644 --- a/docs/html/training/tv/discovery/index.jd +++ b/docs/html/training/tv/discovery/index.jd @@ -1,4 +1,5 @@ -page.title=Helping Users Find Content on TV +page.title=Helping Users Find Your Content on TV +page.tags="tv", "leanback" startpage=true diff --git a/docs/html/training/tv/games/index.jd b/docs/html/training/tv/games/index.jd index 2f510a9..5276d7f 100644 --- a/docs/html/training/tv/games/index.jd +++ b/docs/html/training/tv/games/index.jd @@ -1,5 +1,7 @@ page.title=Building TV Games -page.tags="controller" +page.tags="tv", "games", "controller" +page.image=images/games/game-controller-buttons_2x_crop.png +page.metaDescription=How to bring your games to Android TV, including recommendations and examples. page.article=true @jd:body @@ -180,7 +182,7 @@ href="{@docRoot}training/game-controllers/controller-input.html#button" It includes a white controller on black background and a black controller on white background (shown in figure 1), as a PNG file and an Adobe® Illustrator® file.</p> -<img src="{@docRoot}images/games/game-controller-buttons_2x.png" width="700" +<img itemprop="image" src="{@docRoot}images/games/game-controller-buttons_2x.png" width="700" srcset="{@docRoot}images/games/game-controller-buttons_2x.png 2x, {@docRoot}images/games/game-controller-buttons.png 1x" /> <p class="img-caption"><b>Figure 1.</b> Example controller instructions using the @@ -194,22 +196,22 @@ It includes a white controller on black background and a black controller on whi <p>There are a some special things games should include in the Android manifest.</p> -<h3 id="Launcher">Show your game in the launcher</h3> +<h3 id="Launcher">Show your game on the home screen</h3> <p> - The Android TV launcher home screen displays games in a separate row from regular apps. - To make your game appear in the list of games, add the - <a href="{@docRoot}guide/topics/manifest/meta-data-element.html" - ><code><meta-data></code></a> tag in your app manifest with <code>android:name</code> - set to <code>"isGame"</code> and <code>android:value</code> - set to <code>"true"</code>. For example: + The Android TV home screen displays games in a separate row from regular apps. + To make your game appear in the list of games, set the + <a href="{@docRoot}guide/topics/manifest/application-element.html#isGame"> + {@code android:isGame}</a> attribute to <code>"true"</code> in your app manifest's + <a href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code> + </a> tag. For example: </p> <pre class="fragment"> -<application> - ... - <meta-data android:name="isGame" android:value="true" > - ... -</application> +<application + ... + android:isGame="true" + ... +> </pre> diff --git a/docs/html/training/tv/index.jd b/docs/html/training/tv/index.jd index 56667a9..d52e1e8 100644 --- a/docs/html/training/tv/index.jd +++ b/docs/html/training/tv/index.jd @@ -1,8 +1,11 @@ page.title=Building Apps for TV page.trainingcourse=true - +page.metaDescription=Starting point for building apps and games for Android TV, with guidelines, information, and examples. +page.image=design/tv/images/focus.png @jd:body -<p>These classes teach you how to build apps for TV devices.</p>
\ No newline at end of file +<p>These classes teach you how to build apps for TV devices.</p> + +<p class="note"><strong>Note:</strong> For details on how to publish your TV apps in Google Play, see <a href="{docRoot}distribute/googleplay/tv.html">Distributing to Android TV</a>.</p>
\ No newline at end of file diff --git a/docs/html/training/tv/playback/index.jd b/docs/html/training/tv/playback/index.jd index 118fc6c..09c3f24 100644 --- a/docs/html/training/tv/playback/index.jd +++ b/docs/html/training/tv/playback/index.jd @@ -1,5 +1,5 @@ page.title=Building TV Playback Apps -page.tags="leanback" +page.tags="tv","leanback" startpage=true diff --git a/docs/html/training/tv/start/index.jd b/docs/html/training/tv/start/index.jd index ceefea1..fb478a8 100644 --- a/docs/html/training/tv/start/index.jd +++ b/docs/html/training/tv/start/index.jd @@ -1,4 +1,5 @@ page.title=Building TV Apps +page.tags="tv", "leanback" startpage=true @jd:body diff --git a/docs/html/training/tv/start/start.jd b/docs/html/training/tv/start/start.jd index bebeedd..3b26abf 100644 --- a/docs/html/training/tv/start/start.jd +++ b/docs/html/training/tv/start/start.jd @@ -100,7 +100,8 @@ startpage=true <p>The following code snippet shows how to include this intent filter in your manifest:</p> <pre> -<application> +<application + android:banner="@drawable/banner" > ... <activity android:name="com.example.android.MainActivity" @@ -141,6 +142,34 @@ startpage=true "{@docRoot}training/tv/start/layouts.html">Building TV Layouts</a>. </p> +<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: +</p> + +<pre> +<application + . . . + android:banner="@drawable/banner" > + . . . +</application> +</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><application></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><activity></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> <h3 id="tv-libraries">Add TV support libraries</h3> diff --git a/docs/html/training/tv/tif/index.jd b/docs/html/training/tv/tif/index.jd index 4746e42..cde8ba7 100644 --- a/docs/html/training/tv/tif/index.jd +++ b/docs/html/training/tv/tif/index.jd @@ -1,5 +1,5 @@ page.title=Building Live TV Apps -page.tags=tif +page.tags="tv", "tif" page.article=true @jd:body diff --git a/docs/html/training/wearables/apps/bt-debugging.jd b/docs/html/training/wearables/apps/bt-debugging.jd index 8d09c43..98cf804 100644 --- a/docs/html/training/wearables/apps/bt-debugging.jd +++ b/docs/html/training/wearables/apps/bt-debugging.jd @@ -58,7 +58,8 @@ Target: connected </li> <li>Connect the handheld to your machine over USB and run: <pre> -adb forward tcp:4444 localabstract:/adb-hub; adb connect localhost:4444 +adb forward tcp:4444 localabstract:/adb-hub +adb connect localhost:4444 </pre> <p class="note"><b>Note</b>: You can use any available port that you have access to.</p> diff --git a/docs/html/training/wearables/apps/layouts.jd b/docs/html/training/wearables/apps/layouts.jd index e62d3e5..a35acb0 100644 --- a/docs/html/training/wearables/apps/layouts.jd +++ b/docs/html/training/wearables/apps/layouts.jd @@ -90,9 +90,10 @@ PendingIntent notificationPendingIntent = PendingIntent.getActivity(this, 0, not </ol> <h2 id="UiLibrary">Create Layouts with the Wearable UI Library</h2> <p> -There's an unofficial UI library that is automatically included when you create your wearable -app with the Android Studio Project Wizard. You can also add the library to your <code>build.gradle</code> +The Wearable UI Library is automatically included when you create your wearable +app with the Android Studio Project Wizard. You can also add this library to your <code>build.gradle</code> file with the following dependency declaration: +</p> <pre> dependencies { @@ -101,8 +102,11 @@ dependencies { compile 'com.google.android.gms:play-services-wearable:+' } </pre> -This library helps you build UIs that are designed for wearables. Here are some of the major classes: -</p> + +<p>This library helps you build UIs that are designed for wearables. For more information, see +<a href="{@docRoot}training/wearables/ui/index.html">Creating Custom UIs for Wear Devices</a>.</p> + +<p>Here are some of the major classes in the Wearable UI Library:</p> <ul> <li><code>BoxInsetLayout</code> - A FrameLayout that's aware of screen shape and can box its diff --git a/docs/html/training/wearables/data-layer/index.jd b/docs/html/training/wearables/data-layer/index.jd index 39d6561..6ef3fc7 100644 --- a/docs/html/training/wearables/data-layer/index.jd +++ b/docs/html/training/wearables/data-layer/index.jd @@ -8,7 +8,7 @@ page.title=Sending and Syncing Data <h2>Dependencies and prerequisites</h2> <ul> <li>Android 4.3 (API Level 18) or higher on the handset device</li> - <li>The latest version of <a href="{@docRoot}google/play">Google Play services</a></li> + <li>The latest version of <a href="{@docRoot}google/play-services/index.html">Google Play services</a></li> <li>An Android Wear device or Wear AVD</li> </ul> </div> diff --git a/docs/html/training/wearables/notifications/pages.jd b/docs/html/training/wearables/notifications/pages.jd index d74c8ea..6315037 100644 --- a/docs/html/training/wearables/notifications/pages.jd +++ b/docs/html/training/wearables/notifications/pages.jd @@ -57,15 +57,14 @@ Notification secondPageNotification = .setStyle(secondPageStyle) .build(); -// Add second page with wearable extender and extend the main notification -Notification twoPageNotification = - new WearableExtender() - .addPage(secondPageNotification) - .extend(notificationBuilder) - .build(); +// Extend the notification builder with the second page +Notification notification = notificationBuilder + .extend(new NotificationCompat.WearableExtender() + .addPage(secondPageNotification)) + .build(); // Issue the notification notificationManager = NotificationManagerCompat.from(this); -notificationManager.notify(notificationId, twoPageNotification); +notificationManager.notify(notificationId, notification); </pre>
\ No newline at end of file diff --git a/docs/html/training/wearables/notifications/voice-input.jd b/docs/html/training/wearables/notifications/voice-input.jd index 4a27826..3ce1c80 100644 --- a/docs/html/training/wearables/notifications/voice-input.jd +++ b/docs/html/training/wearables/notifications/voice-input.jd @@ -37,7 +37,7 @@ so you can type replies instead.</p> <h2 id="VoiceInput">Define the Voice Input</h2> -<p>To create an action that supports voice input, create an instance of +<p>To create an action that supports voice input, create an instance of {@link android.support.v4.app.RemoteInput.Builder} that you can add to your notification action. This class's constructor accepts a string that the system uses as the key for the voice input, which you'll later use to retrieve the text of the @@ -166,9 +166,8 @@ which is referenced by the <code>EXTRA_VOICE_REPLY</code> key that is used in th private CharSequence getMessageText(Intent intent) { Bundle remoteInput = RemoteInput.getResultsFromIntent(intent); - if (remoteInput != null) { - return remoteInput.getCharSequence(EXTRA_VOICE_REPLY); - } + if (remoteInput != null) { + return remoteInput.getCharSequence(EXTRA_VOICE_REPLY); } return null; } diff --git a/docs/html/tv/index.jd b/docs/html/tv/index.jd index 71e177b..e4d7f7a 100644 --- a/docs/html/tv/index.jd +++ b/docs/html/tv/index.jd @@ -1,5 +1,9 @@ -page.title=Android TV +page.title=About Android TV +page.type=about +page.image=tv/images/hero.jpg page.viewport_width=970 +page.tags="tv", "leanback" +page.metaDescription=Bring your apps, games, and content to the biggest screen in the house. fullpage=true no_footer_links=true page.type=about |
