diff options
Diffstat (limited to 'docs/html/guide')
127 files changed, 13196 insertions, 7393 deletions
diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd index 7d119ca..bc7d83b 100644 --- a/docs/html/guide/appendix/api-levels.jd +++ b/docs/html/guide/appendix/api-levels.jd @@ -154,7 +154,7 @@ Highlights</a></td></tr> <td>2</td> <td>{@link android.os.Build.VERSION_CODES#BASE_1_1}</td><td></td></tr> - <tr><td><a href="{@docRoot}sdk/android-1.0.html">Android 1.0</td> + <tr><td>Android 1.0</td> <td>1</td> <td>{@link android.os.Build.VERSION_CODES#BASE}</td> <td></td></tr> @@ -350,11 +350,11 @@ including the latest version, and provides an updater tool that you can use to download other platform versions as necessary. </p> <p>To access the updater, use the <code>android</code> command-line tool, -located in the <sdk>/tools directory. You can launch the Updater by using -the <code>android</code> command without specifying any options. You can +located in the <sdk>/tools directory. You can launch the SDK updater by +executing <code>android sdk</code>. You can also simply double-click the android.bat (Windows) or android (OS X/Linux) file. In ADT, you can also access the updater by selecting -<strong>Window</strong> > <strong>Android SDK and AVD +<strong>Window</strong> > <strong>Android SDK Manager</strong>.</p> <p>To run your application against different platform versions in the emulator, diff --git a/docs/html/guide/appendix/install-location.jd b/docs/html/guide/appendix/install-location.jd index 292d3e7..63a3817 100644 --- a/docs/html/guide/appendix/install-location.jd +++ b/docs/html/guide/appendix/install-location.jd @@ -172,9 +172,9 @@ persist after external storage is remounted.</dd> before the external storage is mounted to the device. If your application is installed on the external storage, it can never receive this broadcast.</dd> <dt>Copy Protection</dt> - <dd>Your application cannot be installed to a device's SD card if it uses Android Market's - Copy Protection feature. However, if you use Android Market's - <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a> instead, your + <dd>Your application cannot be installed to a device's SD card if it uses Google Play's + Copy Protection feature. However, if you use Google Play's + <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a> instead, your application <em>can</em> be installed to internal or external storage, including SD cards.</dd> </dl> diff --git a/docs/html/guide/appendix/market-filters.jd b/docs/html/guide/appendix/market-filters.jd index 6610f5f..3e502d7 100644 --- a/docs/html/guide/appendix/market-filters.jd +++ b/docs/html/guide/appendix/market-filters.jd @@ -1,4 +1,4 @@ -page.title=Market Filters +page.title=Filters on Google Play @jd:body <div id="qv-wrapper"> @@ -6,15 +6,15 @@ page.title=Market Filters <h2>Quickview</h2> <ul> -<li>Android Market applies filters that control which Android-powered devices can access your -application on Market.</li> +<li>Google Play applies filters that control which Android-powered devices can access your +application when the user is visiting the store.</li> <li>Filtering is determined by comparing device configurations that you declare in you app's manifest file to the configurations defined by the device, as well as other factors.</li> </ul> <h2>In this document</h2> <ol> - <li><a href="#how-filters-work">How Filters Work in Android Market</a></li> + <li><a href="#how-filters-work">How Filters Work on Google Play</a></li> <li><a href="#manifest-filters">Filtering based on Manifest Elements</a> <ol> <li><a href="#advanced-filters">Advanced manifest filters</a></li> @@ -47,10 +47,10 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></c <div id="qv-extra"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0 5px;"> - <h2 style="color:#669999;">Interested in publishing your app on Android Market?</h2> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0 5px;"> + <h2 style="color:#669999;padding-top:1em;">Interested in publishing your app on Google Play?</h2> <p><a id="publish-link" -href="http://market.android.com/publish">Go to Android Market</a> to create a publisher +href="http://play.google.com/apps/publish">Go to Google Play</a> to create a publisher account and upload your app.</p></div> </div> @@ -58,44 +58,44 @@ account and upload your app.</p></div> </div> -<p>When a user searches or browses in Android Market on an Android device, the results are filtered +<p>When a user searches or browses on Google Play on an Android device, the results are filtered based on which applications are compatible with that device. For example, if an application -requires a camera (as specified in the application manifest file), then Android Market will not show +requires a camera (as specified in the application manifest file), then Google Play will not show the app on any device that does not have a camera.</p> <p>Declarations in the manifest file that are compared to the device's configuration is not the only part of how applications are filtered. Filtering might also occur due to the user's country and carrier, the presence or absence of a SIM card, and other factors. </p> -<p>Changes to the Android Market filters are independent of changes to the Android platform itself. -This document is updated periodically to reflect any changes that affect the way Android Market +<p>Changes to the Google Play filters are independent of changes to the Android platform itself. +This document is updated periodically to reflect any changes that affect the way Google Play filters applications.</p> -<h2 id="how-filters-work">How Filters Work in Android Market</h2> +<h2 id="how-filters-work">How Filters Work on Google Play</h2> -<p>Android Market uses the filter restrictions described below to determine +<p>Google Play uses the filter restrictions described below to determine whether to show your application to a user who is browsing or searching for -applications from the Android Market app. When determining whether to display your app, -Market checks the device's hardware and software configuration, as well as it's +applications from the Google Play app. When determining whether to display your app, +Google Play checks the device's hardware and software configuration, as well as it's carrier, location, and other characteristics. It then compares those against the restrictions and dependencies expressed by the application's manifest file and publishing details. If the application is -compatible with the device according to the filter rules, Market displays the -application to the user. Otherwise, Market hides your application from search +compatible with the device according to the filter rules, Google Play displays the +application to the user. Otherwise, Google Play hides your application from search results and category browsing, even if a user specifically requests -the app by clicking a deep link that points directly to the app's ID within Market..</p> +the app by clicking a deep link that points directly to the app's ID within Google Play..</p> <p class="note"><strong>Note:</strong> When users browse the <a -href="http://market.android.com">Android Market web site</a>, they can see all published -applications. The Android Market web site compares the application requirements to each of the +href="http://play.google.com/apps">Google Play web site</a>, they can see all published +applications. The Google Play web site compares the application requirements to each of the user's registered devices for compatibility, though, and only allows them to install the application if it's compatible with their device.</p> <p>You can use any combination of the available filters for your app. For example, you can set a <code>minSdkVersion</code> requirement of <code>"4"</code> and set <code>smallScreens="false"</code> -in the app, then when uploading the app to Market you could target European countries (carriers) -only. Android Market's filters will thus prevent the application from being available on any device +in the app, then when uploading the app to Google Play you could target European countries (carriers) +only. Google Play's filters will thus prevent the application from being available on any device that does not match all three of these requirements. </p> <p>All filtering restrictions are associated with an application's version and can @@ -106,15 +106,15 @@ available.</p> <h2 id="manifest-filters">Filtering based on Manifest Elements</h2> -<p>Most Market filters are triggered by elements within an application's +<p>Most filters are triggered by elements within an application's manifest file, <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> (although not everything in the manifest file can trigger filtering). -Table 1 lists the manifest elements that you should use to trigger Android -Market filtering, and explains how the filtering for each element works.</p> +Table 1 lists the manifest elements that you should use to trigger +filtering, and explains how the filtering for each element works.</p> <p id="table1" class="table-caption"><strong>Table 1.</strong> Manifest elements that -trigger filtering on Market.</p> +trigger filtering on Google Play.</p> <table> <tr> <th>Manifest Element</th> @@ -129,19 +129,19 @@ trigger filtering on Market.</p> <p>An application indicates the screen sizes that it is capable of supporting by setting attributes of the <code><supports-screens></code> element. When -the application is published, Market uses those attributes to determine whether +the application is published, Google Play uses those attributes to determine whether to show the application to users, based on the screen sizes of their devices. </p> -<p>As a general rule, Market assumes that the platform on the device can adapt +<p>As a general rule, Google Play assumes that the platform on the device can adapt smaller layouts to larger screens, but cannot adapt larger layouts to smaller screens. Thus, if an application declares support for "normal" screen size only, -Market makes the application available to both normal- and large-screen devices, +Google Play makes the application available to both normal- and large-screen devices, but filters the application so that it is not available to small-screen devices.</p> <p>If an application does not declare attributes for -<code><supports-screens></code>, Market uses the default values for those +<code><supports-screens></code>, Google Play uses the default values for those attributes, which vary by API Level. Specifically: </p> <ul> @@ -150,7 +150,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">android: minSdkVersion</a></code> or <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">android: targetSdkVersion</a></code> to 3 or lower, the <code><supports-screens></code> element itself -is undefined and no attributes are available. In this case, Market assumes that +is undefined and no attributes are available. In this case, Google Play assumes that the application is designed for normal-size screens and shows the application to devices that have normal or larger screens. </p> @@ -165,20 +165,20 @@ default.</li> <p><strong>Example 1</strong><br /> The manifest declares <code><uses-sdk android:minSdkVersion="3"></code> - and does not does not include a <code><supports-screens></code> element. - <strong>Result</strong>: Android Market will not show the app to a user of a + and does not include a <code><supports-screens></code> element. + <strong>Result</strong>: Google Play will not show the app to a user of a small-screen device, but will show it to users of normal and large-screen - devices, users, unless other filters apply. </p> + devices, unless other filters apply. </p> <p><strong>Example 2<br /> </strong>The manifest declares <code><uses-sdk android:minSdkVersion="3" android:targetSdkVersion="4"></code> and does not include a <code><supports-screens></code> element. - <strong>Result</strong>: Android Market will show the app to users on all + <strong>Result</strong>: Google Play will show the app to users on all devices, unless other filters apply. </p> <p><strong>Example 3<br /> </strong>The manifest declares <code><uses-sdk android:minSdkVersion="4"></code> and does not include a <code><supports-screens></code> element. - <strong>Result</strong>: Android Market will show the app to all users, + <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply. </p> <p>For more information on how to declare support for screen sizes in your application, see <code><a @@ -195,11 +195,11 @@ default.</li> Configuration: <br /> keyboard, navigation, touch screen</td> <td valign="top"><p>An application can - request certain hardware features, and Android Market will show the app only on devices that have the required hardware.</p> + request certain hardware features, and Google Play will show the app only on devices that have the required hardware.</p> <p><strong>Example 1<br /> - </strong>The manifest includes <code><uses-configuration android:reqFiveWayNav="true" /></code>, and a user is searching for apps on a device that does not have a five-way navigational control. <strong>Result</strong>: Android Market will not show the app to the user. </p> + </strong>The manifest includes <code><uses-configuration android:reqFiveWayNav="true" /></code>, and a user is searching for apps on a device that does not have a five-way navigational control. <strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2<br /> - </strong>The manifest does not include a <code><uses-configuration></code> element. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply.</p> + </strong>The manifest does not include a <code><uses-configuration></code> element. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply.</p> <p>For more details, see <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code></a>.</p></td> </tr> @@ -218,16 +218,16 @@ Level 5).</p> </strong>The manifest includes <code><uses-feature android:name="android.hardware.sensor.light" /></code>, and a user is searching for apps on a device that does not have a light sensor. -<strong>Result</strong>: Android Market will not show the app to the user. </p> +<strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2<br /> </strong>The manifest does not include a <code><uses-feature></code> -element. <strong>Result</strong>: Android Market will show the app to all users, +element. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply.</p> <p>For complete information, see <code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> </code>.</p> - <p><em>Filtering based on implied features:</em> In some cases, Android -Market interprets permissions requested through + <p><em>Filtering based on implied features:</em> In some cases, Google +Play interprets permissions requested through <code><uses-permission></code> elements as feature requirements equivalent to those declared in <code><uses-feature></code> elements. See <a href="#uses-permission-filtering"><code><uses-permission></code></a>, @@ -245,19 +245,19 @@ below.</p> <p><strong>Example 1<br /> </strong>An app requests multiple OpenGL-ES versions by specifying <code>openGlEsVersion</code> multiple times in the - manifest. <strong>Result</strong>: Market assumes that the app requires the highest of the indicated versions.</p> + manifest. <strong>Result</strong>: Google Play assumes that the app requires the highest of the indicated versions.</p> <p><strong>Example 2<br /> </strong>An app - requests OpenGL-ES version 1.1, and a user is searching for apps on a device that supports OpenGL-ES version 2.0. <strong>Result</strong>: Android Market will show the app to the user, unless other filters apply. If a - device reports that it supports OpenGL-ES version <em>X</em>, Market assumes that it + requests OpenGL-ES version 1.1, and a user is searching for apps on a device that supports OpenGL-ES version 2.0. <strong>Result</strong>: Google Play will show the app to the user, unless other filters apply. If a + device reports that it supports OpenGL-ES version <em>X</em>, Google Play assumes that it also supports any version earlier than <em>X</em>. </p> <p><strong>Example 3<br /> </strong>A user is searching for apps on a device that does not - report an OpenGL-ES version (for example, a device running Android 1.5 or earlier). <strong>Result</strong>: Android Market assumes that the device - supports only OpenGL-ES 1.0. Market will only show the user apps that do not specify <code>openGlEsVersion</code>, or apps that do not specify an OpenGL-ES version higher than 1.0. </p> + report an OpenGL-ES version (for example, a device running Android 1.5 or earlier). <strong>Result</strong>: Google Play assumes that the device + supports only OpenGL-ES 1.0. Google Play will only show the user apps that do not specify <code>openGlEsVersion</code>, or apps that do not specify an OpenGL-ES version higher than 1.0. </p> <p><strong>Example 4<br /> - </strong>The manifest does not specify <code>openGlEsVersion</code>. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply. </p> + </strong>The manifest does not specify <code>openGlEsVersion</code>. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply. </p> <p>For more details, see <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a>.</p></td> </tr> @@ -268,28 +268,28 @@ href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses- <td valign="top"><p>An application can require specific shared libraries to be present on the device. </p> <p><strong>Example 1<br /> - </strong>An app requires the <code>com.google.android.maps</code> library, and a user is searching for apps on a device that does not have the <code>com.google.android.maps</code> library. <strong>Result</strong>: Android Market will not show the app to the user. </p> + </strong>An app requires the <code>com.google.android.maps</code> library, and a user is searching for apps on a device that does not have the <code>com.google.android.maps</code> library. <strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2</strong><br /> - The manifest does not include a <code><uses-library></code> element. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply.</p> + The manifest does not include a <code><uses-library></code> element. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply.</p> <p>For more details, see <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a>.</p></td> </tr> <tr id="uses-permission-filtering"> <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></td> <td valign="top"> </td> - <td valign="top">Strictly, Android Market does not filter based on + <td valign="top">Strictly, Google Play does not filter based on <code><uses-permission></code> elements. However, it does read the elements to determine whether the application has hardware feature requirements that may not have been properly declared in <code><uses-feature></code> elements. For example, if an application requests the <code>CAMERA</code> permission but does not declare a <code><uses-feature></code> element for -<code>android.hardware.camera</code>, Android Market considers that the +<code>android.hardware.camera</code>, Google Play considers that the application requires a camera and should not be shown to users whose devices do not offer a camera.</p> <p>In general, if an application requests hardware-related permissions, -Android Market assumes that the application requires the underlying hardware +Google Play assumes that the application requires the underlying hardware features, even though there might be no corresponding to -<code><uses-feature></code> declarations. Android Market then sets up +<code><uses-feature></code> declarations. Google Play then sets up filtering based on the features implied by the <code><uses-feature></code> declarations.</p> <p>For a list of permissions that imply hardware features, see @@ -305,9 +305,9 @@ element.</p> <td valign="top"><p>An application can require a minimum API level. </p> <p><strong>Example 1</strong><br /> The manifest includes <code><uses-sdk - android:minSdkVersion="3"></code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Android Market will not show the app to the user. </p> + android:minSdkVersion="3"></code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2</strong><br /> - The manifest does not include <code>minSdkVersion</code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Android Market assumes that <code>minSdkVersion</code> is "1" and that the app is compatible with all versions of Android. Market shows the app to the user and allows the user to download the app. The app crashes at runtime. </p> + The manifest does not include <code>minSdkVersion</code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Google Play assumes that <code>minSdkVersion</code> is "1" and that the app is compatible with all versions of Android. Google Play shows the app to the user and allows the user to download the app. The app crashes at runtime. </p> <p>Because you want to avoid this second scenario, we recommend that you always declare a <code>minSdkVersion</code>. For details, see <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min"><code>android:minSdkVersion</code></a>.</p></td> </tr> @@ -316,7 +316,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min"><code>android:m <td valign="top"><p><em>Deprecated.</em> Android 2.1 and later do not check or enforce the <code>maxSdkVersion</code> attribute, and the SDK will not compile if <code>maxSdkVersion</code> is set in an app's manifest. For devices already - compiled with <code>maxSdkVersion</code>, Market will respect it and use it for + compiled with <code>maxSdkVersion</code>, Google Play will respect it and use it for filtering.</p> <p> Declaring <code>maxSdkVersion</code> is <em>not</em> recommended. For details, see <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:maxSdkVersion</code></a>.</p></td> @@ -327,7 +327,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:m <h3 id="advanced-filters">Advanced manifest filters</h3> -<p>In addition to the manifest elements in <a href="#table1">table 1</a>, Android Market can also +<p>In addition to the manifest elements in <a href="#table1">table 1</a>, Google Play can also filter applications based on the advanced manifest elements in table 2.</p> <p>These manifest elements and the filtering they trigger are for exceptional use-cases @@ -336,14 +336,14 @@ require strict controls on application distribution. <strong>Most applications s these filters</strong>.</p> <p id="table2" class="table-caption"><strong>Table 2.</strong> Advanced manifest elements for -Android Market filtering.</p> +Google Play filtering.</p> <table> <tr><th>Manifest Element</th><th>Summary</th></tr> <tr> <td><nobr><a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code <compatible-screens>}</a></nobr></td> <td> - <p>Android Market filters the application if the device screen size and density does not match + <p>Google Play filters the application if the device screen size and density does not match any of the screen configurations (declared by a {@code <screen>} element) in the {@code <compatible-screens>} element.</p> <p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use @@ -360,7 +360,7 @@ with alternative resources.</p> <td><nobr><a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code <supports-gl-texture>}</a></nobr></td> <td> - <p>Android Market filters the application unless one or more of the GL texture compression + <p>Google Play filters the application unless one or more of the GL texture compression formats supported by the application are also supported by the device. </p> </td> </tr> @@ -370,16 +370,16 @@ formats supported by the application are also supported by the device. </p> <h2 id="other-filters">Other Filters</h2> -<p>Android Market uses other application characteristics to determine whether to show or hide an application for a particular user on a given device, as described in the table below. </p> +<p>Google Play uses other application characteristics to determine whether to show or hide an application for a particular user on a given device, as described in the table below. </p> <p id="table3" class="table-caption"><strong>Table 3.</strong> Application and publishing -characteristics that affect filtering on Market.</p> +characteristics that affect filtering on Google Play.</p> <table> <tr> <th>Filter Name</th> <th>How It Works</th> </tr> <tr> <td valign="top">Publishing Status</td> <td valign="top"><p>Only published applications will appear in - searches and browsing within Android Market.</p> <p>Even if an app is unpublished, it can + searches and browsing within Google Play.</p> <p>Even if an app is unpublished, it can be installed if users can see it in their Downloads area among their purchased, installed, or recently uninstalled apps.</p> <p>If an application has been suspended, users will not be able to reinstall or update it, even if it appears in their Downloads.</p> </td></tr> @@ -390,36 +390,36 @@ must have a SIM card and be running Android 1.1 or later, and it must be in a country (as determined by SIM carrier) in which paid apps are available.</p></td> </tr> <tr> <td valign="top">Country / Carrier Targeting</td> <td valign="top"> <p>When you upload your app to - the Android Market, you can select specific countries to target. The app will only + Google Play, you can select specific countries to target. The app will only be visible to the countries (carriers) that you select, as follows:</p> <ul><li><p>A device's country is determined based on the carrier, if a carrier is - available. If no carrier can be determined, the Market application tries to + available. If no carrier can be determined, Google Play tries to determine the country based on IP.</p></li> <li><p>Carrier is determined based on the device's SIM (for GSM devices), not the current roaming carrier.</p></li></ul> </td> </tr> <tr> <td valign="top">Native Platform</td> <td valign="top"><p>An application that includes native - libraries that target a specific platform (ARM EABI v7, for example) will only be - visible on devices that support that platform. For details about the NDK and using + libraries that target a specific platform (ARM EABI v7 or x86, for example) are + visible only on devices that support that platform. For details about the NDK and using native libraries, see <a href="{@docRoot}sdk/ndk/index.html#overview">What is the Android NDK?</a></p> </tr> <tr> <td valign="top">Copy-Protected Applications</td> <td valign="top"><p>To copy protect an application, set copy protection to "On" when you configure publishing -options for your application. Market will not show copy-protected applications on +options for your application. Google Play will not show copy-protected applications on developer devices or unreleased devices.</p></td> </tr> </table> <h2 id="MultiApks">Publishing Multiple APKs with Different Filters</h2> -<p>Some specific Android Market filters allow you to publish multiple APKs for the same +<p>Some specific Google Play filters allow you to publish multiple APKs for the same application in order to provide a different APK to different device configurations. For example, if you're creating a video game that uses high-fidelity graphic assets, you might want to create two APKs that each support different texture compression formats. This way, you can reduce the size of the APK file by including only the textures that are required for each device -configuration. Depending on each device's support for your texture compression formats, Android -Market will deliver it the APK that you've declared to support that device.</p> +configuration. Depending on each device's support for your texture compression formats, Google +Play will deliver it the APK that you've declared to support that device.</p> -<p>Currently, Android Market allows you to publish multiple APKs for the same application only +<p>Currently, Google Play allows you to publish multiple APKs for the same application only when each APK provides different filters based on the following configurations:</p> <ul> <li>OpenGL texture compression formats @@ -440,7 +440,7 @@ href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code </ul> <p>All other filters still work the same as usual, but these three are the only filters that can -distinguish one APK from another within the same application listing on Android Market. For example, +distinguish one APK from another within the same application listing on Google Play. For example, you <em>cannot</em> publish multiple APKs for the same application if the APKs differ only based on whether the device has a camera.</p> @@ -450,5 +450,5 @@ APK that supports a wide range of device configurations</strong>. Publishing mul requires that you follow specific rules within your filters and that you pay extra attention to the version codes for each APK to ensure proper update paths for each configuration.</p> -<p>If you need more information about how to publish multiple APKs on Android Market, read <a +<p>If you need more information about how to publish multiple APKs on Google Play, read <a href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> diff --git a/docs/html/guide/developing/building/building-cmdline.jd b/docs/html/guide/developing/building/building-cmdline.jd index c43962a..fd90b1a 100644 --- a/docs/html/guide/developing/building/building-cmdline.jd +++ b/docs/html/guide/developing/building/building-cmdline.jd @@ -202,12 +202,12 @@ ant release <ol> <li> - <strong>Open the SDK and AVD Manager and launch a virtual device</strong> + <strong>Open the AVD Manager and launch a virtual device</strong> - <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool with no - arguments:</p> + <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool +with the <code>avd</code> options:</p> <pre> -android +android avd </pre> <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p> @@ -237,7 +237,7 @@ adb -s emulator-5554 install <em>path/to/your/app</em>.apk </ol> <p>If you don't see your application on the emulator, try closing the emulator and launching the - virtual device again from the SDK and AVD Manager. Sometimes when you install an application for the + virtual device again from the AVD Manager. Sometimes when you install an application for the first time, it won't show up in the application launcher or be accessible by other applications. This is because the package manager usually examines manifests completely only on emulator startup.</p> diff --git a/docs/html/guide/developing/building/index.jd b/docs/html/guide/developing/building/index.jd index 59c4645..569cd28 100644 --- a/docs/html/guide/developing/building/index.jd +++ b/docs/html/guide/developing/building/index.jd @@ -27,8 +27,8 @@ page.title=Building and Running <p>To run an application on an emulator or device, the application must be signed using debug or release mode. You typically want to sign your application in debug mode when you develop and test your application, because the build tools use a debug key with a known password so you do not have - to enter it every time you build. When you are ready to release the application to Android - Market, you must sign the application in release mode, using your own private key.</p> + to enter it every time you build. When you are ready to release the application to Google + Play, you must sign the application in release mode, using your own private key.</p> <p>Fortunately, Eclipse or your Ant build script signs the application for you in debug mode when you build your application. You can also easily setup Eclipse or your Ant build to sign your diff --git a/docs/html/guide/developing/debugging/ddms.jd b/docs/html/guide/developing/debugging/ddms.jd index 4398ec9..9892e49 100644 --- a/docs/html/guide/developing/debugging/ddms.jd +++ b/docs/html/guide/developing/debugging/ddms.jd @@ -11,7 +11,19 @@ parent.link=index.html <li><a href="#running">Running DDMS</a></li> <li><a href="#how-ddms-works">How DDMS Interacts with a Debugger</a></li> - <li><a href="#using-ddms">Using DDMS</a></li> + <li><a href="#using-ddms">Using DDMS</a> + <ol> + <li><a href="#heap">Viewing heap usage for a process</a></li> + <li><a href="#alloc">Tracking memory allocation of objects</a></li> + <li><a href="#emulator">Working with an emulator or device's file system</a></li> + <li><a href="#thread">Examining thread information</a></li> + <li><a href="#profiling">Starting method profiling</a></li> + <li><a href="#network">Using the Network Traffic tool</a></li> + <li><a href="#logcat">Using LogCat</a></li> + <li><a href="#ops-location">Emulating phone operations and location</a></li> + </ol> + + </li> </ol> </div> </div> @@ -90,7 +102,7 @@ parent.link=index.html <a href="#running">Running DDMS</a>. - <h3>Viewing heap usage for a process</h3> + <h3 id="heap">Viewing heap usage for a process</h3> <p>DDMS allows you to view how much heap memory a process is using. This information is useful in tracking heap usage at a certain point of time during the execution of your application.</p> @@ -110,15 +122,13 @@ parent.link=index.html allocated for a particular memory size in bytes.</li> </ol> - <h3>Tracking memory allocation of objects</h3> + <h3 id="alloc">Tracking memory allocation of objects</h3> <p>DDMS provides a feature to track objects that are being allocated to memory and to see which classes and threads are allocating the objects. This allows you to track, in real time, where objects are being allocated when you perform certain actions in your application. This information is valuable for assessing memory usage that can affect application performance. - If you want more granular control over where allocation data is collected, use the - {@link android.os.Debug#startAllocCounting()} and {@link android.os.Debug#stopAllocCounting()} - methods.</p> + </p> <p>To track memory allocation of objects:</p> <ol> @@ -140,7 +150,7 @@ parent.link=index.html line number of the code that allocated the object.</li> </ol> - <h3>Working with an emulator or device's file system</h3> + <h3 id="emulator">Working with an emulator or device's file system</h3> <p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the device. This feature is useful in examining files that are created by your application or if you @@ -160,7 +170,7 @@ parent.link=index.html <!-- Need to elaborate more on where things are stored in the file system, databases, apks, user info, files that are important to look at --> - <h3>Examining thread information</h3> + <h3 id="thread">Examining thread information</h3> <p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p> @@ -204,6 +214,67 @@ parent.link=index.html Profiling</strong>.</li> </ol> + <h3 id="network">Using the Network Traffic tool</h3> + + <p>In Android 4.0, the DDMS (Dalvik Debug Monitor Server) includes a Detailed +Network Usage tab that makes it possible to track when your application is +making network requests. Using this tool, you can monitor how and when your app +transfers data and optimize the underlying code appropriately. You can also +distinguish between different traffic types by applying a “tag” to network +sockets before use.</p> + +<p>These tags are shown in a stack area chart in DDMS, as shown in figure 2:</p> + +<img src="{@docRoot}images/developing/ddms-network.png" /> +<p class="img-caption"><strong>Figure 2.</strong> Network Usage tab.</p> + +<p>By monitoring the frequency of your data transfers, and the amount of data +transferred during each connection, you can identify areas of your application +that can be made more battery-efficient. Generally, you should look for +short spikes that can be delayed, or that should cause a later transfer to be +pre-empted. </p> + +<p>To better identify the cause of transfer spikes, the +{@link android.net.TrafficStats} API allows you +to tag the data transfers occurring within a thread using {@link +android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}, followed +by manually tagging (and untagging) individual sockets using {@link +android.net.TrafficStats#tagSocket tagSocket()} and {@link +android.net.TrafficStats#untagSocket untagSocket()}. For example:</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); +TrafficStats.tagSocket(outputSocket); +// Transfer data using socket +TrafficStats.untagSocket(outputSocket);</pre> + +<p>Alternatively, the Apache {@link org.apache.http.client.HttpClient} and +{@link java.net.URLConnection} APIs included in the platform +automatically tag sockets internally based on the active tag (as +identified by +{@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}). +These APIs correctly tag/untag sockets when recycled through +keep-alive pools. In the following example, +{@link android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()} +sets the active tag to be {@code 0xF00D}. +There can only be one active tag per thread. +That is the value that will +be returned by {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()} +and thus used by {@link org.apache.http.client.HttpClient} + to tag sockets. The {@code finally} statement +invokes +{@link android.net.TrafficStats#clearThreadStatsTag clearThreadStatsTag()} +to clear the tag.</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); + try { + // Make network request using HttpClient.execute() + } finally { + TrafficStats.clearThreadStatsTag(); +}</pre> + +<p>Socket tagging is supported in Android 4.0, but real-time stats will only be +displayed on devices running Android 4.0.3 or higher.</p> + <h3 id="logcat">Using LogCat</h3> <p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log} @@ -230,7 +301,7 @@ parent.link=index.html with the log tags or with the process id that generated the log message. The add filter, edit filter, and delete filter buttons let you manage your custom filters.</p> - <h3>Emulating phone operations and location</h3> + <h3 id="ops-location">Emulating phone operations and location</h3> <p>The Emulator control tab lets you simulate a phone's voice and data network status. This is useful when you want to test your application's robustness in differing network environments.</p> diff --git a/docs/html/guide/developing/debugging/debugging-log.jd b/docs/html/guide/developing/debugging/debugging-log.jd index 295772d..b5b626e 100644 --- a/docs/html/guide/developing/debugging/debugging-log.jd +++ b/docs/html/guide/developing/debugging/debugging-log.jd @@ -221,19 +221,20 @@ export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S" below.</p> <ul> - <li><code>brief</code> — Display priority/tag and PID of originating process (the default - format).</li> + <li><code>brief</code> — Display priority/tag and PID of the process issuing the + message (the default format).</li> <li><code>process</code> — Display PID only.</li> <li><code>tag</code> — Display the priority/tag only.</li> - <li><code>thread</code> — Display process:thread and priority/tag only.</li> - <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the - originating process.</li> + process issuing the message.</li> + + <li><code>threadtime</code> — Display the date, invocation time, priority, tag, and + the PID and TID of the thread issuing the message.</li> <li><code>long</code> — Display all metadata fields and separate messages with blank lines.</li> @@ -304,4 +305,4 @@ $ adb shell start <p> If you're developing a web application for Android, you can debug your JavaScript using the console JavaScript APIs, which output messages to LogCat. For more information, see - <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p>
\ No newline at end of file + <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p> diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd index 76b2516..d91551a 100644 --- a/docs/html/guide/developing/device.jd +++ b/docs/html/guide/developing/device.jd @@ -51,19 +51,13 @@ would on the emulator. Before you can start, there are just a few things to do:< <ol> <li>Declare your application as "debuggable" in your Android Manifest. - <p>In Eclipse, you can do this from the <b>Application</b> tab when viewing the Manifest - (on the right side, set <b>Debuggable</b> to <em>true</em>). Otherwise, in the -<code>AndroidManifest.xml</code> - file, add <code>android:debuggable="true"</code> to the <code><application></code> -element.</p> - </li> - <li>Set up your device to allow installation of non-Market applications. <p>On -the device, go to <strong>Settings > Applications</strong> and enable - -<strong>Unknown sources</strong> (on an Android 4.0 device, the setting is -located in <strong>Settings > Security</strong>).</p> - - </li> + <p>When using Eclipse, you can skip this step, because running your app directly from +the Eclipse IDE automatically enables debugging.</p> + <p>In the <code>AndroidManifest.xml</code> file, add <code>android:debuggable="true"</code> to +the <code><application></code> element.</p> + <p class="note"><strong>Note:</strong> If you manually enable debugging in the manifest + file, be sure to disable it before you build for release (your published application +should usually <em>not</em> be debuggable).</p></li> <li>Turn on "USB Debugging" on your device. <p>On the device, go to <strong>Settings > Applications > Development</strong> and enable <strong>USB debugging</strong> @@ -72,17 +66,12 @@ located in <strong>Settings > Developer options</strong>).</p> </li> <li>Set up your system to detect your device. <ul> - <li>If you're developing on Windows, you need to install a USB driver - for adb. If you're using an Android Developer Phone (ADP), Nexus One, or Nexus S, - see the <a href="{@docRoot}sdk/win-usb.html">Google Windows USB - Driver</a>. Otherwise, you can find a link to the appropriate OEM driver in the - <a href="{@docRoot}sdk/oem-usb.html">OEM USB Drivers</a> document.</li> + <li>If you're developing on Windows, you need to install a USB driver for adb. For an +installation guide and links to OEM drivers, see the <a href="{@docRoot}sdk/oem-usb.html">OEM USB +Drivers</a> document.</li> <li>If you're developing on Mac OS X, it just works. Skip this step.</li> - - <li>If you're developing on Ubuntu Linux, you need to add a <a -href="http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html"> -<code>udev</code></a> -rules file that contains a USB configuration for each type of device + <li>If you're developing on Ubuntu Linux, you need to add a +<code>udev</code> rules file that contains a USB configuration for each type of device you want to use for development. In the rules file, each device manufacturer is identified by a unique vendor ID, as specified by the <code>ATTR{idVendor}</code> property. For a list of vendor IDs, see <a @@ -116,7 +105,7 @@ rules</a>.</p> </li> </ol> -<p>You can verify that your device is connected by executing <code>adb +<p>When plugged in over USB, can verify that your device is connected by executing <code>adb devices</code> from your SDK {@code platform-tools/} directory. If connected, you'll see the device name listed as a "device."</p> @@ -145,39 +134,47 @@ above.</p> </tr> <tr> <td>ASUS</td> - <td><code>0B05</code></td> + <td><code>0b05</code></td> </tr> <tr> <td>Dell</td> - <td><code>413C</code></td> + <td><code>413c</code></td> </tr> <tr> <td>Foxconn</td> <td><code>0489</code></td> </tr> <tr> + <td>Fujitsu</td> + <td><code>04c5</code></td> + </tr> + <tr> + <td>Fujitsu Toshiba</td> + <td><code>04c5</code></td> + </tr> + <tr> <td>Garmin-Asus</td> - <td><code>091E</code></td> + <td><code>091e</code></td> </tr> <tr> <td>Google</td> - <td><code>18D1</code></td> + <td><code>18d1</code></td> </tr> <tr> <td>Hisense</td> - <td><code>109B</code></td> + <td><code>109b</code></td> </tr> <tr> <td>HTC</td> - <td><code>0BB4</code></td> + <td><code>0bb4</code></td> </tr> <tr> <td>Huawei</td> - <td><code>12D1</code></td> + <td><code>12d1</code></td> </tr> <tr> <td>K-Touch</td> - <td><code>24E3</code></td> + <td><code>24e3</code></td> </tr> <tr> <td>KT Tech</td> @@ -188,8 +185,8 @@ above.</p> <td><code>0482</code></td> </tr> <tr> - <td>Lenevo</td> - <td><code>17EF</code></td> + <td>Lenovo</td> + <td><code>17ef</code></td> </tr> <tr> <td>LG</td> @@ -197,7 +194,7 @@ above.</p> </tr> <tr> <td>Motorola</td> - <td><code>22B8</code></td> + <td><code>22b8</code></td> </tr> <tr> <td>NEC</td> @@ -217,11 +214,11 @@ above.</p> </tr> <tr> <td>Pantech</td> - <td><code>10A9</code></td> + <td><code>10a9</code></td> </tr> <tr> <td>Pegatron</td> - <td><code>1D4D</code></td> + <td><code>1d4d</code></td> </tr> <tr> <td>Philips</td> @@ -229,27 +226,35 @@ above.</p> </tr> <tr> <td>PMC-Sierra</td> - <td><code>04DA</code></td> + <td><code>04da</code></td> </tr> <tr> <td>Qualcomm</td> - <td><code>05C6</code></td> + <td><code>05c6</code></td> </tr> <tr> <td>SK Telesys</td> - <td><code>1F53</code></td> + <td><code>1f53</code></td> </tr> <tr> <td>Samsung</td> - <td><code>04E8</code></td> + <td><code>04e8</code></td> </tr> <tr> <td>Sharp</td> - <td><code>04DD</code></td> + <td><code>04dd</code></td> + </tr> + <tr> + <td>Sony</td> + <td><code>054c</code></td> </tr> <tr> <td>Sony Ericsson</td> - <td><code>0FCE</code></td> + <td><code>0fce</code></td> + </tr> + <tr> + <td>Teleepoch</td> + <td><code>2340</code></td> </tr> <tr> <td>Toshiba</td> @@ -257,6 +262,6 @@ above.</p> </tr> <tr> <td>ZTE</td> - <td><code>19D2</code></td> + <td><code>19d2</code></td> </tr> </table> diff --git a/docs/html/guide/developing/devices/emulator.jd b/docs/html/guide/developing/devices/emulator.jd index 8211275..5edd1f5 100644 --- a/docs/html/guide/developing/devices/emulator.jd +++ b/docs/html/guide/developing/devices/emulator.jd @@ -9,28 +9,58 @@ parent.link=index.html <h2>In this document</h2> <ol> <li><a href="#overview">Overview</a></li> + <li><a href="#avds">Android Virtual Devices and the Emulator</a></li> <li><a href="#starting">Starting and Stopping the Emulator</a></li> - <li><a href="#starting">Android Virtual Devices and the Emulator</a></li> - <li><a href="#controlling">Controlling the Emulator</a></li> - <li><a href="#startup-options">Emulator Startup Options</a></li> + <li><a href="#apps">Installing Applications on the Emulator</a></li> + <li><a href="#acceleration">Using Hardware Acceleration</a> + <ol> + <li><a href="#accel-graphics">Configuring Graphics Acceleration</a></li> + <li><a href="#accel-vm">Configuring Virtual Machine Acceleration</a></li> + </ol> + </li> + <li><a href="#sdcard">SD Card Emulation</a> + <ol> + <li><a href="#sdcard-creating">Creating an SD card image</a></li> + <li><a href="#sdcard-files">Copying files to an SD card image</a></li> + <li><a href="#sdcard-loading">Loading an SD card image</a></li> + </ol> + </li> <li><a href="#diskimages">Working with Emulator Disk Images</a> <ol> - <li><a href="#defaultimages">Default Images</a></li> - <li><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></li> - <li><a href="#temporaryimages">Temporary Images</a></li> + <li><a href="#defaultimages">Default image files</a></li> + <li><a href="#runtimeimages">Runtime images: user data and SD card</a></li> + <li><a href="#temporaryimages">Temporary images</a></li> </ol> </li> <li><a href="#emulatornetworking">Emulator Networking</a> <ol> <li><a href="#networkaddresses">Network Address Space</a></li> <li><a href="#networkinglimitations">Local Networking Limitations</a></li> - <li><a href="#redirections">Using Network Redirections</a></li> + <li><a href="#redirection">Using Network Redirection</a></li> <li><a href="#dns">Configuring the Emulator's DNS Settings</a></li> <li><a href="#proxy">Using the Emulator with a Proxy</a></li> <li><a href="#connecting">Interconnecting Emulator Instances</a></li> <li><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></li> </ol> </li> + <li><a href="#console">Using the Emulator Console</a> + <ol> + <li><a href="#portredirection">Port Redirection</a></li> + <li><a href="#geo">Geo Location Provider Emulation</a></li> + <li><a href="#events">Hardware Events Emulation</a></li> + <li><a href="#power">Device Power Characteristics</a></li> + <li><a href="#netstatus">Network Status</a></li> + <li><a href="#netdelay">Network Delay Emulation</a></li> + <li><a href="#netspeed">Network Speed Emulation</a></li> + <li><a href="#telephony">Telephony Emulation</a></li> + <li><a href="#sms">SMS Emulation</a></li> + <li><a href="#vm">VM State</a></li> + <li><a href="#window">Emulator Window</a></li> + <li><a href="#terminating">Terminating an Emulator Instance</a></li> + </ol> + </li> + <li><a href="#limitations">Emulator Limitations</a></li> + <li><a href="#troubleshooting">Troubleshooting Emulator Problems</a></li> </ol> <h2>See also</h2> @@ -44,7 +74,7 @@ parent.link=index.html <img src="{@docRoot}images/emulator-wvga800l.png" alt="Image of the Android Emulator" width="367" height="349" style="margin-left:2em;float:right;"/> <p>The Android SDK includes a virtual mobile device emulator -that runs on your computer. The emulator lets you prototype, develop, and test +that runs on your computer. The emulator lets you prototype, develop and test Android applications without using a physical device. </p> <p>The Android emulator mimics all of the hardware and software features @@ -52,7 +82,7 @@ of a typical mobile device, except that it cannot place actual phone calls. It provides a variety of navigation and control keys, which you can "press" using your mouse or keyboard to generate events for your application. It also provides a screen in which your application is displayed, together with any other -Android applications running. </p> +active Android applications. </p> <p>To let you model and test your application more easily, the emulator utilizes Android Virtual Device (AVD) configurations. AVDs let you define certain hardware @@ -62,35 +92,34 @@ the emulator, it can use the services of the Android platform to invoke other applications, access the network, play audio and video, store and retrieve data, notify the user, and render graphical transitions and themes. </p> -<p>The emulator also includes a variety of debug capabilities, such as a console -from which you can log kernel output, simulate application interrupts (such as -arriving SMS messages or phone calls), and simulate latency effects and dropouts -on the data channel.</p> +<p>The emulator also includes a variety of debug capabilities, such as a console +from which you can log kernel output, simulate application interrupts (such as +arriving SMS messages or phone calls), and simulate latency effects and dropouts +on the data network.</p> -<h2 id="overview">Overview</h2> +<h2 id="overview">Overview</h2> -<p>The Android emulator is a QEMU-based application that provides a virtual ARM +<p>The Android emulator is an application that provides a virtual mobile device on which you can run your Android applications. It runs a full Android system stack, down to the kernel level, that includes a set of preinstalled applications (such as the dialer) that you can access from your applications. You can choose what version of the Android system you want to run in the emulator by configuring AVDs, and you can also customize the mobile device skin and key mappings. When launching the emulator and at runtime, -you can use a variety of commands and options to control the its behaviors. +you can use a variety of commands and options to control its behavior. </p> -<p>The Android system image distributed in the SDK contains ARM machine code for -the Android Linux kernel, the native libraries, the Dalvik VM, and the various -Android package files (such as for for the Android framework and preinstalled -applications). The emulator's QEMU layers provide dynamic binary translation of -the ARM machine code to the OS and processor architecture of your development -machine. </p> +<p>The Android system images available through the Android SDK Manager contain +code for the Android Linux kernel, the native libraries, the Dalvik VM, and the +various Android packages (such as the Android framework and preinstalled +applications). The emulator provides dynamic binary translation of device +machine code to the OS and processor architecture of your development +machine.</p> -<p>Adding custom capabilities to the underlying QEMU services, the Android -emulator supports many hardware features likely to be found on mobile devices, -including: </p> +<p>The Android emulator supports many hardware features likely to be found on +mobile devices, including: </p> <ul> <li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li> @@ -101,41 +130,37 @@ buttons)</li> <li>Flash memory partitions (emulated through disk image files on the development machine)</li> <li>A GSM modem, including a simulated SIM Card</li> + <li>A camera, using a webcam connected to your development computer.</li> + <li>Sensors like an accelerometer, using data from a USB-connected Android device.</li> </ul> -<p>The sections below provide more information about the emulator and how to use -it for developing Android applications.</p> - +<p>The following sections describe the emulator and its use for development of Android +applications in more detail.</p> -<a name="avds"></a> -<h2>Android Virtual Devices and the Emulator</h2> +<h2 id="avds">Android Virtual Devices and the Emulator</h2> <p>To use the emulator, you first must create one or more AVD configurations. In each configuration, you specify an Android platform to run in the emulator and the set of hardware options and emulator skin you want to use. Then, when you launch the emulator, you specify the AVD configuration that you want to load. </p> -<p>To specify the AVD you want to load when starting the emulator, you use the -<code>-avd</code> argument, as shown in the previous section. </p> - <p>Each AVD functions as an independent device, with its own private storage for user data, SD card, and so on. When you launch the emulator with an AVD configuration, it automatically loads the user data and SD card data from the AVD directory. By default, the emulator stores the user data, SD card data, and cache in the AVD directory.</p> <p>To create and manage AVDs you use the AVD Manager UI or the <code>android</code> tool -that is included in the SDK. +that is included in the SDK. For complete information about how to set up AVDs, see <a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> -<a name="starting"></a> -<h2>Starting and Stopping the Emulator</h2> +<h2 id="starting">Starting and Stopping the Emulator</h2> <p>During development and testing of your application, you install and run your application in the Android emulator. You can launch the emulator as a standalone -application, from a command line, or you can use it as part of your Eclipse +application from a command line, or you can run it from within your Eclipse development environment. In either case, you specify the AVD configuration to load and any startup options you want to use, as described in this document. </p> @@ -144,20 +169,24 @@ load and any startup options you want to use, as described in this document. depending on your needs, you can start multiple emulator instances and run your application in more than one emulated device. You can use the emulator's built-in commands to simulate GSM phone calling or SMS between emulator -instances, and you can set up network redirections that allow emulators to send +instances, and you can set up network redirection that allows emulators to send data to one another. For more information, see <a href="#telephony">Telephony Emulation</a>, <a href="#sms">SMS Emulation</a>, and <a href="#emulatornetworking">Emulator Networking</a></p> -<p>To start an instance of the emulator from the command line, change to the +<p>To start an instance of the emulator from the command line, navigate to the <code>tools/</code> folder of the SDK. Enter <code>emulator</code> command like this: </p> -<pre>emulator -avd <avd_name></pre> +<pre>emulator -avd <avd_name> [<options>]</pre> + +<p>This initializes the emulator, loads an AVD configuration and displays the emulator +window. For more information about command line options for the emulator, see the +<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> tool reference.</p> -<p>This initializes the emulator and loads an AVD configuration (see the next -section for more information about AVDs). You will see the emulator window -appear on your screen. </p> +<p class="note"><strong>Note:</strong> You can run multiple +instances of the emulator concurrently, each with its own AVD configuration and +storage area for user data, SD card, and so on.</p> <p>If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically, when you run or debug @@ -171,585 +200,435 @@ on the Emulator</a> for information about how to install your application.</p> <p>To stop an emulator instance, just close the emulator's window.</p> <p>For a reference of the emulator's startup commands and keyboard mapping, see -the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> document.</p> +the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> tool +reference.</p> + + +<h2 id="apps">Installing Applications on the Emulator</h2> + +<p>If you don't have access to Eclipse or the ADT Plugin, you can install your application on the +emulator using the <a href="{@docRoot}guide/developing/tools/adb.html#move">adb</a> utility. Before +installing the application, you need to build and package it into an <code>.apk</code> as described +in <a href="{@docRoot}guide/developing/building/index.html">Building and +Running Apps</a>. Once the application is installed, you can start the emulator from the command +line as described previously, using any startup options necessary. +When the emulator is running, you can also connect to the emulator instance's +<a href="#console">console</a> to issue commands as needed.</p> + +<p>As you update your code, you periodically package and install it on the emulator. +The emulator preserves the application and its state data across restarts, +in a user-data disk partition. To ensure that the application runs properly +as you update it, you may need to delete the emulator's user-data partition. +To do so, start the emulator with the <code>-wipe-data</code> option. +For more information about the user-data partition and other emulator storage, +see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> +<h2 id="acceleration">Using Hardware Acceleration</h2> +<p>In order to make the Android emulator run faster and be more responsive, you can configure it to +take advantage of hardware acceleration, using a combination of configuration options, specific +Android system images and hardware drivers.</p> -<a name="controlling"></a> +<h3 id="accel-graphics">Configuring Graphics Acceleration</h3> +<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the graphics +acceleration feature for the emulator is experimental; be alert for incompatibilities and +errors when using this feature. </p> -<h2>Controlling the Emulator</h2> +<p>Graphics acceleration for the emulator takes advantage of your development computer's graphics +hardware, specifically its graphics processing unit (GPU), to make screen drawing faster. To use +the graphics acceleration feature, you must have the following versions of the Android development +tools installed:</p> -<p>You can use emulator <a href="#startup-options">startup options</a> and <a -href="#console">console commands</a> to control the behaviors and -characteristics of the emulated environment itself. -</p> +<ul> + <li>Android SDK Tools, Revision 17 or higher</li> + <li>Android SDK Platform API 15, Revision 3 or higher</li> +</ul> -<p>When the emulator is running, you can interact with the emulated mobile -device just as you would an actual mobile device, except that you use your mouse -pointer to "touch" the touchscreen and your keyboard keys to -"press" the simulated device keys. </p> +<p>Use the <a href="{@docRoot}sdk/installing.html#AddingComponents">Android SDK +Manager</a> to install these components:</p> -<p>The table below summarizes the mappings between the emulator keys and and -the keys of your keyboard. </p> +<p class="note"><strong>Note:</strong> Not all applications are compatible with graphics hardware +acceleration. In particular, the Browser application and applications using the {@link +android.webkit.WebView} component are not compatible with graphics acceleration.</p> -<table border="0" style="clear:left;"> - <tr> - <th>Emulated Device Key </th> - <th>Keyboard Key </th> - </tr> - <tr> - <td>Home</td> - <td>HOME</td> - </tr> - <tr> - <td>Menu (left softkey)</td> - <td>F2 <em>or</em> Page-up button</td> - </tr> - <tr> - <td>Star (right softkey)</td> - <td>Shift-F2 <em>or </em>Page Down</td> - </tr> - <tr> - <td>Back</td> - <td>ESC</td> - </tr> - <tr> - <td>Call/dial button </td> - <td>F3</td> - </tr> - <tr> - <td>Hangup/end call button</td> - <td>F4</td> - </tr> - <tr> - <td>Search</td> - <td>F5 </td> - </tr> - <tr> - <td>Power button</td> - <td>F7 </td> - </tr> - <tr> - <td>Audio volume up button</td> - <td>KEYPAD_PLUS, Ctrl-5</td> - </tr> +<p>To configure an AVD to use graphics acceleration:</p> - <tr> - <td>Audio volume down button</td> - <td>KEYPAD_MINUS, Ctrl-F6</td> - </tr> - <tr> - <td>Camera button</td> - <td>Ctrl-KEYPAD_5, Ctrl-F3</td> - </tr> - <tr> - <td>Switch to previous layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_7, Ctrl-F11</td> - </tr> - <tr> - <td>Switch to next layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_9, Ctrl-F12</td> - </tr> - <tr> - <td>Toggle cell networking on/off</td> - <td>F8</td> - </tr> - <tr> - <td>Toggle code profiling</td> - <td>F9 (only with <code>-trace</code> startup option)</td> - </tr> - <tr> - <td>Toggle fullscreen mode</td> - <td>Alt-Enter</td> - </tr> - <tr> - <td>Toggle trackball mode</td> - <td>F6</td> - </tr> - <tr> - <td>Enter trackball mode temporarily (while key is pressed)</td> - <td>Delete</td> - </tr> - <tr> - <td>DPad left/up/right/down</td> - <td>KEYPAD_4/8/6/2</td> - </tr> - <tr> - <td>DPad center click</td> - <td>KEYPAD_5</td> - </tr> - <tr> - <td>Onion alpha increase/decrease</td> - <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> - </tr> -</table> +<ol> + <li>Make sure you have the required SDK components installed (listed above).</li> + <li>Start the AVD Manager and create a new AVD with the <strong>Target</strong> value of +<strong>Android 4.0.3 (API Level 15)</strong>, revision 3 or higher.</li> + <li>If you want to have graphics acceleration enabled by default for this AVD, in the +<strong>Hardware</strong> section, click <strong>New</strong>, select <strong>GPU emulation</strong> +and set the value to <strong>Yes</strong>. + <p class="note"><strong>Note:</strong> You can also enable graphics acceleration when you +start an emulator using command line options as describe in the next section.</p> + </li> + <li>Name the AVD instance and select any other configuration options. + <p class="caution"><strong>Caution:</strong> Do not select the <strong>Snapshot: Enabled</strong> +option. Snapshots are not supported for emulators with graphics acceleration enabled.</p> + </li> + <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li> +</ol> -<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> +<p>If you set <strong>GPU emulation</strong> to <strong>Yes</strong> for your AVD, then graphics +acceleration is automatically enabled when you run it. If you did not enable <strong>GPU +emulation</strong> when you created the AVD, you can still enable it at runtime.</p> -<h2 id="emulator">Emulator Startup Options</h2> +<p>To enable graphics acceleration at runtime for an AVD:</p> -<p>The emulator supports a variety of options that you can specify -when launching the emulator, to control its appearance or behavior. -Here's the command-line usage for launching the emulator with options: </p> +<ul> + <li>If you are running the emulator from the command line, just include the {@code -gpu on} +option: +<pre>emulator -avd <avd_name> -gpu on</pre> + <p class="note"><strong>Note:</strong> You must specify an AVD configuration that uses +Android 4.0.3 (API Level 15, revision 3) or higher system image target. Graphics acceleration is not +available for earlier system images.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application using an AVD with +the {@code -gpu on} option enabled: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the AVD you created in the previous procedure.</li> + <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter:<br> + {@code -gpu on}</li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> -<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> -<p>The table below summarizes the available options.</p> +<h3 id="accel-vm">Configuring Virtual Machine Acceleration</h2> -<table> -<tr> - <th width="10%" >Category</th> - <th width="20%" >Option</th> - <th width="30%" >Description</th> - <th width="40%" >Comments</th> -</tr> +<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the virtual machine +acceleration feature for the emulator is experimental; be alert for incompatibilities and errors +when using this feature.</p> + +<p>Many modern CPUs provide extensions for running virtual machines (VMs) more efficiently. Taking +advantage of these extensions with the Android emulator requires some additional configuration of +your development system, but can significantly improve the execution speed. Before attempting to use +this type of acceleration, you should first determine if your development system’s CPU supports one +of the following virtualization extensions technologies:</p> -<tr> - <td rowspan="9">Help</td> - <td><code>-help</code></td> - <td>Print a list of all emulator options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-all</code></td> - <td>Print help for all startup options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-<option></code></td> - <td>Print help for a specific startup option.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-debug-tags</code></td> - <td>Print a list of all tags for <code>-debug <tags></code>.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-disk-images</code></td> - <td>Print help for using emulator disk images.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-environment</code></td> - <td>Print help for emulator environment variables.</td> - <td> </td> -</tr><tr> - <td><code>-help-keys</code></td> - <td>Print the current mapping of keys.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-keyset-file</code></td> - <td>Print help for defining a custom key mappings file.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-virtual-device</code></td> - <td>Print help for Android Virtual Device usage.</td> - <td> </td> -</tr> -<tr> - <td>AVD</td> - <td><code>-avd <avd_name></code> or <br> - <code>@<avd_name></code></td> - <td><strong>Required</strong>. Specifies the AVD to load for this emulator - instance.</td> - <td>You must create an AVD configuration before launching the emulator. For - information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing - Virtual Devices with AVD Manager</a>.</td> -<tr> - <td rowspan="7">Disk Images</td> - <td><code>-cache <filepath></code></td> - <td>Use <filepath> as the working cache partition image. </td> - <td>Optionally, you can specify a path relative to the current working directory. - If no cache file is specified, the emulator's default behavior is to use a temporary file instead. - <p>For more information on disk images, use <code>-help-disk-images</code>.</p> -</td></tr> -<tr> - <td><code>-data <filepath></code></td> - <td>Use <filepath> as the working user-data disk image. </td> - <td>Optionally, you can specify a path relative to the current working directory. - If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" - in the storage area of the AVD being used (see <code>-avd</code>). -</td></tr> -<!-- -<tr> - <td><code>-datadir <dir></code></td> - <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> - <td><code><dir></code> is a path relative to the current working directory. - -<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image -in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information -on disk images, use <code>-help-disk-images</code>.</p> -</td></tr> ---> -<!-- -<tr> - <td><code>-image <filepath></code></td> - <td>Use <filepath> as the system image.</td> - <td>Optionally, you can specify a path relative to the current working directory. - Default is <system>/system.img.</td> -</tr> ---> -<tr> - <td><code>-initdata <filepath></code></td> - <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents - of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> - <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. - <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> -</tr> -<!-- -<tr> - <td><code>-kernel <filepath></code></td> - <td>Use <filepath> as the emulated kernel.</td> - <td>Optionally, you can specify a path relative to the current working directory. </td> -</tr> ---> -<tr> - <td><code>-nocache</code></td> - <td>Start the emulator without a cache partition.</td> - <td>See also <code>-cache <file></code>.</td> -</tr> -<tr> - <td><code>-ramdisk <filepath></code></td> - <td>Use <filepath> as the ramdisk image.</td> - <td>Default value is <code><system>/ramdisk.img</code>. - <p>Optionally, you can specify a path relative to the current working directory. - For more information on disk images, use <code>-help-disk-images</code>.</p> -</td> -</tr> -<tr> - <td><code>-sdcard <filepath></code></td> - <td>Use <file> as the SD card image.</td> - <td>Default value is <code><system>/sdcard.img</code>. - <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> -</td> -</tr> -<!-- -<tr> - <td><code>-system <dirpath></code></td> - <td>Search for system, ramdisk and user data images in <dir>.</td> - <td><code><dir></code> is a directory path relative to the current - working directory.</td> -</tr> ---> -<tr> - <td><code>-wipe-data</code></td> - <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and - <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, - then copies the contents of the file at <code>-inidata</code> data to the image file before starting. - </td> - <td>See also <code>-initdata</code>. - <p>For more information on disk images, use <code>-help-disk-images</code>.</p> -</td> -</tr> -<tr> - <td rowspan="9">Debug</td> - <td><code>-debug <tags></code></td> - <td>Enable/disable debug messages for the specified debug tags.</td> - <td><code><tags></code> is a space/comma/column-separated list of debug component names. - Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> -</tr> -<tr> - <td><code>-debug-<tag></code></td> - <td>Enable/disable debug messages for the specified debug tag.</td> - <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td> -</tr> -<tr> - <td><code>-debug-no-<tag></code></td> - <td>Disable debug messages for the specified debug tag.</td> -</tr> -<tr> - <td><code>-logcat <logtags></code></td> - <td>Enable logcat output with given tags.</td> - <td>If the environment variable ANDROID_LOG_TAGS is defined and not - empty, its value will be used to enable logcat output by default.</td> -</tr> -<tr> - <td><code>-shell</code></td> - <td>Create a root shell console on the current terminal.</td> - <td>You can use this command even if the adb daemon in the emulated system is broken. - Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> -</tr> -<tr> - <td><code>-shell-serial <device></code></td> - <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character - device to use for communication with the shell.</td> - <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at - <a href="http://www.nongnu.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> - for a list of device types. - -<p>Here are some examples: </p> <ul> - <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li> - <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li> - <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li> - <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li> - </ul> -</td> -</tr> -<tr> - <td><code>-show-kernel <name></code></td> - <td>Display kernel messages.</td> - <td> </td> -</tr> -<tr> - <td><code>-trace <name></code></td> - <td>Enable code profiling (press F9 to start), written to a specified file.</td> - <td> </td> -</tr> -<tr> - <td><code>-verbose</code></td> - <td>Enable verbose output.</td> - <td>Equivalent to <code>-debug-init</code>. -<p>You can define the default verbose output options used by emulator instances in the Android environment variable -ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: -<code>-debug-<tags>.</code> </p> -<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: -<p><code>ANDROID_VERBOSE=init,modem</code></p> -<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> -</td> -</tr> -<tr> - <td rowspan="6">Media</td> - <td><code>-audio <backend></code></td> - <td>Use the specified audio backend.</td> - <td> </td> -</tr> -<tr> - <td><code>-audio-in <backend></code></td> - <td>Use the specified audio-input backend.</td> - <td> </td> -</tr> -<tr> - <td><code>-audio-out <backend></code></td> - <td>Use the specified audio-output backend.</td> - <td> </td> -</tr> -<!--<tr> - <td><code>-mic <device or file></code></td> - <td>Use device or WAV file for audio input.</td> - <td> </td> -</tr> ---> -<tr> - <td><code>-noaudio</code></td> - <td>Disable audio support in the current emulator instance.</td> - <td> </td> -</tr> -<tr> - <td><code>-radio <device></code></td> - <td>Redirect radio modem interface to a host character device.</td> - <td> </td></tr> -<tr> - <td><code>-useaudio</code></td> - <td>Enable audio support in the current emulator instance.</td> - <td>Enabled by default. </td> -</tr> + <li>Intel Virtualization Technology (VT, VT-x, vmx) extensions</li> + <li>AMD Virtualization (AMD-V, SVM) extensions (only supported for Linux)</li> +</ul> -<tr> - <td rowspan="7">Network</td> - <td><code>-dns-server <servers></code></td> - <td>Use the specified DNS server(s). </td> - <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or - IP addresses.</td> -</tr> -<tr> - <td><code>-http-proxy <proxy></code></td> - <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td> - <td>The value of <code><proxy></code> can be one of the following:<br> - <code>http://<server>:<port></code><br> - <code>http://<username>:<password>@<server>:<port></code> - <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied, - the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching - the <code><proxy></code> format described above.</p></td> -</tr> -<tr> - <td><code>-netdelay <delay></code></td> - <td>Set network latency emulation to <delay>.</td> - <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for - supported <code><delay></code> values. </td> -</tr> -<tr> - <td><code>-netfast</code></td> - <td>Shortcut for <code>-netspeed full -netdelay none</code></td> - <td> </td></tr> -<tr> - <td><code>-netspeed <speed></code></td> - <td>Set network speed emulation to <speed>.</td> - <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for - supported <code><speed></code> values. </td> -</tr> -<tr> - <td><code>-port <port></code></td> - <td>Set the console port number for this emulator instance to <code><port></code>.</td> - <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 - must also be free and will be reserved for ADB.</td> -</tr> -<tr> - <td><code>-report-console <socket></code></td> - <td>Report the assigned console port for this emulator instance to a remote third party - before starting the emulation. </td> - <td><code><socket></code> must use one of these formats: +<p>The specifications from the manufacturer of your CPU should indicate if it supports +virtualization extensions. If your CPU does not support one of these virtualization technologies, +then you cannot use virtual machine acceleration.</p> -<p><code>tcp:<port>[,server][,max=<seconds>]</code></br> -<code>unix:<port>[,server][,max=<seconds>]</code></p> +<p class="note"><strong>Note:</strong> Virtualization extensions are typically enabled through +your computer's BIOS and are frequently turned off by default. Check the documentation for your +system's motherboard to find out how to enable virtualization extensions.</p> -<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> -</tr> -<tr> - <td rowspan="8">System</td> - <td><code>-cpu-delay <delay></code></td> - <td>Slow down emulated CPU speed by <delay> </td> - <td>Supported values for <delay> are integers between 0 and 1000. - -<p>Note that the <delay> does not correlate to clock speed or other absolute metrics -— it simply represents an abstract, relative delay factor applied non-deterministically -in the emulator. Effective performance does not always -scale in direct relationship with <delay> values.</p> -</td> -</tr> -<tr> - <td><code>-gps <device></code></td> - <td>Redirect NMEA GPS to character device.</td> - <td>Use this command to emulate an NMEA-compatible GPS unit connected to - an external character device or socket. The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at - <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. -</td> -</tr> -<tr> - <td><code>-nojni</code></td> - <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> -<tr> - <td><code>-qemu</code></td> - <td>Pass arguments to qemu.</td> - <td> </td></tr> -<tr> - <td><code>-qemu -h</code></td> - <td>Display qemu help.</td> - <td></td></tr> -<tr> - <td><code>-radio <device></code></td> - <td>Redirect radio mode to the specified character device.</td> - <td>The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at -<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. -</td> -</tr> -<tr> - <td><code>-timezone <timezone></code></td> - <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td> - <td><code><timezone></code> must be specified in zoneinfo format. For example: -<p>"America/Los_Angeles"<br> -"Europe/Paris"</p> -</td> -</tr> -<tr> - <td><code>-version</code></td> - <td>Display the emulator's version number.</td> - <td> </td> -</tr> -<tr> - <td rowspan="12">UI</td> - <td><code>-dpi-device <dpi></code></td> - <td>Scale the resolution of the emulator to match the screen size - of a physical device.</td> - <td>The default value is 165. See also <code>-scale</code>.</td> -</tr> -<tr> - <td><code>-no-boot-anim</code></td> - <td>Disable the boot animation during emulator startup.</td> - <td>Disabling the boot animation can speed the startup time for the emulator.</td> -</tr> -<tr> - <td><code>-no-window</code></td> - <td>Disable the emulator's graphical window display.</td> - <td> </td> -</tr> -<tr> - <td><code>-scale <scale></code></td> - <td>Scale the emulator window. </td> - <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" - tells the emulator to select the best window size.</td> -</tr> -<tr> - <td><code>-raw-keys</code></td> - <td>Disable Unicode keyboard reverse-mapping.</td> - <td> </td></tr> -<tr> - <td><code>-noskin</code></td> - <td>Don't use any emulator skin.</td> - <td> </td></tr> -<tr> - <td><code>-keyset <file></code></td> - <td>Use the specified keyset file instead of the default.</td> - <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. - For more information, use <code>-help-keyset</code> to print information about this topic. -</td> -</tr> -<tr> - <td><code>-onion <image></code></td> - <td>Use overlay image over screen.</td> - <td>No support for JPEG. Only PNG is supported.</td></tr> -<tr> - <td><code>-onion-alpha <percent></code></td> - <td>Specify onion skin translucency value (as percent). - <td>Default is 50.</td> -</tr> -<tr> - <td><code>-onion-rotation <position></code></td> - <td>Specify onion skin rotation. - <td><code><position></code> must be one of the values 0, 1, 2, 3.</td> -</tr> -<tr> - <td><code>-skin <skinID></code></td> - <td>This emulator option is deprecated. </td> - <td>Please set skin options using AVDs, rather than by using this emulator -option. Using this option may yield unexpected and in some cases misleading -results, since the density with which to render the skin may not be defined. -AVDs let you associate each skin with a default density and override the default -as needed. For more information, see <a -href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices -with AVD Manager</a>. -</td> -</tr> -<tr> - <td><code>-skindir <dir></code></td> - <td>This emulator option is deprecated. </td> - <td>See comments for <code>-skin</code>, above.</td></tr> -</table> +<p>Once you have determined that your CPU supports virtualization extensions, make sure you can work +within these additional requirements of running an emulator inside an accelerated virtual +machine:</p> + +<ul> + <li><strong>x86 AVD Only</strong> - You must use an AVD that is uses an x86 system image target. +AVDs that use ARM-based system images cannot be accelerated using the emulator configurations +described here.</li> + <li><strong>Not Inside a VM</strong> - You cannot run a VM-accelerated emulator inside another +virtual machine, such as a VirtualBox or VMWare-hosted virtual machine. You must run the emulator +directly on your system hardware.</li> + <li><strong>Other VM Drivers</strong> - If you are running another virtualization technology on +your system such as VirtualBox or VMWare, you may need to unload the driver for that virtual machine +hosting software before running an accelerated emulator.</li> + <li><strong>OpenGL® Graphics</strong> - Emulation of OpenGL ES graphics may not perform at the +same level as an actual device.</li> +</ul> + +<p>To use virtual machine acceleration with the emulator, you need the following version of Android +development tools. Use the <a href="{@docRoot}sdk/installing.html#AddingComponents">Android SDK +Manager</a> to install these components:</p> + +<ul> + <li>Android SDK Tools, Revision 17 or higher</li> + <li>Android x86-based system image</li> +</ul> + +<p>If your development environment meets all of the requirements for running a VM-accelerated +emulator, you can use the AVD Manager to create an x86-based AVD configuration:</p> + +<ol> + <li>In the Android SDK Manager, make sure you have an x86-based <strong>System Image</strong> + installed for your target Android version. If you do not have an x86 <strong>System + Image</strong> installed, select one in the Android SDK Manager and install it. + <p class="note"><strong>Tip:</strong> System images are listed under each API Level in the SDK + Manager. An x86 system image may not be available for all API levels.</p> + </li> + <li>Start the AVD Manager and create a new AVD with an x86 value for the +<strong>CPU/ABI</strong> field. You may need to select a specific <strong>Target</strong> value, or +select a <strong>Target</strong> value and then select a specific <strong>CPU/ABI</strong> +option.</li> + <li>Name the emulator instance and select any other configuration options.</li> + <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li> +</ol> + +<h4 id="vm-windows">Configuring VM Acceleration on Windows</h4> + +<p>Virtual machine acceleration for Windows requires the installation of the Intel Hardware +Accelerated Execution Manager (Intel HAXM). The software requires an Intel CPU with +Virtualization Technology (VT) support and one of the following operating systems:</p> + +<ul> + <li>Windows 7 (32/64-bit)</li> + <li>Windows Vista (32/64-bit)</li> + <li>Windows XP (32-bit only)</li> +</ul> + +<p>To install the virtualization driver:</p> + +<ol> + <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel +Hardware Accelerated Execution Manager</strong>.</li> + <li>After the download completes, execute {@code +<sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.exe}.</li> + <li>Follow the on-screen instructions to complete installation.</li> + <li>After installation completes, confirm that the virtualization driver is operating correctly by +opening a command prompt window and running the following command: + <pre>sc query intelhaxm</pre> + <p>You should see a status message including the following information:</p> +<pre> +SERVICE_NAME: intelhaxm + ... + STATE : 4 RUNNING + ... +</pre> + </li> +</ol> + +<p>To run an x86-based emulator with VM acceleration:</p> +<ul> + <li>If you are running the emulator from the command line, just specify an x86-based AVD: +<pre>emulator -avd <avd_name></pre> + <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration +name, otherwise VM acceleration will not be enabled.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application with an x86-based +AVD: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the x86-based AVD you created previously.</li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> + +<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running +its installer.</p> + +<p>You can stop using the virtualization driver by uninstalling it. Re-run the installer or use +the Control Panel to remove the software.</p> + + +<h4 id="vm-mac">Configuring VM Acceleration on Mac</h4> + +<p>Virtual machine acceleration on a Mac requires the installation of the Intel Hardware Accelerated +Execution Manager (Intel HAXM) kernel extension to allow the Android emulator to make use of CPU +virtualization extensions. The kernel extension is compatible with Mac OS X Snow Leopard (version +10.6.0) and higher.</p> + +<p>To install the Intel HAXM kernel extension:</p> + +<ol> + <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel +Hardware Accelerated Execution Manager</strong>. + <li>After the download completes, execute + {@code <sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.dmg}.</li> + <li>Double click the <strong>IntelHAXM.mpkg</strong> icon to begin installation.</li> + <li>Follow the on-screen instructions to complete installation.</li> + <li>After installation completes, confirm that the new kernel extension is operating correctly by +opening a terminal window and running the following command: + <pre>kextstat | grep intel</pre> + <p>You should see a status message containing the following extension name, indicating that the + kernel extension is loaded:</p> + <pre>com.intel.kext.intelhaxm</pre> + </li> +</ol> + +<p>To run an x86-based emulator with VM acceleration:</p> +<ul> + <li>If you are running the emulator from the command line, just specify an x86-based AVD: +<pre>emulator -avd <avd_name></pre> + <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration +name, otherwise VM acceleration will not be enabled.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application with an x86-based +AVD: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the x86-based AVD you created previously.</li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> + +<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running +the installer.</p> + +<p>You can stop using the virtualization kernel driver by uninstalling it. Before removing it, shut +down any running x86 emulators. To unload the virtualization kernel driver, run the following +command in a terminal window:</p> + +<pre>sudo /System/Library/Extensions/intelhaxm.kext/Contents/Resources/uninstall.sh</pre> + +<h4 id="vm-linux">Configuring VM Acceleration on Linux</h4> + +<p>Linux-based systems support virtual machine acceleration through the KVM software package. Follow +<a href="https://www.google.com/?q=kvm+installation">instructions for installing KVM</a> on your +Linux system, and verify that KVM is enabled. In addition to following the installation +instructions, be aware of these configuration requirements:</p> + +<ul> + <li>Running KVM requires specific user permissions, make sure you have sufficient permissions +according to the KVM installation instructions.</li> + <li>If you use another virtualization technology in your Linux platform, unload its kernel driver +before running the x86 emulator. For example, the VirtualBox driver program is {@code vboxdrv}.</li> +</ul> + +<p>To run an x86-based emulator with VM acceleration:</p> + +<ul> + <li>If you are running the emulator from the command line, start the emulator with an x86-based +AVD and include the KVM options: +<pre>emulator -avd <avd_name> -qemu -m 512 -enable-kvm</pre> + <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration +name, otherwise VM acceleration will not be enabled.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application with an x86-based +AVD and include the KVM options: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the x86-based AVD you created previously.</li> + <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter: + <pre>-qemu -m 512 -enable-kvm</pre> + </li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> + +<p class="note"><strong>Important:</strong> When using the {@code -qemu} command line option, make sure +it is the last parameter in your command. All subsequent options are interpreted as qemu-specific +parameters.</p> + + +<h2 id="sdcard">SD Card Emulation</h2> + +<p>You can create a disk image and then load it to the emulator at startup, to +simulate the presence of a user's SD card in the device. To do this, you can specify +an SD card image when you create an AVD, or you can use the mksdcard utility included +in the SDK.</p> + +<p>The following sections describe how to create an SD card disk image, how to copy +files to it, and how to load it in the emulator at startup. </p> + +<p>Note that you can only load a disk image at emulator startup. Similarly, you +can not remove a simulated SD card from a running emulator. However, you can +browse, send files to, and copy/remove files from a simulated SD card either +with adb or the emulator. </p> + +<p>The emulator supports emulated SDHC cards, so you can create an SD card image +of any size up to 128 gigabytes.</p> + + +<h3 id="sdcard-creating">Creating an SD card image</h3> + +<p>There are several ways of creating an SD card image. The easiest way is to use the +<strong>AVD Manager</strong> to create a new SD card by specifying a size when you create an AVD. +You can also use the {@code android} command line tool when creating an AVD. Just add the +<code>-c</code> option to your command: </p> + +<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> + +<p>The <code>-c</code> option can also be used to to specify a path to an SD card +image for the new AVD. For more information, see <a +href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing Virtual Devices +from the Command Line</a>. +</p> + +<p>You can also use the mksdcard tool, included in the SDK, to create a FAT32 disk +image that you can load in the emulator at startup. You can access mksdcard in +the tools/ directory of the SDK and create a disk image like this: </p> + +<pre>mksdcard <size> <file></pre> + +<p>For example:</p> + +<pre>mksdcard 1024M sdcard1.iso</pre> + +<p>For more information, see <a +href="{@docRoot}guide/developing/tools/mksdcard.html"><code>mksdcard</code></a>.</p> + + +<h3 id="sdcard-files">Copying files to an SD card image</h3> + +<p>Once you have created the disk image, you can copy files to it prior to +loading it in the emulator. To copy files, you can mount the image as a loop +device and then copy the files to it, or you can use a utility such as {@code mtools} to +copy the files directly to the image. The {@code mtools} package is available for Linux, +Mac, and Windows.</p> + +<p>Alternatively, you can use the {@code adb push} command to move files onto an SD card image +while it is loaded in an emulator. For more information see the <a +href="{@docRoot}guide/developing/tools/adb.html#copyfiles">{@code adb push}</a> documentation.</p> + +<h3 id="sdcard-loading">Loading an SD card image</h3> +<p>By default, the emulator loads the SD card image that is stored with the active +AVD (see the <code>-avd</code> startup option).</p> + +<p>Alternatively, you can start the emulator with the +<code>-sdcard</code> flag and specify the name and path of your image (relative +to the current working directory): </p> + +<pre>emulator -sdcard <filepath></pre> -<a name="diskimages"></a> -<h2>Working with Emulator Disk Images</h2> +<h2 id="diskimages">Working with Emulator Disk Images</h2> <p>The emulator uses mountable disk images stored on your development machine to -simulate flash (or similar) partitions on an actual device. For example, it uses +simulate flash (or similar) partitions on an actual device. For example, it uses a disk image containing an emulator-specific kernel, the Android system, a ramdisk image, and writeable images for user data and simulated SD card.</p> <p>To run properly, the emulator requires access to a specific set of disk image -files. By default, the Emulator always looks for the disk images in the -private storage area of the AVD in use. If no images exist there when -the Emulator is launched, it creates the images in the AVD directory based on +files. By default, the Emulator always looks for the disk images in the +private storage area of the AVD in use. If no images exist there when +the Emulator is launched, it creates the images in the AVD directory based on default versions stored in the SDK. </p> -<p class="note"><strong>Note:</strong> The default storage location for -AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and -Settings\<user>\.android\</code> on Windows XP, and +<p class="note"><strong>Note:</strong> The default storage location for +AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and +Settings\<user>\.android\</code> on Windows XP, and <code>C:\Users\<user>\.android\</code> on Windows Vista.</p> <p>To let you use alternate or custom versions of the image files, the emulator provides startup options that override the default locations and filenames of -the image files. When you use the options, the emulator searches for the image +the image files. When you use one of these options, the emulator searches for the image file under the image name or location that you specify; if it can not locate the image, it reverts to using the default names and location.</p> @@ -757,20 +636,19 @@ image, it reverts to using the default names and location.</p> image files, and temporary image files. The sections below describe how to override the location/name of each type of file. </p> -<a name="defaultimages"></a> -<h3>Default Images</h3> +<h3 id="defaultimages">Default image files</h3> -<p>When the emulator launches but does not find an existing user data image in +<p>When the emulator launches, but does not find an existing user data image in the active AVD's storage area, it creates a new one from a default version -included in the SDK. The default user data image is read-only. The image +included in the SDK. The default user data image is read-only. The image files are read-only.</p> <p>The emulator provides the <code>-system <dir></code> startup option to -let you override the location under which the emulator looks for the default +let you override the location where the emulator looks for the default user data image. </p> <p>The emulator also provides a startup option that lets you override the name -of the default user data image, as described in the table below. When you use the +of the default user data image, as described in the following table. When you use the option, the emulator looks in the default directory, or in a custom location (if you specified <code>-system <dir></code>). </p> @@ -810,25 +688,24 @@ option, the emulator looks in the default directory, or in a custom location </table> -<a name="runtimeimages"></a> -<h3>Runtime Images: User Data and SD Card</h3> +<h3 id="runtimeimages">Runtime images: user data and SD card</h3> -<p>At runtime, the emulator reads and writes data on two disk images: a -user-data image and (optionally) an SD card image. This emulates the user-data +<p>At runtime, the emulator reads and writes data to two disk images: a +user-data image and (optionally) an SD card image. These images emulate the user-data partition and removable storage media on actual device. </p> -<p>The emulator provides a default user-data disk image. At startup, the emulator -creates the default image as a copy of the system user-data image (user-data.img), +<p>The emulator provides a default user-data disk image. At startup, the emulator +creates the default image as a copy of the system user-data image (user-data.img), described above. The emulator stores the new image with the files of the active AVD.</p> <!-- -<p>The emulator provides a startup option, <code>-datadir <dir></code>, +<p>The emulator provides a startup option, <code>-datadir <dir></code>, that you can use to override the location under which the emulator looks for the runtime image files. </p> --> -<p>The emulator provides startup options to let you override the actual names and storage -locations of the runtime images to load, as described in the table below. When you use one +<p>The emulator provides startup options to let you override the actual names and storage +locations of the runtime images to load, as described in the following table. When you use one of these options, the emulator looks for the specified file(s) in the current working directory, in the AVD directory, or in a custom location (if you specified a path with the filename). </p> @@ -842,7 +719,7 @@ in the AVD directory, or in a custom location (if you specified a path with the <td><code>userdata-qemu.img</code></td> <td>An image to which the emulator writes runtime user-data for a unique user.</td> <td>Override using <code>-data <filepath></code>, where <code><filepath></code> is the -path the image, relative to the current working directory. If you supply a filename only, +path the image, relative to the current working directory. If you supply a filename only, the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does not exist, the emulator creates an image from the default userdata.img, stores it under the name you specified, and persists user data to it at shutdown. </td> @@ -852,7 +729,7 @@ specified, and persists user data to it at shutdown. </td> <td><code>sdcard.img</code></td> <td>An image representing an SD card inserted into the emulated device.</td> <td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the -path the image, relative to the current working directory. If you supply a filename only, +path the image, relative to the current working directory. If you supply a filename only, the emulator looks for the file in the current working directory. </td> </tr> @@ -864,38 +741,38 @@ the emulator looks for the file in the current working directory. </td> session-specific data. For example, it uses the image to store a unique user's installed application data, settings, databases, and files. </p> -<p>At startup, the emulator attempts to load a user-data image stored during -a previous session. It looks for the file in the current working directory, -in the AVD directory as described above, and at the custom location/name +<p>At startup, the emulator attempts to load a user-data image stored during +a previous session. It looks for the file in the current working directory, +in the AVD directory described in a previous section and at the custom location/name that you specified at startup. </p> <ul> -<li>If it finds a user-data image, it mounts the image and makes it available -to the system for reading/writing of user data. </li> +<li>If it finds a user-data image, it mounts the image and makes it available +to the system for reading and writing of user data. </li> <li>If it does not find one, it creates an image by copying the system user-data image (userdata.img), described above. At device power-off, the system persists -the user data to the image, so that it will be available in the next session. +the user data to the image, so that it will be available in the next session. Note that the emulator stores the new disk image at the location/name that you specify in <code>-data</code> startup option.</li> </ul> <p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator, -each emulator instance now gets its own dedicated storage. There is no need +each emulator instance gets its own dedicated storage. There is no longer a need to use the <code>-d</code> option to specify an instance-specific storage area.</p> <h4>SD Card</h4> <P>Optionally, you can create a writeable disk image that the emulator can use -to simulate removeable storage in an actual device. For information about how to create an +to simulate removeable storage in an actual device. For information about how to create an emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> <p>You can also use the android tool to automatically create an SD Card image -for you, when creating an AVD. For more information, see <a +for you, when creating an AVD. For more information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices with AVD Manager</a>. -<a name="temporaryimages"></a> -<h3>Temporary Images</h3> + +<h3 id="temporaryimages">Temporary Images</h3> <p>The emulator creates two writeable images at startup that it deletes at device power-off. The images are: </p> @@ -909,8 +786,8 @@ device power-off. The images are: </p> persisting it at device power-off. </p> <p>The <code>/cache</code> partition image is initially empty, and is used by -the browser to cache downloaded web pages and images. The emulator provides an -<code>-cache <file></code>, which specifies the name of the file at which +the browser to cache downloaded web pages and images. The emulator provides an +<code>-cache <file></code>, which specifies the name of the file in which to persist the <code>/cache</code> image at device power-off. If <code><file> </code> does not exist, the emulator creates it as an empty file. </p> @@ -918,16 +795,14 @@ to persist the <code>/cache</code> image at device power-off. If <code><file& <code>-nocache</code> option at startup. </p> -<a name="emulatornetworking"></a> -<h2>Emulator Networking</h2> +<h2 id="emulatornetworking">Emulator Networking</h2> <p>The emulator provides versatile networking capabilities that you can use to set up complex modeling and testing environments for your application. The sections below introduce the emulator's network architecture and capabilities. </p> -<a name="networkaddresses"></a> -<h3>Network Address Space</h3> +<h3 id="networkaddresses">Network Address Space</h3> <p>Each instance of the emulator runs behind a virtual router/firewall service that isolates it from your development machine's network interfaces and settings @@ -990,14 +865,13 @@ specific to the Android emulator and will probably be very different on real devices (which are also very likely to be NAT-ed, i.e., behind a router/firewall)</p> -<a name="networkinglimitations"></a> -<h3>Local Networking Limitations</h3> -<p>Each emulator instance runs behind a virtual router, but unlike an actual -device connected to a physical router, the emulated device doesn't have access -to a physical network. Instead it runs as part of a normal application on your -development machine. This means that it is subject to the same networking -limitations as other applications on your machine:</p> +<h3 id="networkinglimitations">Local Networking Limitations</h3> + +<p>Android applications running in an emulator can connect to the network available on your +workstation. However, they connect through the emulator, not directly to hardware, and the emulator +acts like a normal application on your workstation. This means that the emulator, and thus your +Android applications, are subject to some limitations:</p> <ul> <li>Communication with the emulated device may be blocked by a firewall @@ -1016,25 +890,24 @@ host operating system and network.</p> protocols (such as ICMP, used for "ping") might not be supported. Currently, the emulator does not support IGMP or multicast. </p> -<a name="redirections"></a> -<h3>Using Network Redirections</h3> +<h3 id="redirection">Using Network Redirection</h3> <p>To communicate with an emulator instance behind its virtual router, you need -to set up network redirections on the virtual router. Clients can then connect +to set up network redirection on the virtual router. Clients can then connect to a specified guest port on the router, while the router directs traffic to/from that port to the emulated device's host port. </p> -<p>To set up the network redirections, you create a mapping of host and guest +<p>To set up the network redirection, you create a mapping of host and guest ports/addresses on the the emulator instance. There are two ways to set up -network redirections: using emulator console commands and using the ADB tool, as +network redirection: using emulator console commands and using the ADB tool, as described below. </p> -<a name="consoleredir"></a> -<h4>Setting up Redirections through the Emulator Console</h4> + +<h4 id="consoleredir">Setting up Redirection through the Emulator Console</h4> <p>Each emulator instance provides a control console the you can connect to, to issue commands that are specific to that instance. You can use the -<code>redir</code> console command to set up redirections as needed for an +<code>redir</code> console command to set up redirection as needed for an emulator instance. </p> <p>First, determine the console port number for the target emulator instance. @@ -1044,25 +917,25 @@ its console port number, as follows: </p> <pre><code>telnet localhost 5554</code></pre> -<p>Once connected, use the <code>redir</code> command to work with redirections. +<p>Once connected, use the <code>redir</code> command to work with redirection. To add a redirection, use:</p> <pre><code>add <protocol>:<host-port>:<guest-port></code> </pre> -<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, -and <code><host-port></code> and <code><guest-port></code> sets the +<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, +and <code><host-port></code> and <code><guest-port></code> sets the mapping between your own machine and the emulated system, respectively. </p> -<p>For example, the following command sets up a redirection that will handle all +<p>For example, the following command sets up a redirection that handles all incoming TCP connections to your host (development) machine on 127.0.0.1:5000 and will pass them through to the emulated system's 10.0.2.15:6000.:</p> <pre>redir add tcp:5000:6000</pre> <p>To delete a redirection, you can use the <code>redir del</code> command. To -list all redirections for a specific instance, you can use <code>redir -list</code>. For more information about these and other console commands, see +list all redirection for a specific instance, you can use <code>redir +list</code>. For more information about these and other console commands, see <a href="#console">Using the Emulator Console</a>. </p> <p>Note that port numbers are restricted by your local environment. this typically @@ -1071,29 +944,28 @@ administrator privileges. Also, you won't be able to set up a redirection for a host port that is already in use by another process on your machine. In that case, <code>redir</code> generates an error message to that effect. </p> -<a name="adbredir"></a> -<h4>Setting Up Redirections through ADB</h4> +<h4 id="adbredir">Setting Up Redirection through ADB</h4> <p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate -way for you to set up network redirections. For more information, see <a +way for you to set up network redirection. For more information, see <a href="{@docRoot}guide/developing/tools/adb.html#forwardports">Forwarding Ports</a> in the ADB documentation.</p> <p>Note that ADB does not currently offer any way to remove a redirection, except by killing the ADB server.</p> -<a name="dns"></a> -<h3>Configuring the Emulator's DNS Settings</h3> + +<h3 id="dns">Configuring the Emulator's DNS Settings</h3> <p>At startup, the emulator reads the list of DNS servers that your system is currently using. It then stores the IP addresses of up to four servers on this list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, 10.0.2.5 and 10.0.2.6 as needed. </p> -<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing -the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the -addresses by calling the <code>GetNetworkParams()</code> API. Note that this -usually means that the emulator ignores the content of your "hosts" file +<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing +the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the +addresses by calling the <code>GetNetworkParams()</code> API. Note that this +usually means that the emulator ignores the content of your "hosts" file (<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code> on Windows).</P> @@ -1104,8 +976,8 @@ list of server names or IP addresses. You might find this option useful if you encounter DNS resolution problems in the emulated network (for example, an "Unknown Host error" message that appears when using the web browser).</p> -<a name="proxy"></a> -<h3>Using the Emulator with a Proxy</h3> + +<h3 id="proxy">Using the Emulator with a Proxy</h3> <p>If your emulator must access the Internet through a proxy server, you can use the <code>-http-proxy <proxy></code> option when starting the emulator, to @@ -1132,18 +1004,18 @@ startup and uses its value automatically, if defined. </p> <p>You can use the <code>-verbose-proxy</code> option to diagnose proxy connection problems.</p> -<a name="connecting"></a> -<h3>Interconnecting Emulator Instances</h3> + +<h3 id="connecting">Interconnecting Emulator Instances</h3> <p>To allow one emulator instance to communicate with another, you must set up -the necessary network redirections as illustrated below. </p> +the necessary network redirection as illustrated below. </p> <p>Assume that your environment is</p> <ul> <li>A is you development machine</li> <li>B is your first emulator instance, running on A</li> - <li>C is your second emulator instance, running on A too</li> + <li>C is your second emulator instance, also running on A</li> </ul> <p>and you want to run a server on B, to which C will connect, here is how you @@ -1168,10 +1040,11 @@ B:10.0.2.15:<serverPort></code></li> <li>C connects to 10.0.2.2:8080</li> </ul> -<a name="calling"></a> -<h3>Sending a Voice Call or SMS to Another Emulator Instance</h3> +<h3 id="calling">Sending a Voice Call or SMS to Another Emulator Instance</h3> -<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator </p> +<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to +another. To send a voice call or SMS, use the dialer application or SMS application, respectively, +from one of the emulators.</p> <p>To initiate a simulated voice call to another emulator instance:</p> <ol> @@ -1186,16 +1059,23 @@ B:10.0.2.15:<serverPort></code></li> <p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>. -<a name="console"></a> -<h2>Using the Emulator Console</h2> +<h2 id="console">Using the Emulator Console</h2> + +<p>Each running emulator instance provides a console that lets you query and control the emulated +device environment. For example, you can use the console to manage port redirection, network +characteristics, and telephony events while your application is running on the emulator. To +access the console and enter commands, use telnet to connect to the console's port number.</p> -<p>Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number. </p> <p>To connect to the console of any running emulator instance at any time, use this command: </p> <pre>telnet localhost <console-port></pre> -<p>An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> +<p>An emulator instance occupies a pair of adjacent ports: a console port and an {@code adb} port. +The port numbers differ by 1, with the {@code adb} port having the higher port number. The console +of the first emulator instance running on a given machine uses console port 5554 and {@code adb} +port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, +5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> <p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p> @@ -1209,12 +1089,14 @@ B:10.0.2.15:<serverPort></code></li> <p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p> -<p>The sections below describe the major functional areas of the console.</p> +<p>The following sections below describe the major functional areas of the console.</p> + -<a name="portredirection"></a> +<h3 id="portredirection">Port Redirection</h3> + +<p>You can use the console to add and remove port redirection while the emulator is running. After +you connect to the console, manage port redirection by entering the following command:</p> -<h3>Port Redirection</h3> -<p>You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:</p> <pre>redir <list|add|del> </pre> <p>The <code>redir</code> command supports the subcommands listed in the table below. </p> @@ -1225,14 +1107,14 @@ B:10.0.2.15:<serverPort></code></li> <th width="30%" >Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>list</code></td> - <td>List the current port redirections.</td> + <td>List the current port redirection.</td> <td> </td> </tr> - + <tr> <td><code>add <protocol>:<host-port>:<guest-port></code></td> <td>Add a new port redirection.</td> @@ -1244,16 +1126,16 @@ B:10.0.2.15:<serverPort></code></li> <tr> <td><code>del <protocol>:<host-port></code></td> <td>Delete a port redirection.</td> -<td>See above for meanings of <protocol> and <host-port>.</td> +<td>The meanings of <protocol> and <host-port> are listed in the previous row.</td> </tr> </table> -<a name="geo"></a> -<h3>Geo Location Provider Emulation</h3> -<p>The console provides commands to let you set the geo position used by an emulator emulated device. -You can use the <code>geo</code> command to send a simple GPS fix to the emulator, without needing to -use NMEA 1083 formatting. The usage for the command is:</p> +<h3 id="geo">Geo Location Provider Emulation</h3> + +<p>You can use the console to set the geographic location reported to the applications running +inside an emulator. Use the <code>geo</code> command to send a simple GPS fix to the +emulator, with or without NMEA 1083 formatting:</p> <pre>geo <fix|nmea></pre> @@ -1261,11 +1143,11 @@ use NMEA 1083 formatting. The usage for the command is:</p> <table> <tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> + <th width="25%">Subcommand</th> + <th width="30%">Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>fix <longitude> <latitude> [<altitude>]</code></td> <td>Send a simple GPS fix to the emulator instance.</td> @@ -1278,19 +1160,21 @@ use NMEA 1083 formatting. The usage for the command is:</p> </tr> </table> -<p>You can issue the <code>geo</code> command to fix the GPS location as soon as an emulator instance is running. -The emulator creates a mock location provider that sends it to GPS-aware applications as soon as they start and -register location listeners. Any application can query the location manager to obtain the current GPS fix for the -emulated device by calling: +<p>You can issue the <code>geo</code> command as soon as an emulator instance is running. The +emulator sets the location you enter by creating a mock location provider. This provider responds to +location listeners set by applications, and also supplies the location to the {@link +android.location.LocationManager}. Any application can query the location manager to obtain the +current GPS fix for the emulated device by calling: <pre>LocationManager.getLastKnownLocation("gps")</pre> -<p>For more information about the Location Manager, see {@link android.location.LocationManager} and its methods.</p> +<p>For more information about the Location Manager, see {@link android.location.LocationManager}. +</p> -<a name="events"></a> -<h3>Hardware Events Emulation</h3> +<h3 id="events">Hardware Events Emulation</h3> -<p>You can use the <code>event</code> command to send various events to the emulator.The usage for the command is: </p> +<p>The {@code event} console commands sends hardware events to the emulator. The syntax for this +command is as follows:</p> <pre>event <send|types|codes|text></pre> @@ -1302,7 +1186,7 @@ emulated device by calling: <th width="30%" >Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>send <type>:<code>:<value> [...]</code></td> <td>Send one or more events to the Android kernel. </td> @@ -1315,7 +1199,7 @@ emulated device by calling: </tr> <tr> <td><code>codes <type></code></td> - <td>List all <code><codes></code> string aliases supported by the <code>event</code> + <td>List all <code><codes></code> string aliases supported by the <code>event</code> subcommands for the specified <code><type></code>.</td> <td> </td> </tr> @@ -1326,10 +1210,11 @@ emulated device by calling: </tr> </table> -<a name="power"></a> -<h3>Device Power Characteristics</h3> -<p>You can use the <code>power</code> command to control the simulated power state of the emulator instance.The usage for the command is: </p> +<h3 id="power">Device Power Characteristics</h3> + +<p>The {@code power} command controls the power state reported by the emulator to applications. The +syntax for this command is as follows: </p> <pre>power <display|ac|status|present|health|capacity></pre> @@ -1341,7 +1226,7 @@ emulated device by calling: <th width="30%" >Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>display</code></td> <td>Display battery and charger state.</td> @@ -1375,23 +1260,32 @@ emulated device by calling: </tr> </table> -<a name="netstatus"></a> -<h3>Network Status</h3> + +<h3 id="netstatus">Network Status</h3> <p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p> <pre>network status </pre> -<a name="netdelay"></a> -<h3>Network Delay Emulation</h3> -<p>The emulator lets you simulate various network latency levels, so that you can test your application in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator. </p> -<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a supported <code><delay></code> value, as listed in the table below. Here are some examples:</p> +<h3 id="netdelay">Network Delay Emulation</h3> + +<p>The emulator lets you simulate various network latency levels, so that you can test your +application in an environment more typical of the actual conditions in which it will run. You can +set a latency level or range at emulator startup or you can use the console to change the latency, +while the application is running in the emulator. </p> + +<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a +supported <code><delay></code> value, as listed in the table below. Here are some +examples:</p> + <pre>emulator -netdelay gprs emulator -netdelay 40 100</pre> -<p>To make dynamic changes to network delay while the emulator is running, connect to the console and use the <code>netdelay</code> command with a supported <code><delay></code> value from the table below. </p> +<p>To make changes to network delay while the emulator is running, connect to the console and use +the <code>netdelay</code> command with a supported <code><delay></code> value from the table +below.</p> <pre>network delay gprs</pre> @@ -1401,7 +1295,7 @@ emulator -netdelay 40 100</pre> <tr> <th width="30%" >Value</th> <th width="35%" >Description</th><th width="35%">Comments</th></tr> - + <tr><td><code>gprs</code></td><td>GPRS</td> <td>(min 150, max 550)</td> </tr> @@ -1421,19 +1315,22 @@ emulator -netdelay 40 100</pre> <td> </td></tr> </table> -<a name="netspeed"></a> -<h3>Network Speed Emulation</h3> -<p>The emulator also lets you simulate various network transfer rates. -You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically, -while the application is running in the emulator.</p> +<h3 id="netspeed">Network Speed Emulation</h3> + +<p>The emulator also lets you simulate various network transfer rates. +You can set a transfer rate or range at emulator startup or you can use the console to change the +rate, while the application is running in the emulator.</p> <p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported <code><speed></code> value, as listed in the table below. Here are some examples:</p> + <pre>emulator -netspeed gsm emulator -netspeed 14.4 80</pre> -<p>To make dynamic changes to network speed while the emulator is running, connect to the console and use the <code>netspeed</code> command with a supported <code><speed></code> value from the table below. </p> +<p>To make changes to network speed while the emulator is running, connect to the console and use +the <code>netspeed</code> command with a supported <code><speed></code> value from the table +below.</p> <pre>network speed 14.4 80</pre> @@ -1444,7 +1341,7 @@ kilobits/sec):</p> <tr> <th width="30%">Value</th> <th width="35%">Description</th><th width="35%">Comments</th></tr> - + <tr> <td><code>gsm</code></td> <td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr> @@ -1476,14 +1373,19 @@ kilobits/sec):</p> <td>Set exact rates for upload and download separately.</td><td></td></tr> </table> -<a name="telephony"></a> -<h3>Telephony Emulation</h3> +<h3 id="telephony">Telephony Emulation</h3> + +<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony +functions in the emulator. For example, you can simulate inbound phone calls, establish data +connections and terminate them. The Android system handles simulated calls exactly as it would +actual calls. The emulator does not support call audio.</p> + +<p>You can use the {@code gsm} command to access the emulator's telephony functions after connecting +to the console. The syntax for this command is as follows:</p> -<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release. </p> -<p>You can use the console to access the emulator's telephony functions. After connecting to the console, you can use</p> <pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre> -<p>to invoke telephony functions. </p> + <p>The <code>gsm</code> command supports the subcommands listed in the table below. </p> <table> <tr> @@ -1559,11 +1461,12 @@ kilobits/sec):</p> </tr> </table> -<a name="sms"></a> -<h3>SMS Emulation</h3> +<h3 id="sms">SMS Emulation</h3> -<p>The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using this command:</p> +<p>The Android emulator console lets you generate an SMS message and direct it to an emulator +instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using +the following command:</p> <pre>sms send <senderPhoneNumber> <textmessage></pre> @@ -1571,11 +1474,11 @@ kilobits/sec):</p> <p>The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type. </p> -<a name="vm"></a> -<h3>VM State</h3> +<h3 id="vm">VM State</h3> -<p>You can use the <code>vm</code> command to control the VM on an emulator instance.The usage for the command is: </p> +<p>You can use the <code>vm</code> command to control the VM on an emulator instance. The syntax for +this command is as follows: </p> <pre>vm <start|stop|status></pre> @@ -1583,8 +1486,8 @@ kilobits/sec):</p> <table> <tr> - <th width="25%" >Subcommand </th> - <th width="30%" >Description</th> + <th width="25%">Subcommand</th> + <th width="30%">Description</th> <th width="35%">Comments</th> </tr> <tr> @@ -1605,11 +1508,10 @@ kilobits/sec):</p> </table> -<a name="window"></a> +<h3 id="window">Emulator Window</h3> -<h3>Emulator Window</h3> - -<p>You can use the <code>window</code> command to manage the emulator window. The usage for the command is: </p> +<p>You can use the <code>window</code> command to manage the emulator window. The syntax for this +command is as follows: </p> <pre>window <scale></pre> @@ -1617,158 +1519,53 @@ kilobits/sec):</p> <table> <tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> + <th width="25%">Subcommand</th> + <th width="30%">Description</th> <th width="35%">Comments</th> </tr> <tr> <td><code>scale <scale></code></td> <td>Scale the emulator window.</td> - <td><scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + <td>A number between 0.1 and 3 that sets the scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" tells the emulator to select the best window size.</td> </tr> </table> -<a name="terminating"></a> - -<h3>Terminating an Emulator Instance</h3> +<h3 id="terminating">Terminating an Emulator Instance</h3> <p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p> -<a name="skins"></a> - -<h2>Using Emulator Skins</h2> - -<p>The Android SDK includes several Emulator skins that you can use to control the resolution and density of the emulated device's screen. To select a specific skin for running the emulator, create an AVD that uses that skin. Please do not use deprecated emulator options such as <code>-skin</code> to control the skin used by an emulator instance. For more information about AVDs, see <a -href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> - - -<a name="multipleinstances"></a> - -<h2>Running Multiple Emulator Instances</h2> - -<p>Through the AVDs configurations used by the emulator, you can run multiple -instances of the emulator concurrently, each with its own AVD configuration and -storage area for user data, SD card, and so on. You no longer need to use the -<code>-d</code> option when launching the emulator, to point to an -instance-specific storage area. </p> - -<a name="apps"></a> - -<h2>Installing Applications on the Emulator</h2> - -<p>If you don't have access to Eclipse or the ADT Plugin, you can install -your application on the emulator <a href="{@docRoot}guide/developing/tools/adb.html#move">using -the adb utility</a>. Before installing the application, you need to build and package it -into an <code>.apk</code> as described in <a href="{@docRoot}guide/developing/building/index.html">Building and -Running Apps</a>. Once the application is installed, you can start the emulator from the command -line, as described in this document, using any startup options necessary. -When the emulator is running, you can also connect to the emulator instance's -console to issue commands as needed.</p> - -<p>As you update your code, you periodically package and install it on the emulator. -The emulator preserves the application and its state data across restarts, -in a user-data disk partition. To ensure that the application runs properly -as you update it, you may need to delete the emulator's user-data partition. -To do so, start the emulator with the <code>-wipe-data</code> option. -For more information about the user-data partition and other emulator storage, -see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> +<h2 id="limitations">Emulator Limitations</h2> -<a name="sdcard"></a> -<a name="creating"></a> - -<h2>SD Card Emulation</h2> - -<p>You can create a disk image and then load it to the emulator at startup, to -simulate the presence of a user's SD card in the device. To do this, you can use -the android tool to create a new SD card image with a new AVD, or you can use -the mksdcard utility included in the SDK. </p> - -<p>The sections below describe how to create an SD card disk image, how to copy -files to it, and how to load it in the emulator at startup. </p> - -<p>Note that you can only load disk image at emulator startup. Similarly, you -can not remove a simulated SD card from a running emulator. However, you can -browse, send files to, and copy/remove files from a simulated SD card either -with adb or the emulator. </p> - -<p>The emulator supports emulated SDHC cards, so you can create an SD card image -of any size up to 128 gigabytes.</p> - -<h3 id="creatinga">Creating an SD card image using the android tool</h3> - -<p>The easiest way to create a new SD card is to use the android tool. When -creating an AVD, you simply specify the <code>-c</code> option, like this: </p> - -<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> - -<p>You can also use the <code>-c</code> option to specify a path to an SD card -image to use in the new AVD. For more information, see <a -href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing Virtual Devices -from the Command Line</a>. -</p> - -<h3 id="creatingm">Creating an SD card image using mksdcard</h3> - -<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk -image that you can load in the emulator at startup. You can access mksdcard in -the tools/ directory of the SDK and create a disk image like this: </p> - -<pre>mksdcard <size> <file></pre> - -<p>For example:</p> - -<pre>mksdcard 1024M sdcard1.iso</pre> - -<p>For more information, see <a href="{@docRoot}guide/developing/tools/mksdcard.html"><code>mksdcard</code></a>.</p> - -<a name="copying"></a> -<h3>Copying Files to a Disk Image</h3> - -<p>Once you have created the disk image, you can copy files to it prior to -loading it in the emulator. To copy files, you can mount the image as a loop -device and then copy the files to it, or you can use a utility such as mtools to -copy the files directly to the image. The mtools package is available for Linux, -Mac, and Windows.</p> - -<a name="loading"></a> -<a name="step3" id="step3"></a> - -<h3>Loading the Disk Image at Emulator Startup</h3> - -<p>By default, the emulator loads the SD card image that is stored with the active -AVD (see the <code>-avd</code> startup option).</p> - -<p>Alternatively, you ca start the emulator with the -<code>-sdcard</code> flag and specify the name and path of your image (relative -to the current working directory): </p> - -<pre>emulator -sdcard <filepath></pre> +<p>The functional limitations of the emulator include: </p> +<ul> + <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed + and received) through the emulator console, however. </li> + <li>No support for USB connections</li> + <li>No support for device-attached headphones</li> + <li>No support for determining network connected state</li> + <li>No support for determining battery charge level and AC charging state</li> + <li>No support for determining SD card insert/eject</li> + <li>No support for Bluetooth</li> +</ul> -<a name="troubleshooting"></a> -<h2>Troubleshooting Emulator Problems</h2> +<h2 id="troubleshooting">Troubleshooting Emulator Problems</h2> -<p>The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as <code>install</code>. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p> +<p>The {@code adb} utility sees the emulator as an actual physical device. For this reason, you +might have to use the {@code -d} flag with some common {@code adb} commands, such as +<code>install</code>. The {@code -d} flag lets you specify which of several connected devices to use +as the target of a command. If you don't specify {@code -d}, the emulator targets the first +device in its list. For more information about {@code adb}, see <a +href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p> -<p>For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If not, please run the following line in a command window:</p> +<p>For emulators running on Mac OS X, if you see an error {@code Warning: No DNS servers found} +when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If +not, please run the following line in a command window:</p> <pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre> -<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more troubleshooting information. </p> - -<a name="limitations"></a> - <h2>Emulator Limitations</h2> - <p>In this release, the limitations of the emulator include: </p> - <ul> - <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however. </li> - <li>No support for USB connections</li> - <li>No support for camera/video capture (input).</li> - <li>No support for device-attached headphones</li> - <li>No support for determining connected state</li> - <li>No support for determining battery charge level and AC charging state</li> - <li>No support for determining SD card insert/eject</li> - <li>No support for Bluetooth</li> - </ul> +<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more +troubleshooting information. </p> diff --git a/docs/html/guide/developing/devices/index.jd b/docs/html/guide/developing/devices/index.jd index a7d00f3..64651a1 100644 --- a/docs/html/guide/developing/devices/index.jd +++ b/docs/html/guide/developing/devices/index.jd @@ -7,9 +7,9 @@ page.title=Managing Virtual Devices <p>The easiest way to create an AVD is to use the graphical <a href= "{@docRoot}guide/developing/devices/managing-avds.html">AVD Manager</a>, which you launch - from Eclipse by clicking <strong>Window > Android SDK and AVD Manager</strong>. You can also start - the AVD Manager from the command line by calling the <code>android</code> tool in the <strong>tools</strong> - directory of the Android SDK.</p> + from Eclipse by clicking <strong>Window > AVD Manager</strong>. You can also start the AVD +Manager from the command line by calling the <code>android</code> tool with the <code>avd</code> +options, from the <strong><sdk>/tools/</strong> directory.</p> <p>You can also create AVDs on the command line by passing the <code>android</code> tool options. For more information on how to create AVDs in this manner, see <a href= diff --git a/docs/html/guide/developing/devices/managing-avds.jd b/docs/html/guide/developing/devices/managing-avds.jd index 1817ce7..412bd91 100644 --- a/docs/html/guide/developing/devices/managing-avds.jd +++ b/docs/html/guide/developing/devices/managing-avds.jd @@ -42,8 +42,8 @@ parent.link=index.html <li>Start the AVD Manager: <ul> - <li>In Eclipse: select <strong>Window > Android SDK and AVD Manager</strong>, or click - the Android SDK and AVD Manager icon in the Eclipse toolbar.</li> + <li>In Eclipse: select <strong>Window > AVD Manager</strong>, or click + the AVD Manager icon in the Eclipse toolbar.</li> <li>In other IDEs: Navigate to your SDK's <code>tools/</code> directory and execute the <code>android</code> tool with no arguments.</li> @@ -72,7 +72,7 @@ parent.link=index.html <li>Click <strong>Create AVD</strong>.</li> </ol> - <p>Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or + <p>Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or launch an emulator with the AVD by selecting a device and clicking <strong>Start</strong>.</p> <h3 id="hardwareopts">Hardware options</h3> @@ -233,13 +233,5 @@ to emulate:</p> <td>hw.lcd.density</td> </tr> - - <tr> - <td>Trackball support</td> - - <td>Whether there is a trackball present.</td> - - <td>hw.trackBall</td> - </tr> </table> diff --git a/docs/html/guide/developing/projects/index.jd b/docs/html/guide/developing/projects/index.jd index ac8a1a5..b16e466 100644 --- a/docs/html/guide/developing/projects/index.jd +++ b/docs/html/guide/developing/projects/index.jd @@ -179,8 +179,9 @@ page.title=Managing Projects <dd>Customizable computer-specific properties for the build system. If you use Ant to build the project, this contains the path to the SDK installation. Because the content of the file - is specific to the local installation of the SDK, maintained it in a source - revision control system. If you use Eclipse, this file is not used.</dd> + is specific to the local installation of the SDK, the <code>local.properties</code> should not +be maintained in a source revision control system. If you use Eclipse, this file is not +used.</dd> <dt><code>ant.properties</code></dt> @@ -208,8 +209,8 @@ page.title=Managing Projects application uses code and resources from an example library project called TicTacToeLib.</p> <p>To download the sample applications and run them as projects in - your environment, use the <em>Android SDK and AVD Manager</em> to download the "Samples for - SDK API 8" (or later) component into your SDK.</p> + your environment, use the <em>Android SDK Manager</em> to download the "Samples for + SDK API 8" (or later) package into your SDK.</p> <p>For more information and to browse the code of the samples, see the <a href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain @@ -226,8 +227,8 @@ page.title=Managing Projects <p class="note"><strong>Note:</strong> You need SDK Tools r14 or newer to use the new library project feature that generates each library project into its own JAR file. You can download the tools and platforms using the - <em>Android SDK and AVD Manager</em>, as described in - <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> + <em>Android SDK Manager</em>, as described in + <a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>.</p> <p>If you have source code and resources that are common to multiple Android projects, you can move them to a library project so that it is easier to maintain across applications and diff --git a/docs/html/guide/developing/projects/projects-cmdline.jd b/docs/html/guide/developing/projects/projects-cmdline.jd index 81c2c58..b8db5f3 100644 --- a/docs/html/guide/developing/projects/projects-cmdline.jd +++ b/docs/html/guide/developing/projects/projects-cmdline.jd @@ -218,7 +218,7 @@ android update lib-project \ <p>To add a reference to a library project, navigate to the <code><sdk>/tools/</code> directory and use this command:</p> <pre> -android update lib-project \ +android update project \ --target <em><target_ID></em> \ --path <em>path/to/your/project</em> --library <em>path/to/library_projectA</em> diff --git a/docs/html/guide/developing/testing/testing_otheride.jd b/docs/html/guide/developing/testing/testing_otheride.jd index 93af979..7745ae7 100644 --- a/docs/html/guide/developing/testing/testing_otheride.jd +++ b/docs/html/guide/developing/testing/testing_otheride.jd @@ -209,7 +209,7 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd <p> To update a test project with the <code>android</code> tool, enter: </p> -<pre>android update-test-project -m <main_path> -p <test_path></pre> +<pre>android update test-project -m <main_path> -p <test_path></pre> <table> <tr> diff --git a/docs/html/guide/developing/tools/adb.jd b/docs/html/guide/developing/tools/adb.jd index d32cf66..50c7236 100644 --- a/docs/html/guide/developing/tools/adb.jd +++ b/docs/html/guide/developing/tools/adb.jd @@ -546,12 +546,12 @@ of each message, given as <code><priority>/<tag></code>. </p> <p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, you use the <code>-v</code> option and specify one of the supported output formats listed below. </p> <ul> - <li><code>brief</code> — Display priority/tag and PID of originating process (the default format).</li> + <li><code>brief</code> — Display priority/tag and the PID of process issuing the message (the default format).</li> <li><code>process</code> — Display PID only.</li> <li><code>tag</code> — Display the priority/tag only. </li> - <li><code>thread</code> — Display process:thread and priority/tag only. </li> <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> - <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the originating process.</li> + <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the process issuing the message.</li> + <li><code>threadtime</code> — Display the date, invocation time, priority, tag, and the PID and TID of the thread issuing the message.</li> <li><code>long</code> — Display all metadata fields and separate messages with a blank lines.</li> </ul> diff --git a/docs/html/guide/developing/tools/adt.jd b/docs/html/guide/developing/tools/adt.jd index e48a5ae..d473e85 100644 --- a/docs/html/guide/developing/tools/adt.jd +++ b/docs/html/guide/developing/tools/adt.jd @@ -102,9 +102,8 @@ Project site.</p> (<strong>Window > Open Perspective > Traceview</strong>). </li> <li><a href="{@docRoot}guide/developing/tools/android.html">android</a>: Provides access to - the Android SDK and AVD Manager. Other <code>android</code> features such as creating or - updating projects (application and library) are integrated throughout the Eclipse IDE - (<strong>Window > Android SDK and AVD Manager</strong>). </li> + the Android SDK Manager and AVD Manager. Other <code>android</code> features such as creating or + updating projects (application and library) are integrated throughout the Eclipse IDE. </li> <li><a href="{@docRoot}guide/developing/debugging/debugging-ui.html#HierarchyViewer">Hierarchy Viewer</a>: Allows you to visualize your application's view hierarchy to find inefficiencies diff --git a/docs/html/guide/developing/tools/android.jd b/docs/html/guide/developing/tools/android.jd index a67012f..295a720 100644 --- a/docs/html/guide/developing/tools/android.jd +++ b/docs/html/guide/developing/tools/android.jd @@ -15,9 +15,16 @@ Line</a>.</li> the Command Line</a>.</li> <li>Update your Android SDK with new platforms, add-ons, and documentation. See <a href= - "{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li> + "{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>.</li> </ul>If you are using Eclipse, the <code>android</code> tool's features are integrated into ADT, so you should not need to use this tool directly. + + <p class="note"><strong>Note:</strong> The documentation of options below is not exhaustive +and may be out of date. For the most current list of options, execute <code>android +--help</code>.</p> + + + <h2>Syntax</h2> <pre>android [global options] action [action options]</pre> @@ -52,6 +59,26 @@ Line</a>.</li> </tr> <tr> + <td rowspan="6"><code>avd</code></td> + + <td>None</td> + + <td>Launch the AVD Manager</td> + + <td></td> + </tr> + + <tr> + <td rowspan="6"><code>sdk</code></td> + + <td>None</td> + + <td>Launch the Android SDK Manager</td> + + <td></td> + </tr> + + <tr> <td rowspan="6"><code>create avd</code></td> <td><code>-n <name></code></td> diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd index 5151ec1..21d4263 100644 --- a/docs/html/guide/developing/tools/emulator.jd +++ b/docs/html/guide/developing/tools/emulator.jd @@ -8,8 +8,8 @@ parent.link=index.html <h2>In this document</h2> <ol> - <li><a href="#startup-options">Emulator Startup Options</a></li> - <li><a href="#KeyMapping">Emulator Keyboard Mapping</a></li> + <li><a href="#KeyMapping">Keyboard Commands</a></li> + <li><a href="#startup-options">Command Line Parameters</a></li> </ol> <h2>See also</h2> @@ -22,30 +22,123 @@ parent.link=index.html </div> -<p>The Android SDK includes a mobile device emulator — a virtual mobile device +<p>The Android SDK includes a mobile device emulator — a virtual mobile device that runs on your computer. The emulator lets you develop and test Android applications without using a physical device.</p> -<p>When the emulator is running, you can interact with the emulated mobile -device just as you would an actual mobile device, except that you use your mouse -pointer to "touch" the touchscreen and can use some keyboard keys to -invoke certain keys on the device. </p> - -<p>This document is a reference to the available command line options and the keyboard mapping to device keys. -For a complete guide to using the Android Emulator, see +<p>This document is a reference to the available command line options and the keyboard mapping to +device keys. +For a complete guide to using the Android Emulator, see <a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>. -<h2 id="startup-options">Emulator Startup Options</h2> +<h2 id="KeyMapping">Keyboard Commands</h2> -<p>The emulator supports a variety of options that you can specify -when launching the emulator, to control its appearance or behavior. -Here's the command-line usage for launching the emulator with options: </p> +<p>Table 1 summarizes the mappings between the emulator keys and the keys of your keyboard.</p> + +<p class="table-caption"><strong>Table 1.</strong> Emulator keyboard mapping</p> +<table border="0" style="clear:left;"> + <tr> + <th>Emulated Device Key </th> + <th>Keyboard Key </th> + </tr> + <tr> + <td>Home</td> + <td>HOME</td> + </tr> + <tr> + <td>Menu (left softkey)</td> + <td>F2 <em>or</em> Page-up button</td> + </tr> + <tr> + <td>Star (right softkey)</td> + <td>Shift-F2 <em>or </em>Page Down</td> + </tr> + <tr> + <td>Back</td> + <td>ESC</td> + </tr> + <tr> + <td>Call/dial button </td> + <td>F3</td> + </tr> + <tr> + <td>Hangup/end call button</td> + <td>F4</td> + </tr> + <tr> + <td>Search</td> + <td>F5 </td> + </tr> + <tr> + <td>Power button</td> + <td>F7 </td> + </tr> + <tr> + <td>Audio volume up button</td> + <td>KEYPAD_PLUS, Ctrl-F5</td> + </tr> + + <tr> + <td>Audio volume down button</td> + <td>KEYPAD_MINUS, Ctrl-F6</td> + </tr> + <tr> + <td>Camera button</td> + <td>Ctrl-KEYPAD_5, Ctrl-F3</td> + </tr> + <tr> + <td>Switch to previous layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_7, Ctrl-F11</td> + </tr> + <tr> + <td>Switch to next layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_9, Ctrl-F12</td> + </tr> + <tr> + <td>Toggle cell networking on/off</td> + <td>F8</td> + </tr> + <tr> + <td>Toggle code profiling</td> + <td>F9 (only with <code>-trace</code> startup option)</td> + </tr> + <tr> + <td>Toggle fullscreen mode</td> + <td>Alt-Enter</td> + </tr> + <tr> + <td>Toggle trackball mode</td> + <td>F6</td> + </tr> + <tr> + <td>Enter trackball mode temporarily (while key is pressed)</td> + <td>Delete</td> + </tr> + <tr> + <td>DPad left/up/right/down</td> + <td>KEYPAD_4/8/6/2</td> + </tr> + <tr> + <td>DPad center click</td> + <td>KEYPAD_5</td> + </tr> + <tr> + <td>Onion alpha increase/decrease</td> + <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> + </tr> +</table> -<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> -<p class="table-caption"><strong>Table 1.</strong>Emulator startup options</p> +<h2 id="startup-options">Command Line Parameters</h2> +<p>The emulator supports a variety of options that you can specify +when launching the emulator, to control its appearance or behavior. +Here's the command-line syntax of the options available to the {@code emulator} program:</p> + +<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> + +<p class="table-caption"><strong>Table 2.</strong> Emulator command line parameters</p> <table> <tr> <th width="10%" >Category</th> @@ -55,106 +148,55 @@ Here's the command-line usage for launching the emulator with options: </p> </tr> <tr> - <td rowspan="9">Help</td> - <td><code>-help</code></td> - <td>Print a list of all emulator options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-all</code></td> - <td>Print help for all startup options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-<option></code></td> - <td>Print help for a specific startup option.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-debug-tags</code></td> - <td>Print a list of all tags for <code>-debug <tags></code>.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-disk-images</code></td> - <td>Print help for using emulator disk images.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-environment</code></td> - <td>Print help for emulator environment variables.</td> - <td> </td> -</tr><tr> - <td><code>-help-keys</code></td> - <td>Print the current mapping of keys.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-keyset-file</code></td> - <td>Print help for defining a custom key mappings file.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-virtual-device</code></td> - <td>Print help for Android Virtual Device usage.</td> - <td> </td> -</tr> -<tr> <td>AVD</td> <td><code>-avd <avd_name></code> or <br> <code>@<avd_name></code></td> <td><strong>Required</strong>. Specifies the AVD to load for this emulator instance.</td> <td>You must create an AVD configuration before launching the emulator. For - information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> - Managing AVDs with AVD Manager</a>.</td> + information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing + AVDs with AVD Manager</a>.</td> <tr> <td rowspan="7">Disk Images</td> <td><code>-cache <filepath></code></td> <td>Use <filepath> as the working cache partition image. </td> - <td>Optionally, you can specify a path relative to the current working directory. + <td>An absolute or relative path to the current working directory. If no cache file is specified, the emulator's default behavior is to use a temporary file instead. <p>For more information on disk images, use <code>-help-disk-images</code>.</p> </td></tr> <tr> <td><code>-data <filepath></code></td> - <td>Use <filepath> as the working user-data disk image. </td> - <td>Optionally, you can specify a path relative to the current working directory. - If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" - in the storage area of the AVD being used (see <code>-avd</code>). + <td>Use {@code <filepath>} as the working user-data disk image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If <code>-data</code> is not used, the emulator looks for a file named {@code userdata-qemu.img} + in the storage area of the AVD being used (see <code>-avd</code>). </td></tr> <!-- <tr> <td><code>-datadir <dir></code></td> <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> - <td><code><dir></code> is a path relative to the current working directory. + <td><code><dir></code> is a path relative to the current working directory. -<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image -in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information +<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image +in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information on disk images, use <code>-help-disk-images</code>.</p> </td></tr> --> -<!-- +<!-- <tr> <td><code>-image <filepath></code></td> <td>Use <filepath> as the system image.</td> - <td>Optionally, you can specify a path relative to the current working directory. + <td>Optionally, you can specify a path relative to the current working directory. Default is <system>/system.img.</td> </tr> --> <tr> <td><code>-initdata <filepath></code></td> - <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents + <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> - <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> -</tr> -<!-- -<tr> - <td><code>-kernel <filepath></code></td> - <td>Use <filepath> as the emulated kernel.</td> - <td>Optionally, you can specify a path relative to the current working directory. </td> + <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> </tr> ---> <tr> <td><code>-nocache</code></td> <td>Start the emulator without a cache partition.</td> @@ -163,8 +205,9 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-ramdisk <filepath></code></td> <td>Use <filepath> as the ramdisk image.</td> - <td>Default value is <code><system>/ramdisk.img</code>. - <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> + <td>Default value is <code><system>/ramdisk.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. + For more information on disk images, use <code>-help-disk-images</code>.</p> </td> </tr> <tr> @@ -178,17 +221,17 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-system <dirpath></code></td> <td>Search for system, ramdisk and user data images in <dir>.</td> - <td><code><dir></code> is a directory path relative to the current + <td><code><dir></code> is a directory path relative to the current working directory.</td> </tr> --> <tr> <td><code>-wipe-data</code></td> - <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and - <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, - then copies the contents of the file at <code>-inidata</code> data to the image file before starting. + <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and + <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, + then copies the contents of the file at <code>-inidata</code> data to the image file before starting. </td> - <td>See also <code>-initdata</code>. + <td>See also <code>-initdata</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p> </td> </tr> @@ -196,7 +239,7 @@ on disk images, use <code>-help-disk-images</code>.</p> <td rowspan="9">Debug</td> <td><code>-debug <tags></code></td> <td>Enable/disable debug messages for the specified debug tags.</td> - <td><code><tags></code> is a space/comma/column-separated list of debug component names. + <td><code><tags></code> is a space/comma/column-separated list of debug component names. Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> </tr> <tr> @@ -217,16 +260,16 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-shell</code></td> <td>Create a root shell console on the current terminal.</td> - <td>You can use this command even if the adb daemon in the emulated system is broken. + <td>You can use this command even if the adb daemon in the emulated system is broken. Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> </tr> <tr> <td><code>-shell-serial <device></code></td> - <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character + <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character device to use for communication with the shell.</td> - <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at - <a href="http://wiki.qemu.org/download/qemu-doc.html">wiki.qemu.org</a> - for more information.</p> + <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at + <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a> + for a list of device types. <p>Here are some examples: </p> <ul> @@ -250,11 +293,11 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-verbose</code></td> <td>Enable verbose output.</td> - <td>Equivalent to <code>-debug-init</code>. -<p>You can define the default verbose output options used by emulator instances in the Android environment variable -ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: + <td>Equivalent to <code>-debug-init</code>. +<p>You can define the default verbose output options used by emulator instances in the Android environment variable +ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: <code>-debug-<tags>.</code> </p> -<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: +<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: <p><code>ANDROID_VERBOSE=init,modem</code></p> <p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> </td> @@ -316,8 +359,9 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s <tr> <td><code>-netdelay <delay></code></td> <td>Set network latency emulation to <delay>.</td> - <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for - supported <code><delay></code> values. </td> + <td>Default value is <code>none</code>. See the table in + <a href="{@docRoot}guide/developing/devices/emulator.html#netdelay">Network Delay Emulation</a> + for supported <code><delay></code> values. </td> </tr> <tr> <td><code>-netfast</code></td> @@ -326,18 +370,19 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s <tr> <td><code>-netspeed <speed></code></td> <td>Set network speed emulation to <speed>.</td> - <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for + <td>Default value is <code>full</code>. See the table in + <a href="{@docRoot}guide/developing/devices/emulator.html#netspeed">Network Speed Emulation</a> for supported <code><speed></code> values. </td> </tr> <tr> <td><code>-port <port></code></td> <td>Set the console port number for this emulator instance to <code><port></code>.</td> - <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 + <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 must also be free and will be reserved for ADB.</td> </tr> <tr> <td><code>-report-console <socket></code></td> - <td>Report the assigned console port for this emulator instance to a remote third party + <td>Report the assigned console port for this emulator instance to a remote third party before starting the emulation. </td> <td><code><socket></code> must use one of these formats: @@ -347,14 +392,14 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s <p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> </tr> <tr> - <td rowspan="8">System</td> + <td rowspan="10">System</td> <td><code>-cpu-delay <delay></code></td> <td>Slow down emulated CPU speed by <delay> </td> <td>Supported values for <delay> are integers between 0 and 1000. -<p>Note that the <delay> does not correlate to clock speed or other absolute metrics -— it simply represents an abstract, relative delay factor applied non-deterministically -in the emulator. Effective performance does not always +<p>Note that the <delay> does not correlate to clock speed or other absolute metrics +— it simply represents an abstract, relative delay factor applied non-deterministically +in the emulator. Effective performance does not always scale in direct relationship with <delay> values.</p> </td> </tr> @@ -362,9 +407,9 @@ scale in direct relationship with <delay> values.</p> <td><code>-gps <device></code></td> <td>Redirect NMEA GPS to character device.</td> <td>Use this command to emulate an NMEA-compatible GPS unit connected to - an external character device or socket. The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at - <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. + an external character device or socket. The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at + <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. </td> </tr> <tr> @@ -372,18 +417,37 @@ scale in direct relationship with <delay> values.</p> <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> <tr> <td><code>-qemu</code></td> - <td>Pass arguments to qemu.</td> - <td> </td></tr> + <td>Pass arguments to the qemu emulator software.</td> + <td><p class="caution"><strong>Important:</strong> When using this option, make sure it is the + <em>last option</em> specified, since all options after it are interpretted as qemu-specific + options.</p></td></tr> +<tr> + <td><code>-qemu -enable-kvm</code></td> + <td>Enable KVM acceleration of the emulator virtual machine.</td> + <td>This option is only effective when your system is set up to use + <a href="{@docRoot}guide/developing/devices/emulator.html#vm-linux">KVM-based VM acceleration</a>. + You can optionally specify a memory size ({@code -m <size>}) for the VM, which should match + your emulator's memory size:</p> + {@code -qemu -m 512 -enable-kvm}<br> + {@code -qemu -m 1024 -enable-kvm} + </td></tr> <tr> <td><code>-qemu -h</code></td> <td>Display qemu help.</td> <td></td></tr> <tr> + <td><code>-gpu on</code></td> + <td>Turn on graphics acceleration for the emulator.</td> + <td>This option is only available for emulators using a system image with API Level 15, revision 3 + and higher. For more information, see + <a href="{@docRoot}guide/developing/devices/emulator.html#accel-graphics">Using the Android + Emulator</a>.</td></tr> +<tr> <td><code>-radio <device></code></td> <td>Redirect radio mode to the specified character device.</td> - <td>The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at -<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. + <td>The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at +<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. </td> </tr> <tr> @@ -419,8 +483,8 @@ scale in direct relationship with <delay> values.</p> <tr> <td><code>-scale <scale></code></td> <td>Scale the emulator window. </td> - <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" tells the emulator to select the best window size.</td> </tr> <tr> @@ -434,7 +498,7 @@ scale in direct relationship with <delay> values.</p> <tr> <td><code>-keyset <file></code></td> <td>Use the specified keyset file instead of the default.</td> - <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. + <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. For more information, use <code>-help-keyset</code> to print information about this topic. </td> </tr> @@ -460,113 +524,58 @@ option. Using this option may yield unexpected and in some cases misleading results, since the density with which to render the skin may not be defined. AVDs let you associate each skin with a default density and override the default as needed. For more information, see <a -href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> -Managing Virtual Devices with AVD Manager</a>. +href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices +with AVD Manager</a>. </td> </tr> <tr> <td><code>-skindir <dir></code></td> <td>This emulator option is deprecated. </td> - <td>See comments for <code>-skin</code>, above.</td></tr> -</table> - - - -<h2 id="KeyMapping">Emulator Keyboard Mapping</h2> - -<p>The table below summarizes the mappings between the emulator keys and and -the keys of your keyboard. </p> -<p class="table-caption"><strong>Table 2.</strong> Emulator keyboard mapping</p> -<table border="0" style="clear:left;"> - <tr> - <th>Emulated Device Key </th> - <th>Keyboard Key </th> - </tr> - <tr> - <td>Home</td> - <td>HOME</td> - </tr> - <tr> - <td>Menu (left softkey)</td> - <td>F2 <em>or</em> Page-up button</td> - </tr> - <tr> - <td>Star (right softkey)</td> - <td>Shift-F2 <em>or </em>Page Down</td> - </tr> - <tr> - <td>Back</td> - <td>ESC</td> - </tr> - <tr> - <td>Call/dial button </td> - <td>F3</td> - </tr> - <tr> - <td>Hangup/end call button</td> - <td>F4</td> - </tr> - <tr> - <td>Search</td> - <td>F5 </td> - </tr> - <tr> - <td>Power button</td> - <td>F7 </td> - </tr> - <tr> - <td>Audio volume up button</td> - <td>KEYPAD_PLUS, Ctrl-5</td> - </tr> - - <tr> - <td>Audio volume down button</td> - <td>KEYPAD_MINUS, Ctrl-F6</td> - </tr> - <tr> - <td>Camera button</td> - <td>Ctrl-KEYPAD_5, Ctrl-F3</td> - </tr> - <tr> - <td>Switch to previous layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_7, Ctrl-F11</td> - </tr> - <tr> - <td>Switch to next layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_9, Ctrl-F12</td> - </tr> - <tr> - <td>Toggle cell networking on/off</td> - <td>F8</td> - </tr> - <tr> - <td>Toggle code profiling</td> - <td>F9 (only with <code>-trace</code> startup option)</td> - </tr> - <tr> - <td>Toggle fullscreen mode</td> - <td>Alt-Enter</td> - </tr> - <tr> - <td>Toggle trackball mode</td> - <td>F6</td> - </tr> - <tr> - <td>Enter trackball mode temporarily (while key is pressed)</td> - <td>Delete</td> - </tr> - <tr> - <td>DPad left/up/right/down</td> - <td>KEYPAD_4/8/6/2</td> - </tr> - <tr> - <td>DPad center click</td> - <td>KEYPAD_5</td> - </tr> - <tr> - <td>Onion alpha increase/decrease</td> - <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> - </tr> + <td>See comments for <code>-skin</code>, above.</td> +</tr> +<tr> + <td rowspan="9">Help</td> + <td><code>-help</code></td> + <td>Print a list of all emulator options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-all</code></td> + <td>Print help for all startup options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-<option></code></td> + <td>Print help for a specific startup option.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-debug-tags</code></td> + <td>Print a list of all tags for <code>-debug <tags></code>.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-disk-images</code></td> + <td>Print help for using emulator disk images.</td> + <td> </td> + </tr> +<tr> + <td><code>-help-environment</code></td> + <td>Print help for emulator environment variables.</td> + <td> </td>s +</tr><tr> + <td><code>-help-keys</code></td> + <td>Print the current mapping of keys.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-keyset-file</code></td> + <td>Print help for defining a custom key mappings file.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-virtual-device</code></td> + <td>Print help for Android Virtual Device usage.</td> + <td> </td> +</tr> </table> - -<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index 3d831f3..5e9f686 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -12,8 +12,8 @@ latest Android platform.</p> <h2 id="tools-sdk">SDK Tools</h2> <p>The SDK tools are installed with the SDK starter package and are periodically updated. The SDK tools are required if you are developing Android applications. The most important SDK tools -include the Android SDK and AVD Manager (<code>android</code>), the emulator -(<code>emulator</code>), and the Dalvik Debug Monitor Server +include the Android SDK Manager (<code>android sdk</code>), the AVD Manager (<code>android +avd</code>) the emulator (<code>emulator</code>), and the Dalvik Debug Monitor Server (<code>ddms</code>). A short summary of some frequently-used SDK tools is provided below.</p> <dl> diff --git a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd index 499b610..346a0c6 100644 --- a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd +++ b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd @@ -236,7 +236,7 @@ Table 1 explains the flags and arguments. You can generate an API reference for monkeyrunner by running: </p> <pre> -monkeyrunner <format> help.py <outfile> +monkeyrunner help.py <format> <outfile> </pre> <p> The arguments are: diff --git a/docs/html/guide/developing/tools/proguard.jd b/docs/html/guide/developing/tools/proguard.jd index eca262a..ea8a1ea 100644 --- a/docs/html/guide/developing/tools/proguard.jd +++ b/docs/html/guide/developing/tools/proguard.jd @@ -39,7 +39,7 @@ parent.link=index.html sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your application harder to reverse engineer, it is important that you use it when your application utilizes features that are sensitive to security like when you are - <a href="{@docRoot}guide/publishing/licensing.html">Licensing Your Applications</a>.</p> + <a href="{@docRoot}guide/market/licensing/index.html">Licensing Your Applications</a>.</p> <p>ProGuard is integrated into the Android build system, so you do not have to invoke it manually. ProGuard runs only when you build your application in release mode, so you do not diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index a9c4d30..62d18ae 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -8,15 +8,16 @@ <ul> <li> - <h2><span class="en">Android Basics</span> - <span class="de" style="display:none">Einführung in Android</span> - <span class="es" style="display:none">Información básica sobre Android</span> - <span class="fr" style="display:none">Présentation d'Android</span> - <span class="it" style="display:none">Nozioni di base su Android</span> - <span class="ja" style="display:none">Android の基本</span> - <span class="zh-CN" style="display:none">Android 基础知识</span> - <span class="zh-TW" style="display:none">Android 簡介</span> - </h2> + <span class="heading"> + <span class="en">Android Basics</span> + <span class="de" style="display:none">Einführung in Android</span> + <span class="es" style="display:none">Información básica sobre Android</span> + <span class="fr" style="display:none">Présentation d'Android</span> + <span class="it" style="display:none">Nozioni di base su Android</span> + <span class="ja" style="display:none">Android の基本</span> + <span class="zh-CN" style="display:none">Android 基础知识</span> + <span class="zh-TW" style="display:none">Android 簡介</span> + </span> <ul> <li><a href="<?cs var:toroot ?>guide/basics/what-is-android.html"> <span class="en">What Is Android?</span> @@ -46,7 +47,7 @@ </li> <li> - <h2> + <span class="heading"> <span class="en">Framework Topics</span> <span class="de" style="display:none">Framework-Themen</span> <span class="es" style="display:none">Temas sobre el framework</span> @@ -55,7 +56,7 @@ <span class="ja" style="display:none">フレームワーク トピック</span> <span class="zh-CN" style="display:none">框架主题</span> <span class="zh-TW" style="display:none">架構主題</span> - </h2> + </span> <ul> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/fundamentals/activities.html"> @@ -87,10 +88,23 @@ <span class="en">Content Providers</span> </a></div> <ul> - <li><a href="<?cs var:toroot ?>guide/topics/providers/calendar-provider.html"> - <span class="en">Calendar Provider</span></a> - <span class="new">new!</span> - </li> + <li> + <a href="<?cs var:toroot ?>guide/topics/providers/content-provider-basics.html"> + <span class="en">Content Provider Basics<span +class="new"> new!</span></span> + </a> + </li> + <li> + <a href="<?cs var:toroot ?>guide/topics/providers/content-provider-creating.html"> + <span class="en">Creating a Content Provider<span +class="new"> new!</span></span> + </a> + </li> + <li> + <a href="<?cs var:toroot ?>guide/topics/providers/calendar-provider.html"> + <span class="en">Calendar Provider<span class="new"> new!</span></span> + </a> + </li> </ul> </li> <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html"> @@ -115,7 +129,7 @@ <span class="en">Input Events</span> </a></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html"> - <span class="en">Menus</span> + <span class="en">Menus<span class="new"> new!</span></span> </a></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html"> <span class="en">Action Bar</span> @@ -145,6 +159,19 @@ <li><a href="<?cs var:toroot ?>guide/topics/ui/custom-components.html"> <span class="en">Custom Components</span> </a></li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/topics/ui/accessibility/index.html"> + <span class="en">Accessibility<span class="new"> new!</span></span> + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/ui/accessibility/apps.html"> + <span class="en">Making Applications Accessible</span> + </a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/accessibility/services.html"> + <span class="en">Building Accessibility Services</span> + </a></li> + </ul> + </li> <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html"> <span class="en">Binding to Data with AdapterView</span> </a></li> @@ -244,13 +271,13 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html"> <span class="en">Graphics</span> - </a> <span class="new-child">new!</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/graphics/2d-graphics.html"> <span class="en">Canvas and Drawables</span></a></li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/hardware-accel.html"> <span class="en">Hardware Acceleration</span></a> - <span class="new">new!</span></li> + </li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/opengl.html"> <span class="en">OpenGL</span> </a></li> @@ -271,7 +298,7 @@ </li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/renderscript/index.html"> - <span class="en">RenderScript</span></a> + <span class="en">Renderscript</span></a> </div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/renderscript/graphics.html"> @@ -282,6 +309,10 @@ <span class="en">Compute</span> </a> </li> + <li><a href="<?cs var:toroot ?>guide/topics/renderscript/reference.html"> + <span class="en">Runtime API Reference</span> + </a> + </li> </ul> </li> @@ -298,7 +329,6 @@ </li> <li><a href="<?cs var:toroot ?>guide/topics/media/camera.html"> <span class="en">Camera</span></a> - <span class="new">new!</span> </li> <li><a href="<?cs var:toroot ?>guide/topics/media/audio-capture.html"> <span class="en">Audio Capture</span></a> @@ -312,7 +342,7 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/sensors/index.html"> <span class="en">Sensors</span> - </a> <span class="new">new!</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/sensors/sensors_overview.html"> <span class="en">Sensors Overview</span> @@ -353,13 +383,16 @@ </li> <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/topics/nfc/index.html"> - <span class="en">Near Field Communication</span></a> <span class="new">updated</span> + <span class="en">Near Field Communication</span></a> </div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/nfc/nfc.html">NFC Basics</a></li> <li><a href="<?cs var:toroot ?>guide/topics/nfc/advanced-nfc.html">Advanced NFC</a></li> </ul> </li> + <li><a href="<?cs var:toroot?>guide/topics/wireless/wifip2p.html"> + <span class="en">Wi-Fi Direct</span></a> + </li> <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/topics/usb/index.html"> <span class="en">USB</span></a> @@ -422,14 +455,30 @@ <li> <h2> - <span class="en">Android Market Topics</span> + <span class="en">Google Play Topics</span> </h2> <ul> <li><a href="<?cs var:toroot ?>guide/publishing/publishing.html"> - <span class="en">Publishing on Android Market</span> + <span class="en">Publishing on Google Play</span> </a></li> - <li><a href="<?cs var:toroot ?>guide/publishing/licensing.html"> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/market/licensing/index.html"> <span class="en">Application Licensing</span></a> + </div> + <ul> + <li><a href="<?cs var:toroot?>guide/market/licensing/overview.html"> + <span class="en">Licensing Overview</span></a> + </li> + <li><a href="<?cs var:toroot?>guide/market/licensing/setting-up.html"> + <span class="en">Setting Up for Licensing</span></a> + </li> + <li><a href="<?cs var:toroot?>guide/market/licensing/adding-licensing.html"> + <span class="en">Adding Licensing to Your App</span></a> + </li> + <li><a href="<?cs var:toroot?>guide/market/licensing/licensing-reference.html"> + <span class="en">Licensing Reference</span></a> + </li> + </ul> </li> <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/market/billing/index.html"> @@ -457,25 +506,29 @@ </ul> </li> <li><a href="<?cs var:toroot ?>guide/appendix/market-filters.html"> - <span class="en">Market Filters</span></a> + <span class="en">Filters on Google Play</span></a> </li> <li><a href="<?cs var:toroot ?>guide/market/publishing/multiple-apks.html"> <span class="en">Multiple APK Support</span></a> </li> + <li><a href="<?cs var:toroot ?>guide/market/expansion-files.html"> + <span class="en">APK Expansion Files<span class="new"> new!</span></span></a> + </li> </ul> </li> <li> - <h2><span class="en">Developing</span> - <span class="de" style="display:none">Entwicklung</span> - <span class="es" style="display:none">Desarrollo</span> - <span class="fr" style="display:none">Développement</span> - <span class="it" style="display:none">Sviluppo</span> - <span class="ja" style="display:none">開発</span> - <span class="zh-CN" style="display:none">开发</span> - <span class="zh-TW" style="display:none">開發</span> - </h2> + <span class="heading"> + <span class="en">Developing</span> + <span class="de" style="display:none">Entwicklung</span> + <span class="es" style="display:none">Desarrollo</span> + <span class="fr" style="display:none">Développement</span> + <span class="it" style="display:none">Sviluppo</span> + <span class="ja" style="display:none">開発</span> + <span class="zh-CN" style="display:none">开发</span> + <span class="zh-TW" style="display:none">開發</span> + </span> <ul> <!--<li><a href="">Developing for Android</a></li> signing, upgrading, selecting a package name, select device profile, touch, trackball, dpad available, etc. --> @@ -661,15 +714,16 @@ </li> <li> - <h2><span class="en">Publishing</span> - <span class="de" style="display:none">Veröffentlichung</span> - <span class="es" style="display:none">Publicación</span> - <span class="fr" style="display:none">Publication</span> - <span class="it" style="display:none">Pubblicazione</span> - <span class="ja" style="display:none">公開</span> - <span class="zh-CN" style="display:none">发布</span> - <span class="zh-TW" style="display:none">發佈</span> - </h2> + <span class="heading"> + <span class="en">Publishing</span> + <span class="de" style="display:none">Veröffentlichung</span> + <span class="es" style="display:none">Publicación</span> + <span class="fr" style="display:none">Publication</span> + <span class="it" style="display:none">Pubblicazione</span> + <span class="ja" style="display:none">公開</span> + <span class="zh-CN" style="display:none">发布</span> + <span class="zh-TW" style="display:none">發佈</span> + </span> <ul> <li><a href="<?cs var:toroot ?>guide/publishing/publishing_overview.html"> <span class="en">Publishing Overview</span> @@ -711,15 +765,16 @@ applications</span> </li> <li> - <h2><span class="en">Best Practices</span> - <span class="de" style="display:none">Bewährte Verfahren</span> - <span class="es" style="display:none">Prácticas recomendadas</span> - <span class="fr" style="display:none">Meilleures pratiques</span> - <span class="it" style="display:none">Best practice</span> - <span class="ja" style="display:none">ベスト プラクティス</span> - <span class="zh-CN" style="display:none">最佳实践</span> - <span class="zh-TW" style="display:none">最佳實務</span> - </h2> + <span class="heading"> + <span class="en">Best Practices</span> + <span class="de" style="display:none">Bewährte Verfahren</span> + <span class="es" style="display:none">Prácticas recomendadas</span> + <span class="fr" style="display:none">Meilleures pratiques</span> + <span class="it" style="display:none">Best practice</span> + <span class="ja" style="display:none">ベスト プラクティス</span> + <span class="zh-CN" style="display:none">最佳实践</span> + <span class="zh-TW" style="display:none">最佳實務</span> + </span> <ul> <li><a href="<?cs var:toroot ?>guide/practices/compatibility.html"> <span class="en">Compatibility</span> @@ -742,7 +797,7 @@ applications</span> </li> <li><a href="<?cs var:toroot ?>guide/practices/tablets-and-handsets.html"> <span class="en">Supporting Tablets and Handsets</span> - </a> <span class="new">new!</span></li> + </a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/index.html"> <span class="en">UI Guidelines</span> @@ -751,20 +806,20 @@ applications</span> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design.html"> <span class="en">Icon Design</span> - </a> <span class="new">updated</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_launcher.html"> <span class="en">Launcher Icons</span> - </a> <span class="new">updated</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_menu.html"> <span class="en">Menu Icons</span> </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_action_bar.html"> <span class="en">Action Bar Icons</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_status_bar.html"> <span class="en">Status Bar Icons</span> - </a> <span class="new">updated</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_tab.html"> <span class="en">Tab Icons</span> </a></li> @@ -779,19 +834,10 @@ applications</span> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/widget_design.html"> <span class="en">App Widget Design</span> </a></li> - <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/activity_task_design.html"> - <span class="en">Activity and Task Design</span> - </a></li> - <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/menu_design.html"> - <span class="en">Menu Design</span> - </a></li> </ul> </li> </ul> <ul> - <li><a href="<?cs var:toroot ?>guide/practices/design/accessibility.html"> - <span class="en">Designing for Accessibility</span> - </a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/design/performance.html"> <span class="en">Designing for Performance</span> @@ -815,8 +861,9 @@ applications</span> </li> <li> - <h2><span class="en">Web Applications</span> - </h2> + <span class="heading"> + <span class="en">Web Applications</span> + </span> <ul> <li><a href="<?cs var:toroot ?>guide/webapps/index.html"> <span class="en">Web Apps Overview</span> @@ -837,15 +884,16 @@ applications</span> </li> <li> - <h2><span class="en">Appendix</span> - <span class="de" style="display:none">Anhang</span> - <span class="es" style="display:none">Apéndice</span> - <span class="fr" style="display:none">Annexes</span> - <span class="it" style="display:none">Appendice</span> - <span class="ja" style="display:none">付録</span> - <span class="zh-CN" style="display:none">附录</span> - <span class="zh-TW" style="display:none">附錄</span> - </h2> + <span class="heading"> + <span class="en">Appendix</span> + <span class="de" style="display:none">Anhang</span> + <span class="es" style="display:none">Apéndice</span> + <span class="fr" style="display:none">Annexes</span> + <span class="it" style="display:none">Appendice</span> + <span class="ja" style="display:none">付録</span> + <span class="zh-CN" style="display:none">附录</span> + <span class="zh-TW" style="display:none">附錄</span> + </span> <ul> <li><a href="<?cs var:toroot ?>guide/appendix/api-levels.html"> <span class="en">Android API Levels</span> diff --git a/docs/html/guide/index.jd b/docs/html/guide/index.jd index 38f71c0..8378472 100644 --- a/docs/html/guide/index.jd +++ b/docs/html/guide/index.jd @@ -34,9 +34,9 @@ Fundamentals</a>. Then explore other topics — from designing a user interface and setting up resources to storing data and using permissions — as needed.</dd> -<dt><b>Android Market Topics</b></dt> -<dd>Documentation for topics that concern publishing and monetizing applications on Android -Market, such as how to enforce licensing policies and implement in-app billing.</dd> +<dt><b>Google Play Topics</b></dt> +<dd>Documentation for topics that concern publishing and monetizing applications on Google Play, +such as how to enforce licensing policies and implement in-app billing.</dd> <dt><b>Developing</b></dt> <dd>Directions for using Android's development and debugging tools, diff --git a/docs/html/guide/market/billing/billing_admin.jd b/docs/html/guide/market/billing/billing_admin.jd index a84eb4e..0f869ab 100755 --- a/docs/html/guide/market/billing/billing_admin.jd +++ b/docs/html/guide/market/billing/billing_admin.jd @@ -38,19 +38,19 @@ parent.link=index.html few administrative tasks, including setting up and maintaining your product list on the publisher site, registering test accounts, and handling refunds when necessary.</p> -<p>You must have an Android Market publisher account to register test accounts. And you must have a +<p>You must have a Google Play publisher account to register test accounts. And you must have a Google Checkout merchant account to create a product list and issue refunds to your users. If you -already have a publisher account on Android Market, you can use your existing account. You do not +already have a publisher account on Google Play, you can use your existing account. You do not need to register for a new account to support in-app billing. If you do not have a publisher -account, you can register as an Android Market developer and set up a publisher account at the -Android Market <a href="http://market.android.com/publish">publisher site</a>. If you do not have a +account, you can register as a Google Play developer and set up a publisher account at the +Google Play <a href="http://play.google.com/apps/publish">publisher site</a>. If you do not have a Google Checkout merchant account, you can register for one at the <a href="http://checkout.google.com">Google Checkout site</a>.</p> <h2 id="billing-list-setup">Creating a Product List</h2> -<p>The Android Market publisher site provides a product list for each of your published -applications. You can sell an item using Android Market's in-app billing feature only if the item is +<p>The Google Play publisher site provides a product list for each of your published +applications. You can sell an item using Google Play's in-app billing feature only if the item is listed on an application's product list. Each application has its own product list; you cannot sell items that are listed in another application's product list.</p> @@ -77,7 +77,7 @@ storing and delivering the digital content that you sell in your applications.</ </p> <p>You can create a product list for any published application or any draft application that's been -uploaded and saved to the Android Market site. However, you must have a Google Checkout merchant +uploaded and saved to the Google Play site. However, you must have a Google Checkout merchant account and the application's manifest must include the <code>com.android.vending.BILLING</code> permission. If an application's manifest does not include this permission, you will be able to edit existing items in the product list but you will not be able to add new items to the list. For more @@ -104,8 +104,8 @@ number of in-app items.</p> <p>To add an item to a product list using the In-app Products UI, follow these steps:</p> <ol> - <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li> - <li>In the <strong>All Android Market listings</strong> panel, under the application name, click + <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li> + <li>In the <strong>All Google Play listings</strong> panel, under the application name, click <strong>In-app Products</strong>.</li> <li>On the In-app Products List page, click <strong>Add in-app product</strong>.</li> <li>On the Create New In-app Product page (see figure 3), provide details about the item you are @@ -137,7 +137,7 @@ number of in-app items.</p> <li><strong>Publishing State</strong> <p>An item's publishing state can be <strong>Published</strong> or <strong>Unpublished </strong>. To be visible to a user during checkout, an item's publishing state must be set to - <strong>Published</strong> and the item's application must be published on Android Market.</p> + <strong>Published</strong> and the item's application must be published on Google Play.</p> <p class="note"><strong>Note:</strong> This is not true for test accounts. An item is visible to a test account if the application is not published and the item is published. See <a href="{@docRoot}guide/market/billing/billing_testing.html#billing-testing-real">Testing In-app @@ -167,9 +167,9 @@ number of in-app items.</p> <p>You must provide a default price in your home currency. You can also provide prices in other currencies, but you can do this only if a currency's corresponding country is listed as a target country for your application. You can specify target countries on the Edit Application - page in the Android Market developer console.</p> + page in the Google Play developer console.</p> <p>To specify prices in other currencies, you can manually enter the price for each - currency or you can click <strong>Auto Fill</strong> and let Android Market do a one-time + currency or you can click <strong>Auto Fill</strong> and let Google Play do a one-time conversion from your home currency to the currencies you are targeting (see figure 4).</p> </li> </ul> @@ -357,8 +357,8 @@ with the <em>locale</em> field.</p> <p>To import the items that are specified in your CSV file, do the following:</p> <ol> - <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li> - <li>In the <strong>All Android Market listings</strong> panel, under the application name, click + <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li> + <li>In the <strong>All Google Play listings</strong> panel, under the application name, click <strong>In-app Products</strong>.</li> <li>On the In-app Products List page, click <strong>Choose File</strong> and select your CSV file. @@ -381,17 +381,17 @@ a product list and you want to start managing the product list through a CSV fil <h3 id="billing-purchase-type">Choosing a Purchase Type</h3> -<p>An item's purchase type controls how Android Market manages the purchase of the item. There are +<p>An item's purchase type controls how Google Play manages the purchase of the item. There are two purchase types: "managed per user account" and "unmanaged."</p> <p>Items that are managed per user account can be purchased only once per user account. When an item -is managed per user account, Android Market permanently stores the transaction information for each -item on a per-user basis. This enables you to query Android Market with the +is managed per user account, Google Play permanently stores the transaction information for each +item on a per-user basis. This enables you to query Google Play with the <code>RESTORE_TRANSACTIONS</code> request and restore the state of the items a specific user has purchased.</p> -<p>If a user attempts to purchase a managed item that has already been purchased, Android Market -displays an "Item already purchased" error. This occurs during checkout, when Android Market +<p>If a user attempts to purchase a managed item that has already been purchased, Google Play +displays an "Item already purchased" error. This occurs during checkout, when Google Play displays the price and description information on the checkout page. When the user dismisses the error message, the checkout page disappears and the user returns to your user interface. As a best practice, your application should prevent the user from seeing this error. The sample application @@ -404,10 +404,10 @@ or application features. These items are not transient and usually need to be re user reinstalls your application, wipes the data on their device, or installs your application on a new device.</p> -<p>Items that are unmanaged do not have their transaction information stored on Android Market, -which means you cannot query Android Market to retrieve transaction information for items whose +<p>Items that are unmanaged do not have their transaction information stored on Google Play, +which means you cannot query Google Play to retrieve transaction information for items whose purchase type is listed as unmanaged. You are responsible for managing the transaction information -of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Android Market +of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Google Play is concerned, so it's also up to you to control how many times an unmanaged item can be purchased.</p> @@ -417,10 +417,10 @@ times.</p> <h2 id="billing-refunds">Handling Refunds</h2> -<p>In-app billing does not allow users to send a refund request to Android Market. Refunds for +<p>In-app billing does not allow users to send a refund request to Google Play. Refunds for in-app purchases must be directed to you (the application developer). You can then process the -refund through your Google Checkout merchant account. When you do this, Android Market receives a -refund notification from Google Checkout, and Android Market sends a refund message to your +refund through your Google Checkout merchant account. When you do this, Google Play receives a +refund notification from Google Checkout, and Google Play sends a refund message to your application. For more information, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling IN_APP_NOTIFY messages</a> and <a @@ -434,9 +434,9 @@ information.</p> <h2 id="billing-testing-setup">Setting Up Test Accounts</h2> -<p>The Android Market publisher site lets you set up one or more test accounts. A test account is a +<p>The Google Play publisher site lets you set up one or more test accounts. A test account is a regular Google account that you register on the publisher site as a test account. Test accounts are -authorized to make in-app purchases from applications that you have uploaded to the Android Market +authorized to make in-app purchases from applications that you have uploaded to the Google Play site but have not yet published.</p> <p>You can use any Google account as a test account. Test accounts are useful if you want to let @@ -458,7 +458,7 @@ accounts yourself and distribute the credentials to your developers or testers.< <p>To add test accounts to your publisher account, follow these steps:</p> <ol> - <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li> + <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li> <li>On the upper left part of the page, under your name, click <strong>Edit profile</strong>.</li> <li>On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 5).</li> @@ -480,7 +480,7 @@ support resources listed in the following table (see table 2). By directing your correct forum, you can get the support you need more quickly.</p> <p class="table-caption" id="support-table"><strong>Table 2.</strong> Developer support resources -for Android Market in-app billing.</p> +for Google Play in-app billing.</p> <table> @@ -502,8 +502,8 @@ href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.co android</a></td> </tr> <tr> -<td>Market billing issue tracker</td> -<td><a href="http://code.google.com/p/marketbilling/issues/">Market billing +<td>Billing issue tracker</td> +<td><a href="http://code.google.com/p/marketbilling/issues/">Billing project issue tracker</a></td> <td>Bug and issue reports related specifically to in-app billing sample code.</td> </tr> diff --git a/docs/html/guide/market/billing/billing_best_practices.jd b/docs/html/guide/market/billing/billing_best_practices.jd index d9776af..e100ce5 100755 --- a/docs/html/guide/market/billing/billing_best_practices.jd +++ b/docs/html/guide/market/billing/billing_best_practices.jd @@ -32,7 +32,7 @@ parent.link=index.html <p>As you design your in-app billing implementation, be sure to follow the security and design guidelines that are discussed in this document. These guidelines are recommended best practices for -anyone who is using Android Market's in-app billing service.</p> +anyone who is using Google Play's in-app billing service.</p> <h2>Security Best Practices</h2> @@ -92,7 +92,7 @@ replay attacks.</p> nonces on the server.</p> <h4>Take action against trademark and copyright infringement</h4> -<p>If you see your content being redistributed on Android Market, act quickly and decisively. File a +<p>If you see your content being redistributed on Google Play, act quickly and decisively. File a <a href="http://market.android.com/support/bin/answer.py?hl=en&answer=141511">trademark notice of infringement</a> or a <a href="http://www.google.com/android_dmca.html">copyright notice of infringement</a>.</p> @@ -102,7 +102,7 @@ infringement</a>.</p> purchase state of the unlocked content whenever a user accesses the content. This allows you to revoke use when necessary and minimize piracy.</p> -<h4>Protect your Android Market public key</h4> +<h4>Protect your Google Play public key</h4> <p>To keep your public key safe from malicious users and hackers, do not embed it in any code as a literal string. Instead, construct the string at runtime from pieces or use bit manipulation (for example, XOR with some other string) to hide the actual key. The key itself is not secret diff --git a/docs/html/guide/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd index 6017583..4b3650f 100755 --- a/docs/html/guide/market/billing/billing_integrate.jd +++ b/docs/html/guide/market/billing/billing_integrate.jd @@ -35,8 +35,8 @@ parent.link=index.html </div> </div> -<p>Android Market In-app Billing provides a straightforward, simple interface for sending in-app -billing requests and managing in-app billing transactions using Android Market. This document helps +<p>In-app Billing on Google Play provides a straightforward, simple interface for sending in-app +billing requests and managing in-app billing transactions using Google Play. This document helps you implement in-app billing by stepping through the primary implementation tasks, using the in-app billing sample application as an example.</p> @@ -53,23 +53,23 @@ billing.</p> <li><a href="#billing-permission">Update your AndroidManifest.xml file</a>.</li> <li><a href="#billing-service">Create a Service</a> and bind it to the <code>MarketBillingService</code> so your application can send billing requests and receive - billing responses from the Android Market application.</li> + billing responses from Google Play.</li> <li><a href="#billing-broadcast-receiver">Create a BroadcastReceiver</a> to handle broadcast - intents from the Android Market application.</li> + intents from Google Play.</li> <li><a href="#billing-signatures">Create a security processing component</a> to verify the - integrity of the transaction messages that are sent by Android Market .</li> + integrity of the transaction messages that are sent by Google Play.</li> <li><a href="#billing-implement">Modify your application code</a> to support in-app billing.</li> </ol> <h2 id="billing-download">Downloading the Sample Application</h2> <p>The in-app billing sample application shows you how to perform several tasks that are common to -all Android Market in-app billing implementations, including:</p> +all in-app billing implementations, including:</p> <ul> - <li>Sending in-app billing requests to the Android Market application.</li> - <li>Handling synchronous responses from the Android Market application.</li> - <li>Handling broadcast intents (asynchronous responses) from the Android Market application.</li> + <li>Sending in-app billing requests to Google Play.</li> + <li>Handling synchronous responses from Google Play.</li> + <li>Handling broadcast intents (asynchronous responses) from Google Play.</li> <li>Using in-app billing security mechanisms to verify the integrity of billing responses.</li> <li>Creating a user interface that lets users select items for purchase.</li> </ul> @@ -91,8 +91,8 @@ application source files.</p> <tr> <td>IMarketBillingService.aidl</td> -<td>Android Interface Definition Library (AIDL) file that defines the IPC interface to Android -Market's in-app billing service (<code>MarketBillingService</code>).</td> +<td>Android Interface Definition Library (AIDL) file that defines the IPC interface to Google +Play's in-app billing service (<code>MarketBillingService</code>).</td> </tr> <tr> @@ -109,12 +109,12 @@ history.</td> <tr> <td>BillingReceiver.java</td> <td>A {@link android.content.BroadcastReceiver} that receives asynchronous response messages - (broadcast intents) from Android Market. Forwards all messages to the + (broadcast intents) from Google Play. Forwards all messages to the <code>BillingService</code>.</td> </tr> <tr> <td>BillingService.java</td> - <td>A {@link android.app.Service} that sends messages to Android Market on behalf of the + <td>A {@link android.app.Service} that sends messages to Google Play on behalf of the application by connecting (binding) to the <code>MarketBillingService</code>.</td> </tr> @@ -136,8 +136,8 @@ history.</td> <tr> <td>Consts.java</td> -<td>Defines various Android Market constants and sample application constants. All constants that -are defined by Android Market must be defined the same way in your application.</td> +<td>Defines various Google Play constants and sample application constants. All constants that +are defined by Google Play must be defined the same way in your application.</td> </tr> <tr> @@ -149,8 +149,8 @@ relies on these utility classes.</td> </table> <p>The in-app billing sample application is available as a downloadable component of the Android -SDK. To download the sample application component, launch the Android SDK and AVD Manager and then -select the "Google Market Billing package" component (see figure 1), and click <strong>Install +SDK. To download the sample application component, launch the Android SDK Manager and then +select the <strong>Google Market Billing package</strong> component (see figure 1), and click <strong>Install Selected</strong> to begin the download.</p> @@ -160,7 +160,7 @@ Selected</strong> to begin the download.</p> the AIDL file. </p> -<p>When the download is complete, the Android SDK and AVD Manager saves the component into the +<p>When the download is complete, the Android SDK Manager saves the component into the following directory:</p> <p><code><sdk>/extras/google/market_billing/</code></p> @@ -171,7 +171,7 @@ running the sample application involves three tasks:</p> <ul> <li>Configuring and building the sample application.</li> - <li>Uploading the sample application to Android Market.</li> + <li>Uploading the sample application to Google Play.</li> <li>Setting up test accounts and running the sample application.</li> </ul> @@ -186,12 +186,12 @@ your project</a>.</p> following:</p> <ol> - <li><strong>Add your Android Market public key to the sample application code.</strong> + <li><strong>Add your Google Play public key to the sample application code.</strong> <p>This enables the application to verify the signature of the transaction information that is - returned from Android Market. To add your public key to the sample application code, do the + returned from Google Play. To add your public key to the sample application code, do the following:</p> <ol> - <li>Log in to your Android Market <a href="http://market.android.com/publish">publisher + <li>Log in to your Google Play <a href="http://play.google.com/apps/publish">publisher account</a>.</li> <li>On the upper left part of the page, under your name, click <strong>Edit Profile</strong>.</li> @@ -208,7 +208,7 @@ following:</p> </ol> </li> <li><strong>Change the package name of the sample application.</strong> - <p>The current package name is <code>com.example.dungeons</code>. Android Market does not let + <p>The current package name is <code>com.example.dungeons</code>. Google Play does not let you upload applications with package names that contain <code>com.example</code>, so you must change the package name to something else.</p> </li> @@ -221,14 +221,14 @@ following:</p> <h3>Uploading the sample application</h3> <p>After you build a release version of the sample application and sign it, you need to upload it as -a draft to the Android Market publisher site. You also need to create a product list for the in-app +a draft to the Google Play publisher site. You also need to create a product list for the in-app items that are available for purchase in the sample application. The following instructions show you how to do this.</p> <ol> - <li><strong>Upload the release version of the sample application to Android Market.</strong> + <li><strong>Upload the release version of the sample application to Google Play.</strong> <p>Do not publish the sample application; leave it as an unpublished draft application. The sample application is for demonstration purposes only and should not be made publicly available - on Android Market. To learn how to upload an application to Android Market, see <a + on Google Play. To learn how to upload an application to Google Play, see <a href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading applications</a>.</p> </li> @@ -253,7 +253,7 @@ how to do this.</p> onto a device to run it. To run the sample application, do the following:</p> <ol> - <li><strong>Make sure you have at least one test account registered under your Android Market + <li><strong>Make sure you have at least one test account registered under your Google Play publisher account.</strong> <p>You cannot purchase items from yourself (Google Checkout prohibits this), so you need to create at least one test account that you can use to purchase items in the sample application. @@ -261,18 +261,18 @@ onto a device to run it. To run the sample application, do the following:</p> href="{@docRoot}guide/market/billing/billing_testing.html#billing-testing-setup">Setting up Test Accounts</a>.</p> </li> - <li><strong>Verify that your device is running a supported version of the Android Market + <li><strong>Verify that your device is running a supported version of the Google Play application or the MyApps application.</strong> <p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the - version of the Android Market application, see <a - href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android - Market</a>.</p> + requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the + version of the Google Play application, see <a + href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google + Play</a>.</p> </li> <li><strong>Install the application onto your device.</strong> - <p>Even though you uploaded the application to Android Market, the application is not published, - so you cannot download it from Android Market to a device. Instead, you must install the + <p>Even though you uploaded the application to Google Play, the application is not published, + so you cannot download it from Google Play to a device. Instead, you must install the application onto your device. To learn how to install an application onto a device, see <a href="{@docRoot}guide/developing/building/building-cmdline.html#RunningOnDevice">Running on a device</a>.</p> @@ -280,7 +280,7 @@ onto a device to run it. To run the sample application, do the following:</p> <li><strong>Make one of your test accounts the primary account on your device.</strong> <p>The primary account on your device must be one of the <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">test accounts</a> - that you registered on the Android Market site. If the primary account on your device is not a + that you registered on the Google Play publisher site. If the primary account on your device is not a test account, you must do a factory reset of the device and then sign in with one of your test accounts. To perform a factory reset, do the following:</p> <ol> @@ -306,7 +306,7 @@ to <code>true</code> in the <code>Consts.java</code> file.</p> <h2 id="billing-add-aidl">Adding the AIDL file to your project</h2> <p>The sample application contains an Android Interface Definition Language (AIDL) file, which -defines the interface to Android Market's in-app billing service +defines the interface to Google Play's in-app billing service (<code>MarketBillingService</code>). When you add this file to your project, the Android build environment creates an interface file (<code>IMarketBillingService.java</code>). You can then use this interface to make billing requests by invoking IPC method calls.</p> @@ -333,29 +333,29 @@ the <code>gen</code> folder of your project.</p> <h2 id="billing-permission">Updating Your Application's Manifest</h2> -<p>In-app billing relies on the Android Market application, which handles all communication between -your application and the Android Market server. To use the Android Market application, your +<p>In-app billing relies on the Google Play application, which handles all communication between +your application and the Google Play server. To use the Google Play application, your application must request the proper permission. You can do this by adding the <code>com.android.vending.BILLING</code> permission to your AndroidManifest.xml file. If your application does not declare the in-app billing permission, but attempts to send billing requests, -Android Market will refuse the requests and respond with a <code>RESULT_DEVELOPER_ERROR</code> +Google Play will refuse the requests and respond with a <code>RESULT_DEVELOPER_ERROR</code> response code.</p> <p>In addition to the billing permission, you need to declare the {@link android.content.BroadcastReceiver} that you will use to receive asynchronous response messages -(broadcast intents) from Android Market, and you need to declare the {@link android.app.Service} -that you will use to bind with the <code>IMarketBillingService</code> and send messages to Android -Market. You must also declare <a +(broadcast intents) from Google Play, and you need to declare the {@link android.app.Service} +that you will use to bind with the <code>IMarketBillingService</code> and send messages to Google +Play. You must also declare <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">intent filters</a> for the {@link android.content.BroadcastReceiver} so that the Android system knows how to handle the broadcast -intents that are sent from the Android Market application.</p> +intents that are sent from the Google Play application.</p> <p>For example, here is how the in-app billing sample application declares the billing permission, the {@link android.content.BroadcastReceiver}, the {@link android.app.Service}, and the intent filters. In the sample application, <code>BillingReceiver</code> is the {@link -android.content.BroadcastReceiver} that handles broadcast intents from the Android Market +android.content.BroadcastReceiver} that handles broadcast intents from the Google Play application and <code>BillingService</code> is the {@link android.app.Service} that sends requests -to the Android Market application.</p> +to the Google Play application.</p> <pre> <?xml version="1.0" encoding="utf-8"?> @@ -391,11 +391,11 @@ to the Android Market application.</p> <h2 id="billing-service">Creating a Local Service</h2> <p>Your application must have a local {@link android.app.Service} to facilitate messaging between -your application and Android Market. At a minimum, this service must do the following:</p> +your application and Google Play. At a minimum, this service must do the following:</p> <ul> <li>Bind to the <code>MarketBillingService</code>. - <li>Send billing requests (as IPC method calls) to the Android Market application. The five types + <li>Send billing requests (as IPC method calls) to the Google Play application. The five types of billing requests include: <ul> <li><code>CHECK_BILLING_SUPPORTED</code> requests</li> @@ -474,7 +474,7 @@ The five request types are specified using the <code>BILLING_REQUEST</code> Bund key can have the following five values:</p> <ul> - <li><code>CHECK_BILLING_SUPPORTED</code>—verifies that the Android Market application + <li><code>CHECK_BILLING_SUPPORTED</code>—verifies that the Google Play application supports in-app billing.</li> <li><code>REQUEST_PURCHASE</code>—sends a purchase request for an in-app item.</li> <li><code>GET_PURCHASE_INFORMATION</code>—retrieves transaction information for a purchase @@ -510,7 +510,7 @@ application's main thread.</p> <h4>Verifying that in-app billing is supported (CHECK_BILLING_SUPPPORTED)</h4> -<p>The following code sample shows how to verify whether the Android Market application supports +<p>The following code sample shows how to verify whether the Google Play application supports in-app billing. In the sample, <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p> @@ -533,7 +533,7 @@ android.os.Bundle} response, which contains only a single key: <code>RESPONSE_CO <li><code>RESULT_BILLING_UNAVAILABLE</code>—in-app billing is not available because the API version you specified is not recognized or the user is not eligible to make in-app purchases (for example, the user resides in a country that prohibits in-app purchases).</li> - <li><code>RESULT_ERROR</code>—there was an error connecting with the Android Market + <li><code>RESULT_ERROR</code>—there was an error connecting with the Google Play application.</li> <li><code>RESULT_DEVELOPER_ERROR</code>—the application is trying to make an in-app billing request but the application has not declared the <code>com.android.vending.BILLING</code> @@ -546,10 +546,10 @@ android.os.Bundle} response, which contains only a single key: <code>RESPONSE_CO <p>We recommend that you invoke the <code>CHECK_BILLING_SUPPORTED</code> request within a <code>RemoteException</code> block. When your code throws a <code>RemoteException</code> it -indicates that the remote method call failed, which means that the Android Market application is out +indicates that the remote method call failed, which means that the Google Play application is out of date and needs to be updated. In this case, you can provide users with an error message that contains a link to the <a -href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android Market</a> +href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google Play</a> Help topic.</p> <p>The sample application demonstrates how you can handle this error condition (see @@ -561,16 +561,16 @@ Help topic.</p> <ul> <li>Send the <code>REQUEST_PURCHASE</code> request.</li> - <li>Launch the {@link android.app.PendingIntent} that is returned from the Android Market + <li>Launch the {@link android.app.PendingIntent} that is returned from the Google Play application.</li> - <li>Handle the broadcast intents that are sent by the Android Market application.</li> + <li>Handle the broadcast intents that are sent by the Google Play application.</li> </ul> <h5>Making the request</h5> <p>You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make a purchase request for a single in-app item. In the sample, -<code>mProductId</code> is the Android Market product ID of an in-app item (which is listed in the +<code>mProductId</code> is the Google Play product ID of an in-app item (which is listed in the application's <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-list-setup">product list</a>), and <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p> @@ -644,25 +644,25 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) { context and not an application context. Also, you cannot use the <code>singleTop</code> <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launch mode</a> to launch the pending intent. If you do either of these, the Android system will not attach the pending intent to -your application process. Instead, it will bring Android Market to the foreground, disrupting your +your application process. Instead, it will bring Google Play to the foreground, disrupting your application.</p> <h5>Handling broadcast intents</h5> <p>A <code>REQUEST_PURCHASE</code> request also triggers two asynchronous responses (broadcast -intents). First, the Android Market application sends a <code>RESPONSE_CODE</code> broadcast intent, +intents). First, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides error information about the request. If the request does not generate an error, the <code>RESPONSE_CODE</code> broadcast intent returns <code>RESULT_OK</code>, which indicates that the request was successfully sent. (To be clear, a <code>RESULT_OK</code> response does not indicate that the requested purchase was successful; it indicates that the request was sent -successfully to Android Market.)</p> +successfully to Google Play.)</p> <p>Next, when the requested transaction changes state (for example, the purchase is successfully -charged to a credit card or the user cancels the purchase), the Android Market application sends an +charged to a credit card or the user cancels the purchase), the Google Play application sends an <code>IN_APP_NOTIFY</code> broadcast intent. This message contains a notification ID, which you can use to retrieve the transaction details for the <code>REQUEST_PURCHASE</code> request.</p> -<p class="note"><strong>Note:</strong> The Android Market application also sends +<p class="note"><strong>Note:</strong> The Google Play application also sends an <code>IN_APP_NOTIFY</code> for refunds. For more information, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling IN_APP_NOTIFY messages</a>.</p> @@ -670,7 +670,7 @@ IN_APP_NOTIFY messages</a>.</p> <p>Because the purchase process is not instantaneous and can take several seconds (or more), you must assume that a purchase request is pending from the time you receive a <code>RESULT_OK</code> message until you receive an <code>IN_APP_NOTIFY</code> message for the transaction. While the -transaction is pending, the Android Market checkout UI displays an "Authorizing purchase..." +transaction is pending, the Google Play checkout UI displays an "Authorizing purchase..." notification; however, this notification is dismissed after 60 seconds and you should not rely on this notification as your primary means of conveying transaction status to users. Instead, we recommend that you do the following:</p> @@ -693,12 +693,12 @@ status of pending and completed in-app purchases.</p> be sure that your pending status UI does not block your application. For example, you should avoid using a hovering progress wheel to convey the status of a pending transaction because a pending transaction could last a long time, particularly if a device loses network connectivity and cannot -receive transaction updates from Android Market.</p> +receive transaction updates from Google Play.</p> <p class="caution"><strong>Important:</strong> If a user purchases a managed item, you must prevent the user from purchasing the item again while the original transaction is pending. If a user -attempts to purchase a managed item twice, and the first transaction is still pending, Android -Market will display an error to the user; however, Android Market will not send an error to your +attempts to purchase a managed item twice, and the first transaction is still pending, Google +Play will display an error to the user; however, Google Play will not send an error to your application notifying you that the second purchase request was canceled. This might cause your application to get stuck in a pending state while it waits for an <code>IN_APP_NOTIFY</code> message for the second purchase request.</p> @@ -730,7 +730,7 @@ three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The additional keys are then added to the bundle prior to invoking the <code>sendBillingRequest()</code> method. The <code>REQUEST_NONCE</code> key contains a cryptographically secure nonce (number used once) that you -must generate. The Android Market application returns this nonce with the +must generate. The Google Play application returns this nonce with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent so you can verify the integrity of the transaction information. The <code>NOTIFY_IDS</code> key contains an array of notification IDs, which you received in the <code>IN_APP_NOTIFY</code> broadcast intent.</p> @@ -741,9 +741,9 @@ you with the status of the request and the <code>REQUEST_ID</code> key provides request identifier for the request.</p> <p>A <code>GET_PURCHASE_INFORMATION</code> request also triggers two asynchronous responses -(broadcast intents). First, the Android Market application sends a <code>RESPONSE_CODE</code> +(broadcast intents). First, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status and error information about the request. Next, if the -request was successful, the Android Market application sends a <code>PURCHASE_STATE_CHANGED</code> +request was successful, the Google Play application sends a <code>PURCHASE_STATE_CHANGED</code> broadcast intent. This message contains detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.</p> @@ -783,8 +783,8 @@ request identifier for the request.</p> <code>RESPONSE_CODE</code> broadcast intent. This broadcast intent provides status and error information about the request.</p> -<p>You must send a confirmation when you receive transaction information from Android Market. If you -don't send a confirmation message, Android Market will continue sending +<p>You must send a confirmation when you receive transaction information from Google Play. If you +don't send a confirmation message, Google Play will continue sending <code>IN_APP_NOTIFY</code> messages for the transactions you have not confirmed. Also, your application must be able to handle <code>IN_APP_NOTIFY</code> messages that contain multiple orders.</p> @@ -792,7 +792,7 @@ orders.</p> <p>In addition, as a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> request for a purchased item until you have delivered the item to the user. This way, if your application crashes or something else prevents your application from delivering the product, your application -will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Android Market indicating +will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Google Play indicating that you need to deliver the product.</p> <h4>Restoring transaction information (RESTORE_TRANSACTIONS)</h4> @@ -817,7 +817,7 @@ three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The additional <code>REQUEST_NONCE</code> key is then added to the bundle prior to invoking the <code>sendBillingRequest()</code> method. The <code>REQUEST_NONCE</code> key contains a cryptographically secure nonce (number used once) that you -must generate. The Android Market application returns this nonce with the transactions information +must generate. The Google Play application returns this nonce with the transactions information contained in the <code>PURCHASE_STATE_CHANGED</code> broadcast intent so you can verify the integrity of the transaction information.</p> @@ -827,9 +827,9 @@ you with the status of the request and the <code>REQUEST_ID</code> key provides request identifier for the request.</p> <p>A <code>RESTORE_TRANSACTIONS</code> request also triggers two asynchronous responses (broadcast -intents). First, the Android Market application sends a <code>RESPONSE_CODE</code> broadcast intent, +intents). First, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status and error information about the request. Next, if the request was successful, -the Android Market application sends a <code>PURCHASE_STATE_CHANGED</code> broadcast intent. This +the Google Play application sends a <code>PURCHASE_STATE_CHANGED</code> broadcast intent. This message contains the detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.</p> @@ -842,7 +842,7 @@ application has been removed from a device and reinstalled.</p> <p>You may also want your {@link android.app.Service} to receive intent messages from your {@link android.content.BroadcastReceiver}. You can use these intent messages to convey the information that -was sent asynchronously from the Android Market application to your {@link +was sent asynchronously from the Google Play application to your {@link android.content.BroadcastReceiver}. To see an example of how you can send and receive these intent messages, see the <code>BillingReceiver.java</code> and <code>BillingService.java</code> files in the sample application. You can use these samples as a basis for your own implementation. However, @@ -851,16 +851,16 @@ href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and D <h2 id="billing-broadcast-receiver">Creating a BroadcastReceiver</h2> -<p>The Android Market application uses broadcast intents to send asynchronous billing responses to +<p>The Google Play application uses broadcast intents to send asynchronous billing responses to your application. To receive these intent messages, you need to create a {@link android.content.BroadcastReceiver} that can handle the following intents:</p> <ul> <li>com.android.vending.billing.RESPONSE_CODE - <p>This broadcast intent contains an Android Market response code, and is sent after you make an + <p>This broadcast intent contains a Google Play response code, and is sent after you make an in-app billing request. For more information about the response codes that are sent with this response, see <a - href="{@docRoot}guide/market/billing/billing_reference.html#billing-codes">Android Market Response + href="{@docRoot}guide/market/billing/billing_reference.html#billing-codes">Google Play Response Codes for In-app Billing</a>.</p> </li> <li>com.android.vending.billing.IN_APP_NOTIFY @@ -895,18 +895,18 @@ sent in response to billing requests.</p> <td><code>com.android.vending.billing.RESPONSE_CODE</code></td> <td><code>request_id</code></td> <td>A <code>long</code> representing a request ID. A request ID identifies a specific billing - request and is returned by Android Market at the time a request is made.</td> + request and is returned by Google Play at the time a request is made.</td> </tr> <tr> <td><code>com.android.vending.billing.RESPONSE_CODE</code></td> <td><code>response_code</code></td> - <td>An <code>int</code> representing the actual Android Market server response code.</td> + <td>An <code>int</code> representing the actual Google Play server response code.</td> </tr> <tr> <td><code>com.android.vending.billing.IN_APP_NOTIFY</code></td> <td><code>notification_id</code></td> <td>A <code>String</code> representing the notification ID for a given purchase state change. - Android Market notifies you when there is a purchase state change and the notification includes a + Google Play notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</td> </tr> @@ -933,16 +933,16 @@ public class BillingReceiver extends BroadcastReceiver { private static final String TAG = "BillingReceiver"; - // Intent actions that we receive in the BillingReceiver from Android Market. - // These are defined by Android Market and cannot be changed. + // Intent actions that we receive in the BillingReceiver from Google Play. + // These are defined by Google Play and cannot be changed. // The sample application defines these in the Consts.java file. public static final String ACTION_NOTIFY = "com.android.vending.billing.IN_APP_NOTIFY"; public static final String ACTION_RESPONSE_CODE = "com.android.vending.billing.RESPONSE_CODE"; public static final String ACTION_PURCHASE_STATE_CHANGED = "com.android.vending.billing.PURCHASE_STATE_CHANGED"; - // The intent extras that are passed in an intent from Android Market. - // These are defined by Android Market and cannot be changed. + // The intent extras that are passed in an intent from Google Play. + // These are defined by Google Play and cannot be changed. // The sample application defines these in the Consts.java file. public static final String NOTIFICATION_ID = "notification_id"; public static final String INAPP_SIGNED_DATA = "inapp_signed_data"; @@ -974,7 +974,7 @@ public class BillingReceiver extends BroadcastReceiver { } </pre> -<p>In addition to receiving broadcast intents from the Android Market application, your {@link +<p>In addition to receiving broadcast intents from the Google Play application, your {@link android.content.BroadcastReceiver} must handle the information it received in the broadcast intents. Usually, your {@link android.content.BroadcastReceiver} does this by sending the information to a local service (discussed in the next section). The <code>BillingReceiver.java</code> file in the @@ -985,8 +985,8 @@ href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and D <h2 id="billing-signatures">Verifying Signatures and Nonces</h2> -<p>Android Market's in-app billing service uses two mechanisms to help verify the integrity of the -transaction information you receive from Android Market: nonces and signatures. A nonce (number used +<p>Google Play's in-app billing service uses two mechanisms to help verify the integrity of the +transaction information you receive from Google Play: nonces and signatures. A nonce (number used once) is a cryptographically secure number that your application generates and sends with every <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, enabling you to verify that @@ -1023,12 +1023,12 @@ implementation, be sure to follow the guidelines in <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a> and obfuscate your code.</p> -<p>You will need to use your Android Market public key to perform the signature verification. The -following procedure shows you how to retrieve Base64-encoded public key from the Android Market +<p>You will need to use your Google Play public key to perform the signature verification. The +following procedure shows you how to retrieve Base64-encoded public key from the Google Play publisher site.</p> <ol> - <li>Log in to your <a href="http://market.android.com/publish">publisher account</a>.</li> + <li>Log in to your <a href="http://play.google.com/apps/publish">publisher account</a>.</li> <li>On the upper left part of the page, under your name, click <strong>Edit profile</strong>.</li> <li>On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 2).</li> @@ -1080,8 +1080,8 @@ unmanaged items is important because unmanaged items cannot be restored by using <h3>Creating a user interface for selecting items</h3> -<p>You must provide users with a means for selecting items that they want to purchase. Android -Market provides the checkout user interface (which is where the user provides a form of payment and +<p>You must provide users with a means for selecting items that they want to purchase. Google +Play provides the checkout user interface (which is where the user provides a form of payment and approves the purchase), but your application must provide a control (widget) that invokes the <code>sendBillingRequest()</code> method when a user selects an item for purchase.</p> diff --git a/docs/html/guide/market/billing/billing_overview.jd b/docs/html/guide/market/billing/billing_overview.jd index 8f9fd4c..b593811 100755 --- a/docs/html/guide/market/billing/billing_overview.jd +++ b/docs/html/guide/market/billing/billing_overview.jd @@ -38,24 +38,24 @@ parent.link=index.html </div> </div> -<p>Android Market In-app Billing is an Android Market service that provides checkout processing for +<p>In-app Billing is a Google Play service that provides checkout processing for in-app purchases. To use the service, your application sends a billing request for a specific in-app product. The service then handles all of the checkout details for the transaction, including requesting and validating the form of payment and processing the financial transaction. When the checkout process is complete, the service sends your application the purchase details, such as the order number, the order date and time, and the price paid. At no point does your application have to -handle any financial transactions; that role is provided by Android Market's in-app billing +handle any financial transactions; that role is provided by Google Play's in-app billing service.</p> <h2 id="billing-arch">In-app Billing Architecture</h2> <p>In-app billing uses an asynchronous message loop to convey billing requests and billing responses -between your application and the Android Market server. In practice, your application never directly -communicates with the Android Market server (see figure 1). Instead, your application sends billing -requests to the Android Market application over interprocess communication (IPC) and receives -purchase responses from the Android Market application in the form of asynchronous broadcast -intents. Your application does not manage any network connections between itself and the Android -Market server or use any special APIs from the Android platform.</p> +between your application and the Google Play server. In practice, your application never directly +communicates with the Google Play server (see figure 1). Instead, your application sends billing +requests to the Google Play application over interprocess communication (IPC) and receives +purchase responses from the Google Play application in the form of asynchronous broadcast +intents. Your application does not manage any network connections between itself and the Google +Play server or use any special APIs from the Android platform.</p> <p>Some in-app billing implementations may also use a private remote server to deliver content or validate transactions, but a remote server is not required to implement in-app billing. A remote @@ -70,16 +70,16 @@ to security attacks.</p> <img src="{@docRoot}images/billing_arch.png" alt="" height="582" /> <p class="img-caption"> <strong>Figure 1.</strong> Your application sends and receives billing messages through the - Android Market application, which handles all communication with the Android Market server.</p> + Google Play application, which handles all communication with the Google Play server.</p> </div> <p>A typical in-app billing implementation relies on three components:</p> <ul> <li>A {@link android.app.Service} (named <code>BillingService</code> in the sample application), - which processes purchase messages from the application and sends billing requests to Android - Market's in-app billing service.</li> + which processes purchase messages from the application and sends billing requests to the Google + Play in-app billing service.</li> <li>A {@link android.content.BroadcastReceiver} (named <code>BillingReceiver</code> in the sample - application), which receives all asynchronous billing responses from the Android Market + application), which receives all asynchronous billing responses from the Google Play application.</li> <li>A security component (named <code>Security</code> in the sample application), which performs security-related tasks, such as signature verification and nonce generation. For more information @@ -99,19 +99,19 @@ to security attacks.</p> <p>In addition to these components, your application must provide a way to store information about users' purchases and some sort of user interface that lets users select items to purchase. You do -not need to provide a checkout user interface. When a user initiates an in-app purchase, the Android -Market application presents the checkout user interface to your user. When the user completes the +not need to provide a checkout user interface. When a user initiates an in-app purchase, the Google +Play application presents the checkout user interface to your user. When the user completes the checkout process, your application resumes.</p> <h2 id="billing-msgs">In-app Billing Messages</h2> -<p>When the user initiates a purchase, your application sends billing messages to Android Market's +<p>When the user initiates a purchase, your application sends billing messages to Google Play's in-app billing service (named <code>MarketBillingService</code>) using simple IPC method calls. The -Android Market application responds to all billing requests synchronously, providing your -application with status notifications and other information. The Android Market application also +Google Play application responds to all billing requests synchronously, providing your +application with status notifications and other information. The Google Play application also responds to some billing requests asynchronously, providing your application with error messages and detailed transaction information. The following section describes the basic request-response -messaging that takes place between your application and the Android Market application.</p> +messaging that takes place between your application and the Google Play application.</p> <h3 id="billing-request">In-app billing requests</h3> @@ -133,31 +133,31 @@ Service Interface</a>. <p>One of the most important keys that every request Bundle must have is the <code>BILLING_REQUEST</code> key. This key lets you specify the type of billing request you are -making. Android Market's in-app billing service supports the following five types of billing +making. Google Play's in-app billing service supports the following five types of billing requests:</p> <ul> <li><code>CHECK_BILLING_SUPPORTED</code> - <p>This request verifies that the Android Market application supports in-app billing. You + <p>This request verifies that the Google Play application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.</p> </li> <li><code>REQUEST_PURCHASE</code> - <p>This request sends a purchase message to the Android Market application and is the foundation + <p>This request sends a purchase message to the Google Play application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase - an item in your application. Android Market then handles the financial transaction by displaying + an item in your application. Google Play then handles the financial transaction by displaying the checkout user interface.</p> </li> <li><code>GET_PURCHASE_INFORMATION</code> <p>This request retrieves the details of a purchase state change. A purchase changes state when a requested purchase is billed successfully or when a user cancels a transaction during - checkout. It can also occur when a previous purchase is refunded. Android Market notifies your + checkout. It can also occur when a previous purchase is refunded. Google Play notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.</p> </li> <li><code>CONFIRM_NOTIFICATIONS</code> <p>This request acknowledges that your application received the details of a purchase state - change. Android Market sends purchase state change notifications to your application until you + change. Google Play sends purchase state change notifications to your application until you confirm that you received them.</p> </li> <li><code>RESTORE_TRANSACTIONS</code> @@ -171,7 +171,7 @@ requests:</p> <h3 id="billing-response">In-app Billing Responses</h3> -<p>The Android Market application responds to in-app billing requests with both synchronous and +<p>The Google Play application responds to in-app billing requests with both synchronous and asynchronous responses. The synchronous response is a {@link android.os.Bundle} with the following three keys:</p> @@ -196,9 +196,9 @@ include the following:</p> <ul> <li><code>com.android.vending.billing.RESPONSE_CODE</code> - <p>This response contains an Android Market server response code, and is sent after you make an + <p>This response contains a Google Play server response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was - successfully sent to Android Market or it can indicate that some error occurred during a billing + successfully sent to Google Play or it can indicate that some error occurred during a billing request. This response is <em>not</em> used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see <a @@ -253,7 +253,7 @@ broadcast intents that are sent for every request.</p> <ol> <li>Your application sends a purchase request (<code>REQUEST_PURCHASE</code> type), specifying a product ID and other parameters.</li> - <li>The Android Market application sends your application a Bundle with the following keys: + <li>The Google Play application sends your application a Bundle with the following keys: <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and <code>REQUEST_ID</code>. The <code>PURCHASE_INTENT</code> key provides a {@link android.app.PendingIntent}, which your application uses to start the checkout UI for the given product ID.</li> @@ -262,20 +262,20 @@ broadcast intents that are sent for every request.</p> context and not an application context.</p> </li> <li>When the checkout flow finishes (that is, the user successfully purchases the item or cancels - the purchase), Android Market sends your application a notification message (an + the purchase), Google Play sends your application a notification message (an <code>IN_APP_NOTIFY</code> broadcast intent). The notification message includes a notification ID, which references the transaction.</li> <li>Your application requests the transaction information by sending a <code>GET_PURCHASE_STATE_CHANGED</code> request, specifying the notification ID for the transaction.</li> - <li>The Android Market application sends a Bundle with a <code>RESPONSE_CODE</code> key and a + <li>The Google Play application sends a Bundle with a <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. - <li>Android Market sends the transaction information to your application in a + <li>Google Play sends the transaction information to your application in a <code>PURCHASE_STATE_CHANGED</code> broadcast intent.</li> <li>Your application confirms that you received the transaction information for the given notification ID by sending a confirmation message (<code>CONFIRM_NOTIFICATIONS</code> type), specifying the notification ID for which you received transaction information.</li> - <li>The Android Market application sends your application a Bundle with a + <li>The Google Play application sends your application a Bundle with a <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key.</li> </ol> @@ -284,13 +284,13 @@ broadcast intents that are sent for every request.</p> <strong>Figure 2.</strong> Message sequence for a purchase request. </p> -<p>Keep in mind, you must send a confirmation when you receive transaction information from Android -Market (step 8 in figure 2). If you don't send a confirmation message, Android Market will +<p>Keep in mind, you must send a confirmation when you receive transaction information from Google +Play (step 8 in figure 2). If you don't send a confirmation message, Google Play will continue sending <code>IN_APP_NOTIFY</code> messages for the transactions you have not confirmed. As a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> request for a purchased item until you have delivered the item to the user. This way, if your application crashes or something else prevents your application from delivering the product, your application -will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Android Market indicating +will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Google Play indicating that you need to deliver the product. Also, as a best practice, your application must be able to handle <code>IN_APP_NOTIFY</code> messages that contain multiple orders.</p> @@ -307,7 +307,7 @@ broadcast intents that are sent for every request.</p> </div> <p>The request triggers three responses. The first is a {@link android.os.Bundle} with a -<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Android Market +<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status information or error information about the request. As always, the <code>RESPONSE_CODE</code> message references a specific request ID, so you can determine which request a <code>RESPONSE_CODE</code> message @@ -338,18 +338,18 @@ is supported; a <code>RESULT_BILLING_UNAVAILABLE</code> response code indicates is unavailable because the API version you specified is unrecognized or the user is not eligible to make in-app purchases (for example, the user resides in a country that does not allow in-app billing). A <code>SERVER_ERROR</code> can also be returned, indicating that there was a problem with -the Android Market server.</p> +the Google Play server.</p> <h3 id="billing-action-notify">Handling IN_APP_NOTIFY messages</h3> -<p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Android -Market in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The +<p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Google +Play in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The <code>IN_APP_NOTIFY</code> broadcast intent informs your application that the state of a requested purchase has changed. To retrieve the details of that purchase, your application sends a -<code>GET_PURCHASE_INFORMATION</code> request. Android Market responds with a +<code>GET_PURCHASE_INFORMATION</code> request. Google Play responds with a <code>PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the details of the purchase state change. Your application then sends a <code>CONFIRM_NOTIFICATIONS</code> message, informing -Android Market that you have received the purchase state change information.</p> +Google Play that you have received the purchase state change information.</p> <p>In some special cases, you may receive multiple <code>IN_APP_NOTIFY</code> messages even though you have confirmed receipt of the purchase information, or you may receive @@ -358,13 +358,13 @@ purchase. Your application must handle both of these special cases.</p> <h4>Handling multiple IN_APP_NOTIFY messages</h4> -<p>When Android Market receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given +<p>When Google Play receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given <code>PURCHASE_STATE_CHANGED</code> message, it usually stops sending <code>IN_APP_NOTIFY</code> -intents for that <code>PURCHASE_STATE_CHANGED</code> message. Sometimes, however, Android -Market may send repeated <code>IN_APP_NOTIFY</code> intents for a +intents for that <code>PURCHASE_STATE_CHANGED</code> message. Sometimes, however, Google +Play may send repeated <code>IN_APP_NOTIFY</code> intents for a <code>PURCHASE_STATE_CHANGED</code> message even though your application has sent a <code>CONFIRM_NOTIFICATIONS</code> message. This can occur if a device loses network connectivity -while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Android Market +while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Google Play might not receive your <code>CONFIRM_NOTIFICATIONS</code> message and it could send multiple <code>IN_APP_NOTIFY</code> messages until it receives acknowledgement that you received the transaction message. Therefore, your application must be able to recognize that the subsequent @@ -390,7 +390,7 @@ IN_APP_NOTIFY messages.</p> <p>In the first case, your application may receive an <code>IN_APP_NOTIFY</code> broadcast intent when a user has your application installed on two (or more) devices and the user makes an in-app -purchase from one of the devices. In this case, Android Market sends an <code>IN_APP_NOTIFY</code> +purchase from one of the devices. In this case, Google Play sends an <code>IN_APP_NOTIFY</code> message to the second device, informing the application that there is a purchase state change. Your application can handle this message the same way it handles the response from an application-initiated <code>REQUEST_PURCHASE</code> message, so that ultimately your application @@ -400,8 +400,8 @@ href="{@docRoot}guide/market/billing/billing_admin.html#billing-purchase-type">p to "managed per user account."</p> <p>In the second case, your application can receive an <code>IN_APP_NOTIFY</code> broadcast intent -when Android Market receives a refund notification from Google Checkout. In this case, Android -Market sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle +when Google Play receives a refund notification from Google Checkout. In this case, Google +Play sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle this message the same way it handles responses from an application-initiated <code>REQUEST_PURCHASE</code> message so that ultimately your application receives a <code>PURCHASE_STATE_CHANGED</code> message that includes information about the item that has been @@ -417,13 +417,13 @@ information.</p> <h2 id="billing-security">Security Controls</h2> <p>To help ensure the integrity of the transaction information that is sent to your application, -Android Market signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code> -broadcast intent. Android Market uses the private key that is associated with your publisher account +Google Play signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code> +broadcast intent. Google Play uses the private key that is associated with your publisher account to create this signature. The publisher site generates an RSA key pair for each publisher account. You can find the public key portion of this key pair on your account's profile page. It is the same -public key that is used with Android Market licensing.</p> +public key that is used with Google Play licensing.</p> -<p>When Android Market signs a billing response, it includes the signed JSON string (unencrypted) +<p>When Google Play signs a billing response, it includes the signed JSON string (unencrypted) and the signature. When your application receives this signed response you can use the public key portion of your RSA key pair to verify the signature. By performing signature verification you can help detect responses that have been tampered with or that have been spoofed. You can perform this @@ -431,9 +431,9 @@ signature verification step in your application; however, if your application co remote server then we recommend that you perform the signature verification on that server.</p> <p>In-app billing also uses nonces (a random number used once) to help verify the integrity of the -purchase information that's returned from Android Market. Your application must generate a nonce and +purchase information that's returned from Google Play. Your application must generate a nonce and send it with a <code>GET_PURCHASE_INFORMATION</code> request and a <code>RESTORE_TRANSACTIONS</code> -request. When Android Market receives the request, it adds the nonce to the JSON string that +request. When Google Play receives the request, it adds the nonce to the JSON string that contains the transaction information. The JSON string is then signed and returned to your application. When your application receives the JSON string, you need to verify the nonce as well as the signature of the JSON string.</p> @@ -447,20 +447,20 @@ href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and D limitations.</p> <ul> - <li>In-app billing can be implemented only in applications that you publish through Android - Market.</li> - <li>You must have a Google Checkout Merchant account to use Android Market In-app Billing.</li> + <li>In-app billing can be implemented only in applications that you publish through Google + Play.</li> + <li>You must have a Google Checkout Merchant account to use Google Play In-app Billing.</li> <li>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application.</li> + requires version 2.3.4 (or higher) of the Google Play application.</li> <li>An application can use in-app billing only if the device is running Android 1.6 (API level 4) or higher.</li> <li>You can use in-app billing to sell only digital content. You cannot use in-app billing to sell physical goods, personal services, or anything that requires physical delivery.</li> - <li>Android Market does not provide any form of content delivery. You are responsible for + <li>Google Play does not provide any form of content delivery. You are responsible for delivering the digital content that you sell in your applications.</li> <li>You cannot implement in-app billing on a device that never connects to the network. To - complete in-app purchase requests, a device must be able to access the Android Market server over + complete in-app purchase requests, a device must be able to access the Google Play server over the network. </li> </ul> diff --git a/docs/html/guide/market/billing/billing_reference.jd b/docs/html/guide/market/billing/billing_reference.jd index 5a7ba56..e8cf2ee 100755 --- a/docs/html/guide/market/billing/billing_reference.jd +++ b/docs/html/guide/market/billing/billing_reference.jd @@ -36,20 +36,20 @@ parent.link=index.html <p>The following document provides technical reference information for the following:</p> <ul> - <li><a href="#billing-codes">Android Market Server Response Codes for In-app Billing</a></li> + <li><a href="#billing-codes">Google Play Server Response Codes for In-app Billing</a></li> <li><a href="#billing-interface">In-app Billing Interface Parameters</a></li> <li><a href="#billing-intents">In-app Billing Broadcast Intents</a></li> </ul> -<h2 id="billing-codes">Android Market Server Response Codes for In-app Billing</h2> +<h2 id="billing-codes">Google Play Server Response Codes for In-app Billing</h2> -<p>The following table lists all of the server response codes that are sent from Android Market to -your application. Android Market sends these response codes asynchronously as +<p>The following table lists all of the server response codes that are sent from Google Play to +your application. Google Play sends these response codes asynchronously as <code>response_code</code> extras in the <code>com.android.vending.billing.RESPONSE_CODE</code> broadcast intent. Your application must handle all of these response codes.</p> <p class="table-caption" id="response-codes-table"><strong>Table 1.</strong> Summary of response -codes returned by Android Market.</p> +codes returned by Google Play.</p> <table> @@ -80,13 +80,13 @@ codes returned by Android Market.</p> <td><code>RESULT_BILLING_UNAVAILABLE</code></td> <td>3</td> <td>Indicates that in-app billing is not available because the <code>API_VERSION</code> that you - specified is not recognized by the Android Market application or the user is ineligible for in-app + specified is not recognized by the Google Play application or the user is ineligible for in-app billing (for example, the user resides in a country that prohibits in-app purchases).</td> </tr> <tr> <td><code>RESULT_ITEM_UNAVAILABLE</code></td> <td>4</td> - <td>Indicates that Android Market cannot find the requested item in the application's product + <td>Indicates that Google Play cannot find the requested item in the application's product list. This can happen if the product ID is misspelled in your <code>REQUEST_PURCHASE</code> request or if an item is unpublished in the application's product list.</td> </tr> @@ -108,7 +108,7 @@ purchase an item from yourself, which is not allowed by Google Checkout.</td> <h2 id="billing-interface">In-app Billing Service Interface</h2> -<p>The following section describes the interface for Android Market's in-app billing service. The +<p>The following section describes the interface for Google Play's in-app billing service. The interface is defined in the <code>IMarketBillingService.aidl</code> file, which is included with the in-app billing <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample @@ -144,7 +144,7 @@ pairs, which are summarized in table 2.</p> <td><code>int</code></td> <td>1</td> <td>Yes</td> - <td>The version of Android Market's in-app billing service you are using. The current version is + <td>The version of Google Play's in-app billing service you are using. The current version is 1.</td> </tr> <tr> @@ -160,8 +160,8 @@ pairs, which are summarized in table 2.</p> <td>Any valid product identifier.</td> <td>Required for <code>REQUEST_PURCHASE</code> requests.</td> <td>The product ID of the item you are making a billing request for. Every in-app item that you - sell using Android Market's in-app billing service must have a unique product ID, which you - specify on the Android Market publisher site.</td> + sell using Google Play's in-app billing service must have a unique product ID, which you + specify on the Google Play publisher site.</td> </tr> <tr> <td><code>NONCE</code></td> @@ -172,7 +172,7 @@ pairs, which are summarized in table 2.</p> <td>A number used once. Your application must generate and send a nonce with each <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, so you can use this value - to verify the integrity of transaction responses form Android Market.</td> + to verify the integrity of transaction responses form Google Play.</td> </tr> <tr> <td><code>NOTIFY_IDS</code></td> @@ -202,20 +202,20 @@ pairs, which are summarized in table 2.</p> <ul> <li><code>CHECK_BILLING_SUPPORTED</code> - <p>This request verifies that the Android Market application supports in-app billing. You + <p>This request verifies that the Google Play application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.</p> </li> <li><code>REQUEST_PURCHASE</code> - <p>This request sends a purchase message to the Android Market application and is the foundation + <p>This request sends a purchase message to the Google Play application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase - an item in your application. Android Market then handles the financial transaction by displaying + an item in your application. Google Play then handles the financial transaction by displaying the checkout user interface.</p> </li> <li><code>GET_PURCHASE_INFORMATION</code> <p>This request retrieves the details of a purchase state change. A purchase state change can occur when a purchase request is billed successfully or when a user cancels a transaction during - checkout. It can also occur when a previous purchase is refunded. Android Market notifies your + checkout. It can also occur when a previous purchase is refunded. Google Play notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.</p> </li> @@ -294,8 +294,8 @@ each in-app billing request type.</p> <h2 id="billing-intents">In-app Billing Broadcast Intents</h2> -<p>The following section describes the in-app billing broadcast intents that are sent by the Android -Market application. These broadcast intents inform your application about in-app billing actions +<p>The following section describes the in-app billing broadcast intents that are sent by the Google +Play application. These broadcast intents inform your application about in-app billing actions that have occurred. Your application must implement a {@link android.content.BroadcastReceiver} to receive these broadcast intents, such as the <code>BillingReceiver</code> that's shown in the in-app billing <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample @@ -303,21 +303,21 @@ application</a>.</p> <h4>com.android.vending.billing.RESPONSE_CODE</h4> -<p>This broadcast intent contains an Android Market response code, and is sent after you make an +<p>This broadcast intent contains a Google Play response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was successfully -sent to Android Market or it can indicate that some error occurred during a billing request. This +sent to Google Play or it can indicate that some error occurred during a billing request. This intent is not used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see <a -href="#billing-codes">Android Market Response Codes for In-app Billing</a>. The sample application +href="#billing-codes">Google Play Response Codes for In-app Billing</a>. The sample application assigns this broadcast intent to a constant named <code>ACTION_RESPONSE_CODE</code>.</p> <h5>Extras</h5> <ul type="none"> <li><code>request_id</code>—a <code>long</code> representing a request ID. A request ID - identifies a specific billing request and is returned by Android Market at the time a request is + identifies a specific billing request and is returned by Google Play at the time a request is made.</li> - <li><code>response_code</code>—an <code>int</code> representing the Android Market server + <li><code>response_code</code>—an <code>int</code> representing the Google Play server response code.</li> </ul> @@ -335,7 +335,7 @@ message details. The sample application assigns this broadcast intent to a const <ul type="none"> <li><code>notification_id</code>—a <code>String</code> representing the notification ID for - a given purchase state change. Android Market notifies you when there is a purchase state change + a given purchase state change. Google Play notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</li> </ul> @@ -375,15 +375,15 @@ a <code>PURCHASE_STATE_CHANGED</code> intent.</p> <tr> <td>nonce</td> <td>A number used once. Your application generates the nonce and sends it with the - <code>GET_PURCHASE_INFORMATION</code> request. Android Market sends the nonce back as part of the + <code>GET_PURCHASE_INFORMATION</code> request. Google Play sends the nonce back as part of the JSON string so you can verify the integrity of the message.</td> </tr> <tr> <td>notificationId</td> <td>A unique identifier that is sent with an <code>IN_APP_NOTIFY</code> broadcast intent. Each <code>notificationId</code> corresponds to a specify message that is waiting to be retrieved on - the Android Market server. Your application sends back the <code>notificationId</code> with the - <code>GET_PURCHASE_INFORMATION</code> message so Android Market can determine which messages you + the Google Play server. Your application sends back the <code>notificationId</code> with the + <code>GET_PURCHASE_INFORMATION</code> message so Google Play can determine which messages you are retrieving.</td> </tr> <tr> @@ -398,7 +398,7 @@ a <code>PURCHASE_STATE_CHANGED</code> intent.</p> <tr> <td>productId</td> <td>The item's product identifier. Every item has a product ID, which you must specify in the - application's product list on the Android Market publisher site.</td> + application's product list on the Google Play publisher site.</td> </tr> <tr> <td>purchaseTime</td> diff --git a/docs/html/guide/market/billing/billing_testing.jd b/docs/html/guide/market/billing/billing_testing.jd index 5453047..77aa3ed 100755 --- a/docs/html/guide/market/billing/billing_testing.jd +++ b/docs/html/guide/market/billing/billing_testing.jd @@ -32,16 +32,16 @@ parent.link=index.html </div> </div> -<p>The Android Market publisher site provides several tools that help you test your in-app billing +<p>The Google Play publisher site provides several tools that help you test your in-app billing implementation before it is published. You can use these tools to create test accounts and purchase special reserved items that send static billing responses to your application.</p> <p>To test in-app billing in an application you must install the application on an Android-powered device. You cannot use the Android emulator to test in-app billing. The device you use for testing must run a standard version of the Android 1.6 or later platform (API level 4 or higher), and have -the most current version of the Android Market application installed. If a device is not running the -most current Android Market application, your application won't be able to send in-app billing -requests to Android Market. For general information about how to set up a device for use in +the most current version of the Google Play application installed. If a device is not running the +most current Google Play application, your application won't be able to send in-app billing +requests to Google Play. For general information about how to set up a device for use in developing Android applications, see <a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a>.</p> @@ -50,12 +50,12 @@ Devices</a>.</p> <h2 id="billing-testing-static">Testing in-app purchases with static responses</h2> <p>We recommend that you first test your in-app billing implementation using static responses from -Android Market. This enables you to verify that your application is handling the primary Android -Market responses correctly and that your application is able to verify signatures correctly.</p> +Google Play. This enables you to verify that your application is handling the primary Google +Play responses correctly and that your application is able to verify signatures correctly.</p> <p>To test your implementation with static responses, you make an in-app billing request using a special item that has a reserved product ID. Each reserved product ID returns a specific static -response from Android Market. No money is transferred when you make in-app billing requests with the +response from Google Play. No money is transferred when you make in-app billing requests with the reserved product IDs. Also, you cannot specify the form of payment when you make a billing request with a reserved product ID. Figure 1 shows the checkout flow for the reserved item that has the product ID android.test.purchased.</p> @@ -65,7 +65,7 @@ product ID android.test.purchased.</p> <strong>Figure 1.</strong> Checkout flow for the special reserved item android.test.purchased. </p> -<p>You do not need to list the reserved products in your application's product list. Android Market +<p>You do not need to list the reserved products in your application's product list. Google Play already knows about the reserved product IDs. Also, you do not need to upload your application to the publisher site to perform static response tests with the reserved product IDs. You can simply install your application on a device, log into the device, and make billing requests using the @@ -75,24 +75,24 @@ reserved product IDs.</p> <ul> <li><strong>android.test.purchased</strong> - <p>When you make an in-app billing request with this product ID, Android Market responds as + <p>When you make an in-app billing request with this product ID, Google Play responds as though you successfully purchased an item. The response includes a JSON string, which contains fake purchase information (for example, a fake order ID). In some cases, the JSON string is signed and the response includes the signature so you can test your signature verification implementation using these responses.</p> </li> <li><strong>android.test.canceled</strong> - <p>When you make an in-app billing request with this product ID Android Market responds as + <p>When you make an in-app billing request with this product ID Google Play responds as though the purchase was canceled. This can occur when an error is encountered in the order process, such as an invalid credit card, or when you cancel a user's order before it is charged.</p> </li> <li><strong>android.test.refunded</strong> - <p>When you make an in-app billing request with this product ID, Android Market responds as - though the purchase was refunded. Refunds cannot be initiated through Android Market's in-app + <p>When you make an in-app billing request with this product ID, Google Play responds as + though the purchase was refunded. Refunds cannot be initiated through Google Play's in-app billing service. Refunds must be initiated by you (the merchant). After you process a refund request through your Google Checkout account, a refund message is sent to your application by - Android Market. This occurs only when Android Market gets notification from Google Checkout that + Google Play. This occurs only when Google Play gets notification from Google Checkout that a refund has been made. For more information about refunds, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling IN_APP_NOTIFY messages</a> and <a @@ -100,7 +100,7 @@ reserved product IDs.</p> Pricing</a>.</p> </li> <li><strong>android.test.item_unavailable</strong> - <p>When you make an in-app billing request with this product ID, Android Market responds as + <p>When you make an in-app billing request with this product ID, Google Play responds as though the item being purchased was not listed in your application's product list.</p> </li> </ul> @@ -185,20 +185,20 @@ application's product list you use one of the reserved product IDs.</p> <p>You do not need to use a test account if you are testing only with the reserved product IDs.</p> </li> - <li><strong>Verify that your device is running a supported version of the Android Market + <li><strong>Verify that your device is running a supported version of the Google Play application or the MyApps application.</strong> <p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the - version of the Android Market application, see <a - href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android - Market</a>.</p> + requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the + version of the Google Play application, see <a + href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google + Play</a>.</p> </li> <li><strong>Run your application and purchase the reserved product IDs.</strong></li> </ol> <p class="note"><strong>Note</strong>: Making in-app billing requests with the reserved product IDs -overrides the usual Android Market production system. When you send an in-app billing request for a +overrides the usual Google Play production system. When you send an in-app billing request for a reserved product ID, the quality of service will not be comparable to the production environment.</p> @@ -207,7 +207,7 @@ environment.</p> <p>After you finish your static response testing, and you verify that signature verification is working in your application, you can test your in-app billing implementation by making actual in-app purchases. Testing real in-app purchases enables you to test the end-to-end in-app billing -experience, including the actual responses from Android Market and the actual checkout flow that +experience, including the actual responses from Google Play and the actual checkout flow that users will experience in your application.</p> <p class="note"><strong>Note</strong>: You do not need to publish your application to do end-to-end @@ -215,7 +215,7 @@ testing. You only need to upload your application as a draft application to perf testing.</p> <p>To test your in-app billing implementation with actual in-app purchases, you will need to -register at least one test account on the Android Market publisher site. You cannot use your +register at least one test account on the Google Play publisher site. You cannot use your developer account to test the complete in-app purchase process because Google Checkout does not let you buy items from yourself. If you have not set up test accounts before, see <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">Setting up test @@ -237,7 +237,7 @@ actual payouts to your merchant account.</p> IDs; you only need to upload your application as a draft application. However, you must sign your application with your release key before you upload it as a draft application. Also, the version number of the uploaded application must match the version number of the application you - load to your device for testing. To learn how to upload an application to Android Market, see + load to your device for testing. To learn how to upload an application to Google Play, see <a href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading applications</a>.</p> </li> @@ -257,7 +257,7 @@ actual payouts to your merchant account.</p> <p>To perform end-to-end testing of in-app billing, the primary account on your device must be one of the <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">test accounts</a> - that you registered on the Android Market site. If the primary account on your device is not a + that you registered on the Google Play site. If the primary account on your device is not a test account, you must do a factory reset of the device and then sign in with one of your test accounts. To perform a factory reset, do the following:</p> <ol> @@ -269,14 +269,14 @@ actual payouts to your merchant account.</p> device setup process.</li> </ol> </li> - <li><strong>Verify that your device is running a supported version of the Android Market + <li><strong>Verify that your device is running a supported version of the Google Play application or the MyApps application.</strong> <p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the - version of the Android Market application, see <a - href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android - Market</a>.</p> + requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the + version of the Google Play application, see <a + href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google + Play</a>.</p> </li> <li><strong>Make in-app purchases in your application.</strong></li> </ol> @@ -285,7 +285,7 @@ actual payouts to your merchant account.</p> do a factory reset, making sure you log on with your primary account first.</p> <p>When you are finished testing your in-app billing implementation, you are ready to -publish your application on Android Market. You can follow the normal steps for <a +publish your application on Google Play. You can follow the normal steps for <a href="{@docRoot}guide/publishing/preparing.html">preparing</a>, <a href="{@docRoot}guide/publishing/app-signing.html">signing</a>, and <a href="{@docRoot}guide/publishing/publishing.html">publishing your application</a>. diff --git a/docs/html/guide/market/billing/index.jd b/docs/html/guide/market/billing/index.jd index fdfa6fa..036761f 100755 --- a/docs/html/guide/market/billing/index.jd +++ b/docs/html/guide/market/billing/index.jd @@ -30,18 +30,18 @@ page.title=In-app Billing </div> </div> -<p>Android Market In-app Billing is an Android Market service that lets you sell digital content in +<p>Google Play In-app Billing is a Google Play service that lets you sell digital content in your applications. You can use the service to sell a wide range of content, including downloadable content such as media files or photos, and virtual content such as game levels or potions.</p> -<p>When you use Android Market's in-app billing service to sell an item, Android Market handles all +<p>When you use Google Play's in-app billing service to sell an item, Google Play handles all checkout details so your application never has to directly process any financial transactions. -Android Market uses the same checkout service that is used for application purchases, so your users +Google Play uses the same checkout service that is used for application purchases, so your users experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for in-app purchases is the same as the transaction fee for application purchases (30%).</p> -<p>Any application that you publish through Android Market can implement in-app billing. No special -account or registration is required other than an Android Market publisher account and a Google +<p>Any application that you publish through Google Play can implement in-app billing. No special +account or registration is required other than a Google Play app publisher account and a Google Checkout Merchant account. Also, because the service uses no dedicated framework APIs, you can add in-app billing to any application that uses a minimum API level of 4 or higher.</p> @@ -59,11 +59,11 @@ obfuscate the sample code before you use it in a production application. For mor <img src="{@docRoot}images/billing_checkout_flow.png" height="382" id="figure1" /> <p class="img-caption"> <strong>Figure 1.</strong> Applications initiate in-app billing requests through their own UI - (first screen). Android Market responds to the request by providing the checkout user interface + (first screen). Google Play responds to the request by providing the checkout user interface (middle screen). When checkout is complete, the application resumes. </p> -<p>To learn more about Android Market's in-app billing service and start integrating it into your +<p>To learn more about Google Play's in-app billing service and start integrating it into your applications, read the following documents:</p> <dl> @@ -88,7 +88,7 @@ applications, read the following documents:</p> <dd>Learn how to set up your product list, register test accounts, and handle refunds.</dd> <dt><strong><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></strong></dt> - <dd>Get detailed information about Android Market response codes and the in-app billing + <dd>Get detailed information about Google Play response codes and the in-app billing interface.</dd> </dl> diff --git a/docs/html/guide/market/expansion-files.jd b/docs/html/guide/market/expansion-files.jd new file mode 100644 index 0000000..36b8f9c --- /dev/null +++ b/docs/html/guide/market/expansion-files.jd @@ -0,0 +1,1270 @@ +page.title=APK Expansion Files +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>Recommended for most apps that exceed the 50MB APK limit</li> + <li>You can provide up to 4GB of additional data for each APK</li> + <li>Google Play hosts and serves the expansion files at no charge</li> + <li>The files can be any file type you want and are saved to the device's shared storage</li> +</ul> + +<h2>In this document</h2> +<ol> + <li><a href="#Overview">Overview</a> + <ol> + <li><a href="#Filename">File name format</a></li> + <li><a href="#StorageLocation">Storage location</a></li> + <li><a href="#DownloadProcess">Download process</a></li> + <li><a href="#Checklist">Development checklist</a></li> + </ol> + </li> + <li><a href="#Rules">Rules and Limitations</a></li> + <li><a href="#Downloading">Downloading the Expansion Files</a> + <ol> + <li><a href="#AboutLibraries">About the Downloader Library</a></li> + <li><a href="#Preparing">Preparing to use the Downloader Library</a></li> + <li><a href="#Permissions">Declaring user permissions</a></li> + <li><a href="#DownloaderService">Implementing the downloader service</a></li> + <li><a href="#AlarmReceiver">Implementing the alarm receiver</a></li> + <li><a href="#Download">Starting the download</a></li> + <li><a href="#Progress">Receiving download progress</a></li> + </ol> + </li> + <li><a href="#ExpansionPolicy">Using APKExpansionPolicy</a></li> + <li><a href="#ReadingTheFile">Reading the Expansion File</a> + <ol> + <li><a href="#GettingFilenames">Getting the file names</a></li> + <li><a href="#ZipLib">Using the APK Expansion Zip Library</a></li> + </ol> + </li> + <li><a href="#Testing">Testing Your Expansion Files</a> + <ol> + <li><a href="#TestingReading">Testing file reads</a></li> + <li><a href="#TestingReading">Testing file downloads</a></li> + </ol> + </li> + <li><a href="#Updating">Updating Your Application</a></li> +</ol> + +<h2>See also</h2> +<ol> + <li><a href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a></li> + <li><a href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple +APK Support</a></li> +</ol> +</div> +</div> + + + +<p>Google Play currently requires that your APK file be no more than 50MB. For most +applications, this is plenty of space for all the application's code and assets. +However, some apps need more space for high-fidelity graphics, media files, or other large assets. +Previously, if your app exceeded 50MB, you had to host and download the additional resources +yourself when the user opens the app. Hosting and serving the extra files can be costly, and the +user experience is often less than ideal. To make this process easier for you and more pleasant +for users, Google Play allows you to attach two large expansion files that supplement your +APK.</p> + +<p>Google Play hosts the expansion files for your application and serves them to the device at +no cost to you. The expansion files are saved to the device's shared storage location (the +SD card or USB-mountable partition; also known as the "external" storage) where your app can access +them. On most devices, Google Play downloads the expansion file(s) at the same time it +downloads the APK, so your application has everything it needs when the user opens it for the +first time. In some cases, however, your application must download the files from Google Play +when your application starts.</p> + + + +<h2 id="Overview">Overview</h2> + +<p>Each time you upload an APK using the Google Play Android Developer Console, you have the option to +add one or two expansion files to the APK. Each file can be up to 2GB and it can be any format you +choose, but we recommend you use a compressed file to conserve bandwidth during the download. +Conceptually, each expansion file plays a different role:</p> + +<ul> + <li>The <strong>main</strong> expansion file is the +primary expansion file for additional resources required by your application.</li> + <li>The <strong>patch</strong> expansion file is optional and intended for small updates to the +main expansion file.</li> +</ul> + +<p>While you can use the two expansion files any way you wish, we recommend that the main +expansion file deliver the primary assets and should rarely if ever updated; the patch expansion +file should be smaller and serve as a “patch carrier,” getting updated with each major +release or as necessary.</p> + +<p>However, even if your application update requires only a new patch expansion file, you still must +upload a new APK with an updated <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code +versionCode}</a> in the manifest. (The +Developer Console does not allow you to upload an expansion file to an existing APK.)</p> + +<p class="note"><strong>Note:</strong> The patch expansion file is semantically the same as the +main expansion file—you can use each file any way you want. The system does +not use the patch expansion file to perform patching for your app. You must perform patching +yourself or be able to distinguish between the two files.</p> + + + +<h3 id="Filename">File name format</h3> + +<p>Each expansion file you upload can be any format you choose (ZIP, PDF, MP4, etc.). Regardless of +the file type, Google Play considers them opaque binary blobs and renames the files +using the following scheme:</p> + +<pre class="classic no-pretty-print"> +[main|patch].<expansion-version>.<package-name>.obb +</pre> + +<p>There are three components to this scheme:</p> + +<dl> + <dt>{@code main} or {@code patch}</dt> + <dd>Specifies whether the file is the main or patch expansion file. There can be +only one main file and one patch file for each APK.</dd> + <dt>{@code <expansion-version>}</dt> + <dd>This is an integer that matches the version code of the APK with which the expansion is +<em>first</em> associated (it matches the application's <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> +value). + <p>"First" is emphasized because although the Developer Console allows you to +re-use an uploaded expansion file with a new APK, the expansion file's name does not change—it +retains the version applied to it when you first uploaded the file.</p></dd> + <dt>{@code <package-name>}</dt> + <dd>Your application's Java-style package name.</dd> +</dl> + +<p>For example, suppose your APK version is 314159 and your package name is com.example.app. If you +upload a main expansion file, the file is renamed to:</p> +<pre class="classic no-pretty-print">main.314159.com.example.app.obb</pre> + + +<h3 id="StorageLocation">Storage location</h3> + +<p>When Google Play downloads your expansion files to a device, it saves them to the system's +shared storage location. To ensure proper behavior, you must not delete, move, or rename the +expansion files. In the event that your application must perform the download from Google Play +itself, you must save the files to the exact same location.</p> + +<p>The specific location for your expansion files is:</p> + +<pre class="classic no-pretty-print"> +<shared-storage>/Android/obb/<package-name>/ +</pre> + +<ul> + <li>{@code <shared-storage>} is the path to the shared storage space, available from +{@link android.os.Environment#getExternalStorageDirectory()}.</li> + <li>{@code <package-name>} is your application's Java-style package name, available +from {@link android.content.Context#getPackageName()}.</li> +</ul> + +<p>For each application, there are never more than two expansion files in this directory. +One is the main expansion file and the other is the patch expansion file (if necessary). Previous +versions are overwritten when you update your application with new expansion files.</p> + +<p>If you must unpack the contents of your expansion files, <strong>do not</strong> delete the +{@code .obb} expansion files afterwards and <strong>do not</strong> save the unpacked data +in the same directory. You should save your unpacked files in the directory +specified by {@link android.content.Context#getExternalFilesDir getExternalFilesDir()}. However, +if possible, it's best if you use an expansion file format that allows you to read directly from +the file instead of requiring you to unpack the data. For example, we've provided a library +project called the <a href="#ZipLib">APK Expansion Zip Library</a> that reads your data directly +from the ZIP file.</p> + +<p class="note"><strong>Note:</strong> Unlike APK files, any files saved on the shared storage can +be read by the user and other applications.</p> + +<p class="note"><strong>Tip:</strong> If you're packaging media files into a ZIP, you can use media +playback calls on the files with offset and length controls (such as {@link +android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and +{@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}) without the +need to unpack your ZIP. In order for this to work, you must not perform additional compression on +the media files when creating the ZIP packages. For example, when using the <code>zip</code> tool, +you should use the <code>-n</code> option to specify the file suffixes that should not be +compressed: <br/> +<code>zip -n .mp4;.ogg main_expansion media_files</code></p> + + +<h3 id="DownloadProcess">Download process</h3> + +<p>Most of the time, Google Play downloads and saves your expansion files at the same time it +downloads the APK to the device. However, in some cases Google Play +cannot download the expansion files or the user might have deleted previously downloaded expansion +files. To handle these situations, your app must be able to download the files +itself when the main activity starts, using a URL provided by Google Play.</p> + +<p>The download process from a high level looks like this:</p> + +<ol> + <li>User selects to install your app from Google Play.</li> + <li>If Google Play is able to download the expansion files (which is the case for most +devices), it downloads them along with the APK. + <p>If Google Play is unable to download the expansion files, it downloads the +APK only.</p> + </li> + <li>When the user launches your application, your app must check whether the expansion files are +already saved on the device. + <ol> + <li>If yes, your app is ready to go.</li> + <li>If no, your app must download the expansion files over HTTP from Google Play. Your app +must send a request to the Google Play client using the Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service, which +responds with the name, file size, and URL for each expansion file. With this information, you then +download the files and save them to the proper <a href="#StorageLocation">storage location</a>.</li> + </ol> + </li> +</ol> + +<p class="caution"><strong>Caution:</strong> It is critical that you include the necessary code to +download the expansion files from Google Play in the event that the files are not already on the +device when your application starts. As discussed in the following section about <a +href="#Downloading">Downloading the Expansion Files</a>, we've made a library available to you that +greatly simplifies this process and performs the download from a service with a minimal amount of +code from you.</p> + + + + +<h3 id="Checklist">Development checklist</h3> + +<p>Here's a summary of the tasks you should perform to use expansion files with your +application:</p> + +<ol> + <li>First determine whether your application absolutely requires more than 50MB per installation. +Space is precious and you should keep your total application size as small as possible. If your app +uses more than 50MB in order to provide multiple versions of your graphic assets for multiple screen +densities, consider instead publishing <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">multiple APKs</a> in which each APK +contains only the assets required for the screens that it targets.</li> + <li>Determine which application resources to separate from your APK and package them in a +file to use as the main expansion file. + <p>Normally, you should only use the second patch expansion file when performing updates to +the main expansion file. However, if your resources exceed the 2GB limit for the main +expansion file, you can use the patch file for the rest of your assets.</p> + </li> + <li>Develop your application such that it uses the resources from your expansion files in the +device's <a href="#StorageLocation">shared storage location</a>. + <p>Remember that you must not delete, move, or rename the expansion files.</p> + <p>If your application doesn't demand a specific format, we suggest you create ZIP files for +your expansion files, then read them using the <a href="#ZipLib">APK Expansion Zip +Library</a>.</p> + </li> + <li>Add logic to your application's main activity that checks whether the expansion files +are on the device upon start-up. If the files are not on the device, use Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service to request URLs +for the expansion files, then download and save them. + <p>To greatly reduce the amount of code you must write and ensure a good user experience +during the download, we recommend you use the <a href="AboutLibraries">Downloader +Library</a> to implement your download behavior.</p> + <p>If you build your own download service instead of using the library, be aware that you +must not change the name of the expansion files and must save them to the proper +<a href="#StorageLocation">storage location</a>.</p></li> +</ol> + +<p>Once you've finished your application development, follow the guide to <a href="#Testing">Testing +Your Expansion Files</a>.</p> + + + + + + +<h2 id="Rules">Rules and Limitations</h2> + +<p>Adding APK expansion files is a feature available when you upload your application using the +Developer Console. When uploading your application for the first time or updating an +application that uses expansion files, you must be aware of the following rules and limitations:</p> + +<ol type="I"> + <li>Each expansion file can be no more than 2GB.</li> + <li>In order to download your expansion files from Google Play, <strong>the user must have +acquired your application from Google Play</strong>. Google Play will not +provide the URLs for your expansion files if the application was installed by other means.</li> + <li>When performing the download from within your application, the URL that Google Play +provides for each file is unique for every download and each one expires shortly after it is given +to your application.</li> + <li>If you update your application with a new APK or upload <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">multiple APKs</a> for the same +application, you can select expansion files that you've uploaded for a previous APK. <strong>The +expansion file's name does not change</strong>—it retains the version received by the APK to +which the file was originally associated.</li> + <li>If you use expansion files in combination with <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">multiple APKs</a> in order to +provide different expansion files for different devices, you still must upload separate APKs +for each device in order to provide a unique <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> +value and declare different <a href="{@docRoot}guide/appendix/market-filters.html">filters</a> for +each APK.</li> + <li>You cannot issue an update to your application by changing the expansion files +alone—<strong>you must upload a new APK</strong> to update your app. If your changes only +concern the assets in your expansion files, you can update your APK simply by changing the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> (and +perhaps also the <a href="{@docRoot}guide/topics/manifest/manifest-element.html#vname">{@code +versionName}</a>).</p></li> + <li><strong>Do not save other data into your <code>obb/</code> +directory</strong>. If you must unpack some data, save it into the location specified by {@link +android.content.Context#getExternalFilesDir getExternalFilesDir()}.</li> + <li><strong>Do not delete or rename the {@code .obb} expansion file</strong> (unless you're +performing an update). Doing so will cause Google Play (or your app itself) to repeatedly +download the expansion file.</li> + <li>When updating an expansion file manually, you must delete the previous expansion file.</li> +</ol> + + + + + + + + + +<h2 id="Downloading">Downloading the Expansion Files</h2> + +<p>In most cases, Google Play downloads and saves your expansion files to the device at the same +time it installs or updates the APK. This way, the expansion files are available when your +application launches for the first time. However, in some cases your app must download the +expansion files itself by requesting them from a URL provided to you in a response +from Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service.</p> + +<p>The basic logic you need to download your expansion files is the following:</p> + +<ol> + <li>When your application starts, look for the expansion files on the <a +href="#StorageLocation">shared storage location</a> (in the +<code>Android/obb/<package-name>/</code> directory). + <ol type="a"> + <li>If the expansion files are there, you're all set and your application can continue.</li> + <li>If the expansion files are <em>not</em> there: + <ol> + <li>Perform a request using Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> to get your +app's expansion file names, sizes, and URLs.</li> + <li>Use the URLs provided by Google Play to download the expansion files and save +the expansion files. You <strong>must</strong> save the files to the <a +href="#StorageLocation">shared storage location</a> +(<code>Android/obb/<package-name>/</code>) and use the exact file name provided +by Google Play's response. + <p class="note"><strong>Note:</strong> The URL that Google Play provides for your +expansion files is unique for every download and each one expires shortly after it is given to +your application.</p> + </li> + </ol> + </li> + </ol> + </li> +</ol> + + +<p>If your application is free (not a paid app), then you probably haven't used the <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service. It's primarily +designed for you to enforce +licensing policies for your application and ensure that the user has the right to +use your app (he or she rightfully paid for it on Google Play). In order to facilitate the +expansion file functionality, the licensing service has been enhanced to provide a response +to your application that includes the URL of your application's expansion files that are hosted +on Google Play. So, even if your application is free for users, you need to include the +License Verification Library (LVL) to use APK expansion files. Of course, if your application +is free, you don't need to enforce license verification—you simply need the +library to perform the request that returns the URL of your expansion files.</p> + +<p class="note"><strong>Note:</strong> Whether your application is free or not, Google Play +returns the expansion file URLs only if the user acquired your application from Google Play.</p> + +<p>In addition to the LVL, you need a set of code that downloads the expansion files +over an HTTP connection and saves them to the proper location on the device's shared storage. +As you build this procedure into your application, there are several issues you should take into +consideration:</p> + +<ul> + <li>The device might not have enough space for the expansion files, so you should check +before beginning the download and warn the user if there's not enough space.</li> + <li>File downloads should occur in a background service in order to avoid blocking the user +interaction and allow the user to leave your app while the download completes.</li> + <li>A variety of errors might occur during the request and download that you must +gracefully handle.</li> + <li>Network connectivity can change during the download, so you should handle such changes and +if interrupted, resume the download when possible.</li> + <li>While the download occurs in the background, you should provide a notification that +indicates the download progress, notifies the user when it's done, and takes the user back to +your application when selected.</li> +</ul> + + +<p>To simplify this work for you, we've built the <a href="#AboutLibraries">Downloader Library</a>, +which requests the expansion file URLs through the licensing service, downloads the expansion files, +performs all of the tasks listed above, and even allows your activity to pause and resume the +download. By adding the Downloader Library and a few code hooks to your application, almost all the +work to download the expansion files is already coded for you. As such, in order to provide the best +user experience with minimal effort on your behalf, we recommend you use the Downloader Library to +download your expansion files. The information in the following sections explain how to integrate +the library into your application.</p> + +<p>If you'd rather develop your own solution to download the expansion files using the Google +Play URLs, you must follow the <a href="{@docRoot}guide/market/licensing/index.html">Application +Licensing</a> documentation to perform a license request, then retrieve the expansion file names, +sizes, and URLs from the response extras. You should use the <a href="#ExpansionPolicy">{@code +APKExpansionPolicy}</a> class (included in the License Verification Library) as your licensing +policy, which captures the expansion file names, sizes, and URLs from the licensing service..</p> + + + +<h3 id="AboutLibraries">About the Downloader Library</h3> + +<p>To use APK expansion files with your application and provide the best user experience with +minimal effort on your behalf, we recommend you use the Downloader Library that's included in the +Google Market Apk Expansion package. This library downloads your expansion files in a +background service, shows a user notification with the download status, handles network +connectivity loss, resumes the download when possible, and more.</p> + +<p>To implement expansion file downloads using the Downloader Library, all you need to do is:</p> + +<ul> + <li>Extend a special {@link android.app.Service} subclass and {@link +android.content.BroadcastReceiver} subclass that each require just a few +lines of code from you.</li> + <li>Add some logic to your main activity that checks whether the expansion files have +already been downloaded and, if not, invokes the download process and displays a +progress UI.</li> + <li>Implement a callback interface with a few methods in your main activity that +receives updates about the download progress.</li> +</ul> + +<p>The following sections explain how to set up your app using the Downloader Library.</p> + + +<h3 id="Preparing">Preparing to use the Downloader Library</h3> + +<p>To use the Downloader Library, you need to +download two packages from the SDK Manager and add the appropriate libraries to your +application.</p> + +<p>First, open the <a href="{@docRoot}sdk/adding-components.html">Android SDK Manager</a>, expand +<em>Extras</em> and download:</p> +<ul> + <li><em>Google Market Licensing package</em></li> + <li><em>Google Market Apk Expansion package</em></li> +</ul> + +<p>If you're using Eclipse, create a project for each library and add it to your app:</p> +<ol> + <li>Create a new Library Project for the License Verification Library and Downloader +Library. For each library: + <ol> + <li>Begin a new Android project.</li> + <li>Select <strong>Create project from existing +source</strong> and choose the library from the {@code <sdk>/extras/google/} directory +({@code market_licensing/} for the License Verification Library or {@code +market_apk_expansion/downloader_library/} for the Downloader Library).</li> + <li>Specify a <em>Project Name</em> such as "Google Play License Library" and "Google Play +Downloader +Library"</li> + <li>Click <strong>Finish</strong>.</li> + </ol> +<p class="note"><strong>Note:</strong> The Downloader Library depends on the License +Verification Library. Be sure to add the License +Verification Library to the Downloader Library's project properties (same process as +steps 2 and 3 below).</p> + </li> + <li>Right-click the Android project in which you want to use APK expansion files and +select <strong>Properties</strong>.</li> + <li>In the <em>Library</em> panel, click <strong>Add</strong> to select and add each of the +libraries to your application.</li> +</ol> + +<p>Or, from a command line, update your project to include the libraries:</p> +<ol> + <li>Change directories to the <code><sdk>/tools/</code> directory.</li> + <li>Execute <code>android update project</code> with the {@code --library} option to add both the +LVL and the Downloader Library to your project. For example: +<pre class="no-pretty-print"> +android update project --path ~/Android/MyApp \ +--library ~/android_sdk/extras/google/market_licensing \ +--library ~/android_sdk/extras/google/market_apk_expansion/downloader_library +</pre> + </li> +</ol> + +<p>With both the License Verification Library and Downloader Library added to your +application, you'll be able to quickly integrate the ability to download expansion files from +Google Play. The format that you choose for the expansion files and how you read them +from the shared storage is a separate implementation that you should consider based on your +application needs.</p> + +<p class="note"><strong>Tip:</strong> The Apk Expansion package includes a sample +application +that shows how to use the Downloader Library in an app. The sample uses a third library +available in the Apk Expansion package called the APK Expansion Zip Library. If +you plan on +using ZIP files for your expansion files, we suggest you also add the APK Expansion Zip Library to +your application. For more information, see the section below +about <a href="#ZipLib">Using the APK Expansion Zip Library</a>.</p> + + + +<h3 id="Permissions">Declaring user permissions</h3> + +<p>In order to download the expansion files, the Downloader Library +requires several permissions that you must declare in your application's manifest file. They +are:</p> + +<pre> +<manifest ...> + <!-- Required to access Google Play Licensing --> + <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> + + <!-- Required to download files from Google Play --> + <uses-permission android:name="android.permission.INTERNET" /> + + <!-- Required to keep CPU alive while downloading files (NOT to keep screen awake) --> + <uses-permission android:name="android.permission.WAKE_LOCK" /> + + <!-- Required to poll the state of the network connection and respond to changes --> + <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> + + <!-- Required to check whether Wi-Fi is enabled --> + <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/> + + <!-- Required to read and write the expansion files on shared storage --> + <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> + ... +</manifest> +</pre> + +<p class="note"><strong>Note:</strong> By default, the Downloader Library requires API +level 4, but the APK Expansion Zip Library requires API level 5.</p> + + +<h3 id="DownloaderService">Implementing the downloader service</h3> + +<p>In order to perform downloads in the background, the Downloader Library provides its +own {@link android.app.Service} subclass called {@code DownloaderService} that you should extend. In +addition to downloading the expansion files for you, the {@code DownloaderService} also:</p> + +<ul> + <li>Registers a {@link android.content.BroadcastReceiver} that listens for changes to the +device's network connectivity (the {@link android.net.ConnectivityManager#CONNECTIVITY_ACTION} +broadcast) in order to pause the download when necessary (such as due to connectivity loss) and +resume the download when possible (connectivity is acquired).</li> + <li>Schedules an {@link android.app.AlarmManager#RTC_WAKEUP} alarm to retry the download for +cases in which the service gets killed.</li> + <li>Builds a custom {@link android.app.Notification} that displays the download progress and +any errors or state changes.</li> + <li>Allows your application to manually pause and resume the download.</li> + <li>Verifies that the shared storage is mounted and available, that the files don't already exist, +and that there is enough space, all before downloading the expansion files. Then notifies the user +if any of these are not true.</li> +</ul> + +<p>All you need to do is create a class in your application that extends the {@code +DownloaderService} class and override three methods to provide specific application details:</p> + +<dl> + <dt>{@code getPublicKey()}</dt> + <dd>This must return a string that is the Base64-encoded RSA public key for your publisher +account, available from the profile page on the Developer Console (see <a +href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for Licensing</a>).</dd> + <dt>{@code getSALT()}</dt> + <dd>This must return an array of random bytes that the licensing {@code Policy} uses to +create an <a +href="{@docRoot}guide/market/licensing/adding-licensing.html#impl-Obfuscator">{@code +Obfuscator}</a>. The salt ensures that your obfuscated {@link android.content.SharedPreferences} +file in which your licensing data is saved will be unique and non-discoverable.</dd> + <dt>{@code getAlarmReceiverClassName()}</dt> + <dd>This must return the class name of the {@link android.content.BroadcastReceiver} in +your application that should receive the alarm indicating that the download should be +restarted (which might happen if the downloader service unexpectedly stops).</dd> +</dl> + +<p>For example, here's a complete implementation of {@code DownloaderService}:</p> + +<pre> +public class SampleDownloaderService extends DownloaderService { + // You must use the public key belonging to your publisher account + public static final String BASE64_PUBLIC_KEY = "YourLVLKey"; + // You should also modify this salt + public static final byte[] SALT = new byte[] { 1, 42, -12, -1, 54, 98, + -100, -12, 43, 2, -8, -4, 9, 5, -106, -107, -33, 45, -1, 84 + }; + + @Override + public String getPublicKey() { + return BASE64_PUBLIC_KEY; + } + + @Override + public byte[] getSALT() { + return SALT; + } + + @Override + public String getAlarmReceiverClassName() { + return SampleAlarmReceiver.class.getName(); + } +} +</pre> + +<p class="caution"><strong>Notice:</strong> You must update the {@code BASE64_PUBLIC_KEY} value +to be the public key belonging to your publisher account. You can find the key in the Developer +Console under your profile information. This is necessary even when testing +your downloads.</p> + +<p>Remember to declare the service in your manifest file:</p> +<pre> +<application ...> + <service android:name=".SampleDownloaderService" /> + ... +</application> +</pre> + + + +<h3 id="AlarmReceiver">Implementing the alarm receiver</h3> + +<p>In order to monitor the progress of the file downloads and restart the download if necessary, the +{@code DownloaderService} schedules an {@link android.app.AlarmManager#RTC_WAKEUP} alarm that +delivers an {@link android.content.Intent} to a {@link android.content.BroadcastReceiver} in your +application. You must define the {@link android.content.BroadcastReceiver} to call an API +from the Downloader Library that checks the status of the download and restarts +it if necessary.</p> + +<p>You simply need to override the {@link android.content.BroadcastReceiver#onReceive +onReceive()} method to call {@code +DownloaderClientMarshaller.startDownloadServiceIfRequired()}.</p> + +<p>For example:</p> + +<pre> +public class SampleAlarmReceiver extends BroadcastReceiver { + @Override + public void onReceive(Context context, Intent intent) { + try { + DownloaderClientMarshaller.startDownloadServiceIfRequired(context, intent, + SampleDownloaderService.class); + } catch (NameNotFoundException e) { + e.printStackTrace(); + } + } +} +</pre> + +<p>Notice that this is the class for which you must return the name +in your service's {@code getAlarmReceiverClassName()} method (see the previous section).</p> + +<p>Remember to declare the receiver in your manifest file:</p> +<pre> +<application ...> + <receiver android:name=".SampleAlarmReceiver" /> + ... +</application> +</pre> + + + +<h3 id="Download">Starting the download</h3> + +<p>The main activity in your application (the one started by your launcher icon) is +responsible for verifying whether the expansion files are already on the device and initiating +the download if they are not.</p> + +<p>Starting the download using the Downloader Library requires the following +procedures:</p> + +<ol> + <li>Check whether the files have been downloaded. + <p>The Downloader Library includes some APIs in the {@code Helper} class to +help with this process:</p> + <ul> + <li>{@code getExtendedAPKFileName(Context, c, boolean mainFile, int +versionCode)}</li> + <li>{@code doesFileExist(Context c, String fileName, long fileSize)}</li> + </ul> + <p>For example, the sample app provided in the Apk Expansion package calls the +following method in the activity's {@link android.app.Activity#onCreate onCreate()} method to check +whether the expansion files already exist on the device:</p> +<pre> +boolean expansionFilesDelivered() { + for (XAPKFile xf : xAPKS) { + String fileName = Helpers.getExpansionAPKFileName(this, xf.mIsBase, xf.mFileVersion); + if (!Helpers.doesFileExist(this, fileName, xf.mFileSize, false)) + return false; + } + return true; +} +</pre> + <p>In this case, each {@code XAPKFile} object holds the version number and file size of a known +expansion file and a boolean as to whether it's the main expansion file. (See the sample +application's {@code SampleDownloaderActivity} class for details.)</p> + <p>If this method returns false, then the application must begin the download.</p> + </li> + <li>Start the download by calling the static method {@code +DownloaderClientMarshaller.startDownloadServiceIfRequired(Context c, PendingIntent +notificationClient, Class<?> serviceClass)}. + <p>The method takes the following parameters:</p> + <ul> + <li><code>context</code>: Your application's {@link android.content.Context}.</li> + <li><code>notificationClient</code>: A {@link android.app.PendingIntent} to start your main +activity. This is used in the {@link android.app.Notification} that the {@code DownloaderService} +creates to show the download progress. When the user selects the notification, the system +invokes the {@link android.app.PendingIntent} you supply here and should open the activity +that shows the download progress (usually the same activity that started the download).</li> + <li><code>serviceClass</code>: The {@link java.lang.Class} object for your implementation of +{@code DownloaderService}, required to start the service and begin the download if necessary.</li> + </ul> + <p>The method returns an integer that indicates +whether or not the download is required. Possible values are:</p> + <ul> + <li>{@code NO_DOWNLOAD_REQUIRED}: Returned if the files already +exist or a download is already in progress.</li> + <li>{@code LVL_CHECK_REQUIRED}: Returned if a license verification is +required in order to acquire the expansion file URLs.</li> + <li>{@code DOWNLOAD_REQUIRED}: Returned if the expansion file URLs are already known, +but have not been downloaded.</li> + </ul> + <p>The behavior for {@code LVL_CHECK_REQUIRED} and {@code DOWNLOAD_REQUIRED} are essentially the +same and you normally don't need to be concerned about them. In your main activity that calls {@code +startDownloadServiceIfRequired()}, you can simply check whether or not the response is {@code +NO_DOWNLOAD_REQUIRED}. If the response is anything <em>other than</em> {@code NO_DOWNLOAD_REQUIRED}, +the Downloader Library begins the download and you should update your activity UI to +display the download progress (see the next step). If the response <em>is</em> {@code +NO_DOWNLOAD_REQUIRED}, then the files are available and your application can start.</p> + <p>For example:</p> +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + // Check if expansion files are available before going any further + if (!expansionFilesDelivered()) { + // Build an Intent to start this activity from the Notification + Intent notifierIntent = new Intent(this, MainActivity.getClass()); + notifierIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | + Intent.FLAG_ACTIVITY_CLEAR_TOP); + ... + PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, + notifierIntent, PendingIntent.FLAG_UPDATE_CURRENT); + + // Start the download service (if required) + int startResult = DownloaderClientMarshaller.startDownloadServiceIfRequired(this, + pendingIntent, SampleDownloaderService.class); + // If download has started, initialize this activity to show download progress + if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) { + // This is where you do set up to display the download progress (next step) + ... + return; + } // If the download wasn't necessary, fall through to start the app + } + startApp(); // Expansion files are available, start the app +} +</pre> + </li> + <li>When the {@code startDownloadServiceIfRequired()} method returns anything <em>other +than</em> {@code NO_DOWNLOAD_REQUIRED}, create an instance of {@code IStub} by +calling {@code DownloaderClientMarshaller.CreateStub(IDownloaderClient client, Class<?> +downloaderService)}. The {@code IStub} provides a binding between your activity to the downloader +service such that your activity receives callbacks about the download progress. + <p>In order to instantiate your {@code IStub} by calling {@code CreateStub()}, you must pass it +an implementation of the {@code IDownloaderClient} interface and your {@code DownloaderService} +implementation. The next section about <a href="#Progress">Receiving download progress</a> discusses +the {@code IDownloaderClient} interface, which you should usually implement in your {@link +android.app.Activity} class so you can update the activity UI when the download state changes.</p> + <p>We recommend that you call {@code +CreateStub()} to instantiate your {@code IStub} during your activity's {@link +android.app.Activity#onCreate onCreate()} method, after {@code startDownloadServiceIfRequired()} +starts the download. </p> + <p>For example, in the previous code sample for {@link android.app.Activity#onCreate +onCreate()}, you can respond to the {@code startDownloadServiceIfRequired()} result like this:</p> +<pre> + // Start the download service (if required) + int startResult = DownloaderClientMarshaller.startDownloadServiceIfRequired(this, + pendingIntent, SampleDownloaderService.class); + // If download has started, initialize activity to show progress + if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) { + // Instantiate a member instance of IStub + mDownloaderClientStub = DownloaderClientMarshaller.CreateStub(this, + SampleDownloaderService.class); + // Inflate layout that shows download progress + setContentView(R.layout.downloader_ui); + return; + } +</pre> + + <p>After the {@link android.app.Activity#onCreate onCreate()} method returns, your activity +receives a call to {@link android.app.Activity#onResume onResume()}, which is where you should then +call {@code connect()} on the {@code IStub}, passing it your application's {@link +android.content.Context}. Conversely, you should call +{@code disconnect()} in your activity's {@link android.app.Activity#onStop onStop()} callback.</p> +<pre> +@Override +protected void onResume() { + if (null != mDownloaderClientStub) { + mDownloaderClientStub.connect(this); + } + super.onResume(); +} + +@Override +protected void onStop() { + if (null != mDownloaderClientStub) { + mDownloaderClientStub.disconnect(this); + } + super.onStop(); +} +</pre> + <p>Calling {@code connect()} on the {@code IStub} binds your activity to the {@code +DownloaderService} such that your activity receives callbacks regarding changes to the download +state through the {@code IDownloaderClient} interface.</p> + </li> +</ol> + + + +<h3 id="Progress">Receiving download progress</h3> + +<p>To receive updates regarding the download progress and to interact with the {@code +DownloaderService}, you must implement the Downloader Library's {@code IDownloaderClient} interface. +Usually, the activity you use to start the download should implement this interface in order to +display the download progress and send requests to the service.</p> + +<p>The required interface methods for {@code IDownloaderClient} are:</p> + +<dl> + <dt>{@code onServiceConnected(Messenger m)}</dt> + <dd>After you instantiate the {@code IStub} in your activity, you'll receive a call to this +method, which passes a {@link android.os.Messenger} object that's connected with your instance +of {@code DownloaderService}. To send requests to the service, such as to pause and resume +downloads, you must call {@code DownloaderServiceMarshaller.CreateProxy()} to receive the {@code +IDownloaderService} interface connected to the service. + <p>A recommended implementation looks like this:</p> +<pre> +private IDownloaderService mRemoteService; +... + +@Override +public void onServiceConnected(Messenger m) { + mRemoteService = DownloaderServiceMarshaller.CreateProxy(m); + mRemoteService.onClientUpdated(mDownloaderClientStub.getMessenger()); +} +</pre> + <p>With the {@code IDownloaderService} object initialized, you can send commands to the +downloader service, such as to pause and resume the download ({@code requestPauseDownload()} +and {@code requestContinueDownload()}).</p> +</dd> + <dt>{@code onDownloadStateChanged(int newState)}</dt> + <dd>The download service calls this when a change in download state occurs, such as the +download begins or completes. + <p>The <code>newState</code> value will be one of several possible values specified in +by one of the {@code IDownloaderClient} class's {@code STATE_*} constants.</p> + <p>To provide a useful message to your users, you can request a corresponding string +for each state by calling {@code Helpers.getDownloaderStringResourceIDFromState()}. This +returns the resource ID for one of the strings bundled with the Downloader +Library. For example, the string "Download paused because you are roaming" corresponds to {@code +STATE_PAUSED_ROAMING}.</p></dd> + <dt>{@code onDownloadProgress(DownloadProgressInfo progress)}</dt> + <dd>The download service calls this to deliver a {@code DownloadProgressInfo} object, +which describes various information about the download progress, including estimated time remaining, +current speed, overall progress, and total so you can update the download progress UI.</dd> +</dl> +<p class="note"><strong>Tip:</strong> For examples of these callbacks that update the download +progress UI, see the {@code SampleDownloaderActivity} in the sample app provided with the +Apk Expansion package.</p> + +<p>Some public methods for the {@code IDownloaderService} interface you might find useful are:</p> + +<dl> + <dt>{@code requestPauseDownload()}</dt> + <dd>Pauses the download.</dd> + <dt>{@code requestContinueDownload()}</dt> + <dd>Resumes a paused download.</dd> + <dt>{@code setDownloadFlags(int flags)}</dt> + <dd>Sets user preferences for network types on which its OK to download the files. The +current implementation supports one flag, {@code FLAGS_DOWNLOAD_OVER_CELLULAR}, but you can add +others. By default, this flag is <em>not</em> enabled, so the user must be on Wi-Fi to download +expansion files. You might want to provide a user preference to enable downloads over +the cellular network. In which case, you can call: +<pre> +mRemoteService.setDownloadFlags(IDownloaderService.FLAGS_DOWNLOAD_OVER_CELLULAR); +</pre> +</dd> +</dl> + + + + +<h2 id="ExpansionPolicy">Using APKExpansionPolicy</h2> + +<p>If you decide to build your own downloader service instead of using the Google Play +<a href="#AboutLibraries">Downloader Library</a>, you should still use the {@code +APKExpansionPolicy} that's provided in the License Verification Library. The {@code +APKExpansionPolicy} class is nearly identical to {@code ServerManagedPolicy} (available in the +Google Play License Verification Library) but includes additional handling for the APK expansion +file response extras.</p> + +<p class="note"><strong>Note:</strong> If you <em>do use</em> the <a +href="#AboutLibraries">Downloader Library</a> as discussed in the previous section, the +library performs all interaction with the {@code APKExpansionPolicy} so you don't have to use +this class directly.</p> + +<p>The class includes methods to help you get the necessary information about the available +expansion files:</p> + +<ul> + <li>{@code getExpansionURLCount()}</li> + <li>{@code getExpansionURL(int index)}</li> + <li>{@code getExpansionFileName(int index)}</li> + <li>{@code getExpansionFileSize(int index)}</li> +</ul> + +<p>For more information about how to use the {@code APKExpansionPolicy} when you're <em>not</em> +using the <a +href="#AboutLibraries">Downloader Library</a>, see the documentation for <a +href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding Licensing to Your App</a>, +which explains how to implement a license policy such as this one.</p> + + + + + + + +<h2 id="ReadingTheFile">Reading the Expansion File</h2> + +<p>Once your APK expansion files are saved on the device, how you read your files +depends on the type of file you've used. As discussed in the <a href="#Overview">overview</a>, your +expansion files can be any kind of file you +want, but are renamed using a particular <a href="#Filename">file name format</a> and are saved to +{@code <shared-storage>/Android/obb/<package-name>/}.</p> + +<p>Regardless of how you read your files, you should always first check that the external +storage is available for reading. There's a chance that the user has the storage mounted to a +computer over USB or has actually removed the SD card.</p> + +<p class="note"><strong>Note:</strong> When your application starts, you should always check whether +the external storage space is available and readable by calling {@link +android.os.Environment#getExternalStorageState()}. This returns one of several possible strings +that represent the state of the external storage. In order for it to be readable by your +application, the return value must be {@link android.os.Environment#MEDIA_MOUNTED}.</p> + + +<h3 id="GettingFilenames">Getting the file names</h3> + +<p>As described in the <a href="#Overview">overview</a>, your APK expansion files are saved +using a specific file name format:</p> + +<pre class="classic no-pretty-print"> +[main|patch].<expansion-version>.<package-name>.obb +</pre> + +<p>To get the location and names of your expansion files, you should use the +{@link android.os.Environment#getExternalStorageDirectory()} and {@link +android.content.Context#getPackageName()} methods to construct the path to your files.</p> + +<p>Here's a method you can use in your application to get an array containing the complete path +to both your expansion files:</p> + +<pre> +// The shared path to all app expansion files +private final static String EXP_PATH = "/Android/obb/"; + +static String[] getAPKExpansionFiles(Context ctx, int mainVersion, int patchVersion) { + String packageName = ctx.getPackageName(); + Vector<String> ret = new Vector<String>(); + if (Environment.getExternalStorageState().equals(Environment.MEDIA_MOUNTED)) { + // Build the full path to the app's expansion files + File root = Environment.getExternalStorageDirectory(); + File expPath = new File(root.toString() + EXP_PATH + packageName); + + // Check that expansion file path exists + if (expPath.exists()) { + if ( mainVersion > 0 ) { + String strMainPath = expPath + File.separator + "main." + + mainVersion + "." + packageName + ".obb"; + File main = new File(strMainPath); + if ( main.isFile() ) { + ret.add(strMainPath); + } + } + if ( patchVersion > 0 ) { + String strPatchPath = expPath + File.separator + "patch." + + mainVersion + "." + packageName + ".obb"; + File main = new File(strPatchPath); + if ( main.isFile() ) { + ret.add(strPatchPath); + } + } + } + } + String[] retArray = new String[ret.size()]; + ret.toArray(retArray); + return retArray; +} +</pre> + +<p>You can call this method by passing it your application {@link android.content.Context} +and the desired expansion file's version.</p> + +<p>There are many ways you could determine the expansion file version number. One simple way is to +save the version in a {@link android.content.SharedPreferences} file when the download begins, by +querying the expansion file name with the {@code APKExpansionPolicy} class's {@code +getExpansionFileName(int index)} method. You can then get the version code by reading the {@link +android.content.SharedPreferences} file when you want to access the expansion +file.</p> + +<p>For more information about reading from the shared storage, see the <a +href="{@docRoot}guide/topics/data/data-storage.html#filesExternal">Data Storage</a> +documentation.</p> + + + +<h3 id="ZipLib">Using the APK Expansion Zip Library</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Reading media files from a ZIP</h3> + <p>If you're using your expansion files to store media files, a ZIP file still allows you to +use Android media playback calls that provide offset and length controls (such as {@link +android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and +{@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}). In order for +this to work, you must not perform additional compression on the media files when creating the ZIP +packages. For example, when using the <code>zip</code> tool, you should use the <code>-n</code> +option to specify the file suffixes that should not be compressed:</p> +<p><code>zip -n .mp4;.ogg main_expansion media_files</code></p> +</div> +</div> + +<p>The Google Market Apk Expansion package includes a library called the APK +Expansion Zip Library (located in {@code +<sdk>/extras/google/google_market_apk_expansion/zip_file/}). This is an optional library that +helps you read your expansion +files when they're saved as ZIP files. Using this library allows you to easily read resources from +your ZIP expansion files as a virtual file system.</p> + +<p>The APK Expansion Zip Library includes the following classes and APIs:</p> + +<dl> + <dt>{@code APKExpansionSupport}</dt> + <dd>Provides some methods to access expansion file names and ZIP files: + + <dl style="margin-top:1em"> + <dt>{@code getAPKExpansionFiles()}</dt> + <dd>The same method shown above that returns the complete file path to both expansion +files.</dd> + <dt>{@code getAPKExpansionZipFile(Context ctx, int mainVersion, int +patchVersion)}</dt> + <dd>Returns a {@code ZipResourceFile} representing the sum of both the main file and +patch file. That is, if you specify both the <code>mainVersion</code> and the +<code>patchVersion</code>, this returns a {@code ZipResourceFile} that provides read access to +all the data, with the patch file's data merged on top of the main file.</dd> + </dl> + </dd> + + <dt>{@code ZipResourceFile}</dt> + <dd>Represents a ZIP file on the shared storage and performs all the work to provide a virtual +file system based on your ZIP files. You can get an instance using {@code +APKExpansionSupport.getAPKExpansionZipFile()} or with the {@code ZipResourceFile} by passing it the +path to your expansion file. This class includes a variety of useful methods, but you generally +don't need to access most of them. A couple of important methods are: + + <dl style="margin-top:1em"> + <dt>{@code getInputStream(String assetPath)}</dt> + <dd>Provides an {@link java.io.InputStream} to read a file within the ZIP file. The +<code>assetPath</code> must be the path to the desired file, relative to +the root of the ZIP file contents.</dd> + <dt>{@code getAssetFileDescriptor(String assetPath)}</dt> + <dd>Provides an {@link android.content.res.AssetFileDescriptor} for a file within the +ZIP file. The <code>assetPath</code> must be the path to the desired file, relative to +the root of the ZIP file contents. This is useful for certain Android APIs that require an {@link +android.content.res.AssetFileDescriptor}, such as some {@link android.media.MediaPlayer} APIs.</dd> + </dl> + </dd> + + <dt>{@code APEZProvider}</dt> + <dd>Most applications don't need to use this class. This class defines a {@link +android.content.ContentProvider} that marshals the data from the ZIP files through a content +provider {@link android.net.Uri} in order to provide file access for certain Android APIs that +expect {@link android.net.Uri} access to media files. For example, this is useful if you want to +play a video with {@link android.widget.VideoView#setVideoURI VideoView.setVideoURI()}.</p></dd> +</dl> + +<h4>Reading from a ZIP file</h4> + +<p>When using the APK Expansion Zip Library, reading a file from your ZIP usually requires the +following:</p> + +<pre> +// Get a ZipResourceFile representing a merger of both the main and patch files +ZipResourceFile expansionFile = APKExpansionSupport.getAPKExpansionZipFile(appContext, + mainVersion, patchVersion); + +// Get an input stream for a known file inside the expansion file ZIPs +InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip); +</pre> + +<p>The above code provides access to any file that exists in either your main expansion file or +patch expansion file, by reading from a merged map of all the files from both files. All you +need to provide the {@code getAPKExpansionFile()} method is your application {@code +android.content.Context} and the version number for both the main expansion file and patch +expansion file.</p> + +<p>If you'd rather read from a specific expansion file, you can use the {@code +ZipResourceFile} constructor with the path to the desired expansion file:</p> + +<pre> +// Get a ZipResourceFile representing a specific expansion file +ZipResourceFile expansionFile = new ZipResourceFile(filePathToMyZip); + +// Get an input stream for a known file inside the expansion file ZIPs +InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip); +</pre> + +<p>For more information about using this library for your expansion files, look at +the sample application's {@code SampleDownloaderActivity} class, which includes additional code to +verify the downloaded files using CRC. Beware that if you use this sample as the basis for +your own implementation, it requires that you <strong>declare the byte size of your expansion +files</strong> in the {@code xAPKS} array.</p> + + + + +<h2 id="Testing">Testing Your Expansion Files</h2> + +<p>Before publishing your application, there are two things you should test: Reading the +expansion files and downloading the files.</p> + + +<h3 id="TestingReading">Testing file reads</h3> + +<p>Before you upload your application to Google Play, you +should test your application's ability to read the files from the shared storage. All you need to do +is add the files to the appropriate location on the device shared storage and launch your +application:</p> + +<ol> + <li>On your device, create the appropriate directory on the shared storage where Google +Play will save your files. + <p>For example, if your package name is {@code com.example.android}, you need to create +the directory {@code Android/obb/com.example.android/} on the shared storage space. (Plug in +your test device to your computer to mount the shared storage and manually create this +directory.)</p> + </li> + <li>Manually add the expansion files to that directory. Be sure that you rename your files to +match the <a href="#Filename">file name format</a> that Google Play will use. + <p>For example, regardless of the file type, the main expansion file for the {@code +com.example.android} application should be {@code main.0300110.com.example.android.obb}. +The version code can be whatever value you want. Just remember:</p> + <ul> + <li>The main expansion file always starts with {@code main} and the patch file starts with +{@code patch}.</li> + <li>The package name always matches that of the APK to which the file is attached on +Google Play. + </ul> + </li> + <li>Now that the expansion file(s) are on the device, you can install and run your application to +test your expansion file(s).</li> +</ol> + +<p>Here are some reminders about handling the expansion files:</p> +<ul> + <li><strong>Do not delete or rename</strong> the {@code .obb} expansion files (even if you unpack +the data to a different location). Doing so will cause Google Play (or your app itself) to +repeatedly download the expansion file.</li> + <li><strong>Do not save other data into your <code>obb/</code> +directory</strong>. If you must unpack some data, save it into the location specified by {@link +android.content.Context#getExternalFilesDir getExternalFilesDir()}.</li> +</ul> + + + +<h3 id="TestingReading">Testing file downloads</h3> + +<p>Because your application must sometimes manually download the expansion files when it first +opens, it's important that you test this process to be sure your application can successfully query +for the URLs, download the files, and save them to the device.</p> + +<p>To test your application's implementation of the manual download procedure, you must upload +your application to Google Play as a "draft" to make your expansion files available for +download:</p> + +<ol> + <li>Upload your APK and corresponding expansion files using the Google Play Developer +Console.</li> + <li>Fill in the necessary application details (title, screenshots, etc.). You can come back and +finalize these details before publishing your application. + <p>Click the <strong>Save</strong> button. <em>Do not click Publish.</em> This saves +the application as a draft, such that your application is not published for Google Play users, +but the expansion files are available for you to test the download process.</p></li> + <li>Install the application on your test device using the Eclipse tools or <a +href="{@docRoot}guide/developing/tools/adb.html">{@code adb}</a>.</li> + <li>Launch the app.</li> +</ol> + +<p>If everything works as expected, your application should begin downloading the expansion +files as soon as the main activity starts.</p> + + + + +<h2 id="Updating">Updating Your Application</h2> + +<p>One of the great benefits to using expansion files on Google Play is the ability to +update your application without re-downloading all of the original assets. Because Google Play +allows you to provide two expansion files with each APK, you can use the second file as a "patch" +that provides updates and new assets. Doing so avoids the +need to re-download the main expansion file which could be large and expensive for users.</p> + +<p>The patch expansion file is technically the same as the main expansion file and neither +the Android system nor Google Play perform actual patching between your main and patch expansion +files. Your application code must perform any necessary patches itself.</p> + +<p>If you use ZIP files as your expansion files, the <a href="#ZipLib">APK Expansion Zip +Library</a> that's included with the Apk Expansion package includes the ability to merge +your +patch file with the main expansion file.</p> + +<p class="note"><strong>Note:</strong> Even if you only need to make changes to the patch +expansion file, you must still update the APK in order for Google Play to perform an update. +If you don't require code changes in the application, you should simply update the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> in the +manifest.</p> + +<p>As long as you don't change the main expansion file that's associated with the APK +in the Developer Console, users who previously installed your application will not +download the main expansion file. Existing users receive only the updated APK and the new patch +expansion file (retaining the previous main expansion file).</p> + +<p>Here are a few issues to keep in mind regarding updates to expansion files:</p> + +<ul> + <li>There can be only two expansion files for your application at a time. One main expansion +file and one patch expansion file. During an update to a file, Google Play deletes the +previous version (and so must your application when performing manual updates).</li> + <li>When adding a patch expansion file, the Android system does not actually patch your +application or main expansion file. You must design your application to support the patch data. +However, the Apk Expansion package includes a library for using ZIP files +as expansion files, which merges the data from the patch file into the main expansion file so +you can easily read all the expansion file data.</li> +</ul> + + + +<!-- Tools are not ready. + +<h3>Using OBB tool and APIs</h3> + +<pre> +$ mkobb.sh -d /data/myfiles -k my_secret_key -o /data/data.obb +$ obbtool a -n com.example.myapp -v 1 -s seed_from_mkobb /data/data.obb +</pre> + +<pre> +storage = (StorageManager) getSystemService( STORAGE_SERVICE ); +storage.mountObb( obbFilepath, "my_secret_key", myListener ); +obbContentPath = storage.getMountedObbPath( obbFilepath ); +</pre> +--> diff --git a/docs/html/guide/market/licensing/adding-licensing.jd b/docs/html/guide/market/licensing/adding-licensing.jd new file mode 100644 index 0000000..d4dd008 --- /dev/null +++ b/docs/html/guide/market/licensing/adding-licensing.jd @@ -0,0 +1,1072 @@ +page.title=Adding Licensing to Your App +parent.title=Application Licensing +parent.link=index.html +@jd:body + + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#manifest-permission">Adding the Licensing Permission</a></li> + <li><a href="#impl-Policy">Implementing a Policy</a> + <ol> + <li><a href="#custom-policies">Guidelines for custom policies</a></li> + <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a></li> + <li><a href="#StrictPolicy">StrictPolicy</a></li> + </ol> + </li> + <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a> + <ol> + <li><a href="#AESObfuscator">AESObfuscator</a></li> + </ol> + </li> + <li><a href="#impl-lc">Checking the License from an Activity</a> + <ol> + <li><a href="#lc-overview">Overview of license check and response</a></li> + <li><a href="#imports">Add imports</a></li> + <li><a href="#lc-impl">Implement LicenseCheckerCallback as a private inner class</a></li> + <li><a href="#thread-handler">Create a Handler for posting from LicenseCheckerCallback +to the UI thread</a></li> + <li><a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a></li> + <li><a href="#check-access">Call checkAccess() to initiate the license check</a></li> + <li><a href="#account-key">Embed your public key for licensing</a></li> + <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method +to close IPC connections</a></li> + </ol> + </li> + <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a></li> + <li><a href="#app-obfuscation">Obfuscating Your Code</a></li> + <li><a href="#app-publishing">Publishing a Licensed Application</a> + <ol> + <li><a href="#">Removing Copy Protection</a></li> + </ol> + </li> + <li><a href="#support">Where to Get Support</a></li> +</ol> + +</div> +</div> + + + +<p>After you've set up a publisher account and development environment (see <a +href="setting-up.html">Setting Up for Licensing</a>), you are ready to add license verification to +your app with the License Verification Library (LVL).</p> + +<p>Adding license verification with the LVL involves these tasks:</p> + +<ol> +<li><a href="#manifest-permission">Adding the licensing permission</a> your application's manifest.</li> +<li><a href="#impl-Policy">Implementing a Policy</a> — you can choose one of the full implementations provided in the LVL or create your own.</li> +<li><a href="#impl-Obfuscator">Implementing an Obfuscator</a>, if your {@code Policy} will cache any +license response data. </li> +<li><a href="#impl-lc">Adding code to check the license</a> in your application's main +Activity.</li> +<li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a> (optional and not recommended for +most applications).</li> +</ol> + +<p>The sections below describe these tasks. When you are done with the +integration, you should be able to compile your application successfully and you +can begin testing, as described in <a +href="{@docRoot}guide/market/licensing/setting-up.html#test-env">Setting Up the Test +Environment</a>.</p> + +<p>For an overview of the full set of source files included in the LVL, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#lvl-summary">Summary of LVL Classes +and Interfaces</a>.</p> + + +<h2 id="manifest-permission">Adding the Licensing Permission</h2> + +<p>To use the Google Play application for sending a license check to the +server, your application must request the proper permission, +<code>com.android.vending.CHECK_LICENSE</code>. If your application does +not declare the licensing permission but attempts to initiate a license check, +the LVL throws a security exception.</p> + +<p>To request the licensing permission in your application, declare a <a +href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a> +element as a child of <code><manifest></code>, as follows: </p> + +<p style="margin-left:2em;"><code><uses-permission +android:name="com.android.vending.CHECK_LICENSE"></code></p> + +<p>For example, here's how the LVL sample application declares the permission: +</p> + +<pre><?xml version="1.0" encoding="utf-8"?> + +<manifest xmlns:android="http://schemas.android.com/apk/res/android" ..."> + <!-- Devices >= 3 have version of Google Play that supports licensing. --> + <uses-sdk android:minSdkVersion="3" /> + <!-- Required permission to check licensing. --> + <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> + ... +</manifest> +</pre> + +<p class="note"><strong>Note:</strong> Currently, you cannot declare the +<code>CHECK_LICENSE</code> permission in the LVL library project's manifest, +because the SDK Tools will not merge it into the manifests of dependent +applications. Instead, you must declare the permission in each dependent +application's manifest. </p> + + +<h2 id="impl-Policy">Implementing a Policy</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>ServerManagedPolicy</h2> + +<p>The LVL includes a complete {@code Policy} implementation called ServerManagedPolicy +that makes use of license-management settings provided by the Google Play +server. </p> + +<p style="margin-top:.5em;">Use of ServerManagedPolicy as the basis for your +Policy is strongly recommended. For more information, see <a +href="#ServerManagedPolicy">ServerManagedPolicy</a> section, below.</p> + +</div> +</div> + +<p>Google Play licensing service does not itself determine whether a +given user with a given license should be granted access to your application. +Rather, that responsibility is left to a {@code Policy} implementation that you provide +in your application.</p> + +<p>Policy is an interface declared by the LVL that is designed to hold your +application's logic for allowing or disallowing user access, based on the result +of a license check. To use the LVL, your application <em>must</em> provide an +implementation of {@code Policy}. </p> + +<p>The {@code Policy} interface declares two methods, <code>allowAccess()</code> and +<code>processServerResponse()</code>, which are called by a {@code LicenseChecker} +instance when processing a response from the license server. It also declares an +enum called <code>LicenseResponse</code>, which specifies the license response +value passed in calls to <code>processServerResponse()</code>. </p> + +<ul> +<li><code>processServerResponse()</code> lets you preprocess the raw response +data received from the licensing server, prior to determining whether to grant +access. + +<p>A typical implementation would extract some or all fields from the license +response and store the data locally to a persistent store, such as through +{@link android.content.SharedPreferences} storage, to ensure that the data is +accessible across application invocations and device power cycles. For example, +a {@code Policy} would maintain the timestamp of the last successful license check, the +retry count, the license validity period, and similar information in a +persistent store, rather than resetting the values each time the application is +launched.</p> + +<p>When storing response data locally, the {@code Policy} must ensure that the data is +obfuscated (see <a href="#impl-Obfuscator">Implementing an Obfuscator</a>, +below).</p></li> + +<li><code>allowAccess()</code> determines whether to grant the user access to +your application, based on any available license response data (from the +licensing server or from cache) or other application-specific information. For +example, your implementation of <code>allowAccess()</code> could take into +account additional criteria, such as usage or other data retrieved from a +backend server. In all cases, an implementation of <code>allowAccess()</code> +should only return <code>true</code> if the user is licensed to use the +application, as determined by the licensing server, or if there is a transient +network or system problem that prevents the license check from completing. In +such cases, your implementation can maintain a count of retry responses and +provisionally allow access until the next license check is complete.</li> + +</ul> + +<p>To simplify the process of adding licensing to your application and to +provide an illustration of how a {@code Policy} should be designed, the LVL includes +two full {@code Policy} implementations that you can use without modification or +adapt to your needs:</p> + +<ul> +<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible {@code Policy} +that uses server-provided settings and cached responses to manage access across +varied network conditions, and</li> +<li><a href="#StrictPolicy">StrictPolicy</a>, which does not cache any response +data and allows access <em>only</em> if the server returns a licensed +response.</li> +</ul> + +<p>For most applications, the use of ServerManagedPolicy is highly +recommended. ServerManagedPolicy is the LVL default and is integrated with +the LVL sample application.</p> + + +<h3 id="custom-policies">Guidelines for custom policies</h3> + +<p>In your licensing implementation, you can use one of the complete policies +provided in the LVL (ServerManagedPolicy or StrictPolicy) or you can create a +custom policy. For any type of custom policy, there are several important design +points to understand and account for in your implementation.</p> + +<p>The licensing server applies general request limits to guard against overuse +of resources that could result in denial of service. When an application exceeds +the request limit, the licensing server returns a 503 response, which gets +passed through to your application as a general server error. This means that no +license response will be available to the user until the limit is reset, which +can affect the user for an indefinite period.</p> + +<p>If you are designing a custom policy, we recommend that the {@code Policy}: +<ol> +<!-- <li>Limits the number of points at which your app calls for a license check +to the minimum. </li> --> +<li>Caches (and properly obfuscates) the most recent successful license response +in local persistent storage.</li> +<li>Returns the cached response for all license checks, for as long as the +cached response is valid, rather than making a request to the licensing server. +Setting the response validity according to the server-provided <code>VT</code> +extra is highly recommended. See <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response Extras</a> +for more information.</li> +<li>Uses an exponential backoff period, if retrying any requests the result in +errors. Note that the Google Play client automatically retries failed +requests, so in most cases there is no need for your {@code Policy} to retry them.</li> +<li>Provides for a "grace period" that allows the user to access your +application for a limited time or number of uses, while a license check is being +retried. The grace period benefits the user by allowing access until the next +license check can be completed successfully and it benefits you by placing a +hard limit on access to your application when there is no valid license response +available.</li> +</ol> + +<p>Designing your {@code Policy} according to the guidelines listed above is critical, +because it ensures the best possible experience for users while giving you +effective control over your application even in error conditions. </p> + +<p>Note that any {@code Policy} can use settings provided by the licensing server to +help manage validity and caching, retry grace period, and more. Extracting the +server-provided settings is straightforward and making use of them is highly +recommended. See the ServerManagedPolicy implementation for an example of how to +extract and use the extras. For a list of server settings and information about +how to use them, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response +Extras</a>.</p> + +<h3 id="ServerManagedPolicy">ServerManagedPolicy</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Server Response Extras</h2> + +<p>For certain types of licensing responses, the licensing server appends extra +settings to the responses, to help the application manage licensing effectively. +</p> + +<p style="margin-top:.5em;">See <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response Extras</a> +for +a list of settings and <code>ServerManagedPolicy.java</code> for information +about how a {@code Policy} can use the extras.</p> + +</div> +</div> + +<p>The LVL includes a full and recommended implementation of the {@code Policy} +interface called ServerManagedPolicy. The implementation is integrated with the +LVL classes and serves as the default {@code Policy} in the library. </p> + +<p>ServerManagedPolicy provides all of the handling for license and retry +responses. It caches all of the response data locally in a +{@link android.content.SharedPreferences} file, obfuscating it with the +application's {@code Obfuscator} implementation. This ensures that the license response +data is secure and persists across device power cycles. ServerManagedPolicy +provides concrete implementations of the interface methods +<code>processServerResponse()</code> and <code>allowAccess()</code> and also +includes a set of supporting methods and types for managing license +responses.</p> + +<p>Importantly, a key feature of ServerMangedPolicy is its use of +server-provided settings as the basis for managing licensing across an +application's refund period and through varying network and error conditions. +When an application contacts the Google Play server for a license check, the +server appends several settings as key-value pairs in the extras field of certain +license response types. For example, the server provides recommended values for the +application's license validity period, retry grace period, and maximum allowable +retry count, among others. ServerManagedPolicy extracts the values from the +license response in its <code>processServerResponse()</code> method and checks +them in its <code>allowAccess()</code> method. For a list of the server-provided +settings used by ServerManagedPolicy, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response +Extras</a>.</p> + +<p>For convenience, best performance, and the benefit of using license settings +from the Google Play server, <strong>using ServerManagedPolicy as your +licensing {@code Policy} is strongly recommended</strong>. </p> + +<p>If you are concerned about the security of license response data that is +stored locally in {@link android.content.SharedPreferences}, you can use a stronger obfuscation +algorithm or design a stricter {@code Policy} that does not store license data. The LVL +includes an example of such a {@code Policy} — see <a +href="#StrictPolicy">StrictPolicy</a> for more information.</p> + +<p>To use ServerManagedPolicy, simply import it to your Activity, create an +instance, and pass a reference to the instance when constructing your +{@code LicenseChecker}. See <a href="#lc-lcc">Instantiate LicenseChecker and +LicenseCheckerCallback</a> for more information. </p> + +<h3 id="StrictPolicy">StrictPolicy</h3> + +<p>The LVL includes an alternative full implementation of the {@code Policy} interface +called StrictPolicy. The StrictPolicy implementation provides a more restrictive +Policy than ServerManagedPolicy, in that it does not allow the user to access +the application unless a license response is received from the server at the +time of access that indicates that the user is licensed.</p> + +<p>The principal feature of StrictPolicy is that it does not store <em>any</em> +license response data locally, in a persistent store. Because no data is stored, +retry requests are not tracked and cached responses can not be used to fulfill +license checks. The {@code Policy} allows access only if:</p> + +<ul> +<li>The license response is received from the licensing server, and </li> +<li>The license response indicates that the user is licensed to access the +application. </li> +</ul> + +<p>Using StrictPolicy is appropriate if your primary concern is to ensure that, +in all possible cases, no user will be allowed to access the application unless +the user is confirmed to be licensed at the time of use. Additionally, the +Policy offers slightly more security than ServerManagedPolicy — since +there is no data cached locally, there is no way a malicious user could tamper +with the cached data and obtain access to the application.</p> + +<p>At the same time, this {@code Policy} presents a challenge for normal users, since it +means that they won't be able to access the application when there is no network +(cell or Wi-Fi) connection available. Another side-effect is that your +application will send more license check requests to the server, since using a +cached response is not possible.</p> + +<p>Overall, this policy represents a tradeoff of some degree of user convenience +for absolute security and control over access. Consider the tradeoff carefully +before using this {@code Policy}.</p> + +<p>To use StrictPolicy, simply import it to your Activity, create an instance, +and pass a reference to it when constructing your {@code LicenseChecker}. See +<a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a> +for more information. </p> + +<h2 id="impl-Obfuscator">Implementing an Obfuscator</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>AESObfuscator</h2> + +<p>The LVL includes a full {@code Obfuscator} implementation in the +<code>AESObfuscator.java</code> file. The {@code Obfuscator} uses AES encryption to +obfuscate/unobfuscate data. If you are using a {@code Policy} (such as +ServerManagedPolicy) that caches license response data, using AESObfuscator as +basis for your {@code Obfuscator} implementation is highly recommended. </p> + +</div> +</div> + +<p>A typical {@code Policy} implementation needs to save the license response data for +an application to a persistent store, so that it is accessible across +application invocations and device power cycles. For example, a {@code Policy} would +maintain the timestamp of the last successful license check, the retry count, +the license validity period, and similar information in a persistent store, +rather than resetting the values each time the application is launched. The +default {@code Policy} included in the LVL, ServerManagedPolicy, stores license response +data in a {@link android.content.SharedPreferences} instance, to ensure that the +data is persistent. </p> + +<p>Because the {@code Policy} will use stored license response data to determine whether +to allow or disallow access to the application, it <em>must</em> ensure that any +stored data is secure and cannot be reused or manipulated by a root user on a +device. Specifically, the {@code Policy} must always obfuscate the data before storing +it, using a key that is unique for the application and device. Obfuscating using +a key that is both application-specific and device-specific is critical, because +it prevents the obfuscated data from being shared among applications and +devices.</p> + +<p>The LVL assists the application with storing its license response data in a +secure, persistent manner. First, it provides an {@code Obfuscator} +interface that lets your application supply the obfuscation algorithm of its +choice for stored data. Building on that, the LVL provides the helper class +PreferenceObfuscator, which handles most of the work of calling the +application's {@code Obfuscator} class and reading and writing the obfuscated data in a +{@link android.content.SharedPreferences} instance. </p> + +<p>The LVL provides a full {@code Obfuscator} implementation called +AESObfuscator that uses AES encryption to obfuscate data. You can +use AESObfuscator in your application without modification or you +can adapt it to your needs. For more information, see the next section.</p> + + +<h3 id="AESObfuscator">AESObfuscator</h3> + +<p>The LVL includes a full and recommended implementation of the {@code Obfuscator} +interface called AESObfuscator. The implementation is integrated with the +LVL sample application and serves as the default {@code Obfuscator} in the library. </p> + +<p>AESObfuscator provides secure obfuscation of data by using AES to +encrypt and decrypt the data as it is written to or read from storage. +The {@code Obfuscator} seeds the encryption using three data fields provided +by the application: </p> + +<ol> +<li>A salt — an array of random bytes to use for each (un)obfuscation. </li> +<li>An application identifier string, typically the package name of the application.</li> +<li>A device identifier string, derived from as many device-specific sources +as possible, so as to make it as unique.</li> +</ol> + +<p>To use AESObfuscator, first import it to your Activity. Declare a private +static final array to hold the salt bytes and initialize it to 20 randomly +generated bytes.</p> + +<pre> ... + // Generate 20 random bytes, and put them here. + private static final byte[] SALT = new byte[] { + -46, 65, 30, -128, -103, -57, 74, -64, 51, 88, -95, + -45, 77, -117, -36, -113, -11, 32, -64, 89 + }; + ... +</pre> + +<p>Next, declare a variable to hold a device identifier and generate a value for +it in any way needed. For example, the sample application included in the LVL +queries the system settings for the +<code>android.Settings.Secure.ANDROID_ID</code>, which is unique to each device. +</p> + +<p>Note that, depending on the APIs you use, your application might need to +request additional permissions in order to acquire device-specific information. +For example, to query the {@link android.telephony.TelephonyManager} to obtain +the device IMEI or related data, the application will also need to request the +<code>android.permission.READ_PHONE_STATE</code> permission in its manifest.</p> + +<p>Before requesting new permissions for the <em>sole purpose</em> of acquiring +device-specific information for use in your {@code Obfuscator}, consider +how doing so might affect your application or its filtering on Google Play +(since some permissions can cause the SDK build tools to add +the associated <code><uses-feature></code>).</p> + +<p>Finally, construct an instance of AESObfuscator, passing the salt, +application identifier, and device identifier. You can construct the instance +directly, while constructing your {@code Policy} and {@code LicenseChecker}. For example:</p> + +<pre> ... + // Construct the LicenseChecker with a Policy. + mChecker = new LicenseChecker( + this, new ServerManagedPolicy(this, + new AESObfuscator(SALT, getPackageName(), deviceId)), + BASE64_PUBLIC_KEY // Your public licensing key. + ); + ... +</pre> + +<p>For a complete example, see MainActivity in the LVL sample application.</p> + + +<h2 id="impl-lc">Checking the License from an Activity</h2> + +<p>Once you've implemented a {@code Policy} for managing access to your application, the +next step is to add a license check to your application, which initiates a query +to the licensing server if needed and manages access to the application based on +the license response. All of the work of adding the license check and handling +the response takes place in your main {@link android.app.Activity} source file. +</p> + +<p>To add the license check and handle the response, you must:</p> + +<ol> + <li><a href="#imports">Add imports</a></li> + <li><a href="#lc-impl">Implement LicenseCheckerCallback</a> as a private inner class</li> + <li><a href="#thread-handler">Create a Handler</a> for posting from LicenseCheckerCallback to the UI thread</li> + <li><a href="#lc-lcc">Instantiate LicenseChecker</a> and LicenseCheckerCallback</li> + <li><a href="#check-access">Call checkAccess()</a> to initiate the license check</li> + <li><a href="#account-key">Embed your public key</a> for licensing</li> + <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method</a> to close IPC connections.</li> +</ol> + +<p>The sections below describe these tasks. </p> + +<h3 id="lc-overview">Overview of license check and response</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Example: MainActivity</h2> + +<p>The sample application included with the LVL provides a full example of how +to initiate a license check and handle the result, in the +<code>MainActivity.java</code> file.</p> + +</div> +</div> + +<p>In most cases, you should add the license check to your application's main +{@link android.app.Activity}, in the {@link android.app.Activity#onCreate onCreate()} method. This +ensures that when the user launches your application directly, the license check +will be invoked immediately. In some cases, you can add license checks in other +locations as well. For example, if your application includes multiple Activity +components that other applications can start by {@link android.content.Intent}, +you could add license checks in those Activities.</p> + +<p>A license check consists of two main actions: </p> + +<ul> +<li>A call to a method to initiate the license check — in the LVL, this is +a call to the <code>checkAccess()</code> method of a {@code LicenseChecker} object that +you construct.</li> +<li>A callback that returns the result of the license check. In the LVL, this is +a <code>LicenseCheckerCallback</code> interface that you implement. The +interface declares two methods, <code>allow()</code> and +<code>dontAllow()</code>, which are invoked by the library based on to the +result of the license check. You implement these two methods with whatever logic +you need, to allow or disallow the user access to your application. Note that +these methods do not determine <em>whether</em> to allow access — that +determination is the responsibility of your {@code Policy} implementation. Rather, these +methods simply provide the application behaviors for <em>how</em> to allow and +disallow access (and handle application errors). + <p>The <code>allow()</code> and <code>dontAllow()</code> methods do provide a "reason" +for their response, which can be one of the {@code Policy} values, {@code LICENSED}, +{@code NOT_LICENSED}, or {@code RETRY}. In particular, you should handle the case in which +the method receives the {@code RETRY} response for {@code dontAllow()} and provide the user with an +"Retry" button, which might have happened because the service was unavailable during the +request.</p></li> +</ul> + +<div style="margin-bottom:2em;"> + +<img src="{@docRoot}images/licensing_flow.png" style="text-align:left;margin-bottom:0;margin-left:3em;" /> +<div style="margin:.5em 0 1.5em 2em;padding:0"><strong>Figure 6.</strong> Overview of a +typical license check interaction.</div> +</div> + +<p>The diagram above illustrates how a typical license check takes place: </p> + +<ol> +<li>Code in the application's main Activity instantiates {@code LicenseCheckerCallback} +and {@code LicenseChecker} objects. When constructing {@code LicenseChecker}, the code passes in +{@link android.content.Context}, a {@code Policy} implementation to use, and the +publisher account's public key for licensing as parameters. </li> +<li>The code then calls the <code>checkAccess()</code> method on the +{@code LicenseChecker} object. The method implementation calls the {@code Policy} to determine +whether there is a valid license response cached locally, in +{@link android.content.SharedPreferences}. + <ul> + <li>If so, the <code>checkAccess()</code> implementation calls + <code>allow()</code>.</li> + <li>Otherwise, the {@code LicenseChecker} initiates a license check request that is sent + to the licensing server.</li> + </ul> + +<p class="note"><strong>Note:</strong> The licensing server always returns +<code>LICENSED</code> when you perform a license check of a draft application.</p> +</li> +<li>When a response is received, {@code LicenseChecker} creates a LicenseValidator that +verifies the signed license data and extracts the fields of the response, then +passes them to your {@code Policy} for further evaluation. + <ul> + <li>If the license is valid, the {@code Policy} caches the response in +{@link android.content.SharedPreferences} and notifies the validator, which then calls the +<code>allow()</code> method on the {@code LicenseCheckerCallback} object. </li> + <li>If the license not valid, the {@code Policy} notifies the validator, which calls +the <code>dontAllow()</code> method on {@code LicenseCheckerCallback}. </li> + </ul> +</li> +<li>In case of a recoverable local or server error, such as when the network is +not available to send the request, {@code LicenseChecker} passes a {@code RETRY} response to +your {@code Policy} object's <code>processServerResponse()</code> method. + <p>Also, both the {@code allow()} and {@code dontAllow()} callback methods receive a +<code>reason</code> argument. The {@code allow()} method's reason is usually {@code +Policy.LICENSED} or {@code Policy.RETRY} and the {@code dontAllow()} reason is usually {@code +Policy.NOT_LICENSED} or {@code Policy.RETRY}. These response values are useful so you can show +an appropriate response for the user, such as by providing a "Retry" button when {@code +dontAllow()} responds with {@code Policy.RETRY}, which might have been because the service was +unavailable.</p></li> +<li>In case of a application error, such as when the application attempts to +check the license of an invalid package name, {@code LicenseChecker} passes an error +response to the LicenseCheckerCallback's <code>applicationError()</code> +method. </li> +</ol> + +<p>Note that, in addition to initiating the license check and handling the +result, which are described in the sections below, your application also needs +to provide a <a href="#impl-Policy">Policy implementation</a> and, if the {@code Policy} +stores response data (such as ServerManagedPolicy), an <a +href="#impl-Obfuscator">Obfuscator</a> implementation. </p> + + +<h3 id="imports">Add imports</h3> + +<p>First, open the class file of the application's main Activity and import +{@code LicenseChecker} and {@code LicenseCheckerCallback} from the LVL package.</p> + +<pre> import com.android.vending.licensing.LicenseChecker; + import com.android.vending.licensing.LicenseCheckerCallback;</pre> + +<p>If you are using the default {@code Policy} implementation provided with the LVL, +ServerManagedPolicy, import it also, together with the AESObfuscator. If you are +using a custom {@code Policy} or {@code Obfuscator}, import those instead. </p> + +<pre> import com.android.vending.licensing.ServerManagedPolicy; + import com.android.vending.licensing.AESObfuscator;</pre> + +<h3 id="lc-impl">Implement LicenseCheckerCallback as a private inner class</h3> + +<p>{@code LicenseCheckerCallback} is an interface provided by the LVL for handling +result of a license check. To support licensing using the LVL, you must +implement {@code LicenseCheckerCallback} and +its methods to allow or disallow access to the application.</p> + +<p>The result of a license check is always a call to one of the +{@code LicenseCheckerCallback} methods, made based on the validation of the response +payload, the server response code itself, and any additional processing provided +by your {@code Policy}. Your application can implement the methods in any way needed. In +general, it's best to keep the methods simple, limiting them to managing UI +state and application access. If you want to add further processing of license +responses, such as by contacting a backend server or applying custom constraints, +you should consider incorporating that code into your {@code Policy}, rather than +putting it in the {@code LicenseCheckerCallback} methods. </p> + +<p>In most cases, you should declare your implementation of +{@code LicenseCheckerCallback} as a private class inside your application's main +Activity class. </p> + +<p>Implement the <code>allow()</code> and <code>dontAllow()</code> methods as +needed. To start with, you can use simple result-handling behaviors in the +methods, such as displaying the license result in a dialog. This helps you get +your application running sooner and can assist with debugging. Later, after you +have determined the exact behaviors you want, you can add more complex handling. +</p> + +<p>Some suggestions for handling unlicensed responses in +<code>dontAllow()</code> include: </p> + +<ul> +<li>Display a "Try again" dialog to the user, including a button to initiate a +new license check if the <code>reason</code> supplied is {@code Policy.RETRY}. </li> +<li>Display a "Purchase this application" dialog, including a button that +deep-links the user to the application's details page on Google Play, from which the +use can purchase the application. For more information on how to set up such +links, see <a +href="{@docRoot}guide/publishing/publishing.html#marketintent">Linking to your apps +on Google Play</a>. </li> +<li>Display a Toast notification that indicates that the features of the +application are limited because it is not licensed. </li> +</ul> + +<p>The example below shows how the LVL sample application implements +{@code LicenseCheckerCallback}, with methods that display the license check result in a +dialog. </p> + +<pre> +private class MyLicenseCheckerCallback implements LicenseCheckerCallback { + public void allow(int reason) { + if (isFinishing()) { + // Don't update UI if Activity is finishing. + return; + } + // Should allow user access. + displayResult(getString(R.string.allow)); + } + + public void dontAllow(int reason) { + if (isFinishing()) { + // Don't update UI if Activity is finishing. + return; + } + displayResult(getString(R.string.dont_allow)); + + if (reason == Policy.RETRY) { + // If the reason received from the policy is RETRY, it was probably + // due to a loss of connection with the service, so we should give the + // user a chance to retry. So show a dialog to retry. + showDialog(DIALOG_RETRY); + } else { + // Otherwise, the user is not licensed to use this app. + // Your response should always inform the user that the application + // is not licensed, but your behavior at that point can vary. You might + // provide the user a limited access version of your app or you can + // take them to Google Play to purchase the app. + showDialog(DIALOG_GOTOMARKET); + } + } +} +</pre> + +<p>Additionally, you should implement the <code>applicationError()</code> +method, which the LVL calls to let your application handle errors that are not +retryable. For a list of such errors, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server +Response Codes</a> in the <a +href="guide/market/licensing/licensing-reference.html">Licensing Reference</a>. You can implement +the method in any way needed. In most cases, the +method should log the error code and call <code>dontAllow()</code>.</p> + +<h3 id="thread-handler">Create a Handler for posting from LicenseCheckerCallback +to the UI thread</h3> + +<p>During a license check, the LVL passes the request to the Google Play +application, which handles communication with the licensing server. The LVL +passes the request over asynchronous IPC (using {@link android.os.Binder}) so +the actual processing and network communication do not take place on a thread +managed by your application. Similarly, when the Google Play application +receives the result, it invokes a callback method over IPC, which in turn +executes in an IPC thread pool in your application's process.</p> + +<p>The {@code LicenseChecker} class manages your application's IPC communication with +the Google Play application, including the call that sends the request and +the callback that receives the response. {@code LicenseChecker} also tracks open license +requests and manages their timeouts. </p> + +<p>So that it can handle timeouts properly and also process incoming responses +without affecting your application's UI thread, {@code LicenseChecker} spawns a +background thread at instantiation. In the thread it does all processing of +license check results, whether the result is a response received from the server +or a timeout error. At the conclusion of processing, the LVL calls your +{@code LicenseCheckerCallback} methods from the background thread. </p> + +<p>To your application, this means that:</p> + +<ol> +<li>Your {@code LicenseCheckerCallback} methods will be invoked, in many cases, from a +background thread.</li> +<li>Those methods won't be able to update state or invoke any processing in the +UI thread, unless you create a Handler in the UI thread and have your callback +methods post to the Handler.</li> +</ol> + +<p>If you want your {@code LicenseCheckerCallback} methods to update the UI thread, +instantiate a {@link android.os.Handler} in the main Activity's +{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, +as shown below. In this example, the LVL sample application's +{@code LicenseCheckerCallback} methods (see above) call <code>displayResult()</code> to +update the UI thread through the Handler's +{@link android.os.Handler#post(java.lang.Runnable) post()} method.</p> + +<pre>private Handler mHandler; + + @Override + public void onCreate(Bundle savedInstanceState) { + ... + mHandler = new Handler(); + } +</pre> + +<p>Then, in your {@code LicenseCheckerCallback} methods, you can use Handler methods to +post Runnable or Message objects to the Handler. Here's how the sample +application included in the LVL posts a Runnable to a Handler in the UI thread +to display the license status.</p> + +<pre> private void displayResult(final String result) { + mHandler.post(new Runnable() { + public void run() { + mStatusText.setText(result); + setProgressBarIndeterminateVisibility(false); + mCheckLicenseButton.setEnabled(true); + } + }); + } +</pre> + +<h3 id="lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</h3> + +<p>In the main Activity's +{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, +create private instances of LicenseCheckerCallback and {@code LicenseChecker}. You must +instantiate {@code LicenseCheckerCallback} first, because you need to pass a reference +to that instance when you call the constructor for {@code LicenseChecker}. </p> + +<p>When you instantiate {@code LicenseChecker}, you need to pass in these parameters:</p> + +<ul> +<li>The application {@link android.content.Context}</li> +<li>A reference to the {@code Policy} implementation to use for the license check. In +most cases, you would use the default {@code Policy} implementation provided by the LVL, +ServerManagedPolicy. </li> +<li>The String variable holding your publisher account's public key for +licensing. </li> +</ul> + +<p>If you are using ServerManagedPolicy, you won't need to access the class +directly, so you can instantiate it in the {@code LicenseChecker} constructor, +as shown in the example below. Note that you need to pass a reference to a new +Obfuscator instance when you construct ServerManagedPolicy.</p> + +<p>The example below shows the instantiation of {@code LicenseChecker} and +{@code LicenseCheckerCallback} from the <code>onCreate()</code> method of an Activity +class. </p> + +<pre>public class MainActivity extends Activity { + ... + private LicenseCheckerCallback mLicenseCheckerCallback; + private LicenseChecker mChecker; + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + ... + // Construct the LicenseCheckerCallback. The library calls this when done. + mLicenseCheckerCallback = new MyLicenseCheckerCallback(); + + // Construct the LicenseChecker with a Policy. + mChecker = new LicenseChecker( + this, new ServerManagedPolicy(this, + new AESObfuscator(SALT, getPackageName(), deviceId)), + BASE64_PUBLIC_KEY // Your public licensing key. + ); + ... + } +} +</pre> + + +<p>Note that {@code LicenseChecker} calls the {@code LicenseCheckerCallback} methods from the UI +thread <em>only</em> if there is valid license response cached locally. If the +license check is sent to the server, the callbacks always originate from the +background thread, even for network errors. </p> + + +<h3 id="check-access">Call checkAccess() to initiate the license check</h3> + +<p>In your main Activity, add a call to the <code>checkAccess()</code> method of the +{@code LicenseChecker} instance. In the call, pass a reference to your +{@code LicenseCheckerCallback} instance as a parameter. If you need to handle any +special UI effects or state management before the call, you might find it useful +to call <code>checkAccess()</code> from a wrapper method. For example, the LVL +sample application calls <code>checkAccess()</code> from a +<code>doCheck()</code> wrapper method:</p> + +<pre> @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + ... + // Call a wrapper method that initiates the license check + doCheck(); + ... + } + ... + private void doCheck() { + mCheckLicenseButton.setEnabled(false); + setProgressBarIndeterminateVisibility(true); + mStatusText.setText(R.string.checking_license); + mChecker.checkAccess(mLicenseCheckerCallback); + } +</pre> + + +<h3 id="account-key">Embed your public key for licensing</h3> + +<p>For each publisher account, the Google Play service automatically +generates a 2048-bit RSA public/private key pair that is used exclusively for +licensing. The key pair is uniquely associated with the publisher account and is +shared across all applications that are published through the account. Although +associated with a publisher account, the key pair is <em>not</em> the same as +the key that you use to sign your applications (or derived from it).</p> + +<p>The Google Play publisher site exposes the public key for licensing to any +developer signed in to the publisher account, but it keeps the private key +hidden from all users in a secure location. When an application requests a +license check for an application published in your account, the licensing server +signs the license response using the private key of your account's key pair. +When the LVL receives the response, it uses the public key provided by the +application to verify the signature of the license response. </p> + +<p>To add licensing to an application, you must obtain your publisher account's +public key for licensing and copy it into your application. Here's how to find +your account's public key for licensing:</p> + +<ol> +<li>Go to the Google Play <a +href="http://play.google.com/apps/publish">publisher site</a> and sign in. +Make sure that you sign in to the account from which the application you are +licensing is published (or will be published). </li> +<li>In the account home page, locate the "Edit profile" link and click it. </li> +<li>In the Edit Profile page, locate the "Licensing" pane, shown below. Your +public key for licensing is given in the "Public key" text box. </li> +</ol> + +<p>To add the public key to your application, simply copy/paste the key string +from the text box into your application as the value of the String variable +<code>BASE64_PUBLIC_KEY</code>. When you are copying, make sure that you have +selected the entire key string, without omitting any characters. </p> + +<p>Here's an example from the LVL sample application:</p> + +<pre> public class MainActivity extends Activity { + private static final String BASE64_PUBLIC_KEY = "MIIBIjANBgkqhkiG ... "; //truncated for this example + ... + } +</pre> + +<h3 id="handler-cleanup">Call your LicenseChecker's onDestroy() method +to close IPC connections</h3> + +<p>Finally, to let the LVL clean up before your application +{@link android.content.Context} changes, add a call to the {@code LicenseChecker}'s +<code>onDestroy()</code> method from your Activity's +{@link android.app.Activity#onDestroy()} implementation. The call causes the +{@code LicenseChecker} to properly close any open IPC connection to the Google Play +application's ILicensingService and removes any local references to the service +and handler.</p> + +<p>Failing to call the {@code LicenseChecker}'s <code>onDestroy()</code> method +can lead to problems over the lifecycle of your application. For example, if the +user changes screen orientation while a license check is active, the application +{@link android.content.Context} is destroyed. If your application does not +properly close the {@code LicenseChecker}'s IPC connection, your application will crash +when the response is received. Similarly, if the user exits your application +while a license check is in progress, your application will crash when the +response is received, unless it has properly called the +{@code LicenseChecker}'s <code>onDestroy()</code> method to disconnect from the service. +</p> + +<p>Here's an example from the sample application included in the LVL, where +<code>mChecker</code> is the {@code LicenseChecker} instance:</p> + +<pre> @Override + protected void onDestroy() { + super.onDestroy(); + mChecker.onDestroy(); + ... + } +</pre> + +<p>If you are extending or modifying {@code LicenseChecker}, you might also need to call +the {@code LicenseChecker}'s <code>finishCheck()</code> method, to clean up any open IPC +connections.</p> + +<h2 id="impl-DeviceLimiter">Implementing a DeviceLimiter</h2> + +<p>In some cases, you might want your {@code Policy} to limit the number of actual +devices that are permitted to use a single license. This would prevent a user +from moving a licensed application onto a number of devices and using the +application on those devices under the same account ID. It would also prevent a +user from "sharing" the application by providing the account information +associated with the license to other individuals, who could then sign in to that +account on their devices and access the license to the application. </p> + +<p>The LVL supports per-device licensing by providing a +<code>DeviceLimiter</code> interface, which declares a single method, +<code>allowDeviceAccess()</code>. When a LicenseValidator is handling a response +from the licensing server, it calls <code>allowDeviceAccess()</code>, passing a +user ID string extracted from the response.</p> + +<p>If you do not want to support device limitation, <strong>no work is +required</strong> — the {@code LicenseChecker} class automatically uses a default +implementation called NullDeviceLimiter. As the name suggests, NullDeviceLimiter +is a "no-op" class whose <code>allowDeviceAccess()</code> method simply returns +a <code>LICENSED</code> response for all users and devices. </p> + +<div style="border-left:4px solid #FFCF00;margin:1em;padding: 0 0 0 .5em"> +<p><strong>Caution:</strong> Per-device licensing is <em>not recommended for +most applications</em> because:</p> +<ul> +<li>It requires that you provide a backend server to manage a users and devices +mapping, and </li> +<li>It could inadvertently result in a user being denied access to an +application that they have legitimately purchased on another device.</li> +</ul> +</div> + + + + + + + + + + + +<h2 id="app-obfuscation">Obfuscating Your Code</h2> + +<p>To ensure the security of your application, particularly for a paid +application that uses licensing and/or custom constraints and protections, it's +very important to obfuscate your application code. Properly obfuscating your +code makes it more difficult for a malicious user to decompile the application's +bytecode, modify it — such as by removing the license check — +and then recompile it.</p> + +<p>Several obfuscator programs are available for Android applications, including +<a href="http://proguard.sourceforge.net/">ProGuard</a>, which also offers +code-optimization features. The use of ProGuard or a similar program to obfuscate +your code is <em>strongly recommended</em> for all applications that use Google +Play Licensing. </p> + +<h2 id="app-publishing">Publishing a Licensed Application</h2> + +<p>When you are finished testing your license implementation, you are ready to +publish the application on Google Play. Follow the normal steps to <a +href="{@docRoot}guide/publishing/preparing.html">prepare</a>, <a +href="{@docRoot}guide/publishing/app-signing.html">sign</a>, and then <a +href="{@docRoot}guide/publishing/publishing.html">publish the application</a>. +</p> + +<h3>Removing Copy Protection</h3> + +<p>After uploading your licensed application, remember to remove copy protection +from the application, if it is currently used. To check and remove copy +protection, sign in to the publisher site and go the application's upload +details page. In the Publishing options section, make sure that the Copy +Protection radio button selection is "Off".</p> + + +<h2 id="support">Where to Get Support</h2> + +<p>If you have questions or encounter problems while implementing or deploying +publishing in your applications, please use the support resources listed in the +table below. By directing your queries to the correct forum, you can get the +support you need more quickly. </p> + +<p class="table-caption"><strong>Table 2.</strong> Developer support resources +for Google Play Licensing Service.</p> + +<table> + +<tr> +<th>Support Type</th> +<th>Resource</th> +<th>Range of Topics</th> +</tr> +<tr> +<td rowspan="2">Development and testing issues</td> +<td>Google Groups: <a +href="http://groups.google.com/group/android-developers">android-developers</a> +</td> +<td rowspan="2">LVL download and integration, library projects, {@code Policy} +questions, user experience ideas, handling of responses, {@code Obfuscator}, IPC, test +environment setup</td> +</tr> +<tr> +<td>Stack Overflow: <a +href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/android</a></td> +</tr> +<tr> +<td rowspan="2">Accounts, publishing, and deployment issues</td> +<td><a href="http://www.google.com/support/forum/p/Android+Market">Google Play +Help Forum</a></td> +<td rowspan="2">Publisher accounts, licensing key pair, test accounts, server +responses, test responses, application deployment and results</td> +</tr> +<tr> +<td><a +href="http://market.android.com/support/bin/answer.py?answer=186113">Market +Licensing Support FAQ</a></td> +</tr> +<tr> +<td>LVL issue tracker</td> +<td><a href="http://code.google.com/p/marketlicensing/issues/">Marketlicensing +project issue tracker</a></td> +<td>Bug and issue reports related specifically to the LVL source code classes +and interface implementations</td> +</tr> + +</table> + +<p>For general information about how to post to the groups listed above, see <a +href="{@docRoot}resources/community-groups.html">Developer Forums</a> document +in the Resources tab.</p> + + diff --git a/docs/html/guide/market/licensing/index.jd b/docs/html/guide/market/licensing/index.jd new file mode 100644 index 0000000..1f15303 --- /dev/null +++ b/docs/html/guide/market/licensing/index.jd @@ -0,0 +1,61 @@ +page.title=Application Licensing +@jd:body + + +<p>Google Play offers a licensing service that lets you enforce licensing policies for +applications that you publish on Google Play. With Google Play Licensing, your application can +query Google Play at run time to obtain the licensing status for the current user, then allow or +disallow further use as appropriate. </p> + +<p>Using the service, you can apply a flexible licensing policy on an application-by-application +basis—each application can enforce licensing in the way most appropriate for it. If necessary, +an application can apply custom constraints based on the licensing status obtained from Google Play. +For example, an application can check the licensing status and then apply custom constraints +that allow the user to run it unlicensed for a specific validity period. An application can also +restrict use of the application to a specific device, in addition to any other constraints. </p> + +<p>The licensing service is a secure means of controlling access to your applications. When an +application checks the licensing status, the Google Play server signs the licensing status +response using a key pair that is uniquely associated with the publisher account. Your application +stores the public key in its compiled <code>.apk</code> file and uses it to verify the licensing +status response.</p> + +<p>Any application that you publish through Google Play can use the Google Play Licensing +service. No special account or registration is needed. Additionally, because the service uses no +dedicated framework APIs, you can add licensing to any application that uses a minimum API level of +3 or higher.</p> + +<p class="note"><strong>Note:</strong> The Google Play Licensing service is primarily intended +for paid applications that wish to verify that the current user did in fact pay for the application +on Google Play. However, any application (including free apps) may use the licensing service +to initiate the download of an APK expansion file. In which case, the request that your application +sends to the licensing service is not to check whether the user paid for the app, but to request the +URL of the expansion files. For information about downloading expansion files for your application, +read the guide to <a href="{@docRoot}guide/market/expansion-files.html">APK Expansion Files</a>.</p> + + +<p>To learn more about Google Play's application licensing service and start integrating it into +your applications, read the following documents:</p> + +<dl> + <dt><strong><a href="{@docRoot}guide/market/licensing/overview.html">Licensing +Overview</a></strong></dt> + <dd>Describes how the service works and what a typical licensing implementation looks +like.</dd> + <dt><strong><a href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for +Licensing</a></strong></dt> + <dd>Explains how to set up your Google Play account, development environment, and +testing environment in order to add licensing to your app.</dd> + <dt><strong><a href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding +Licensing to Your App</a></strong></dt> + <dd>Provides a step-by-step guide to add licensing verification to your application.</dd> + <dt><strong><a href="{@docRoot}guide/market/licensing/licensing-reference.html">Licensing +Reference</a></strong></dt> + <dd>Provides detailed information about the licensing library's classes and the service response +codes.</dd> +</dl> + + + + + diff --git a/docs/html/guide/market/licensing/licensing-reference.jd b/docs/html/guide/market/licensing/licensing-reference.jd new file mode 100644 index 0000000..0a7e033 --- /dev/null +++ b/docs/html/guide/market/licensing/licensing-reference.jd @@ -0,0 +1,439 @@ +page.title=Licensing Reference +parent.title=Application Licensing +parent.link=index.html +@jd:body + + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#lvl-summary">LVL Classes and Interfaces</a></li> + <li><a href="#server-response-codes">Server Response Codes</a></li> + <li><a href="#extras">Server Response Extras</a></li> + </ol> + +</div> +</div> + + +<h2 id="lvl-summary">LVL Classes and Interfaces</h2> + +<p>Table 1 lists all of the source files in the License Verification +Library (LVL) available through the Android SDK. All of the files are part of +the <code>com.android.vending.licensing</code> package.</p> + +<p class="table-caption"><strong>Table 1.</strong> Summary of LVL library +classes and interfaces.</p> + +<div style="width:99%"> +<table width="100%"> + +<tr> +<th width="15%">Category</th> +<th width="20%">Name</th> +<th width="100%">Description</th> +</tr> + +<tr> +<td rowspan="2">License check and result</td> +<td>LicenseChecker</td> +<td>Class that you instantiate (or subclass) to initiate a license check.</td> +</tr> +<tr> +<td><em>LicenseCheckerCallback</em></td> +<td>Interface that you implement to handle result of the license check.</td> +</tr> + +<tr> +<td rowspan="3" width="15%">Policy</td> +<td width="20%"><em>Policy</em></td> +<td width="100%">Interface that you implement to determine whether to allow +access to the application, based on the license response. </td> +</tr> +<tr> +<td>ServerManagedPolicy</td> +<td width="100%">Default {@code Policy} implementation. Uses settings provided by the +licensing server to manage local storage of license data, license validity, +retry.</td> +</tr> +<tr> +<td>StrictPolicy</td> +<td>Alternative {@code Policy} implementation. Enforces licensing based on a direct +license response from the server only. No caching or request retry.</td> +</tr> + +<tr> +<td rowspan="2" width="15%">Data obfuscation <br><em>(optional)</em></td> +<td width="20%"><em>Obfuscator</em></td> +<td width="100%">Interface that you implement if you are using a {@code Policy} (such as +ServerManagedPolicy) that caches license response data in a persistent store. +Applies an obfuscation algorithm to encode and decode data being written or +read.</td> +</tr> +<tr> +<td>AESObfuscator</td> +<td>Default Obfuscator implementation that uses AES encryption/decryption +algorithm to obfuscate/unobfuscate data.</td> +</tr> + +<tr> +<td rowspan="2" width="15%">Device limitation<br><em>(optional)</em></td> +<td width="20%"><em>DeviceLimiter</em></td> +<td width="100%">Interface that you implement if you want to restrict use of an +application to a specific device. Called from LicenseValidator. Implementing +DeviceLimiter is not recommended for most applications because it requires a +backend server and may cause the user to lose access to licensed applications, +unless designed with care.</td> +</tr> +<tr> +<td>NullDeviceLimiter</td> +<td>Default DeviceLimiter implementation that is a no-op (allows access to all +devices).</td> +</tr> + +<tr> +<td rowspan="6" width="15%">Library core, no integration needed</td> +<td width="20%">ResponseData</td> +<td width="100%">Class that holds the fields of a license response.</td> +</tr> +<tr> +<td>LicenseValidator</td> +<td>Class that decrypts and verifies a response received from the licensing +server.</td> +</tr> +<tr> +<td>ValidationException</td> +<td>Class that indicates errors that occur when validating the integrity of data +managed by an Obfuscator.</td> +</tr> +<tr> +<td>PreferenceObfuscator</td> +<td>Utility class that writes/reads obfuscated data to the system's +{@link android.content.SharedPreferences} store.</td> +</tr> +<tr> +<td><em>ILicensingService</em></td> +<td>One-way IPC interface over which a license check request is passed to the +Google Play client.</td> +</tr> +<tr> +<td><em>ILicenseResultListener</em></td> +<td>One-way IPC callback implementation over which the application receives an +asynchronous response from the licensing server.</td> +</tr> + +</table> +</div> + + +<h2 id="server-response-codes">Server Response Codes</h2> + +<p>Table 2 lists all of the license response codes supported by the +licensing server. In general, an application should handle all of these response +codes. By default, the LicenseValidator class in the LVL provides all of the +necessary handling of these response codes for you. </p> + +<p class="table-caption"><strong>Table 2.</strong> Summary of response codes +returned by the Google Play server in a license response.</p> + +<table> + +<tr> +<th>Response Code</th> +<th>Description</th> +<th>Signed?</th> +<th>Extras</th> +<th>Comments</th> +</tr> +<tr> +<td>{@code LICENSED}</td> +<td>The application is licensed to the user. The user has purchased the +application or the application only exists as a draft.</td> +<td>Yes</td> +<td><code>VT</code>, <code>GT</code>, <code>GR</code></td> +<td><em>Allow access according to {@code Policy} constraints.</em></td> +</tr> +<tr> +<td>{@code LICENSED_OLD_KEY}</td> +<td>The application is licensed to the user, but there is an updated application +version available that is signed with a different key. </td> +<td>Yes </td> +<td><code>VT</code>, <code>GT</code>, <code>GR</code>, <code>UT</code></td> +<td><em>Optionally allow access according to {@code Policy} constraints.</em> +<p style="margin-top:.5em;">Can indicate that the key pair used by the installed +application version is invalid or compromised. The application can allow access +if needed or inform the user that an upgrade is available and limit further use +until upgrade.</p> +</td> +</tr> +<tr> +<td>{@code NOT_LICENSED}</td> +<td>The application is not licensed to the user.</td> +<td>No</td> +<td></td> +<td><em>Do not allow access.</em></td> +</tr> +<tr> +<td>{@code ERROR_CONTACTING_SERVER}</td> +<td>Local error — the Google Play application was not able to reach the +licensing server, possibly because of network availability problems. </td> +<td>No</td> +<td></td> +<td><em>Retry the license check according to {@code Policy} retry limits.</em></td> +</tr> +<tr> +<td>{@code ERROR_SERVER_FAILURE}</td> +<td>Server error — the server could not load the publisher account's key +pair for licensing.</td> +<td>No</td> +<td></td> +<td><em>Retry the license check according to {@code Policy} retry limits.</em> +</td> +</tr> +<tr> +<td>{@code ERROR_INVALID_PACKAGE_NAME}</td> +<td>Local error — the application requested a license check for a package +that is not installed on the device. </td> +<td>No </td> +<td></td> +<td><em>Do not retry the license check.</em> +<p style="margin-top:.5em;">Typically caused by a development error.</p> +</td> +</tr> +<tr> +<td>{@code ERROR_NON_MATCHING_UID}</td> +<td>Local error — the application requested a license check for a package +whose UID (package, user ID pair) does not match that of the requesting +application. </td> +<td>No </td> +<td></td> +<td><em>Do not retry the license check.</em> +<p style="margin-top:.5em;">Typically caused by a development error.</p> +</td> +</tr> +<tr> +<td>{@code ERROR_NOT_MARKET_MANAGED}</td> +<td>Server error — the application (package name) was not recognized by +Google Play. </td> +<td>No</td> +<td></td> +<td><em>Do not retry the license check.</em> +<p style="margin-top:.5em;">Can indicate that the application was not published +through Google Play or that there is an development error in the licensing +implementation.</p> +</td> +</tr> + +</table> + +<p class="note"><strong>Note:</strong> As documented in <a +href="{@docRoot}guide/market/licensing/setting-up.html#test-env"> +Setting Up The Testing Environment</a>, the response code can be manually +overridden for the application developer and any registered test users via the +Google Play publisher site. +<br/><br/> +Additionally, as noted above, applications that are in draft mode (in other +words, applications that have been uploaded but have <em>never</em> been +published) will return {@code LICENSED} for all users, even if not listed as a test +user. Since the application has never been offered for download, it is assumed +that any users running it must have obtained it from an authorized channel for +testing purposes.</p> + + + + +<h2 id="extras">Server Response Extras</h2> + +<p>To assist your application in managing access to the application across the application refund +period and provide other information, The licensing server includes several pieces of +information in the license responses. Specifically, the service provides recommended values for the +application's license validity period, retry grace period, maximum allowable retry count, and other +settings. If your application uses <a href="{@docRoot}guide/market/expansion-files.html">APK +expansion files</a>, the response also includes the file names, sizes, and URLs. The server appends +the settings as key-value pairs in the license response "extras" field. </p> + +<p>Any {@code Policy} implementation can extract the extras settings from the license +response and use them as needed. The LVL default {@code Policy} implementation, <a +href="{@docRoot}guide/market/licensing/adding-licensing.html#ServerManagedPolicy">{@code +ServerManagedPolicy}</a>, serves as a working +implementation and an illustration of how to obtain, store, and use the +settings. </p> + +<p class="table-caption"><strong>Table 3.</strong> Summary of +license-management settings supplied by the Google Play server in a license +response.</p> + +<table> +<tr> +<th>Extra</th><th>Description</th> +</tr> + +<tr> + <td>{@code VT}</td> + <td>License validity timestamp. Specifies the date/time at which the current +(cached) license response expires and must be rechecked on the licensing server. See the section +below about <a href="#VT">License validity period</a>. + </td> +</tr> +<tr> + <td>{@code GT}</td> + <td>Grace period timestamp. Specifies the end of the period during which a +Policy may allow access to the application, even though the response status is +{@code RETRY}. <p>The value is managed by the server, however a typical value would be 5 +or more days. See the section +below about <a href="#GTGR">Retry period and maximum retry count</a>.</p></td> +</tr> +<tr> + <td>{@code GR}</td> + <td>Maximum retries count. Specifies how many consecutive {@code RETRY} license checks +the {@code Policy} should allow, before denying the user access to the application. +<p>The value is managed by the server, however a typical value would be "10" or +higher. See the section +below about <a href="#GTGR">Retry period and maximum retry count</a>.</p></td> +</tr> +<tr> + <td>{@code UT}</td> + <td>Update timestamp. Specifies the day/time when the most recent update to +this application was uploaded and published. <p>The server returns this extra +only for {@code LICENSED_OLD_KEYS} responses, to allow the {@code Policy} to determine how much +time has elapsed since an update was published with new licensing keys before +denying the user access to the application. </p></td> +</tr> + + +<!-- APK EXPANSION FILE RESPONSES --> + +<tr> + <td>{@code FILE_URL1} or {@code FILE_URL2}</td> + <td>The URL for an expansion file (1 is for the main file, 2 is the patch file). Use this to +download the file over HTTP.</td> +</tr> +<tr> + <td>{@code FILE_NAME1} or {@code FILE_NAME2}</td> + <td>The expansion file's name (1 is for the main file, 2 is the patch file). You must use this +name when saving the file on the device.</td> +</tr> +<tr> + <td>{@code FILE_SIZE1} or {@code FILE_SIZE2}</td> + <td>The size of the file in bytes (1 is for the main file, 2 is the patch file). Use this to +assist with downloading and to ensure that enough space is available on the device's shared +storage location before downloading.</td> +</tr> + +</table> + + + +<h4 id="VT">License validity period</h4> + +<p>The Google Play licensing server sets a license validity period for all +downloaded applications. The period expresses the interval of time over which an +application's license status should be considered as unchanging and cacheable by +a licensing {@code Policy} in the application. The licensing server includes the +validity period in its response to all license checks, appending an +end-of-validity timestamp to the response as an extra under the key {@code VT}. A +{@code Policy} can extract the VT key value and use it to conditionally allow access to +the application without rechecking the license, until the validity period +expires. </p> + +<p>The license validity signals to a licensing {@code Policy} when it must recheck the +licensing status with the licensing server. It is <em>not</em> intended to imply +whether an application is actually licensed for use. That is, when an +application's license validity period expires, this does not mean that the +application is no longer licensed for use — rather, it indicates only that +the {@code Policy} must recheck the licensing status with the server. It follows that, +as long as the license validity period has not expired, it is acceptable for the +{@code Policy} to cache the initial license status locally and return the cached license +status instead of sending a new license check to the server.</p> + +<p>The licensing server manages the validity period as a means of helping the +application properly enforce licensing across the refund period offered by +Google Play for paid applications. It sets the validity period based on +whether the application was purchased and, if so, how long ago. Specifically, +the server sets a validity period as follows:</p> + +<ul> +<li>For a paid application, the server sets the initial license validity period +so that the license response remains valid for as long as the application is +refundable. A licensing {@code Policy} in the application may cache the +result of the initial license check and does not need to recheck the license +until the validity period has expired.</li> +<li>When an application is no longer refundable, the server +sets a longer validity period — typically a number of days. </li> + +<!-- TODO: Verify the following behavior is still true w/ OBB: --> +<li>For a free application, the server sets the validity period to a very high +value (<code>long.MAX_VALUE</code>). This ensures that, provided the {@code Policy} has +cached the validity timestamp locally, it will not need to recheck the +license status of the application in the future.</li> +</ul> + +<p>The {@code ServerManagedPolicy} implementation uses the extracted timestamp +(<code>mValidityTimestamp</code>) as a primary condition for determining whether +to recheck the license status with the server before allowing the user access to +the application. </p> + + +<h4 id="GTGR">Retry period and maximum retry count</h4> + +<p>In some cases, system or network conditions can prevent an application's +license check from reaching the licensing server, or prevent the server's +response from reaching the Google Play client application. For example, the +user might launch an application when there is no cell network or data +connection available—such as when on an airplane—or when the +network connection is unstable or the cell signal is weak. </p> + +<p>When network problems prevent or interrupt a license check, the Google +Play client notifies the application by returning a {@code RETRY} response code to +the {@code Policy}'s <code>processServerResponse()</code> method. In the case of system +problems, such as when the application is unable to bind with Google Play's +{@code ILicensingService} implementation, the {@code LicenseChecker} library itself calls the +Policy <code>processServerResonse()</code> method with a {@code RETRY} response code. +</p> + +<p>In general, the {@code RETRY} response code is a signal to the application that an +error has occurred that has prevented a license check from completing. + +<p>The Google Play server helps an application to manage licensing under +error conditions by setting a retry "grace period" and a recommended maximum +retries count. The server includes these values in all license check responses, +appending them as extras under the keys {@code GT} and {@code GR}. </p> + +<p>The application {@code Policy} can extract the {@code GT} and {@code GR} extras and use them to +conditionally allow access to the application, as follows:</p> + +<ul> +<li>For a license check that results in a {@code RETRY} response, the {@code Policy} should +cache the {@code RETRY} response code and increment a count of {@code RETRY} responses.</li> +<li>The {@code Policy} should allow the user to access the application, provided that +either the retry grace period is still active or the maximum retries count has +not been reached.</li> +</ul> + +<p>The {@code ServerManagedPolicy} uses the server-supplied {@code GT} and {@code GR} values as +described above. The example below shows the conditional handling of the retry +responses in the <code>allow()</code> method. The count of {@code RETRY} responses is +maintained in the <code>processServerResponse()</code> method, not shown. </p> + + +<pre> +public boolean allowAccess() { + long ts = System.currentTimeMillis(); + if (mLastResponse == LicenseResponse.LICENSED) { + // Check if the LICENSED response occurred within the validity timeout. + if (ts <= mValidityTimestamp) { + // Cached LICENSED response is still valid. + return true; + } + } else if (mLastResponse == LicenseResponse.RETRY && + ts < mLastResponseTime + MILLIS_PER_MINUTE) { + // Only allow access if we are within the retry period or we haven't used up our + // max retries. + return (ts <= mRetryUntil || mRetryCount <= mMaxRetries); + } + return false; +}</pre> + diff --git a/docs/html/guide/market/licensing/overview.jd b/docs/html/guide/market/licensing/overview.jd new file mode 100644 index 0000000..e7e23f8 --- /dev/null +++ b/docs/html/guide/market/licensing/overview.jd @@ -0,0 +1,246 @@ +page.title=Licensing Overview +parent.title=Application Licensing +parent.link=index.html +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>Licensing allows you to verify your app was purchased from Google Play</li> + <li>Your app maintains control of how it enforces its licensing status</li> + <li>The service is free for all developers who publish on Google Play</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Secure">License Responses are Secure</a></li> + <li><a href="#LVL">Licensing Verification Library</a></li> + <li><a href="#Reqs">Requirements and Limitations</a></li> + <li><a href="#CopyProtection">Replacement for Copy Protection</a></li> +</ol> + +</div> +</div> + + +<p>Google Play Licensing is a network-based service that lets an application query a trusted +Google Play licensing server to determine whether the application is licensed to the current +device user. The licensing service is based on the capability of the Google Play licensing server +to determine whether a given user is licensed to use a given application. Google Play considers a +user to be licensed if the user is a recorded purchaser of the application.</p> + +<p>The request starts when your application makes a request to a service hosted by +the Google Play client application. The Google Play application then sends a request to +the licensing server and receives the result. The Google Play application sends +the result to your application, which can allow or disallow further use of the +application as needed.</p> + +<p class="note"><strong>Note:</strong> If a paid application has been uploaded to Google Play but +saved only as a draft application (the app is unpublished), the licensing server considers all users +to be licensed users of the application (because it's not even possible to purchase the app). +This exception is necessary in order for you to perform testing of your licensing +implementation.</p> + + +<div class="figure" style="width:469px"> +<img src="{@docRoot}images/licensing_arch.png" alt=""/> +<p class="img-caption"><strong>Figure 1.</strong> Your application initiates a +license check through the License Verification Library and the Google Play +client, which handles communication with the Google Play server.</p> +</div> + + +<p>To properly identify the user and determine the license status, the licensing server requires +information about the application and user—your application and the Google Play client work +together to assemble the information and the Google Play client passes it to the server. </p> + +<p>To help you add licensing to your application, the Android SDK provides a downloadable set of +library sources that you can include in your application project: the Google Market +Licensing package. The License Verification Library (LVL) is a library you can add to your +application that +handles all of the licensing-related communication with the Google Play licensing service. With +the LVL added to your application, your application can determine its licensing status for the +current user by simply calling a method and implementing a callback that receives the status +response.</p> + +<p>Your application does not query the licensing server +directly, but instead calls the Google Play client over remote IPC to +initiate a license request. In the license request:</p> + +<ul> +<li>Your application provides: its package name, a nonce that is later used to +validate any response from the server, and a callback over which the +response can be returned asynchronously.</li> +<li>The Google Play client collects the necessary information about the user and the device, +such as the device's primary Google account username, IMSI, and other +information. It then sends the license check request to the server on behalf of +your application.</li> +<li>The Google Play server evaluates the request using all available information, attempting +to establish the user's identity to a sufficient level of confidence. The server +then checks the user identity against purchase records for your application and +returns a license response, which the Google Play client returns to your +application over the IPC callback.</li> +</ul> + +<p>You can choose when, and how often, you want your application to check its +license and you have full control over how it handles the response, verifies the +signed response data, and enforces access controls.</p> + +<p>Notice that during a license check, your application does not manage any +network connections or use any licensing related APIs in the Android platform.</p> + + + + +<h2 id="Secure">License Responses are Secure</h2> + +<p>To ensure the integrity of each license query, the server signs the license +response data using an RSA key pair that is shared exclusively between the Google Play +server and you.</p> + +<p>The licensing service generates a single licensing key pair for each +publisher account and exposes the public key in your account's profile page. You must copy the +public key from the web site and embed it in your application source code. The server retains the +private key internally and uses it to sign license responses for the applications you +publish with that account.</p> + +<p>When your application receives a signed response, it uses the embedded public +key to verify the data. The use of public key cryptography in the licensing +service makes it possible for the application to detect responses that have been +tampered with or that are spoofed.</p> + + + + +<h2 id="LVL">Licensing Verification Library</h2> + +<p>The Android SDK provides a downloadable package called the Google Market Licensing package, +which includes the License Verification Library (LVL). The LVL greatly simplifies the process of +adding licensing to your application and helps ensure a more secure, robust implementation for your +application. The LVL provides internal classes that handle most of the standard operations of a +license query, such as contacting the Google Play client to initiate a license request and +verifying and validating the responses. It also exposes interfaces that let you easily plug in your +custom code for defining licensing policy and managing access as needed by your application. The key +LVL interfaces are: </p> + +<dl> +<dt>{@code Policy}</dt> + <dd>Your implementation determines whether to allow access to the +application, based on the license response received from the server and any +other data available (such as from a backend server associated with your +application). The implementation can evaluate the various fields of the license +response and apply other constraints, if needed. The implementation also lets +you manage the handling of license checks that result in errors, such as network +errors.</dd> + +<dt>{@code LicenseCheckerCallback}</dt> + <dd>Your implementation manages access to the +application, based on the result of the {@code Policy} object's handling of the license +response. Your implementation can manage access in any way needed, including +displaying the license result in the UI or directing the user to purchase the +application (if not currently licensed).</dd> +</dl> + + +<p>To help you get started with a {@code Policy}, the LVL provides two fully complete +{@code Policy} implementations that you can use without modification or adapt to your +needs:</p> + +<dl> +<dt><a href="adding-licensing.html#ServerManagedPolicy">{@code ServerManagedPolicy}</a></dt> + <dd>A flexible {@code Policy} +that uses settings provided by the licensing server to manage response caching +and access to the application while the device is offline (such as when the +user is on an airplane). For most applications, the use of +{@code ServerManagedPolicy} is highly recommended.</dd> + +<dt><a href="adding-licensing.html#StrictPolicy">{@code StrictPolicy}</a></dt> + <dd>A restrictive {@code Policy} that +does not cache any response data and allows the application access <em>only</em> +when the server returns a licensed response.</dd> +</dl> + +<p>The LVL is available as a downloadable package of the Android SDK. The +package includes both the LVL itself and an example application that shows how +the library should be integrated with your application and how your application +should manage response data, UI interaction, and error conditions. </p> + +<p>The LVL sources are provided as an Android <em>library project</em>, which +means that you can maintain a single set of library sources and share them +across multiple applications. A full test environment is also available through +the SDK, so you can develop and test the licensing implementation in your +applications before publishing them, even if you don't have access to a +physical device.</p> + + + + +<h2 id="Reqs">Requirements and Limitations</h2> + +<p>Google Play Licensing is designed to let you apply license controls to +applications that you publish through Google Play. The service is not +designed to let you control access to applications that are not published +through Google Play or that are run on devices that do not offer the Google +Play client. </p> + +<p>Here are some points to keep in mind as you implement licensing in your +application: </p> + +<ul> +<li>An application can use the service only if the Google Play client is +installed on its host device and the device is running Android 1.5 (API level 3) +or higher.</li> +<li>To complete a license check, the licensing server must be accessible over +the network. You can implement license caching behaviors to manage access to your application when +there is no network connectivity. </li> +<li>The security of your application's licensing controls ultimately relies on +the design of your implementation itself. The service provides the building +blocks that let you securely check licensing, but the actual enforcement and +handling of the license are factors are up to you. By following the best +practices in the following documents, you can help ensure that your implementation will be +secure.</li> +<li>Adding licensing to an application does not affect the way the application +functions when run on a device that does not offer Google Play.</li> +<li>You can implement licensing controls for a free app, but only if you're using the service to +provide <a +href="{@docRoot}guide/market/expansion-files.html">APK expansion files</a>.</li> +</ul> + + + +<h2 id="CopyProtection">Replacement for Copy Protection</h2> + +<p>Google Play Licensing is a flexible, secure mechanism for controlling +access to your applications. It effectively replaces the Copy Protection +mechanism offered on Google Play and gives you wider distribution +potential for your applications. </p> + +<ul> +<li>A limitation of the legacy Copy Protection mechanism on Google Play is +that applications using it can be installed only on compatible devices that +provide a secure internal storage environment. For example, a copy-protected +application cannot be downloaded from Google Play to a device that provides root +access, and the application cannot be installed to a device's SD card. </li> +<li>With Google Play licensing, you can move to a license-based model in +which access is not bound to the characteristics of the host device, but to your +publisher account on Google Play and the licensing policy that you define. +Your application can be installed and controlled on any compatible device on +any storage, including SD card.</li> +</ul> + +<p>Although no license mechanism can completely prevent all unauthorized use, +the licensing service lets you control access for most types of normal usage, +across all compatible devices, locked or unlocked, that run Android 1.5 or +higher version of the platform.</p> + +<p>To begin adding application licensing to your application, continue to <a +href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for Licensing</a>.</p> + + + + + + diff --git a/docs/html/guide/market/licensing/setting-up.jd b/docs/html/guide/market/licensing/setting-up.jd new file mode 100644 index 0000000..0de7819 --- /dev/null +++ b/docs/html/guide/market/licensing/setting-up.jd @@ -0,0 +1,701 @@ +page.title=Setting Up for Licensing +parent.title=Application Licensing +parent.link=index.html +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#account">Setting Up a Publisher Account</a></li> + <li><a href="#dev-setup">Setting Up the Development Environment</a> + <ol> + <li><a href="#runtime-setup">Setting up the runtime environment</a></li> + <li><a href="#download-lvl">Downloading the LVL</a></li> + <li><a href="#lvl-setup">Setting Up the Licensing Verification Library</a></li> + <li><a href="#add-library">Including the LVL library project sources in your +application</a></li> + </ol> + </li> + <li><a href="#test-env">Setting Up the Testing Environment</a> + <ol> + <li><a href="#test-response">Setting test responses for license checks</a></li> + <li><a href="#test-acct-setup">Setting up test accounts</a></li> + <li><a href="#acct-signin">Signing in to an authorized account in the runtime +environment</a></li> + </ol> + </li> +</ol> +</div> +</div> + +<p>Before you start adding license verification to your application, you need to set up your Google +Play publishing account, your development environment, and test accounts required to verify +your implementation.</p> + + +<h2 id="account">Setting Up a Publisher Account</h2> + +<p>If you don't already have a publisher account for Google Play, you need to register for one +using your Google account and agree to the terms of service on the Google Play publisher site:</p> + +<p style="margin-left:2em;"><a +href="http://play.google.com/apps/publish">http://play.google.com/apps/publish</a> +</p> + +<p>For more information, see <a +href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a>.</p> + +<p>If you already have a publisher account on Google Play, use your existing +account to set up licensing.</p> + +<p>Using your publisher account on Google Play, you can:</p> + +<ul> +<li>Obtain a public key for licensing</li> +<li>Debug and test an application's licensing implementation, prior to +publishing the application</li> +<li>Publish the applications to which you have added licensing support</li> +</ul> + +<h4>Administrative settings for licensing</h4> + +<p>You can manage several +administrative controls for Google Play licensing on the publisher site. The controls are available +in the Edit Profile page, in the "Licensing" panel, shown in figure 1. The controls +let you: </p> + +<ul> +<li>Set up multiple "test accounts," identified by email address. The licensing +server allows users signed in to test accounts on a device or emulator to send +license checks and receive static test responses.</li> +<li>Obtain the account's public key for licensing. When you are implementing +licensing in an application, you must copy the public key string into the +application.</li> +<li>Configure static test responses that the server sends, when it receives a +license check for an application uploaded to the publisher account, from a user +signed in to the publisher account or a test account.</li> +</ul> + + +<img src="{@docRoot}images/licensing_public_key.png" alt=""/> +<p class="img-caption"><strong>Figure 1.</strong> The Licensing +panel of your account's Edit Profile page lets you manage administrative +settings for licensing.</p> + +<p>For more information about how to work with test accounts and static test +responses, see <a href="#test-env">Setting Up a Testing Environment</a>, below. + + + +<h2 id="dev-setup">Setting Up the Development Environment</h2> + +<p>Setting up your environment for licensing involves these tasks:</p> + +<ol> +<li><a href="#runtime-setup">Setting up the runtime environment</a> for development</li> +<li><a href="#download-lvl">Downloading the LVL</a> into your SDK </li> +<li><a href="#lvl-setup">Setting up the Licensing Verification Library</a></li> +<li><a href="#add-library">Including the LVL library project in your application</a></li> +</ol> + +<p>The sections below describe these tasks. When you are done with setup, +you can begin <a href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding +Licensing to Your App</a>.</p> + +<p>To get started, you need to set up a proper runtime environment on which +you can run, debug, and test your application's implementation of license +checking and enforcement. </p> + + +<h3 id="runtime-setup">Setting up the runtime environment</h3> + +<p>As described earlier, applications check licensing status not by contacting +the licensing server directly, but by binding to a service provided by the +Google Play application and initiating a license check request. The Google +Play service then handles the direct communication with the licensing server +and finally routes the response back to your application. To debug and test +licensing in your application, you need to set up a runtime environment that +includes the necessary Google Play service, so that your application is able +to send license check requests to the licensing server. </p> + +<p>There are two types of runtime environment that you can use: </p> + +<ul> +<li>An Android-powered device that includes the Google Play application, or</li> +<li>An Android emulator running the Google APIs Add-on, API level 8 (release 2) +or higher</li> +</ul> + +<h4 id="runtime-device">Running on a device</h4> + +<p>To use an Android-powered device for +debugging and testing licensing, the device must:</p> + +<ul> +<li>Run a compatible version of Android 1.5 or later (API level +3 or higher) platform, <em>and</em> </li> +<li>Run a system image on which the Google Play client application +is preinstalled. </li> +</ul> + +<p>If Google Play is not preinstalled in the system image, your application won't +be able to communicate with the Google Play licensing server. </p> + +<p>For general information about how to set up a device for use in developing +Android applications, see <a +href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a>.</p> + +<h4 id="runtime-emulator">Running on an Android emulator</h4> + +<p>If you don't have a device available, you can use an Android emulator for debugging and testing +licensing.</p> + +<p>Because the Android platforms provided in the Android SDK <em>do +not</em> include Google Play, you need to download the Google APIs Add-On +platform, API level 8 (or higher), from the SDK repository. After downloading +the add-on, you need to create an AVD configuration that uses that system image. +</p> + +<p>The Google APIs Add-On does not include the full Google Play client. +However, it does provide: </p> + +<ul> +<li>An Google Play background service that implements the +<code>ILicensingService</code> remote interface, so that your application can +send license checks over the network to the licensing server. </li> +<li>A set of underlying account services that let you add an a Google account on +the AVD and sign in using your publisher account or test account credentials. +<p>Signing in using your publisher or test account enables you to debug and test +your application without having publish it. For more information see <a +href="#acct-signin">Signing in to an authorized account</a>, below.</p></li> +</ul> + +<p>Several versions of the Google APIs add-on are available through the SDK Manager, but only +the version for Android 2.2 and higher includes the necessary Google +Play services.</p> + +<p>To set up an emulator for adding licensing to an application, follow +these steps: </p> + +<ol> + <li>Launch the Android SDK Manager (available under the Eclipse <strong>Window</strong> +menu or by executing {@code <sdk>/tools/android sdk}).</li> + <li>Select and download <strong>Google APIs</strong> for the Android version you'd like to target +(must be Android 2.2 or higher).</li> + <li>When the download is complete, open the AVD Manager (available under the Eclipse +<strong>Window</strong> +menu or by executing {@code <sdk>/tools/android avd}).</li> + <li>Click +<strong>New</strong> and set the configuration details for the new AVD. </li> + <li>In the dialog that appears, assign a descriptive name to the AVD and then +use the Target menu to choose the <strong>Google APIs</strong> as +the system image to run on the new AVD. Set the other configuration details as +needed and then click <strong>Create AVD</strong> to finish. The SDK tools +create the new AVD configuration, which then appears in the list of available +Android Virtual Devices.</li> +</ol> + +<p>If you are not familiar with AVDs or how to use them, see <a +href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> + +<h4 id="project-update">Updating your project configuration</h4> + +<p>After you set up a runtime environment that meets the requirements described +above — either on an actual device or on an emulator — make sure to +update your application project or build scripts as needed, so that your compiled +<code>.apk</code> files that use licensing are deployed into that environment. +In particular, if you are developing in Eclipse, make sure that you set up a +Run/Debug Configuration that targets the appropriate device or AVD. </p> + +<p>You do not need to make any changes to your application's +build configuration, provided that the project is already configured to compile +against a standard Android 1.5 (API level 3) or higher library. For example: + +<ul> +<li>If you have an existing application that is compiled against +the Android 1.5 library, you do not need to make any changes to your +build configuration to support licensing. The build target meets the minimum +requirements for licensing, so you would continue building +against the same version of the Android platform.</li> + +<li>Similarly, if you are building against Android 1.5 (API level 3) but +are using an emulator running the Google APIs Add-On API 8 as the application's +runtime environment, there is no need to change your application's build +configuration. </li> +</ul> + +<p>In general, adding licensing to an application should have no impact +whatsoever on the application's build configuration.</p> + + +<h3 id="download-lvl">Downloading the LVL</h3> + +<p>The License Verification Library (LVL) is a collection of helper classes that +greatly simplify the work that you need to do to add licensing to your +application. In all cases, we recommend that you download the LVL and use it as +the basis for the licensing implementation in your application.</p> + +<p>The LVL is available as a downloadable package of the Android SDK. The +package includes: </p> + +<ul> +<li>The LVL sources, stored inside an Android library project. </li> +<li>An example application called "sample" that depends on the LVL library +project. The example illustrates how an application uses the library helper +classes to check and enforce licensing.</li> +</ul> + +<p>To download the LVL package into your development environment, use the +Android SDK Manager. Launch the Android SDK Manager and then +select the <strong>Google Market Licensing</strong> package, as shown in figure 2. +Accept the terms and click <strong>Install Selected</strong> to begin the download. </p> + +<img src="{@docRoot}images/licensing_package.png" alt=""/> +<p class="img-caption"><strong>Figure 2.</strong> The Licensing package contains the LVL and +the LVL sample application.</p> + +<p>When the download is complete, the Android SDK Manager installs both +the LVL library project and the example application into these directories: </p> + +<p style="margin-left:2em"><code><<em>sdk</em>>/extras/google/market_licensing/library/</code> + (the LVL library project)<br /> +<code><<em>sdk</em>>/extras/google/market_licensing/sample/</code> (the example +application)</p> + +<p>If you aren't familiar with how to download packess into your SDK, see the +<a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a> +document. </p> + + +<h3 id="lvl-setup">Setting Up the Licensing Verification Library</h3> + +<p>After downloading the LVL to your computer, you need to set it up in your +development environment, either as an Android library project or by +copying (or importing) the library sources directly into your existing +application package. In general, using the LVL as a library project is recommended, +since it lets you reuse your licensing code across multiple applications and +maintain it more easily over time. Note that the LVL is not designed to be +compiled separately and added to an application as a static .jar file. </p> + +<h4>Moving the library sources to a new location</h4> + +<p>Because you will be customizing the LVL sources to some extent, you should +make sure to <em>move or copy</em> the library sources (the entire +directory at <code><<em>sdk</em>>/market_licensing/library/</code>) +to a working directory outside of the SDK. You should then use the relocated +sources as your working set. If you are using a source-code management +system, add and track the sources that are in the working location rather +than those in default location in the SDK. </p> + +<p>Moving the library sources is important is because, when you later update the +Licensing package, the SDK installs the new files to the same location as +the older files. Moving your working library files to a safe location ensures +that your work won't be inadvertently overwritten should you download a new +version of the LVL.</p> + +<h4>Creating the LVL as a library project</h4> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Working with library projects</h2> + +<p>The LVL is provided as an Android library project, which means that you can +share its code and resources across multiple applications. </p> + +<p style="margin-top:.5em;">If you aren't familiar with library projects or how +to use them, see <a href="{@docRoot}guide/developing/projects/index.html#LibraryProjects"> +Managing Projects</a>. +</p> +</div> +</div> + +<p>The recommended way of using the LVL is setting it up as a new Android +<em>library project</em>. A library project is a type of development project +that holds shared Android source code and resources. Other Android application +projects can reference the library project and, at build time, include its +compiled sources in their <code>.apk</code> files. In the context of licensing, +this means that you can do most of your licensing development once, in a library +project, then include the library sources in your various application projects. +In this way, you can easily maintain a uniform implementation of licensing +across all of your projects and maintain it centrally. </p> + +<p>The LVL is provided as a configured library project — once you have +downloaded it, you can start using it right away. </p> + +<p>If you are working in Eclipse with ADT, you need to add the LVL to your +workspace as a new development project, in the same way as you would a new +application project. </p> + +<ol> +<li>Use the New Project Wizard to create a new +project from existing sources. Select the LVL's <code>library</code> directory +(the directory containing the library's AndroidManifest.xml file) as the project +root.</li> +<li>When you are creating the library project, you can select any application +name, package, and set other fields as needed. </li> +<li>For the library's build target, select Android 1.5 (API level 3) or higher.</li> +</ol> + +<p> When created, the project is +predefined as a library project in its <code>project.properties</code> file, so +no further configuration is needed. </p> + +<p>For more information about how to create an application project or work with +library projects in Eclipse, see <a +href="{@docRoot}guide/developing/projects/projects-eclipse.html">Managing Projects from +Eclipse with ADT</a>.</p> + + +<h4>Copying the LVL sources to your application</h4> + +<p>As an alternative to adding the LVL as a library project, you can copy the +library sources directly into your application. To do so, copy (or import) the +LVL's <code>library/src/com</code> directory into your application's +<code>src/</code> directory.</p> + +<p>If you add the LVL sources directly to your application, you can skip the +next section and start working with the library, as described in <a +href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding +Licensing to Your App</a>.</p> + + +<h3 id="add-library">Including the LVL library project sources in your +application</h3> + +<p>If you want to use the LVL sources as a library project, you need to add a +reference to the LVL library project in your application project properties. This tells +build tools to include the LVL library project sources in your application at +compile time. The process for adding a reference to a library project depends +on your development environment, as described below.</p> + +<p> If you are developing in Eclipse with ADT, you should already have added the +library project to your workspace, as described in the previous section. If you +haven't done that already, do it now before continuing. </p> + +<p>Next, open the application's project properties window, as shown below. +Select the "Android" properties group and click <strong>Add</strong>, then +choose the LVL library project (com_android_vending_licensing) and click +<strong>OK</strong>. For more information, see +<a href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject"> +Managing Projects from Eclipse with ADT</a></p>. + + +<img src="{@docRoot}images/licensing_add_library.png" alt=""/> +<p class="img-caption"><strong>Figure 3.</strong> If you are +working in Eclipse with ADT, you can add the LVL library project to your +application from the application's project properties.</p> + + +<p>If you are developing using the SDK command-line tools, navigate to the +directory containing your application project and open the +<code>project.properties</code> file. Add a line to the file that specifies the +<code>android.library.reference.<n></code> key and the path to the +library. For example: </p> + +<pre>android.library.reference.1=path/to/library_project</pre> + +<p>Alternatively, you can use this command to update the project +properties, including the reference to the library project:</p> + +<pre class="no-pretty-print" style="color:black">android update lib-project +--target <em><target_ID></em> \ +--path <em>path/to/my/app_project</em> \ +--library <em>path/to/my/library_project</em> +</pre> + +<p>For more information about working with library projects, +see <a href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject"> +Setting up a Library Project</a>.</p> + + + + + + + + + + + + + + + + + + + + + +<h2 id="test-env">Setting Up the Testing Environment</h2> + +<p>The Google Play publisher site provides configuration tools that let you +and others test licensing on your application before it is published. As you are +implementing licensing, you can make use of the publisher site tools to test +your application's Policy and handling of different licensing responses and +error conditions.</p> + +<p>The main components of the test environment for licensing include: </p> + +<ul> +<li>A "Test response" configuration in your publisher account that lets you +set the static licensing response returned, when the server processes a +license check for an application uploaded to the publisher account, from a user +signed in to the publisher account or a test account.</li> +<li>An optional set of test accounts that will receive the static test +response when they check the license of an application that you have uploaded +(regardless whether the application is published or not).</li> +<li>A runtime environment for the application that includes the Google Play +application or Google APIs Add-On, on which the user is signed in to the +publisher account or one of the test accounts.</li> +</ul> + +<p>Setting up the test environment properly involves:</p> + +<ol> +<li><a href="#test-response">Setting static test responses</a> that are returned by the licensing server.</li> +<li><a href="#test-acct-setup">Setting up test accounts</a> as needed.</li> +<li><a href="#acct-signin">Signing in</a> properly to an emulator or device, before initiating a license check test.</li> +</ol> + +<p>The sections below provide more information.</p> + + +<h3 id="test-response">Setting test responses for license checks</h3> + +<p>Google Play provides a configuration setting in your publisher account +that lets you override the normal processing of a license check and return a +specified static response code. The setting is for testing only and applies +<em>only</em> to license checks for applications that you have uploaded, made by +any user signed in to an emulator or device using the credentials of the +publisher account or a registered test account. For other users, the server +always processes license checks according to normal rules. </p> + +<p>To set a test response for your account, sign in to your publisher account +and click "Edit Profile". In the Edit Profile page, locate the Test Response +menu in the Licensing panel, shown below. You can select from the full set of +valid server response codes to control the response or condition you want to +test in your application.</p> + +<p>In general, you should make sure to test your application's licensing +implementation with every response code available in the Test Response menu. +For a description of the codes, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server +Response Codes</a> in the <a +href="{@docRoot}guide/market/licensing/licensing-reference.html">Licensing Reference</a>.</p> + +<img src="{@docRoot}images/licensing_test_response.png" alt=""/> +<p class="img-caption"><strong>Figure 4.</strong> The Licensing +panel of your account's Edit Profile page, showing the Test Accounts field and the +Test Response menu.</p> + +<p>Note that the test response that you configure applies account-wide — +that is, it applies not to a single application, but to <em>all</em> +applications associated with the publisher account. If you are testing multiple +applications at once, changing the test response will affect all of those +applications on their next license check (if the user is signed in to +the emulator or device using the publisher account or a test account).</p> + +<p>Before you can successfully receive a test response for a license check, +you must sign in to the device or emulator on which the application +is installed, and from which it is querying the server. Specifically, you must +sign using either your publisher account or one of the test accounts that you +have set up. For more information about test accounts, see the next section.</p> + +<p>See <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server +Response Codes</a> for a list of +test responses available and their meanings. </p> + + +<h3 id="test-acct-setup">Setting up test accounts</h3> + +<p>In some cases, you might want to let multiple teams of developers test +licensing on applications that will ultimately be published through your +publisher account, but without giving them access to your publisher account's +sign-in credentials. To meet that need, the Google Play publisher site lets +you set up one or more optional <em>test accounts</em> — accounts that are +authorized to query the licensing server and receive static test responses from +your publisher account.</p> + +<p>Test accounts are standard Google accounts that you register on your +publisher account, such that they will receive the test response for +applications that you have uploaded. Developers can then sign in to their +devices or emulators using the test account credentials and initiate license +checks from installed applications. When the licensing server receives a license +check from a user of a test account, it returns the static test response +configured for the publisher account. </p> + +<p>Necessarily, there are limitations on the access and permissions given to +users signed in through test accounts, including:</p> + +<ul> +<li>Test account users can query the licensing server only for applications that +are already uploaded to the publisher account. </li> +<li>Test account users do not have permission to upload applications to your +publisher account.</li> +<li>Test account users do not have permission to set the publisher account's +static test response.</li> +</ul> + +<p>The table below summarizes the differences in capabilities, between the +publisher account, a test account, and any other account.</p> + +<p class="table-caption" id="acct-types-table"><strong>Table 1.</strong> +Differences in account types for testing licensing.</p> + +<table> +<tr> +<th>Account Type</th> +<th>Can check license before upload?</th> +<th>Can receive test response?</th> +<th>Can set test response?</th> +</tr> + +<tr> +<td>Publisher account</td> +<td>Yes</td> +<td>Yes</td> +<td>Yes</td> +</tr> + +<tr> +<td>Test account</td> +<td>No</td> +<td>Yes</td> +<td>No</td> +</tr> + +<tr> +<td>Other</td> +<td>No</td> +<td>No</td> +<td>No</td> +</tr> +</table> + +<h4 id="reg-test-acct">Registering test accounts on the publisher account</h4> + +<p>To get started, you need to register each test account in your publisher +account. As shown in Figure 4, you +register test accounts in the Licensing panel of your publisher account's Edit +Profile page. Simply enter the accounts as a comma-delimited list and click +<strong>Save</strong> to save your profile changes.</p> + +<p>You can use any Google account as a test account. If you want to own and +control the test accounts, you can create the accounts yourself and distribute +the credentials to your developers or testers.</p> + +<h4 id="test-app-upload">Handling application upload and distribution for test +account users</h4> + +<p>As mentioned above, users of test accounts can only receive static test +responses for applications that are uploaded to the publisher account. Since +those users do not have permission to upload applications, as the publisher you +will need to work with those users to collect apps for upload and distribute +uploaded apps for testing. You can handle collection and distribution in any way +that is convenient. </p> + +<p>Once an application is uploaded and becomes known to the licensing server, +developers and testers can continue modify the application in their local +development environment, without having to upload new versions. You only need to +upload a new version if the local application increments the +<code>versionCode</code> attribute in the manifest file. </p> + +<h4 id="test-key">Distributing your public key to test account users</h4> + +<p>The licensing server handles static test responses in the normal way, +including signing the license response data, adding extras parameters, and so +on. To support developers who are implementing licensing using test accounts, +rather than the publisher account, you will need to distribute +your public key to them. Developers without access to the publisher site do not +have access to your public key, and without the key they won't be able to +verify license responses. </p> + +<p>Note that if you decide to generate a new licensing key pair for your account +for some reason, you need to notify all users of test accounts. For +testers, you can embed the new key in the application package and distribute it +to users. For developers, you will need to distribute the new key to them +directly. </p> + + +<h3 id="acct-signin">Signing in to an authorized account in the runtime +environment</h3> + +<p>The licensing service is designed to determine whether a given user is +licensed to use a given application — during a license check, the Google +Play application gathers the user ID from the primary account on the system +and sends it to the server, together with the package name of the application +and other information. However, if there is no user information available, the +license check cannot succeed, so the Google Play application terminates the +request and returns an error to the application. </p> + +<p>During testing, to ensure that your application can successfully query the +licensing server, you must make sure that you sign in to an account <em>on the +device or emulator</em> using:</p> + +<ul> +<li>The credentials of a publisher account, or</li> +<li>The credentials of a test account that is registered with a publisher +account</li> +</ul> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Signing in to a Google account on an emulator</h2> + +<p>If you are testing licensing on an emulator, you need to sign in to a Google +account on the emulator. If you do not see an option to create a new Google +account, the problem might be that your AVD is running a standard Android system +image, rather than the Google APIs Add-On, API 8 (release 2) or higher. </p> + +<p style="margin-top:.5em;">For more information, see <a +href="#runtime-setup">Setting up the runtime environment</a>, above.</p> + +</div> +</div> + +<p>Signing in using a publisher account offers the advantage of letting your +applications receive static test responses even before the applications are +uploaded to the publisher site.</p> + +<p>If you are part of a larger organization or are working with external groups +on applications that will be published through your site, you will more likely +want to distribute test accounts instead, then use those to sign in during +testing. </p> + +<p>To sign in on a device or emulator, follow the steps below. The preferred +approach is to sign in as the primary account — however, if there are +other accounts already in use on the device or emulator, you can create an +additional account and sign in to it using the publisher or test account +credentials. </p> + +<ol> +<li>Open Settings > Accounts & sync</li> +<li>Select <strong>Add Account</strong> and choose to add a Google account. +</li> +<li>Select <strong>Next</strong> and then <strong>Sign in</strong>.</li> +<li>Enter the username and password of either the publisher account or a test +account that is registered in the publisher account.</li> +<li>Select <strong>Sign in</strong>. The system signs you in to the new +account.</li> +</ol> + +<p>Once you are signed in, you can begin testing licensing in your application +(if you have completed the LVL integration steps above). When your application +initiates a license check, it will receive a response containing the static test +response configured on the publisher account. </p> + +<p>Note that, if you are using an emulator, you will need to sign in to the +publisher account or test account each time you wipe data when restarting the +emulator.</p> + +<p>Once you've completed the setup procedures, continue to <a +href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding Licensing to Your App</a>.</p> + + + diff --git a/docs/html/guide/market/publishing/multiple-apks.jd b/docs/html/guide/market/publishing/multiple-apks.jd index ff70e85..e7cfa33 100644 --- a/docs/html/guide/market/publishing/multiple-apks.jd +++ b/docs/html/guide/market/publishing/multiple-apks.jd @@ -45,7 +45,7 @@ support all desired devices with a single APK</li> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></li> + <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> <li><a href="{@docRoot}sdk/compatibility-library.html">Compatibility Package</a></li> @@ -55,10 +55,10 @@ Package</a></li> </div> </div> -<p>Multiple APK support is a feature in Android Market that allows you to publish different APKs +<p>Multiple APK support is a feature on Google Play that allows you to publish different APKs for your application that are each targeted to different device configurations. Each APK is a complete and independent version of your application, but they share the same application listing on -Android Market and must share the same package name and be signed with the same release key. This +Google Play and must share the same package name and be signed with the same release key. This feature is useful for cases in which your application cannot reach all desired devices with a single APK.</p> @@ -73,8 +73,8 @@ prevent a single APK from working on all devices.</p> <p>Although <strong>we encourage you to develop and publish a single APK</strong> that supports as many device configurations as possible, doing so is sometimes not possible. To help -you publish your application for as many devices as possible, Android Market allows you to -publish multiple APKs under the same application listing. Android Market then supplies each APK to +you publish your application for as many devices as possible, Google Play allows you to +publish multiple APKs under the same application listing. Google Play then supplies each APK to the appropriate devices based on configuration support you've declared in the manifest file of each APK.</p> @@ -86,7 +86,7 @@ APK.</p> <li>Support different platform versions with each APK.</li> </ul> -<p>Currently, these are the only device characteristics that Android Market supports for publishing +<p>Currently, these are the only device characteristics that Google Play supports for publishing multiple APKs as the same application.</p> <p class="note"><strong>Note:</strong> You should generally use multiple APKs to support @@ -100,8 +100,8 @@ consider your options before publishing multiple APKs.</p> <h2 id="Concepts">Publishing Concepts</h2> -<p>Before you start publishing multiple APKs on Android Market, you must understand a few -concepts regarding how the Android Market publisher site works.</p> +<p>Before you start publishing multiple APKs on Google Play, you must understand a few +concepts regarding how the Google Play publisher site works.</p> <h3 id="Active">Active APKs</h3> @@ -111,20 +111,20 @@ concepts regarding how the Android Market publisher site works.</p> <p>When editing your application, there are two buttons on the top-right side of the page. The first button is either <strong>Publish</strong> or <strong>Unpublish</strong> and the second button is always <strong>Save</strong> (but its behavior changes).</p> - <p>When your application is new or you have unpublished it from Market, the first + <p>When your application is new or you have unpublished it from Google Play, the first button says <strong>Publish</strong>. Clicking it will publish any APKs listed as -Active, making them available on Android Market. Also while your application is new +Active, making them available on Google Play. Also while your application is new or unpublished, clicking <strong>Save</strong> will save any changes you've made, such as information added to the Product details and APKs you've uploaded, but nothing is made visible on -Android Market—this allows you to save your changes and sign out of the publisher site before +Google Play—this allows you to save your changes and sign out of the publisher site before deciding to publish.</p> <p>Once you've published your application, the first button changes to <strong>Unpublish</strong>. Clicking it in this state unpublishes your application so that none -of the APKs are available on Android Market. Also while published, the behavior of the +of the APKs are available on Google Play. Also while published, the behavior of the <strong>Save</strong> button is different. In this state, clicking <strong>Save</strong> not -only saves all your changes, but also publishes them to Android Market. For example, if you've +only saves all your changes, but also publishes them to Google Play. For example, if you've already published your application and then make changes to your product details or activate new -APKs, clicking <strong>Save</strong> makes all those changes live on Android Market.</p> +APKs, clicking <strong>Save</strong> makes all those changes live on Google Play.</p> </div> </div> @@ -135,14 +135,14 @@ moves into the list of <em>Active</em> APKs. This list allows you to preview whi you're about to publish.</p> <p>If there are no errors, any "active" APK will be published to -Android Market when you click the <strong>Publish</strong> button (if the application is +Google Play when you click the <strong>Publish</strong> button (if the application is unpublished) or when you click the <strong>Save</strong> button (if the application is already published).</p> <h3 id="SimpleAndAdvanced">Simple mode and advanced mode</h3> -<p>The Android Market publisher site provides two modes for managing the APKs associated with +<p>The Google Play publisher site provides two modes for managing the APKs associated with your application: <em>simple mode</em> and <em>advanced mode</em>. You can switch between these by clicking the link at the top-right corner of the <strong>APK files</strong> tab.</p> @@ -164,21 +164,21 @@ below.</p> <h2 id="HowItWorks">How Multiple APKs Work</h2> -<p>The concept for using multiple APKs on Android Market is that you have just one entry in -Android Market for your application, but different devices might download a different APK. This +<p>The concept for using multiple APKs on Google Play is that you have just one entry in +Google Play for your application, but different devices might download a different APK. This means that:</p> <ul> <li>You maintain only one set of product details (app description, icons, screenshots, etc.). This also means you <em>cannot</em> charge a different price for different APKs.</li> - <li>All users see only one version of your application on Android Market, so they are not + <li>All users see only one version of your application on Google Play, so they are not confused by different versions you may have published that are "for tablets" or "for phones."</li> <li>All user reviews are applied to the same application listing, even though users on different devices may have different APKs.</li> <li>If you publish different APKs for different versions of Android (for different API levels), then when a user's device receives a system update that qualifies them for a different APK you've -published, Android Market updates the user's application to the APK designed for the higher version +published, Google Play updates the user's application to the APK designed for the higher version of Android. Any system data associated with the application is retained (the same as with normal application updates when using a single APK).</li> </ul> @@ -192,8 +192,8 @@ following sections describe more about how it works.</p> <h3 id="SupportedFilters">Supported filters</h3> <p>Which devices receive each APK is determined by <a -href="{@docRoot}guide/appendix/market-filters.html">Android Market filters</a> that are specified by -elements in the manifest file of each APK. However, Android Market allows you to publish multiple +href="{@docRoot}guide/appendix/market-filters.html">Google Play filters</a> that are specified by +elements in the manifest file of each APK. However, Google Play allows you to publish multiple APKs only when each APK uses filters to support a variation of the following device characteristics:</p> @@ -229,7 +229,7 @@ with a single APK.</p> href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element are "true" if you do not declare them otherwise. However, because the {@code android:xlargeScreens} attribute was added in Android 2.3 (API level -9), Android Market will assume that it is "false" if your application does not set either <a +9), Google Play will assume that it is "false" if your application does not set either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code @@ -266,7 +266,7 @@ with a higher <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min android:minSdkVersion}</a> value must have a higher <a href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> value. This is also true if two APKs overlap their device support based on a different supported -filter. This ensures that when a device receives a system update, Android Market can offer the user +filter. This ensures that when a device receives a system update, Google Play can offer the user an update for your application (because updates are based on an increase in the app version code). This requirement is described further in the section below about <a href="#Rules">Rules for multiple APKs</a>.</li> @@ -286,8 +286,8 @@ higher, as per the previous note).</li> </ul> <p>Other manifest elements that enable <a -href="{@docRoot}guide/appendix/market-filters.html">Android Market filters</a>—but are not -listed above—are still applied for each APK as usual. However, Android Market does not allow +href="{@docRoot}guide/appendix/market-filters.html">Google Play filters</a>—but are not +listed above—are still applied for each APK as usual. However, Google Play does not allow you to publish multiple APKs based on variations of them. Thus, you cannot publish multiple APKs if the above listed filters are the same for each APK (but the APKs differ based on other characteristics in the manifest file). For @@ -312,7 +312,7 @@ android:versionCode}</a> attribute.</li> <li>Each APK <strong>must not exactly match the configuration support of another APK</strong>. <p>That is, each APK must declare slightly different support for at least one of -the <a href="#MarketFiltersSupported">supported Market filters</a> (listed above).</p> +the <a href="#SupportedFilters">supported Google Play filters</a> (listed above).</p> <p>Usually, you will differentiate your APKs based on a specific characteristic (such as the supported texture compression formats), and thus, each APK will declare support for different devices. However, it's OK to publish multiple APKs that overlap their support slightly. When two @@ -330,11 +330,11 @@ application.</li> <li>An APK that requires a <strong>higher API level</strong> must have a <strong>higher version code</strong>. <p>This is true only when either: the APKs differ based <em>only</em> on the -supported API levels (no other <a href="#SupportedMarketFilters">supported market filters</a> +supported API levels (no other <a href="#SupportedFilters">supported filters</a> distinguish the APKs from each other) <em>or</em> when the APKs do use another supported filter, but there is an overlap between the APKs within that filter.</p> <p>This is important because a user's device receives an application update from -Android Market only if the version code for the APK on Android Market is higher than the version +Google Play only if the version code for the APK on Google Play is higher than the version code of the APK currently on the device. This ensures that if a device receives a system update that then qualifies it to install the APK for higher API levels, the device receives an application update because the version code increases.</p> @@ -365,7 +365,7 @@ increase from the lower API level to the higher API level.</li> </ul> -<p>Failure to abide by the above rules results in an error on the Android Market publisher site +<p>Failure to abide by the above rules results in an error on the Google Play publisher site when you activate your APKs—you will be unable to publish your application until you resolve the error.</p> @@ -377,7 +377,7 @@ in warnings rather than errors. Warnings can be caused by the following:</p> APKs support the devices that then fall outside the supported range. For example, if an APK currently supports small and normal size screens and you change it to support only small screens, then you have shrunk the pool of supported devices and some devices will no longer see your -application in Android Market. You can resolve this by adding another APK that supports normal size +application on Google Play. You can resolve this by adding another APK that supports normal size screens so that all previously-supported devices are still supported.</li> <li>When there are "overlaps" between two or more APKs. For example, if an APK supports screen @@ -467,8 +467,8 @@ user visible version assigned to <a href="{@docRoot}guide/topics/manifest/manifest-element.html#vname">{@code android:versionName}</a>), so that it's easy for you to associate the version code and version name.</p> -<p class="note"><strong>Note:</strong> When you increase the version code for an APK, Android -Market will prompt users of the previous version to update the application. Thus, to avoid +<p class="note"><strong>Note:</strong> When you increase the version code for an APK, Google +Play will prompt users of the previous version to update the application. Thus, to avoid unnecessary updates, you should not increase the version code for APKs that do not actually include changes.</p> @@ -507,7 +507,7 @@ configuration support for one or several of the APKs.</p> <h2 id="SingleAPK">Using a Single APK Instead</h2> <p><strong>Creating multiple APKs for your application is not the normal procedure</strong> for -publishing an application on Android Market. In most cases, you should be able to publish your +publishing an application on Google Play. In most cases, you should be able to publish your application to most users with a single APK and we encourage that you do so. When you encounter a situation in which using a single APK becomes difficult, you should carefully consider all your options before deciding to publish multiple APKs.</p> @@ -542,7 +542,7 @@ setup, the user receives your application and it runs using the resources optimi For example, on a new tablet, the user receives your application and it runs with your tablet-optimized resources. This restore process does not work across different APKs, because each APK can potentially have different -permissions that the user has not agreed to, so Android Market may not restore the application at +permissions that the user has not agreed to, so Google Play may not restore the application at all. (If you use multiple APKs, the user receives either the exact same APK if it's compatible or nothing at all and must manually download your application to get the APK designed for the new device.)</p></li> @@ -586,7 +586,7 @@ public void onSurfaceChanged(GL10 gl, int w, int h) { <h3 id="ScreenOptions">Supporting multiple screens</h3> -<p>Unless your APK file exceeds the Android Market size limit of 50MB, supporting multiple screens +<p>Unless your APK file exceeds the Google Play size limit of 50MB, supporting multiple screens should always be done with a single APK. Since Android 1.6, the Android system manages most of the work required for your application to run successfully on a variety of screen sizes and densities.</p> diff --git a/docs/html/guide/practices/compatibility.jd b/docs/html/guide/practices/compatibility.jd index bb7a72e..5e514c4 100644 --- a/docs/html/guide/practices/compatibility.jd +++ b/docs/html/guide/practices/compatibility.jd @@ -7,7 +7,7 @@ page.title=Android Compatibility <h2>See also</h2> <ol> <li><a -href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></li> +href="{@docRoot}guide/appendix/market-filters.html">Filtering on Google Play</a></li> <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing Alternative Resources</a></li> <li><a @@ -39,7 +39,7 @@ variety of hardware.</p> your apps to do that, while at the same time letting you maintain control of what types of devices your app is available to. With a bit of forethought and some minor changes in your app's manifest file, you can ensure that users -whose devices can’t run your app will never see it in the Android Market, and +whose devices can’t run your app will never see it on Google Play, and will not get in trouble by downloading it. This page explains how you can control which devices have access to your apps, and how to prepare your apps to make sure they reach the right audience.</p> @@ -64,7 +64,7 @@ every class and every API for that API level.</p> corresponding hardware or feature. But that’s not a problem: we also designed Android to prevent apps from being visible to devices which don’t have features the apps require. We’ve built support for this right into the SDK tools, and -it’s part of the Android platform itself, as well as Android Market.</p> +it’s part of the Android platform itself, as well as part of Google Play.</p> <p>As a developer, you have complete control of how and where your apps are available. Android provides tools as a first-class part of the platform that let @@ -79,9 +79,9 @@ only the devices capable of running them.</p> <li>You state the features your app requires by declaring <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a> elements its manifest file.</li> -<li>Devices are required to declare the features they include to Android -Market.</li> -<li>Android Market uses your app’s stated requirements to filter it from devices +<li>Devices are required to declare the features they include to Google +Play.</li> +<li>Google Play uses your app’s stated requirements to filter it from devices that don’t meet those requirements.</li> </ol> @@ -103,24 +103,24 @@ instead use the fine-grained controls Android provides.</p> <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Filtering on Android Market</p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;">Filtering on Google Play</p> - <p>Android Market filters the applications that are visible to users, so + <p>Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with their devices.</p> - <p style="margin-top:1em;">One of the ways Market filters applications is by -feature compatibility. To do this, Market checks the + <p style="margin-top:1em;">One of the ways Google Play filters applications is by +feature compatibility. To do this, Google Play checks the <code><uses-feature></code> elements in each application's manifest, to -establish the app's feature needs. Market then shows or hides the application to +establish the app's feature needs. Google Play then shows or hides the application to each user, based on a comparison with the features available on the user's device. <p style="margin-top:1em;">For information about other filters that you can use to control the availability of your apps, see the -<a href="{@docRoot}guide/appendix/market-filters.html">Market -Filters</a> document.</p> +<a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> +document.</p> </div> </div> @@ -142,8 +142,8 @@ future versions, new feature IDs will be added as well.</p> <p>When you write your application, you specify which features your app requires by listing their feature IDs in <code><uses-feature></code> elements in -the <code>AndroidManifest.xml</code> file. This is the information that Android -Market uses to match your app to devices that can run it. For instance, if you +the <code>AndroidManifest.xml</code> file. This is the information that Google +Play uses to match your app to devices that can run it. For instance, if you state that your app requires android.software.live_wallpapers, it won’t be shown to devices that don’t support Live Wallpapers.</p> @@ -170,12 +170,12 @@ audience size and minimizing development costs.</p> business or legal reasons. For instance, an app that displays train schedules for the London Underground is unlikely to be useful to users outside the United Kingdom. Other apps might not be permitted in certain countries for business or -legal reasons. For cases such as these, Android Market itself provides +legal reasons. For cases such as these, Google Play itself provides developers with filtering options that allow them control their app’s availability for non-technical reasons.</p> -<p>The help information for Android Market provides full details, but in a -nutshell, developers can use the Market publisher UI to:</p> +<p>The help information for Google Play provides full details, but in a +nutshell, developers can use the Google Play publisher UI to:</p> <ul> <li>List the countries an app is available in.</li> @@ -185,7 +185,7 @@ nutshell, developers can use the Market publisher UI to:</p> <p>Filtering for technical compatibility (such as required hardware components) is always based on information contained within your <code>.apk</code> file. But filtering for non-technical reasons (such as geographic restrictions) is always -handled in the Market user interface.</p> +handled in the Google Play user interface.</p> <h3 id="futureproofing">Future-proofing</h3> @@ -206,7 +206,7 @@ capability, though a (fixed-focus) camera was still required. Some apps such as barcode scanners do not function as well with cameras that do not auto-focus. To prevent users from having a bad experience with those apps, existing apps that obtain permission to use the Camera were assumed by default to require -auto-focus. This allowed Android Market to filter those apps from devices that +auto-focus. This allowed Google Play to filter those apps from devices that lack auto-focus.</li> <li>Android 2.2, meanwhile, allowed the microphone to be optional on some diff --git a/docs/html/guide/practices/design/accessibility.html b/docs/html/guide/practices/design/accessibility.html new file mode 100644 index 0000000..0fa7b32 --- /dev/null +++ b/docs/html/guide/practices/design/accessibility.html @@ -0,0 +1,11 @@ +<html> +<head> +<meta http-equiv="refresh" +content="0;url=http://developer.android.com/guide/topics/ui/accessibility/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/topics/ui/accessibility/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/practices/design/accessibility.jd b/docs/html/guide/practices/design/accessibility.jd deleted file mode 100644 index a66a974..0000000 --- a/docs/html/guide/practices/design/accessibility.jd +++ /dev/null @@ -1,353 +0,0 @@ -page.title=Designing for Accessibility -@jd:body - - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Quickview</h2> - <ul> - <li>To make your application more accessible, you should make sure your UI is navigable -using a directional controller and your widgets provide content descriptions</li> - <li>If you implement a custom view, you should ensure that it delivers the appropriate -accessibility events during user interaction</li> - </ul> - - <h2>In this document</h2> - <ol> - <li><a href="#Navigation">Allow Navigation with a Directional Controller</a> - <ol> - <li><a href="#FocusOrder">Controlling focus order</a></li> - <li><a href="#ClickingDpad">Clicking with a directional controller</a></li> - </ol> - </li> - <li><a href="#LabelInputs">Label Your Input Widgets</a></li> - <li><a href="#UiBestPractices">Follow Android UI Best Practices</a></li> - <li><a href="#CustomViews">Send Accessibility Events from Custom View Components</a></li> - <li><a href="#Test">Test Your Application’s Accessibility</a></li> - </ol> - - <h2>Key classes</h2> - <ol> - <li>{@link android.view.accessibility.AccessibilityEvent}</li> - <li>{@link android.view.accessibility.AccessibilityEventSource}</li> - </ol> - - <h2>Related samples</h2> - <ol> - <li><a -href="{@docRoot}resources/samples/AccessibilityService/index.html">Accessibility Service</a></li> - </ol> - -</div> -</div> - - - -<p>Many Android users have disabilities that require them to interact with their Android devices in -different ways. These include users who have visual, physical or age-related disabilities that -prevent them from fully using or seeing a touchscreen.</p> - -<p>Android provides an accessibility layer that helps these users navigate their Android-powered -devices more easily. Android's accessibility services provide things like text-to-speech, haptic -feedback, and trackball/d-pad navigation that augment the user experience.</p> - -<p>Your application should follow the guidelines in this document to ensure that it provides a -good experience for users with disabilities. Following these two basic rules will solve most -access-related problems:</p> - -<ul> -<li>Make all of your user interface controls accessible with a trackball or directional -controller (d-pad).</li> -<li>Label your {@link android.widget.ImageButton}, {@link android.widget.EditText}, and other input -widgets using the <a -href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription">{@code -android:contentDescription}</a> attribute.</li> -</ul> - - - -<h2 id="Navigation">Allow Navigation with a Directional Controller</h2> - -<p>Many Android devices come with some sort of directional controller, such as:</p> -<ul> -<li>A clickable trackball that users can move in any direction</li> -<li>A clickable d-pad that allows users to navigate in four directions.</li> -<li>Arrow keys and an OK button that’s equivalent to clicking a trackball or d-pad.</li> -</ul> - -<p>All of these directional controllers allow users to navigate the screen without using the -touchscreen. On some devices, a user can also navigate to the top or bottom of a list by holding -down the <em>alt</em> key while pressing a discrete key for up or down.</p> - -<p>A directional controller is the primary means of navigation for users with visual or some -physical impairments (and also for users without impairments when using devices that don't -have a touchscreen). You should verify that all UI controls in your application are -accessible without using the touchscreen and that clicking with the center button (or OK button) has -the same effect as touching the controls on the touchscreen.</p> - -<p>A UI control (also called a "widget") is accessible using directional controls when it's -"focusable" property is "true." This means that users can focus on the widget using the directional -controls and then interact with it. Widgets provided by the Android APIs are focusable by default -and visually indicate focus by changing the widget visual appearance in some way.</p> - -<p>Android provides several APIs that let you control whether a widget is focusable and even -request that a widget be given focus. Such methods include:</p> - -<ul> - <li>{@link android.view.View#setFocusable setFocusable()}</li> - <li>{@link android.view.View#isFocusable isFocusable()}</li> - <li>{@link android.view.View#requestFocus requestFocus()}</li> -</ul> - -<p>When working with a view that is not focusable by default, you can make it focusable from the XML -layout file by setting the <a -href="{@docRoot}reference/android/view/View.html#attr_android:focusable">{@code -android:focusable}</a> attribute to {@code "true"}.</p> - - - -<h3 id="FocusOrder">Controlling focus order</h3> - -<p>When the user navigates in any direction using the directional controls, focus is passed from one -view to another, as determined by the focus ordering. The ordering of the focus movement is based on -an algorithm that finds the nearest neighbor in a given direction. In rare cases, the default -algorithm may not match the order that you intended for your UI. In these situations, you can -provide explicit overrides to the ordering using the following XML attributes in the layout -file:</p> - -<dl> - <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" ->{@code android:nextFocusDown}</a></dt> - <dd>Defines the next view to receive focus when the user navigates down.</dd> - <a><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusLeft" ->{@code android:nextFocusLeft}</a></dt> - <dd>Defines the next view to receive focus when the user navigates left.</dd> - <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusRight" ->{@code android:nextFocusRight}</a></dt> - <dd>Defines the next view to receive focus when the user navigates right.</dd> - <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" ->{@code android:nextFocusUp}</a></dt> - <dd>Defines the next view to receive focus when the user navigates up.</dd> -</dl> - -<p>For example, here is an XML layout that contains a focusable {@link android.widget.TextView}. -While the {@link android.widget.TextView} is located to the right of the {@link -android.widget.EditText}, it can now be reached by pressing the down arrow when focus is on the -{@link android.widget.EditText}: </p> - -<pre> -<LinearLayout android:orientation="horizontal" - ... > - <EditText android:id="@+id/edit" - android:nextFocusDown=”@+id/text” - ... /> - <TextView android:id="@+id/text" - android:focusable=”true” - android:text="Hello, I am a focusable TextView" - android:nextFocusUp=”@id/edit” - ... /> -</LinearLayout> -</pre> - -<p>When modifying this ordering, be sure that the navigation works as expected in all directions -from each widget and when navigating in reverse (to get back to where you came from).</p> - -<p>You can also modify the focus ordering at runtime, using methods in the {@link -android.view.View} class, such as {@link android.view.View#setNextFocusDownId -setNextFocusDownId()} and {@link android.view.View#setNextFocusRightId -setNextFocusRightId()}.</p> - - -<h3 id="ClickingDpad">Clicking with a directional controller</h3> - -<p>On most devices, clicking a view using a directional controller sends a {@link -android.view.KeyEvent} with {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} to the view currently -in focus. Make sure this event has the same effect as touching the view on the touchscreen. All -standard Android views already handle {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} -appropriately.</p> - -<p>If possible, also treat the {@link android.view.KeyEvent#KEYCODE_ENTER} event the same as -{@link android.view.KeyEvent#KEYCODE_DPAD_CENTER}. That makes interaction much easier from a full -keyboard.</p> - - - - -<h2 id="LabelInputs">Label Your Input Widgets</h2> - -<p>Many input widgets rely on visual cues to inform the user of their meaning. For example, a -notepad application might use an {@link android.widget.ImageButton} with a picture of a plus sign to -indicate that the user can add a new note. Or, an {@link android.widget.EditText} may have -a label near it that indicates its purpose. When a visually impaired user accesses your -application, these visual cues are often useless.</p> - -<p>To provide textual information about these widgets (as an alternative to the visual cues), you -should use the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription" ->{@code android:contentDescription}</a> attribute. The text you provide in this attribute -is not visible on the screen, but if a user has enabled accessibility speech tools then the -description in this attribute is read aloud to the user.</p> - -<p>You should set the <a -href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription" >{@code -android:contentDescription}</a> attribute on every {@link android.widget.ImageButton}, {@link -android.widget.EditText}, {@link android.widget.CheckBox}, and on any other input widgets that might -benefit users with extra information.</p> - -<p>For example, the following {@link android.widget.ImageButton} sets the content description for -the plus button to the {@code add_note} string resource, which might be defined in English as -“Add note":</p> - -<pre> -<ImageButton - android:id=”@+id/add_entry_button” - android:src=”@drawable/plus” - android:contentDescription=”@string/add_note”/> -</pre> - -<p>This way, when using speech accessibility tools, the user hears "Add note" when focused on -this widget.</p> - - - -<h2 id="UiBestPractices">Follow Android UI Best Practices</h2> - -<p>You can make it easier for users to learn how to use your application by developing a user -interface that complies with Android's standard interaction patterns, instead of creating your own -or using interaction patterns from another platform. This consistency is especially important for -many disabled users, as they may have less contextual information available to try to understand -your application’s interface.</p> - -<p>Specifically, you should:</p> - -<ul> -<li>Use the platform's built-in widgets and layouts whenever possible, as these views provide -accessibility support by default.</li> -<li>Use the <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> as an -alternative to complex touchscreen tasks.</li> -<li>Make sure the BACK button correctly moves the user back one logical step in the <a -href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">task's back stack</a> or the -activity's back stack of fragments (when <a -href="{@docRoot}guide/topics/fundamentals/fragments.html#Transactions">performing fragment -transactions</a>), as appropriate.</li> -</ul> - - - -<h2 id="CustomViews">Send Accessibility Events from Custom View Components</h2> - -<p>If your application requires that you create a <a -href="{@docRoot}guide/topics/ui/custom-components.html">custom view component</a>, you may need to -do some additional work to ensure that your view is accessible. Specifically, you should make sure -that your view implements the {@link android.view.accessibility.AccessibilityEventSource} -interface and emits {@link android.view.accessibility.AccessibilityEvent}s at the proper times, -and that each {@link android.view.accessibility.AccessibilityEvent} contains relevant information -about the state of the view.</p> - -<p>Events are emitted whenever something notable happens in the user interface. Currently, there -are five types of accessibility events that a view should send to the system as the user interacts -with it:</p> - -<dl> -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED}</dt> -<dd>Indicates that the user clicked on the view (for example, the user selects a button).</dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}</dt> -<dd>Indicates that the user performed a long press on the view. </dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_SELECTED}</dt> -<dd>Indicates that the user selected an item from within the view. This is usually used in the -context of an {@link android.widget.AdapterView}.</dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_FOCUSED}</dt> -<dd>Indicates that the user moved the focus to the view.</dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}</dt> -<dd>Indicates that the text or contents of the view changed.</dd> -</dl> - - -<p>The basic {@link android.view.View} class implements {@link -android.view.accessibility.AccessibilityEventSource} and emits these events at the proper time in -the standard cases. Your custom view should extend from {@link android.view.View} (or one of its -subclasses) to take advantage of these default implementations.</p> - -<p>Depending on the specifics of your custom view, your view may need to emit one of these events at -a different time than the default {@link android.view.View} implementation. To do so, simply call -{@link android.view.accessibility.AccessibilityEventSource#sendAccessibilityEvent -sendAccessibilityEvent()} with the specific event type at the correct time.</p> - -<p>For example, say you are implementing a custom slider bar that allows the user to select a -numeric value by pressing the left or right arrows. This view should emit an event of type {@link -android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} whenever the slider value -changes:</p> - -<pre> -@Override -public boolean onKeyUp (int keyCode, KeyEvent event) { - if (keyCode == KeyEvent.KEYCODE_DPAD_LEFT) { - mCurrentValue--; - sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED); - return true; - } - ... -} -</pre> - -<p>Each {@link android.view.accessibility.AccessibilityEvent} has a set of required properties that -describe the current state of the view. These properties include things like the view’s class name, -text and checked state. The specific properties required for each event type are described in the -{@link android.view.accessibility.AccessibilityEvent} documentation. The {@link android.view.View} -implementation will fill in default values for these properties. Most of these values, like the -class name and event timestamp, will not need to be changed. However, depending on the specifics of -your custom view, you may want to provide a different value for one or more of the properties. For -example, your view may have additional state information that you want to add to the event text.</p> - -<p>The {@link android.view.View#dispatchPopulateAccessibilityEvent -dispatchPopulateAccessibilityEvent()} method in {@link android.view.View} provides a hook for making -changes to the {@link android.view.accessibility.AccessibilityEvent} object before it is -emitted.</p> - -<p>In the above slider bar example, the view should add the current value of the slider bar to the -text of the event:</p> - -<pre> -@Override -public boolean dispatchPopulateAccessibilityEvent(final AccessibilityEvent event) { - super.dispatchPopulateAccessibilityEvent(event); - if (!isShown()) { - return false; - } - CharSequence text = String.valueOf(mCurrentValue); - if (text.length() > AccessibilityEvent.MAX_TEXT_LENGTH) { - text = text.subSequence(0, AccessiblityEvent.MAX_TEXT_LENGTH); - } - event.getText().add(text); - return true; -} -</pre> - - -<h2 id="Test">Test Your Application’s Accessibility</h2> - -<p>You can simulate the experience for many users by enabling an accessibility service that speaks -as you move around the screen. One such service is <a -href="https://market.android.com/details?id=com.google.android.marvin.talkback">TalkBack</a>, by the -<a href="http://code.google.com/p/eyes-free/">Eyes-Free Project</a>. It comes preinstalled on many -Android-powered devices, but is also available for free from <a -href="https://market.android.com/details?id=com.google.android.marvin.talkback">Android -Market</a>.</p> - -<p>This service requires that you have a text-to-speech engine installed on your phone. You can -verify if you have one installed in the <strong>Text-to-speech</strong> settings menu by selecting -<strong>Listen to an example</strong>. If you do not hear anything spoken, install the required -voice data by selecting <strong>Install voice data</strong>.</p> - -<p>Once text-to-speech is functioning correctly, you can enable TalkBack (or another accessibility -service) in the <strong>Accessibility</strong> settings menu. Enable both -<strong>Accessibility</strong> and <strong>TalkBack</strong>. As you navigate about the device, you -should now hear spoken feedback.</p> - -<p>You can now attempt to use your application as a blind user would. As you move around using only -the directional controller, make sure that the spoken feedback you hear makes sense and is -sufficient to navigate the application without any visual cues.</p> diff --git a/docs/html/guide/practices/optimizing-for-3.0.jd b/docs/html/guide/practices/optimizing-for-3.0.jd index 39662f1..d6c621e 100644 --- a/docs/html/guide/practices/optimizing-for-3.0.jd +++ b/docs/html/guide/practices/optimizing-for-3.0.jd @@ -108,7 +108,7 @@ SDK with the new platform:</p> SDK starter package now</a>.)</p> <ol> - <li><a href="{@docRoot}sdk/adding-components.html#launching">Launch the Android SDK and AVD + <li><a href="{@docRoot}sdk/adding-components.html#launching">Launch the Android SDK Manager</a> and install the following: <ul> <li>SDK Platform Android 3.0</li> @@ -147,7 +147,7 @@ Android 3.0, the emulator is still best way to evaluate your application's appea functionality on Android 3.0.</p> <p class="note"><strong>Tip:</strong> To improve the startup time for the emulator, enable snapshots -for the AVD when you create it with the SDK and AVD Manager (there's a checkbox in the AVD creator +for the AVD when you create it with the AVD Manager (there's a checkbox in the AVD creator to <strong>Enable</strong> snapshots). Then, start the AVD from the AVD manager and check <b>Launch from snapshot</b> and <b>Save to snapshot</b>. This way, when you close the emulator, a snapshot of the AVD state is saved and used to quickly relaunch the AVD next time. However, when you choose to @@ -281,7 +281,7 @@ to help you add features from Android 3.0 without requiring you to change your < href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> or build target, we're providing a static library called the <a href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a> -(downloadable from the AVD and SDK Manager).</p> +(downloadable from the Android SDK Manager).</p> <p>This library includes APIs for <a href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>, <a href="{@docRoot}guide/topics/fundamentals/loaders.html">loaders</a>, and some updated classes. By @@ -421,7 +421,7 @@ href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform</a> document.</p> href="{@docRoot}sdk/android-3.0.html#api">Android 3.0 Platform</a> document also have accompanying samples that allow you to preview the effects and can help you understand how to use them. To get the samples, download them from the SDK repository <a href="{@docRoot}sdk/adding-components.html" ->using the Android SDK and AVD Manager</a>. After downloading the samples ("Samples for SDK API +>using the Android SDK Manager</a>. After downloading the samples ("Samples for SDK API 11"), you can find them in <code><sdk_root>/samples/android-11/</code>. The following list provides links to the browsable source code for some of the samples:</p> @@ -481,7 +481,7 @@ and densities.</p> configurations of screen size and density, you can instead choose to limit the distribution of your application to certain types of screens, such as only tablets or only mobile devices. To do so, you can add elements to your Android manifest file that enable filtering based on screen configuration -by external services such as Android Market.</p> +by external services such as Google Play.</p> <p>However, before you decide to restrict your application to certain screen configurations, you should understand the techniques for <a @@ -517,14 +517,14 @@ screens, you can declare the element in your manifest like this:</p> </manifest> </pre> -<p>External services such as Android Market read this manifest element and use it to ensure that +<p>External services such as Google Play read this manifest element and use it to ensure that your application is available only to devices with an extra large screen.</p> <p class="note"><strong>Note:</strong> If you use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element for the reverse scenario (when your application is not compatible with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then -external services such as Android Market <strong>do not</strong> apply filtering. Your application +external services such as Google Play <strong>do not</strong> apply filtering. Your application will still be available to larger screens, but when it runs, it will not fill the screen—the system will draw it in a "postage stamp" window that's the same relative size as the screen size that your application does support. If you want to prevent your application from being downloaded on @@ -541,7 +541,7 @@ larger devices to download the version designed for smaller screens. In such a c use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code <compatible-screens>}</a> element to manage the distribution of your application based on the combination of screen size and density. External services such as -Android Market uses this information to apply filtering to your application, so that only devices +Google Play uses this information to apply filtering to your application, so that only devices that have a screen configuration with which you declare compatibility can download your application.</p> @@ -551,7 +551,7 @@ which each specify a screen configuration with which your application is compati the {@code android:screenSize} and {@code android:screenDensity} attributes. Each {@code <screen>} element <strong>must include both attributes</strong> to specify an individual screen configuration—if either attribute is missing, then the element is invalid -(external services such as Android Market will ignore it).</p> +(external services such as Google Play will ignore it).</p> <p>For example, if your application is compatible with only small and normal screens, regardless of screen density, then you must specify eight different {@code <screen>} elements, @@ -613,7 +613,7 @@ orientation, you should update your application to support landscape.</p></li> <li><a href="#Telephony">Not all devices have telephony or other features</a> <p>If your application declares the {@code "android.hardware.telephony"} feature in the manifest, then it will not be available to devices that do not offer telephony (such as tablets), based on -Android Market filtering. If your application can function properly without telephony, you should +Google Play filtering. If your application can function properly without telephony, you should update your application to gracefully disable the telephony features when not available on a device.</p></li> </ul> @@ -682,7 +682,7 @@ your applications. For example:</p> <pre><uses-feature android:name="android.hardware.telephony" /></pre> <p>By default, this declares that your application <em>requires</em> telephony features. So, -external services such as Android Market use this information to filter your application from +external services such as Google Play use this information to filter your application from devices that do not offer telephony.</p> <p>If, however, your application uses, but does not require the feature, you should diff --git a/docs/html/guide/practices/screens-distribution.jd b/docs/html/guide/practices/screens-distribution.jd index 60c9c95..a7c4a8e 100644 --- a/docs/html/guide/practices/screens-distribution.jd +++ b/docs/html/guide/practices/screens-distribution.jd @@ -37,7 +37,7 @@ href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for And configurations of screen size and density, you can instead choose to limit the distribution of your application to certain types of screens, such as only tablets and other large devices or only handsets and similar-sized devices. To do so, you can enable filtering by external services such as -Android Market by adding elements to your manifest file that specify the screen configurations your +Google Play by adding elements to your manifest file that specify the screen configurations your application supports.</p> <p>However, before you decide to restrict your application to certain screen configurations, you @@ -58,7 +58,7 @@ might discover that your application can't scale up well or perhaps you've decid versions of your application for different screen configurations. In such a case, you can use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code <compatible-screens>}</a> element to manage the distribution of your application based on -combinations of screen size and density. External services such as Android Market use this +combinations of screen size and density. External services such as Google Play use this information to apply filtering to your application, so that only devices that have a screen configuration with which you declare compatibility can download your application.</p> @@ -68,7 +68,7 @@ configuration with which you declare compatibility can download your application compatible, using both the {@code android:screenSize} and {@code android:screenDensity} attributes. Each {@code <screen>} element <strong>must include both attributes</strong> to specify an individual screen configuration—if either attribute is missing, then the element is invalid -(external services such as Android Market will ignore it).</p> +(external services such as Google Play will ignore it).</p> <p>For example, if your application is compatible with only small and normal size screens, regardless of screen density, you must specify eight different {@code <screen>} elements, @@ -173,7 +173,7 @@ Tools for Managing Screen Sizes</a>.</p> href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element for the reverse scenario (when your application is not compatible with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then -external services such as Android Market <strong>do not</strong> apply filtering. Your application +external services such as Google Play <strong>do not</strong> apply filtering. Your application will still be available to larger screens, but when it runs, it will not resize to fit the screen. Instead, the system will emulate a handset screen size (about 320dp x 480dp; see <a href="{@docRoot}guide/practices/screen-compat-mode.html">Screen Compatibility Mode</a> for more @@ -197,13 +197,13 @@ configurations.</p> <h2 id="MultiApks">Publishing Multiple APKs for Different Screens</h2> -<p>Although we recommend that you publish one APK for your application, Android Market allows +<p>Although we recommend that you publish one APK for your application, Google Play allows you to publish multiple APKs for the same application when each APK supports a different set of screen configurations (as declared in the manifest file). For example, if you want to publish both a handset version and a tablet version of your application, but you're unable to make the same APK work for both screen sizes, you can actually publish two APKs for the same application listing. Depending on each device's -screen configuration, Android Market will deliver it the APK that you've declared to support that +screen configuration, Google Play will deliver it the APK that you've declared to support that device's screen.</p> <p>Beware, however, that publishing multiple APKs for the same application is @@ -212,5 +212,5 @@ APK that can support a wide range of device configurations</strong>. Supporting sizes, especially, is within reason using a single APK, as long as you follow the guide to <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> -<p>If you need more information about how to publish multiple APKs on Android Market, read <a +<p>If you need more information about how to publish multiple APKs on Google Play, read <a href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> diff --git a/docs/html/guide/practices/screens-support-1.5.jd b/docs/html/guide/practices/screens-support-1.5.jd index 9f033b4..4c6fb99 100644 --- a/docs/html/guide/practices/screens-support-1.5.jd +++ b/docs/html/guide/practices/screens-support-1.5.jd @@ -46,7 +46,7 @@ android:targetSdkVersion}</a> set to {@code "4"} or higher, then this document i default, an application written for Android 1.5 or below that does not set the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> set to {@code "4"} or higher runs in <a -href="screen-compat-mode">screen compatibility mode</a> when on a device with a screen larger than +href="screen-compat-mode.html">screen compatibility mode</a> when on a device with a screen larger than the <em>normal</em> screen size (basically, the system displays the application in a small window that is roughly the size of the normal screen size).</p> diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index fb121bd..a870b22 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -882,8 +882,8 @@ application requires is the smallest possible on any device.</p> <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this attribute, so it does not affect how your application behaves at runtime. Instead, it is used -to enable filtering for your application on services such as Android Market. However, -<strong>Android Market currently does not support this attribute for filtering</strong> (on Android +to enable filtering for your application on services such as Google Play. However, +<strong>Google Play currently does not support this attribute for filtering</strong> (on Android 3.2), so you should continue using the other size attributes if your application does not support small screens.</p> </dd> @@ -1242,12 +1242,12 @@ have to buy various devices just to test your application's screen support.</p> <p>To set up an environment for testing your application's screen support, you should create a series of AVDs (Android Virtual Devices), using emulator skins and screen configurations that emulate the screen sizes and densities you want your application to support. To do so, you can use -the Android SDK and AVD Manager to create the AVDs and launch them with a graphical interface.</p> +the AVD Manager to create the AVDs and launch them with a graphical interface.</p> -<p>To launch the Android SDK and AVD Manager, execute the {@code +<p>To launch the Android SDK Manager, execute the {@code SDK Manager.exe} from your Android SDK directory (on Windows only) or execute {@code android} from -the {@code <sdk>/tools/} directory (on all platforms). Figure 6 shows the Android SDK and -AVD Manager with a selection of AVDs, for testing various screen configurations.</p> +the {@code <sdk>/tools/} directory (on all platforms). Figure 6 shows the AVD +Manager with a selection of AVDs, for testing various screen configurations.</p> <p>Table 3 shows the various emulator skins that are available in the Android SDK, which you can use to emulate some of the most common screen configurations.</p> @@ -1340,7 +1340,7 @@ dashboard.</p> <div class="figure" style="width:204px"> <img src="{@docRoot}images/screens_support/avd-start.png" alt="" /> <p class="img-caption"><strong>Figure 7.</strong> - Size and density options you can set, when starting an AVD from the Android SDK and AVD + Size and density options you can set, when starting an AVD from the AVD Manager.</p> </div> @@ -1349,12 +1349,12 @@ up to run at a physical size that closely matches an actual device. This makes it a lot easier to compare the results at various sizes and densities. To do so you need to know the approximate density, in dpi, of your computer monitor (for instance, a 30" Dell monitor has a density of about 96 dpi). When you launch an AVD -from the Android SDK and AVD Manager, you can specify the screen size for the emulator and your +from the AVD Manager, you can specify the screen size for the emulator and your monitor dpi in the Launch Options, as shown in figure 7.</p> <p>If you would like to test your application on a screen that uses a resolution or density not supported by the built-in skins, you can create an AVD that uses a custom resolution -or density. When creating the AVD from the Android SDK and AVD Manager, specify the Resolution, +or density. When creating the AVD from the AVD Manager, specify the Resolution, instead of selecting a Built-in Skin.</p> <p>If you are launching your AVD from the command line, you can specify the scale for diff --git a/docs/html/guide/practices/security.jd b/docs/html/guide/practices/security.jd index 476c301..eeaac44 100644 --- a/docs/html/guide/practices/security.jd +++ b/docs/html/guide/practices/security.jd @@ -126,8 +126,8 @@ applications.</p> <p>Use of <a href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_WRITEABLE"> world writable</a> or <a -href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE -">world readable</a> files for IPC is discouraged because it does not provide +href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE">world +readable</a> files for IPC is discouraged because it does not provide the ability to limit data access to particular applications, nor does it provide any control on data format. As an alternative, you might consider using a ContentProvider which provides read and write permissions, and can make @@ -199,10 +199,10 @@ ContentProvider</a></code>.</p> <p>ContentProviders can also provide more granular access by declaring the <a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> grantUriPermissions</a> element and using the <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMIS -SION">FLAG_GRANT_READ_URI_PERMISSION</a></code> and <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMI -SSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> flags in the Intent object +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMISSION">FLAG_GRANT_READ_URI_PERMISSION</a></code> +and <code><a +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMISSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> +flags in the Intent object that activates the component. The scope of these permissions can be further limited by the <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> @@ -211,14 +211,9 @@ grant-uri-permission element</a></code>.</p> <p>When accessing a <code> <a href="{@docRoot}reference/android/content/ContentProvider.html"> ContentProvider</a></code>, use parameterized query methods such as <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net -.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lan -g.String)">query()</a></code>, <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#update(android.ne -t.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[] -)">update()</a></code>, and <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.ne -t.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid +<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lang.String)">query()</a></code>, <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#update(android.net.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[])">update()</a></code>, and <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.net.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid potential <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL Injection</a> from untrusted data. Note that using parameterized methods is not sufficient if the <code>selection</code> is built by concatenating user data @@ -249,8 +244,9 @@ href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> Activities</a>, and <a href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> Services</a> are all declared in the application manifest. If your IPC mechanism is -not intended for use by other applications, set the android:exported property -to false. This is useful for applications that consist of multiple processes +not intended for use by other applications, set the <a +href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a> +property to false. This is useful for applications that consist of multiple processes within the same UID, or if you decide late in development that you do not actually want to expose functionality as IPC but you don’t want to rewrite the code.</p> @@ -276,11 +272,10 @@ activity.</p> <p>Intents are the preferred mechanism for asynchronous IPC in Android. Depending on your application requirements, you might use <code><a -href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.con -tent.Intent)">sendBroadcast()</a></code>, <code><a -href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(andr -oid.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, or -direct an intent to a specific application component.</p> +href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.content.Intent)">sendBroadcast()</a></code>, +<code><a +href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(android.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, +or direct an intent to a specific application component.</p> <p>Note that ordered broadcasts can be “consumed” by a recipient, so they may not be delivered to all applications. If you are sending an Intent where @@ -311,14 +306,13 @@ and/or access controls on a specific binder interface, those controls must be explicitly added as code in the interface.</p> <p>If providing an interface that does require access controls, use <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(ja -va.lang.String)">checkCallingPermission()</a></code> to verify whether the +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> +to verify whether the caller of the Binder has a required permission. This is especially important before accessing a Service on behalf of the caller, as the identify of your application is passed to other interfaces. If invoking an interface provided by a Service, the <code><a -href="{@docRoot}reference/android/content/Context.html#bindService(android.conte -nt.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> +href="{@docRoot}reference/android/content/Context.html#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> invocation may fail if you do not have permission to access the given Service. If calling an interface provided locally by your own application, it may be useful to use the <code><a @@ -332,14 +326,14 @@ an intent.</p> <p>By default, receivers are exported and can be invoked by any other application. If your <code><a -href={@docRoot}reference/android/content/BroadcastReceiver.html"> +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> BroadcastReceivers</a></code> is intended for use by other applications, you may want to apply security permissions to receivers using the <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestReceiver"> +href="{@docRoot}guide/topics/manifest/receiver-element.html"> <receiver></a></code> element within the application manifest. This will prevent applications without appropriate permissions from sending an intent to the <code><a -href={@docRoot}reference/android/content/BroadcastReceiver.html"> +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> BroadcastReceivers</a></code>.</p> <h3>Using Services</h3> @@ -349,19 +343,21 @@ use. Each service class must have a corresponding <service> declaration in its package's AndroidManifest.xml.</p> <p>By default, Services are exported and can be invoked by any other -application. Services can be protected using the android:permission attribute +application. Services can be protected using the <a +href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">{@code android:permission}</a> +attribute within the manifest’s <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> +href="{@docRoot}guide/topics/manifest/service-element.html"> <service></a></code> tag. By doing so, other applications will need to declare a corresponding <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService_permis -sion"><uses-permission></a></code> element in their own manifest to be +href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a> +</code> element in their own manifest to be able to start, stop, or bind to the service.</p> <p>A Service can protect individual IPC calls into it with permissions, by calling <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(ja -va.lang.String)">checkCallingPermission()</a></code>before executing +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> +before executing the implementation of that call. We generally recommend using the declarative permissions in the manifest, since those are less prone to oversight.</p> @@ -376,9 +372,9 @@ Service to handle IPC, since this modular approach reduces the risk of exposing functionality that is not intended for use by other applications.</p> <p>If you do expose an Activity for purposes of IPC, the <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity_permi -ssion">android:permission</a></code> attribute in the <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> +href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">android:permission</a></code> +attribute in the <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"> <activity></a></code> declaration in the application manifest can be used to restrict access to only those applications which have the stated permissions.</p> @@ -432,8 +428,8 @@ rkeley.edu/~afelt/felt_usenixsec2011.pdf</a></p> <p>Generally, you should strive to create as few permissions as possible while satisfying your security requirements. Creating a new permission is relatively uncommon for most applications, since <a -href="{@docRoot}reference/android/Manifest.permission.html"> -system-defined permissions</a> cover many situations. Where appropriate, +href="{@docRoot}reference/android/Manifest.permission.html">system-defined +permissions</a> cover many situations. Where appropriate, perform access checks using existing permissions.</p> <p>If you must create a new permission, consider whether you can accomplish @@ -560,17 +556,14 @@ href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> does not execute JavaScript so cross-site-scripting is not possible.</p> <p>Use <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with particular care because it allows JavaScript to invoke operations that are normally reserved for Android applications. Only expose <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to sources from which all input is trustworthy. If untrusted input is allowed, untrusted JavaScript may be able to invoke Android methods. In general, we recommend only exposing <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to JavaScript that is contained within your application APK.</p> <p>Do not trust information downloaded over HTTP, use HTTPS instead. Even if @@ -578,13 +571,11 @@ you are connecting only to a single website that you trust or control, HTTP is subject to <a href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">MiTM</a> attacks and interception of data. Sensitive capabilities using <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should not ever be exposed to unverified script downloaded over HTTP. Note that even with the use of HTTPS, <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> increases the attack surface of your application to include the server infrastructure and all CAs trusted by the Android-powered device.</p> @@ -683,8 +674,7 @@ discussed in the Requesting Permissions section.</p> <p>If a GUID is required, create a large, unique number and store it. Do not use phone identifiers such as the phone number or IMEI which may be associated with personal information. This topic is discussed in more detail in the <a -href="http://android-developers.blogspot.com/2011/03/identifying-app-installatio -ns.html">Android Developer Blog</a>.</p> +href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html">Android Developer Blog</a>.</p> <p>Application developers should be careful writing to on-device logs. In Android, logs are a shared resource, and are available @@ -724,9 +714,8 @@ credentials to the wrong application.</p> <p>If credentials are to be used only by applications that you create, then you can verify the application which accesses the <code><a href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> using <code><a href="<code><a -href="{@docRoot}h/reference/android/content/pm/PackageManager.html#checkSignatur -es(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. +AccountManager</a></code> using <code><a +href="{@docRoot}reference/android/content/pm/PackageManager.html#checkSignatures(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. Alternatively, if only one application will use the credential, you might use a <code><a href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> for @@ -756,15 +745,15 @@ RSA provided in the <code><a href="{@docRoot}reference/javax/crypto/Cipher.html">Cipher</a></code> class.</p> <p>Use a secure random number generator ( -<a href="http://developer.android.com/reference/java/security/SecureRandom.html"> +<a href="{@docRoot}reference/java/security/SecureRandom.html"> <code>SecureRandom</code></a>) to initialize any cryptographic keys (<a -href="http://developer.android.com/reference/javax/crypto/KeyGenerator.html"> +href="{@docRoot}reference/javax/crypto/KeyGenerator.html"> <code>KeyGenerator</code></a>). Use of a key that is not generated with a secure random number generator significantly weakens the strength of the algorithm, and may allow offline attacks.</p> <p>If you need to store a key for repeated use, use a mechanism like <code><a -href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> that +href="{@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> that provides a mechanism for long term storage and retrieval of cryptographic keys.</p> diff --git a/docs/html/guide/practices/tablets-and-handsets.jd b/docs/html/guide/practices/tablets-and-handsets.jd index dc35801..8e07a08 100644 --- a/docs/html/guide/practices/tablets-and-handsets.jd +++ b/docs/html/guide/practices/tablets-and-handsets.jd @@ -99,7 +99,8 @@ side.</p> <p>You can enable items from the options menu to appear directly in the action bar as "action items". You can also add navigation features to the action bar, such as tabs or a drop-down list, -and use the application icon to supplement the system's BACK behavior with the option to navigate to +and use the application icon to supplement the system's <em>Back</em> button behavior with the option to +navigate to your application's "home" activity or "up" the application's structural hierarchy.</p> <p>This guide provides some tips for using the action bar in ways that support both tablets and @@ -458,7 +459,8 @@ attribute.</p> developer guide, you can use the application icon in the action bar to facilitate user navigation when appropriate—either as a method to get back to the "home" activity (similar to clicking the logo on a web site) or as a way to navigate up the application's structural hierarchy. Although -it might seem similar to the standard BACK navigation in some cases, the up navigation option +it might seem similar to the standard <em>Back</em> navigation in some cases, the up navigation +option provides a more predictable navigation method for situations in which the user may have entered from an external location, such as a notification, app widget, or a different application.</p> @@ -481,7 +483,7 @@ href="{@docRoot}guide/topics/ui/actionbar.html#Home">Action Bar</a> developer gu information in each list item based on the available space. That is, you can create alternative layouts to be used by the items in your list adapter such that a large screen might display more detail for each item.</li> - <li>Create <a href="{@docRoot}guide/topics/resources/more-resources.html ">alternative resource + <li>Create <a href="{@docRoot}guide/topics/resources/more-resources.html">alternative resource files</a> for values such as integers, dimensions, and even booleans. Using size qualifiers for these resources, you can easily apply different layout sizes, font sizes, or enable/disable features based on the current screen size.</li> diff --git a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd index 31ad466..8e4528e 100644 --- a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd +++ b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd @@ -3,6 +3,43 @@ parent.title=UI Guidelines parent.link=index.html @jd:body + + + +<div id="deprecatedSticker"> + <a href="#" + onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> + <strong>This doc is deprecated</strong></a> +</div> + + +<div id="naMessage" style="display:block"> +<div><p><strong>This document has been deprecated.</strong></p> + <p>For information about designing an activity structure and navigation, read the design guidelines +for <a href="{@docRoot}design/patterns/app-structure.html">App Structure</a> and +<a href="{@docRoot}design/patterns/navigation.html">Navigation</a>, or the developer guide +about <a +href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>.</p> + + <input style="margin-top:1em;padding:5px" type="button" + value="That's nice, but I still want to read this document" +onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> +</div> +</div> + + + + + + + + + + + + + + <div id="qv-wrapper"> <div id="qv"> @@ -40,9 +77,10 @@ parent.link=index.html <li><a href=#reusing_tip>Handle case where no activity matches</a></li> <li><a href=#activity_launching_tip>Consider how to launch your activities</a></li> <li><a href=#activities_added_to_task_tip>Allow activities to add to current task</a></li> - <li><a href=#notifications_get_back_tip>Notifications should let user easily get back</li> + <li><a href=#notifications_get_back_tip>Notifications and App Widgets should provide consistent back behavior</li> <li><a href=#use_notification_tip>Use the notification system</a></li> - <li><a href=#taking_over_back_key>Don't take over BACK key unless you absolutely need to</a></li> + <li><a href=#taking_over_back_key>Don't take over <em>Back</em> button unless you absolutely +need to</a></li> </ol> </li> </ol> @@ -241,8 +279,8 @@ independent of the other Android system keeps a linear navigation history of activities the user has visited. This is the <em>activity stack</em>, also known as the back stack. In general, when a user starts a new activity, it is added - to the activity stack, so that pressing BACK displays the previous - activity on the stack. However, the user cannot use the BACK key to go + to the activity stack, so that pressing <em>Back</em> displays the previous + activity on the stack. However, the user cannot use the <em>Back</em> button to go back further than the last visit to Home. The adding of an activity to the current stack happens whether or not that activity begins a new <a href=#tasks title=task>task</a> (as long as that task was started @@ -256,10 +294,11 @@ independent of the other Activities are the only things that can be added to the activity stack — views, windows, menus, and dialogs cannot. That is, when designing the navigation, if you have screen A and you want the user - to be able go to a subsequent screen B and then use the BACK key to go + to be able go to a subsequent screen B and then use the <em>Back</em> button to go back to screen A, then the screen A needs to be implemented as an activity. The one exception to this rule is if your application - <a href="#taking_over_back_key">takes control of the BACK key</a> and manages the navigation + <a href="#taking_over_back_key">takes control of the <em>Back</em> button</a> and manages the +navigation itself. </p> @@ -287,7 +326,7 @@ itself. launcher, Home screen shortcut or "Recent tasks" switcher (a long press on Home on some devices). The user can return to a task by choosing the icon for its root activity the same way they started the - task. Once inside a task, the BACK key goes to previous activities in + task. Once inside a task, the <em>Back</em> button goes to previous activities in that task. The activity stack is made up of one or more tasks. </p> @@ -331,7 +370,7 @@ itself. Browser are two applications that do this. For example, choosing an address in an email starts the Maps activity as a new task, and choosing a link in an email starts the Browser activity as a new - task. In these cases, the BACK key will return to the previous + task. In these cases, the <em>Back</em> button will return to the previous activity in a different task (Email), because it was not started from Home. </p> @@ -341,7 +380,7 @@ itself. <p> The following examples illustrate basic principles for applications, - activities, the activity stack, the BACK key, tasks and intents. It + activities, the activity stack, the <em>Back</em> button, tasks and intents. It shows how the system responds to user actions such as starting activities and switching between tasks. With most of these examples you can follow along, launching activities on your device as @@ -367,19 +406,20 @@ itself. <img src={@docRoot}images/activity_task_design/HomeTaskBasics1a.png> </p> -<h3 id=navigating_away_from_an_activity>Navigating Away from an Activity with BACK and HOME keys</h3> +<h3 id=navigating_away_from_an_activity>Navigating Away from an Activity with <em>Back</em> and +<em>Home</em> buttons</h3> <p> An activity can keep or lose its state depending on how the user - leaves the activity — by the HOME or BACK key. + leaves the activity — by the <em>Home</em> or <em>Back</em> button. </p> <p> - By default, pressing the BACK key finishes (destroys) the current + By default, pressing the <em>Back</em> button finishes (destroys) the current activity and displays the previous activity to the user. In the following figure, the user starts email by touching the Email icon in the Home screen, which displays a list of email messages. The user - scrolls down the list (changing its initial state). Pressing BACK + scrolls down the list (changing its initial state). Pressing <em>Back</em> destroys the List Messages activity and returns to the previous activity, which is Home. If the user re-launches Email, it would re-load the messages and display its initial, non-scrolled state. @@ -390,15 +430,15 @@ itself. </p> <p> - In the above example, pressing BACK goes to Home because it was the + In the above example, pressing <em>Back</em> goes to Home because it was the last activity the user was viewing. But if the user had gotten to List - Message from some other activity, then pressing BACK would have + Message from some other activity, then pressing <em>Back</em> would have returned there. </p> <p> By contrast, the next figure shows the user leaving List Messages by - pressing HOME instead of BACK — the List Messages activity is + pressing <em>Home</em> instead of <em>Back</em> — the List Messages activity is stopped and moved to the background rather than being destroyed. Starting Email again from its icon would simply bring the List Messages activity to the foreground (changing it from stopped to @@ -423,8 +463,8 @@ itself. <p> In addition, not all activities have the behavior that they are - destroyed when BACK is pressed. When the user starts playing music in - the Music application and then presses BACK, the application overrides + destroyed when <em>Back</em> is pressed. When the user starts playing music in + the Music application and then presses <em>Back</em>, the application overrides the normal back behavior, preventing the player activity from being destroyed, and continues playing music, even though its activity is no longer visible — as a visual substitute, the Music application @@ -451,7 +491,7 @@ itself. activity to get a picture. This is a good example of re-use of the Gallery activity. The following figure illustrates the sequence of activities to do this (up to crop). This is how it's done: The user - chooses Contacts, selects the contact for viewing, chooses MENU > + chooses Contacts, selects the contact for viewing, chooses <em>Menu</em> > Edit contact and touches the picture field, which launches the Gallery activity. The user then chooses the picture they want, crops and saves it. Saving it causes the picture to be inserted into the picture field @@ -484,12 +524,12 @@ itself. <b>Gallery Re-Uses Messaging for Sharing a Picture</b> - Sharing is another good example of one application re-using an activity from a different application. As shown in the following figure, the user - starts Gallery, picks a picture to view, chooses MENU > Share, and + starts Gallery, picks a picture to view, chooses <em>Menu</em> > Share, and picks "Messaging". This starts the Messaging activity, creates a new message and attaches the original picture to it. The user then fills in the "To" field, writes a short message and sends it. User focus remains in the Messaging program. If the user wants to go back to the - Gallery, they must press the BACK key. (The user can back up through + Gallery, they must press the <em>Back</em> button. (The user can back up through each activity all the way to Home.) </p> @@ -552,7 +592,7 @@ itself. <ul> <li> State 2 - The user wants to do something else while they're - waiting, so they press HOME, which does not interrupt the map's + waiting, so they press <em>Home</em>, which does not interrupt the map's network connection and allows the map to continue loading in the background. @@ -729,7 +769,7 @@ href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Fi <b>Start first task.</b> You want to send a text message and attach a photo. You would choose: <p> - Home > Messaging > New message > MENU > Attach + Home > Messaging > New message > <em>Menu</em> > Attach > Pictures. This last step launches the picture gallery for picking a photo. Notice that picture gallery is an activity in a separate application. @@ -883,7 +923,7 @@ href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Fi You can perform this test when initializing the user interface. For instance, you could disable the user control that initiates the Intent object, or display a message to the user that lets them go - to a location, such as the Market, to download its application. + to a location, such as Google Play, to download its application. In this way, your code can start the activity (using either startActivity() or startActivityForResult()) only if the intent has tested to resolve to an activity that is actually present. @@ -961,7 +1001,7 @@ MAIN and address in an email message (or web page), where the Maps activity is started to map the location. No result from maps is expected to be returned to the email message; the user - can return by pressing the BACK key. (Such an activity is + can return by pressing the <em>Back</em> button. (Such an activity is started with {@link android.content.Context#startActivity(android.content.Intent) startActivity()}.) @@ -1063,110 +1103,23 @@ MAIN and </p> -<h3 id="notifications_get_back_tip">Notifications should let the user easily get back to the previous activity</h3> +<h3 id="notifications_get_back_tip">Notifications and App Widgets should provide consistent back behavior</h3> <p> - Applications that are in the background or not running can have - services that send out notifications to the user letting them know about - events of interest. Two examples are Calendar, which can send out notifications of - upcoming events, and Email, which can send out notifications when new - messages arrive. One of the user interface guidelines is that when the - user is in activity A, gets a notification for activity B and - picks that notification, when they press the BACK key, they should - go back to activity A. + Notifications and app widgets are two common ways that a user can launch + your app through something besides its main icon in Launcher. You must + take care when implementing these so that the user has a consistent experience + with the back button, not causing surprises in where they return to or the + state the application ends up in. </p> <p> - The following scenario shows how the activity stack should work - when the user responds to a notification. -</p> - -<ol> - <li> - User is creating a new event in Calendar. They realize they - need to copy part of an email message into this event - </li> - <li> - The user chooses Home > Gmail - </li> - <li> - While in Gmail, they receive a notification from Calendar for an upcoming meeting - </li> - <li> - So they choose that notification, which takes them to a - dedicated Calendar activity that displays brief details of the - upcoming meeting - </li> - <li> - The user chooses this short notice to view further details - </li> - <li> - When done viewing the event, the user presses the BACK - key. They should be taken to Gmail, which is where they were - when they took the notification - </li> -</ol> - -<p> -This behavior doesn't necessarily happen by default. -</p> - -<p> -Notifications generally happen primarily in one of two ways: -</p> - - <ul> - <li> - <b>The chosen activity is dedicated for notification only</b> - - For example, when the user receives a - Calendar notification, choosing that - notification starts a special activity that displays a list - of upcoming calendar events — this view is available only - from the notification, not through the Calendar's own user - interface. After viewing this upcoming event, to ensure that - the user pressing the BACK key will return to the activity - the user was in when they picked the notification, you would - make sure this dedicated activity does not have the same - task affinity as the Calendar or any other activity. (You do - this by setting task affinity to the empty string, which - means it has no affinity to anything.) The explanation for - this follows. - - <p> - Because of the way tasks work, if the taskAffinity of the - dedicated activity is kept as its default, then pressing the - BACK key (in step 6, above) would go to Calendar, rather - than Gmail. The reason is that, by default, all activities - in a given application have the same task - affinity. Therefore, the task affinity of the dedicated - activity matches the Calendar task, which is already running - in step 1. This means in step 4, choosing the notification - brings the existing Calendar event (in step 1) forward and - starts the dedicated activity on top of it. This is not - what you want to have happen. Setting the dedicated - activity's taskAffinity to empty string fixes this. - </p> - </li> - - <li> - <b>The chosen activity is not dedicated, but always comes to - the foreground in its initial state</b> - For example, in - response to a notification, when the Gmail application comes - to the foreground, it always presents the list of conversations. - You can ensure this happens by setting a "clear top" flag in the - intent that the notification triggers. This ensures that when the - activity is launched, it displays its initial activity, preventing - Gmail from coming to the foreground in whatever state the user last - happened to be viewing it. (To do this, you put {@link - android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP - FLAG_ACTIVITY_CLEAR_TOP} in the intent you pass to startActivity()). - </li> - </ul> - -<p> - There are other ways to handle notifications, such as bringing the - activity to the foreground, set to display specific data, such as - displaying the text message thread for the person who just sent a - new text message. + The + <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#HandlingNotifications">Handling + Notifications</a> section of the developer guide's + <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a> + documentation provides an overview of how to write code to correctly handle + notification. This dicussion applies equally to handling interactions with + app widgets. </p> <p> @@ -1189,20 +1142,21 @@ Notifications generally happen primarily in one of two ways: convenience to respond to your message. </p> -<h3 id=taking_over_back_key>Don't take over the BACK key unless you absolutely need to</h3> +<h3 id=taking_over_back_key>Don't take over the <em>Back</em> button unless you absolutely need +to</h3> <p> As a user navigates from one activity to the next, the system adds them to the activity stack. This forms a navigation history that is - accessible with the BACK key. Most activities are relatively limited + accessible with the <em>Back</em> button. Most activities are relatively limited in scope, with just one set of data, such as viewing a list of contacts, composing an email, or taking a photo. But what if your application is one big activity with several pages of content and - needs finer-grained control of the BACK key? Examples of such Google + needs finer-grained control of the <em>Back</em> button? Examples of such Google applications are the Browser, which can have several web pages open at once, and Maps, which can have several layers of geographic data to switch between. Both of these applications take control of the - BACK key and maintain their own internal back stacks that operate + <em>Back</em> button and maintain their own internal back stacks that operate only when these applications have focus. </p> @@ -1211,7 +1165,7 @@ Notifications generally happen primarily in one of two ways: information on a map to the user: displaying the location of a search result, displaying locations of friends, and displaying a line for a street path providing direction between points. Maps - stores these layers in its own history so the BACK key can return to + stores these layers in its own history so the <em>Back</em> button can return to a previous layer. </p> @@ -1222,8 +1176,8 @@ Notifications generally happen primarily in one of two ways: as Windows, Macintosh or Linux). For example, if you did a Google web search in one window of the Android Browser, clicking on a link in the search results displays a web page in that same window, and - then pressing BACK would to the search results page. Pressing - BACK goes to a previous window only if the current window was + then pressing <em>Back</em> would to the search results page. Pressing + <em>Back</em> goes to a previous window only if the current window was launched from that previous window. If the user keeps pressing back, they will eventually leave the browser activity and return Home. diff --git a/docs/html/guide/practices/ui_guidelines/icon_design.jd b/docs/html/guide/practices/ui_guidelines/icon_design.jd index 07b73bb..1c66185 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design.jd @@ -42,8 +42,6 @@ Templates Pack, v4.0 »</a></li> Templates Pack, v2.3 »</a></li> <li><a href="{@docRoot}shareables/icon_templates-v2.0.zip">Android Icon Templates Pack, v2.0 »</a></li> -<li><a href="{@docRoot}shareables/icon_templates-v1.0.zip">Android Icon -Templates Pack, v1.0 »</a></li> </ol> <h2>See also</h2> @@ -57,6 +55,16 @@ Screens</a></li> </div> </div> + +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + + + <p>Creating a unified look and feel throughout a user interface adds value to your product. Streamlining the graphic style will also make the UI seem more professional to users.</p> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd b/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd index 449c27f..2476255 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd @@ -29,6 +29,12 @@ Screens</a></li> </div> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> <p>Action Bar icons are graphical elements placed in the <a diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd b/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd index f78bd86..9b8cce7 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd @@ -27,6 +27,12 @@ Screens</a></li> </div> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> <p>Dialog icons are shown in pop-up dialog boxes that prompt the user for diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd index 3f6061c..4b6768f 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd @@ -26,6 +26,15 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + + + <p>A launcher icon is a graphic that represents your application. Launcher icons are used by Launcher applications and appear on the user’s Home screen. Launcher icons can also be used to represent shortcuts into your application (for example, a contact shortcut icon that opens detail @@ -40,9 +49,9 @@ across the range of devices on which your application can be installed. See <a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#design-tips">Tips for Designers</a> for suggestions on how to work with multiple sets of icons.</p> -<p>A high-resolution version of your application launcher icon is also required by Android Market +<p>A high-resolution version of your application launcher icon is also required by Google Play for use in application listings. For more details on this, see <a -href="#icons_in_market">Application Icons in Android Market</a> below.</p> +href="#icons_in_market">Application Icons on Google Play</a> below.</p> <p class="note"><strong>Note:</strong> @@ -72,7 +81,7 @@ need to review the old guidelines, see the <ol> <li>Promote the brand and tell the story of the app.</li> - <li>Help users discover the app in Android Market.</li> + <li>Help users discover the app on Google Play.</li> <li>Function well in the Launcher.</li> </ol> @@ -91,19 +100,19 @@ app is about. Thus, you should:</p> </ul> -<h3 id="help_users_discover">Help users discover the app in Android Market</h3> +<h3 id="help_users_discover">Help users discover the app on Google Play</h3> -<p>App launcher icons are the first look that prospective users will get of your app in Android -Market. A high quality app icon can influence users to find out more as they scroll through lists of +<p>App launcher icons are the first look that prospective users will get of your app on Google Play. +A high quality app icon can influence users to find out more as they scroll through lists of applications.</p> <p>Quality matters here. A well-designed icon can be a strong signal that your app is of similarly high quality. Consider working with an icon designer to develop the app’s launcher icon.</p> -<p class="note"><strong>Note:</strong> Android Market requires a high-resolution version of your -icon; for more details on this, see <a href="#icons_in_market">Application Icons in Android -Market</a> below.</p> +<p class="note"><strong>Note:</strong> Google Play requires a high-resolution version of your +icon; for more details on this, see <a href="#icons_in_market">Application Icons in Google +Play</a> below.</p> <h3 id="function_well_in_launcher">Function well in the Launcher</h3> @@ -230,21 +239,21 @@ This padding can also be used to make room for a subtle drop shadow, which can h that launcher icons are legible across on any background color.</p> -<h3 id="icons_in_market">Application Icons in Android Market</h3> +<h3 id="icons_in_market">Application Icons on Google Play</h3> <p>If you are <a href="{@docRoot}guide/publishing/publishing.html">publishing your application on -Android Market</a>, you will also need to provide a 512 x 512 pixel, high-resolution application icon -in the <a href="http://market.android.com/publish">developer console</a> at upload time. This icon -will be used in various locations in Android Market and does not replace your launcher icon.</p> +Google Play</a>, you will also need to provide a 512 x 512 pixel, high-resolution application icon +in the <a href="http://play.google.com/apps/publish">developer console</a> at upload time. This icon +will be used in various locations on Google Play and does not replace your launcher icon.</p> <p>For tips and recommendations on creating high-resolution launcher icons that can easily be scaled up to 512x512, see <a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#design-tips"> Tips for Designers</a>.</p> -<p>For information and specifications about high-resolution application icons in Android Market, see +<p>For information and specifications about high-resolution application icons on Google Play, see the following article:</p> <p style="margin-left:2em"><a href="http://market.android.com/support/bin/answer.py?answer=1078870"> -Graphic Assets for your Application (Android Market Help) »</a> +Graphic Assets for your Application (Google Play Help) »</a> <br><br> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd index ea036cd..85a3cc8 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd @@ -56,13 +56,13 @@ suggestions on how to work with multiple sets of icons.</p> -<h2 id="market">Application Icons in Android Market</h2> +<h2 id="market">Application Icons on Google Play</h2> <p>If you are <a href="{@docRoot}guide/publishing/publishing.html">publishing -your application on Android Market</a>, you will also need to provide a 512x512 +your application on Google Play</a>, you will also need to provide a 512x512 pixel, high-resolution application icon in the <a -href="http://market.android.com/publish">developer console</a> at upload-time. -This icon will be used in various locations in Android Market and does +href="http://play.google.com/apps/publish">developer console</a> at upload-time. +This icon will be used in various locations on Google Play and does not replace your launcher icon.</p> <p>For tips and recommendations on creating high-resolution launcher icons that @@ -71,11 +71,11 @@ can easily be scaled up to 512x512, see Tips for Designers</a>.</p> <p>For information and specifications about high-resolution application -icons in Android Market, see the following article:</p> +icons on Google Play, see the following article:</p> <p style="margin-left:2em"><a href="http://market.android.com/support/bin/answer.py?answer=1078870"> - Graphic Assets for your Application (Android Market Help) »</a> + Graphic Assets for your Application (Google Play Help) »</a> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_list.jd b/docs/html/guide/practices/ui_guidelines/icon_design_list.jd index 7bf34cc..fd4dc6b 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_list.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_list.jd @@ -28,6 +28,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>List view icons look a lot like dialog icons, but they use an inner shadow effect where the light source is above the object. They are also designed to be diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd b/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd index 974e48f..e267013 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd @@ -32,6 +32,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>Menu icons are graphical elements placed in the options menu shown to users when they press the Menu button. They are drawn in a flat-front perspective and diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd b/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd index b8e07b5..a20c1ee 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd @@ -40,6 +40,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>Status bar icons are used to represent notifications from your application in the status bar.</p> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd b/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd index 271bd85..f85398d 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd @@ -32,6 +32,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>Tab icons are graphical elements used to represent individual tabs in a multi-tab interface. Each tab icon has two states: unselected and selected.</p> diff --git a/docs/html/guide/practices/ui_guidelines/index.jd b/docs/html/guide/practices/ui_guidelines/index.jd index 0e42788..24fb855 100644 --- a/docs/html/guide/practices/ui_guidelines/index.jd +++ b/docs/html/guide/practices/ui_guidelines/index.jd @@ -2,18 +2,28 @@ page.title=User Interface Guidelines @jd:body -<img src="{@docRoot}assets/images/uiguidelines1.png" alt="" align="right"> + +<div class="design-announce" style="background:none;overflow:auto;padding:10px 5px"> + <a href="{@docRoot}design/index.html"><img src="{@docRoot}images/home/android-design.png" alt="" +style="float:left;margin:0 1em 0 0;"/></a> +<p><strong>New Guides for App Designers!</strong></p> +<p>The Android UX team has put together a set of guidelines for the interaction and +visual design of Android applications. The new collection provides an overview of +Android styles, design patterns, building blocks for exceptional Android designs, and more.</p> +<p><strong><a href="{@docRoot}design/index.html">Android Design</a></strong></p> + +<p>Over time, the documents below will be deprecated as more design information is published at +the new location.</p> +</div> + -<p>The Android UI team has begun developing guidelines for the interaction and -visual design of Android applications. Look here for articles that describe -these guidelines as we release them.</p> <dl> <dt><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design Guidelines</a> and <a href="{@docRoot}shareables/icon_templates-v4.0.zip">Android Icon Templates Pack -» </a> <span class="new">updated</span></dt> +» </a></dt> <dd>Your applications need a wide variety of icons, from a launcher icon to icons in menus, dialogs, tabs, the status bar, and lists. The Icon Guidelines describe each kind of icon in detail, with specifications for the size, color, @@ -22,32 +32,13 @@ The Icon Templates Pack is an archive of Photoshop and Illustrator templates and filters that make it much simpler to create conforming icons.</dd> </dl> <dl> - <dt><a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">Widget Design Guidelines</a> <span class="new">updated</span></dt> + <dt><a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">Widget Design +Guidelines</a> </dt> <dd>A widget displays an application's most important or timely information at a glance, on a user's Home screen. These design guidelines describe how to design widgets that fit with others on the Home screen. They include links to graphics files and templates that will make your designer's life easier.</dd> </dl> - <dl> - <dt><a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html">Activity and Task Design Guidelines</a> </dt> - <dd>Activities are the basic, independent building blocks of applications. - As you design your application's UI and feature set, you are free to - re-use activities from other applications as if they were yours, - to enrich and extend your application. These guidelines - describe how activities work, illustrates them with examples, and - describes important underlying principles and mechanisms, such as - multitasking, activity reuse, intents, the activity stack, and - tasks. It covers this all from a high-level design perspective. -</dd> - <dt><a href="{@docRoot}guide/practices/ui_guidelines/menu_design.html">Menu Design Guidelines</a> </dt> - <dd>Android applications make use of Option menus and Context menus - that enable users to perform operations and navigate to other parts - of your application or to other applications. These guidelines describe - the difference between Options and Context menus, how to arrange - menu items, when to put commands on-screen, and other details about - menu design. -</dd> -</dl> diff --git a/docs/html/guide/practices/ui_guidelines/menu_design.jd b/docs/html/guide/practices/ui_guidelines/menu_design.jd index 3edf33f..b4e2ea7 100644 --- a/docs/html/guide/practices/ui_guidelines/menu_design.jd +++ b/docs/html/guide/practices/ui_guidelines/menu_design.jd @@ -2,7 +2,38 @@ page.title=Menu Design Guidelines parent.title=UI Guidelines parent.link=index.html @jd:body + + + + +<div id="deprecatedSticker"> + <a href="#" + onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> + <strong>This doc is deprecated</strong></a> +</div> + + +<div id="naMessage" style="display:block"> +<div><p><strong>This document has been deprecated.</strong></p> + <p>For design guidelines about adding user actions and other options, read the design guidelines +for <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> or the developer guide about +<a href="{@docRoot}guide/topics/ui/menus.html">Menus</a>.</p> + + <input style="margin-top:1em;padding:5px" type="button" + value="That's nice, but I still want to read this document" +onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> +</div> +</div> + + + + + + + + + <div id="qv-wrapper"> <div id="qv"> @@ -71,7 +102,7 @@ parent.link=index.html <ul> <li>The <em>Options menu</em> contains primary functionality that applies globally to the current activity or starts a related activity. - It is typically invoked by a user pressing a hard button, often labeled MENU.</li> + It is typically invoked by a user pressing a hard button, often labeled <em>Menu</em>.</li> <li>The <em>Context menu</em> contains secondary functionality for the currently selected item. It is typically invoked by a user's touch & hold on an item. Like on the Options menu, the operation can run either @@ -109,10 +140,10 @@ or device to another. </p> <p> - On most devices, a user presses the MENU button to access the Options menu, + On most devices, a user presses the <em>Menu</em> button to access the Options menu, as shown in the screenshot below. To close the menu, the user presses - MENU again, or presses the BACK button. - In fact, to cancel out of any menu, press the BACK button. (Pressing the MENU + <em>Menu</em> again, or presses the <em>Back</em> button. + In fact, to cancel out of any menu, press the <em>Back</em> button. (Pressing the <em>Menu</em> button or touching outside the menu also works.) Note that how to invoke this menu may be different on different devices. </p> @@ -140,7 +171,7 @@ or device to another. <ul> <li> - <b>Options icon menu</b> - The first press of the MENU button displays a + <b>Options icon menu</b> - The first press of the <em>Menu</em> button displays a non-scrollable grid of icons at the bottom of the screen. (On the G1 phone, up to 6 buttons typically appear.) </li> @@ -156,7 +187,7 @@ or device to another. <p> On some versions of Android, the user can display keyboard shortcuts in the - icon menu by long pressing the MENU button — the text in the icon menu + icon menu by long pressing the <em>Menu</em> button — the text in the icon menu alternates between the command names and their keyboard shortcuts (if any). </p> @@ -299,7 +330,7 @@ or device to another. <a href="#location">location</a>) on the screen, put the command in the Context menu for that content. If the command acts on no specific content or location, put it in the Options menu. This separation of commands - is enforced by the system in the following way. When you press the MENU + is enforced by the system in the following way. When you press the <em>Menu</em> button to display the Options menu, the selected content becomes unselected, and so cannot be operated on. For an explanation of why the content becomes unselected, see the article on @@ -340,7 +371,7 @@ or device to another. <p> Before opening a Context menu, it has no visual representation that identifies - its presence (whereas the Options menu has the MENU button), and so is not + its presence (whereas the Options menu has the <em>Menu</em> button), and so is not particularly discoverable. Therefore, in general, a Context menu should <em>duplicate</em> commands found in the corresponding activity screen. For example, while it's useful to @@ -459,7 +490,8 @@ or device to another. <h3 id="a_dialog_should_not_have_an_options_menu">A dialog should not have an Options menu</h3> <p> - When a dialog is displayed, pressing the MENU button should do nothing. This also holds true + When a dialog is displayed, pressing the <em>Menu</em> button should do nothing. This also holds +true for activities that look like dialogs. A dialog box is recognizable by being smaller than full-screen, having zero to three buttons, is non-scrollable, and possibly a list of selectable items that can include checkboxes or radio buttons. @@ -475,7 +507,7 @@ or device to another. <h3 id="do_not_substitute_message">If an activity has no Options menu, do not display a message</h3> <p> - When the user presses the MENU button, if there is no Options menu, the system + When the user presses the <em>Menu</em> button, if there is no Options menu, the system currently does nothing. We recommend you do not perform any action (such as displaying a message). It's a better user experience for this behavior to be consistent across applications. diff --git a/docs/html/guide/practices/ui_guidelines/widget_design.jd b/docs/html/guide/practices/ui_guidelines/widget_design.jd index f63f3c4..d789407 100644 --- a/docs/html/guide/practices/ui_guidelines/widget_design.jd +++ b/docs/html/guide/practices/ui_guidelines/widget_design.jd @@ -44,6 +44,13 @@ parent.link=index.html </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>.</p> +</div> + + <p>App widgets (sometimes just "widgets") are a feature introduced in Android 1.5 and vastly improved in Android 3.0 and 3.1. A widget can display an application's most timely or otherwise relevant information at a glance, on a user's Home screen. The standard Android system image diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd index 9abcdf7..5bd9be55 100644 --- a/docs/html/guide/publishing/app-signing.jd +++ b/docs/html/guide/publishing/app-signing.jd @@ -66,7 +66,7 @@ on an emulator or a device if it is not signed.</li> application's signer certificate expires after the application is installed, the application will continue to function normally.</li> <li>You can use standard tools — Keytool and Jarsigner — to generate keys and -sign your application .apk files.</li> +sign your application {@code .apk} files.</li> <li>After you sign your application for release, we recommend that you use the <code>zipalign</code> tool to optimize the final APK package.</li> </ul> @@ -82,7 +82,7 @@ run it or debug it on an emulator or device.</p> use to build your application. There are two build modes: <em>debug mode</em> and <em>release mode</em>. You use debug mode when you are developing and testing your application. You use release mode when you want to build a release version of your application that you can -distribute directly to users or publish on an application marketplace such as Android Market.</p> +distribute directly to users or publish on an application marketplace such as Google Play.</p> <p>When you build in <em>debug mode</em> the Android SDK build tools use the Keytool utility (included in the JDK) to create a debug key. Because the SDK build tools created the debug key, @@ -158,10 +158,10 @@ you should ensure that your key's validity period exceeds the expected lifespan of <em>all versions of all of the applications</em>, including dependent applications that may be added to the suite in the future. </li> -<li>If you plan to publish your application(s) on Android Market, the +<li>If you plan to publish your application(s) on Google Play, the key you use to sign the application(s) must have a validity period -ending after 22 October 2033. The Market server enforces this requirement -to ensure that users can seamlessly upgrade Market applications when +ending after 22 October 2033. Google Play enforces this requirement +to ensure that users can seamlessly upgrade applications when new versions are available. </li> </ul> @@ -186,9 +186,9 @@ to the Keytool in the JDK.</p> <p>The Android build tools provide a debug signing mode that makes it easier for you to develop and debug your application, while still meeting the Android system -requirement for signing your .apk. +requirement for signing your APK. When using debug mode to build your app, the SDK tools invoke Keytool to automatically create -a debug keystore and key. This debug key is then used to automatically sign the .apk, so +a debug keystore and key. This debug key is then used to automatically sign the APK, so you do not need to sign the package with your own key.</p> <p>The SDK tools create the debug keystore/key with predetermined names/passwords:</p> @@ -215,19 +215,19 @@ to the public when signed with the debug certificate.</p> <p>If you are developing in Eclipse/ADT (and have set up Keytool and Jarsigner as described above in <a href="#setup">Basic Setup for Signing</a>), signing in debug mode is enabled by default. When you run or debug your -application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the -package, then installs it on +application, ADT signs the {@code .apk} file with the debug certificate, runs {@code zipalign} on +the package, then installs it on the selected emulator or connected device. No specific action on your part is needed, provided ADT has access to Keytool.</p> <h3>Ant Users</h3> -<p>If you are using Ant to build your .apk files, debug signing mode +<p>If you are using Ant to build your {@code .apk} file, debug signing mode is enabled by using the <code>debug</code> option with the <code>ant</code> command (assuming that you are using a <code>build.xml</code> file generated by the <code>android</code> tool). When you run <code>ant debug</code> to -compile your app, the build script generates a keystore/key and signs the .apk for you. -The script then also aligns the .apk with the <code>zipalign</code> tool. +compile your app, the build script generates a keystore/key and signs the APK for you. +The script then also aligns the APK with the <code>zipalign</code> tool. No other action on your part is needed. Read <a href="{@docRoot}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps on the Command Line</a> for more information.</p> @@ -292,7 +292,7 @@ key is one that:</p> with the application</li> <li>Has a validity period that exceeds the expected lifespan of the application or application suite. A validity period of more than 25 years is recommended. -<p>If you plan to publish your application(s) on Android Market, note that a +<p>If you plan to publish your application(s) on Google Play, note that a validity period ending after 22 October 2033 is a requirement. You can not upload an application if it is signed with a key whose validity expires before that date. </p></li> @@ -383,8 +383,8 @@ will use later, to refer to this keystore when signing your application. </p> <p>For more information about Keytool, see the documentation at <a -href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> -http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> +href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html"> +http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html</a></p> @@ -399,11 +399,11 @@ You can not release your application unsigned, or signed with the debug key.</p> <h4>With Eclipse</h4> -<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package +<p>To export an <em>unsigned</em> APK from Eclipse, right-click the project in the Package Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application -Package</strong>. Then specify the file location for the unsigned .apk. -(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open -the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p> +Package</strong>. Then specify the file location for the unsigned APK. +(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, select +the <strong>Manifest</strong> tab, and click <strong>Export an unsigned APK</strong>.)</p> <p>Note that you can combine the compiling and signing steps with the Export Wizard. See <a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> @@ -414,11 +414,11 @@ the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)< with the <code>ant</code> command. For example, if you are running Ant from the directory containing your {@code build.xml} file, the command would look like this:</p> -<pre>ant release</pre> +<pre>$ ant release</pre> -<p>By default, the build script compiles the application .apk without signing it. The output file +<p>By default, the build script compiles the application APK without signing it. The output file in your project {@code bin/} will be <code><em><your_project_name></em>-unsigned.apk</code>. -Because the application .apk is still unsigned, you must manually sign it with your private +Because the application APK is still unsigned, you must manually sign it with your private key and then align it using {@code zipalign}.</p> <p>However, the Ant build script can also perform the signing @@ -443,8 +443,8 @@ machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that the keystore containing your private key is available.</p> <p>To sign your application, you run Jarsigner, referencing both the -application's .apk and the keystore containing the private key with which to -sign the .apk. The table below shows the options you could use. </p> +application's APK and the keystore containing the private key with which to +sign the APK. The table below shows the options you could use. </p> <table> <tr> @@ -459,6 +459,14 @@ the keystore containing your private key.</td> <td><code>-verbose</code></td><td>Enable verbose output.</td> </tr> <tr> +<td><code>-sigalg</code></td><td>The name of the signature algorithim to use in signing the APK. +Use the value {@code MD5withRSA}.</td> +</tr> +<tr> +<td><code>-digestalg</code></td><td>The message digest algorithim to use in processing the entries +of an APK. Use the value {@code SHA1}.</td> +</tr> +<tr> <td><code>-storepass <password></code></td><td><p>The password for the keystore. </p><p>As a security precaution, do not include this option in your command line unless you are working at a secure computer. @@ -478,19 +486,23 @@ way, your password is not stored in your shell history.</p></td> <code>my_application.apk</code>, using the example keystore created above. </p> -<pre>$ jarsigner -verbose -keystore my-release-key.keystore +<pre>$ jarsigner -verbose -sigalg MD5withRSA -digestalg SHA1 -keystore my-release-key.keystore my_application.apk alias_name</pre> <p>Running the example command above, Jarsigner prompts you to provide -passwords for the keystore and key. It then modifies the .apk -in-place, meaning the .apk is now signed. Note that you can sign an -.apk multiple times with different keys.</p> +passwords for the keystore and key. It then modifies the APK +in-place, meaning the APK is now signed. Note that you can sign an +APK multiple times with different keys.</p> + +<p class="caution"><strong>Caution:</strong> As of JDK 7, the default signing algorithim has +changed, requiring you to specify the signature and digest algorithims ({@code -sigalg} and {@code +-digestalg}) when you sign an APK.</p> -<p>To verify that your .apk is signed, you can use a command like this:</p> +<p>To verify that your APK is signed, you can use a command like this:</p> <pre>$ jarsigner -verify my_signed.apk</pre> -<p>If the .apk is signed properly, Jarsigner prints "jar verified". +<p>If the APK is signed properly, Jarsigner prints "jar verified". If you want more details, you can try one of these commands:</p> <pre>$ jarsigner -verify -verbose my_application.apk</pre> @@ -502,19 +514,19 @@ If you want more details, you can try one of these commands:</p> <p>The command above, with the <code>-certs</code> option added, will show you the "CN=" line that describes who created the key.</p> -<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the .apk was +<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the APK was signed with the debug key generated by the Android SDK. If you intend to release your application, you must sign it with your private key instead of the debug key.</p> <p>For more information about Jarsigner, see the documentation at -<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> -http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> +<a href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html"> +http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html</a></p> <h3 id="align">4. Align the final APK package</h3> -<p>Once you have signed the .apk with your private key, run <code>zipalign</code> on the file. +<p>Once you have signed the APK with your private key, run <code>zipalign</code> on the file. This tool ensures that all uncompressed data starts with a particular byte alignment, relative to the start of the file. Ensuring alignment at 4-byte boundaries provides a performance optimization when installed on a device. When aligned, the Android @@ -524,16 +536,16 @@ of the data from the package. The benefit is a reduction in the amount of RAM consumed by the running application.</p> <p>The <code>zipalign</code> tool is provided with the Android SDK, inside the -<code>tools/</code> directory. To align your signed .apk, execute:</p> +<code>tools/</code> directory. To align your signed APK, execute:</p> -<pre>zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> +<pre>$ zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> <p>The {@code -v} flag turns on verbose output (optional). {@code 4} is the byte-alignment (don't use anything other than 4). The first file argument is -your signed .apk (the input) and the second file is the destination .apk file (the output). -If you're overriding an existing .apk, add the {@code -f} flag.</p> +your signed {@code .apk} file (the input) and the second file is the destination {@code .apk} file +(the output). If you're overriding an existing APK, add the {@code -f} flag.</p> -<p class="caution"><strong>Caution:</strong> Your input .apk must be signed with your +<p class="caution"><strong>Caution:</strong> Your input APK must be signed with your private key <strong>before</strong> you optimize the package with {@code zipalign}. If you sign it after using {@code zipalign}, it will undo the alignment.</p> @@ -544,7 +556,7 @@ If you sign it after using {@code zipalign}, it will undo the alignment.</p> <h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3> <p>If you are using Eclipse with the ADT plugin, you can use the Export Wizard to -export a <em>signed</em> .apk (and even create a new keystore, +export a <em>signed</em> APK (and even create a new keystore, if necessary). The Export Wizard performs all the interaction with the Keytool and Jarsigner for you, which allows you to sign the package using a GUI instead of performing the manual procedures to compile, sign, @@ -554,7 +566,7 @@ Because the Export Wizard uses both Keytool and Jarsigner, you should ensure that they are accessible on your computer, as described above in the <a href="#setup">Basic Setup for Signing</a>.</p> -<p>To create a signed and aligned .apk in Eclipse:</p> +<p>To create a signed and aligned APK in Eclipse:</p> <ol> <li>Select the project in the Package @@ -563,7 +575,7 @@ Explorer and select <strong>File > Export</strong>.</li> and click <strong>Next</strong>. <p>The Export Android Application wizard now starts, which will guide you through the process of signing your application, - including steps for selecting the private key with which to sign the .apk + including steps for selecting the private key with which to sign the APK (or creating a new keystore and private key).</p> <li>Complete the Export Wizard and your application will be compiled, signed, aligned, and ready for distribution.</li> diff --git a/docs/html/guide/publishing/licensing.html b/docs/html/guide/publishing/licensing.html new file mode 100644 index 0000000..8e97f32 --- /dev/null +++ b/docs/html/guide/publishing/licensing.html @@ -0,0 +1,11 @@ +<html> +<head> +<meta http-equiv="refresh" +content="0;url=http://developer.android.com/guide/market/licensing/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should have been redirected. Please <a +href="http://developer.android.com/guide/market/licensing/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/publishing/licensing.jd b/docs/html/guide/publishing/licensing.jd deleted file mode 100644 index 609241b..0000000 --- a/docs/html/guide/publishing/licensing.jd +++ /dev/null @@ -1,2388 +0,0 @@ -page.title=Application Licensing -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Quickview</h2> - <ul> - <li>Licensing lets you protect your application on any device that includes Android Market.</li> - <li>Your app maintains control of how it enforces its licensing status. </li> - <li>Adding licensing to an app is straightforward, using the library available through the SDK.</li> - <li>The service is free and is available to all developers who publish on Android Market. </li> - </ul> - - <h2>In this document</h2> - <ol> - <li><a href="#account">Setting Up A Publisher Account</a></li> - <li><a href="#dev-setup">Setting Up the Development Environment</a></li> - <li><a href="#app-integration">Integrating the LVL with Your Application</a> - <ol> - <li><a href="#add-library">Including the LVL</a></li> - <li><a href="#manifest-permission">Adding the licensing permission</a></li> - <li><a href="#impl-Policy">Implementing a Policy</a></li> - <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a></li> - <li><a href="#impl-lc">Checking the license</a></li> - <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a></li> - </ol></li> - <li><a href="#test-env">Setting Up the Test Environment</a> - <ol> - <li><a href="#test-response">Test responses</a></li> - <li><a href="#test-acct-setup">Test accounts</a></li> - <li><a href="#acct-signin">Signing in on a device or emulator</a></li> - </ol></li> - <li><a href="#app-obfuscation">Obfuscating Your Application</a></li> - <li><a href="#app-publishing">Publishing a Licensed Application</a></li> - <li><a href="#support">Where to Get Support</a></li> - </ol> - - <h2>Appendix</h2> - <ol> - <li><a href="#lvl-summary">Summary of LVL Classes and Interfaces</a></li> - <li><a href="#server-response-codes">Server Response Codes</a></li> - <li><a href="#extras">Server Response Extras</a></li> - </ol> - -</div> -</div> - -<p>Android Market offers a licensing service that lets you enforce licensing -policies for paid applications that you publish through Android Market. With -Android Market Licensing, your applications can query Android Market at run time to -obtain their licensing status for the current user, then allow or disallow -further use as appropriate. </p> - -<p>Using the service, you can apply a flexible licensing policy on an -application-by-application basis — each application can enforce licensing -in the way most appropriate for it. If necessary, an application can apply custom -constraints based on the licensing status obtained from Android Market. -For example, an application can check the licensing status and then apply custom -constraints that allow the user to run it unlicensed for a specific number -of times, or for a specific validity period. An application can also restrict use of the -application to a specific device, in addition to any other constraints. </p> - -<p>The licensing service is a secure means of controlling access to your -applications. When an application checks the licensing status, the Market server -signs the licensing status response using a key pair that is uniquely associated -with the publisher account. Your application stores the public key in its -compiled <code>.apk</code> file and uses it to verify the licensing status -response.</p> - -<p>Any application that you publish through Android Market can use the Android -Market Licensing service. No special account or registration is needed. -Additionally, because the service uses no dedicated framework APIs, you can add -licensing to any legacy application that uses a minimum API level of 3 or -higher.</p> - -<p>To help you add licensing to your application, the Android SDK provides -library sources that you can include in your application project. The -License Verification Library (LVL) handles all of -the licensing-related communication with the Android Market client and the -licensing service. With the LVL integrated, your application can determine its -licensing status for the current user by simply calling a library checker method -and implementing a callback that receives the status.</p> - -<p>This document explains how the licensing service works and how to add it to -your application. </p> - - -<h2 id="overview">Overview</h2> - -<p>Android Market Licensing is a network-based service that lets an application -on an Android-powered device query a trusted licensing server, to determine -whether the application is licensed to the current device user. After receiving -the server response, the application can then allow or disallow further use of -the application as needed. In the service, the role of the licensing server is -to provide the license status for the current user; the application itself is -responsible for querying the server and conditionally granting access to the -application. </p> - -<h4>Application, Android Market client, and server</h4> - -<p>The licensing service is based on the capability of the Android Market server -to determine whether a given user is licensed to use a given application. The licensing server -considers a user to be licensed if the user is a recorded purchaser of an application. If a paid -application has been uploaded to Android Market but saved only as a draft application (in -other words, the app is unpublished), the licensing server considers all users to be licensed users -of the application. Keep in mind, you cannot implement Android Market Licensing in a free -application.</p> - -<p>To properly identify -the user and determine the license status, the server requires information about -the application and user — the application and the Android Market client -work together to assemble the information and pass it to the server. </p> - -<p>In the licensing service, an application does not query the licensing server -directly, but instead calls the Android Market client over remote IPC to -initiate a license request. In the license request:</p> - -<ul> -<li>The application provides its package name and a nonce that is later used to -validate any response from the server, as well as a callback over which the -response can be returned asynchronously.</li> -<li>The Android Market client, which has greater permissions than the -application, collects the necessary information about the user and the device, -such as the device's primary Google account username, IMSI, and other -information. It then sends the license check request to the server on behalf of -the application.</li> -<li>The server evaluates the request using all available information, attempting -to establish the user's identity to a sufficient level of confidence. The server -then checks the user identity against purchase records for the application and -returns a license response, which the Android Market client returns to the -application over the IPC callback.</li> -</ul> - -<p>Notice that during a license check, the application does not manage any -network connections or use any licensing related APIs in the Android platform. -</p> - -<div class="figure" style="width:469px"> -<img src="{@docRoot}images/licensing_arch.png" alt=""/> -<p class="img-caption"><strong>Figure 1.</strong> Your application initiates a -license check through the LVL and the Android Market -client, which handles communication with the Market server.</p> -</div> - -<h4>License responses secured through public key cryptography</h4> - -<p>To ensure the integrity of each license query, the server signs the license -response data using an RSA key pair that is shared exclusively between the -server and the application publisher.</p> - -<p>The licensing service generates a single licensing key pair for each -publisher account and exposes the public key in the account's profile page. The -publisher copies the public key and embeds it in the application source code, -then compiles and publishes the <code>.apk.</code> The server retains the -private key internally and uses it to sign license responses for applications -published on that account. </p> - -<p>When the application receives a signed response, it uses the embedded public -key to verify the data. The use of public key cryptography in the licensing -service makes it possible for the application to detect responses that have been -tampered with or that are spoofed.</p> - -<h4>Use of licensing in your application</h4> - -<p>To use licensing in your application, add code to the application to -initiate a license check request and handle the response when it is received. -You can choose when, and how often, you want your application to check its -license and you have full control over how it handles the response, verifies the -signed response data, and enforces access controls. </p> - -<p>To simplify the process of adding support for licensing, download and -integrate the Licensing Verification Library, described below. Integration is -straightforward.</p> - -<p>When you are finished integrating the LVL, use a test environment -provided by the publisher site to test your application's handling of server -responses. </p> - -<p>Finally, publish the application <code>.apk</code> on Market using the -normal process. If you previously used the copy-protection provided by Android -Market, you can remove it from applications that use licensing. </p> - -<h4>Licensing Verification Library simplifies implementation</h4> - -<p>The Android SDK includes a License Verification Library (LVL) that you can -download and use as the basis for your application's licensing implementation. -The LVL greatly simplifies the process of adding licensing to your application -and helps ensure a more secure, robust implementation for your application. The -LVL provides internal classes that handle most of the standard operations of a -license query, such as contacting Android Market to initiate a license request -and verifying and validating the responses. It also exposes key interfaces that -let you easily plug in your custom code for defining licensing policy and -managing access as needed by your application. The key LVL interfaces are: </p> - -<ul> -<li>Policy — your implementation determines whether to allow access to the -application, based on the license response received from the server and any -other data available (such as from a backend server associated with your -application). The implementation can evaluate the various fields of the license -response and apply other constraints, if needed. The implementation also lets -you manage the handling of license checks that result in errors, such as network -errors.</li> -<li>LicenseCheckerCallback — your implementation manages access to the -application, based on the result of the Policy's handling of the license -response. Your implementation can manage access in any way needed, including -displaying the license result in the UI or directing the user to purchase the -application (if not currently licensed). </li> -</ul> - -<p>To help you get started with a Policy, the LVL provides two fully complete -Policy implementations that you can use without modification or adapt to your -needs:</p> - -<ul> -<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a> is a flexible Policy -that uses settings provided by the licensing server to manage response caching -and access to the application while the device is offline (such as when the -user is on an airplane). For most applications, the use of -ServerManagedPolicy is highly recommended. </li> -<li><a href="#StrictPolicy">StrictPolicy</a> is a restrictive Policy that -does not cache any response data and allows the application access <em>only</em> -when the server returns a licensed response.</li> -</ul> - -<p>The LVL is available as a downloadable component of the Android SDK. The -component includes both the LVL itself and an example application that shows how -the library should be integrated with your application and how your application -should manage response data, UI interaction, and error conditions. </p> - -<p>The LVL sources are provided as an Android <em>library project</em>, which -means that you can maintain a single set of library sources and share them -across multiple applications. A full test environment is also available through -the SDK, so you can develop and test the licensing implementation in your -applications before publishing them, even if you don't have access to a -physical device.</p> - -<h4>Requirements and limitations</h4> - -<p>Android Market Licensing is designed to let you apply license controls to -applications that you publish through Android Market. The service is not -designed to let you control access to applications that are not published -through Android Market or that are run on devices that do not offer the Android -Market client. </p> - -<p>Here are some points to keep in mind as you implement licensing in your -application: </p> - -<ul> -<li>Only paid applications published through Market can use the -service.</li> -<li>An application can use the service only if the Android Market client is -installed on its host device and the device is running Android 1.5 (API level 3) -or higher.</li> -<li>To complete a license check, the licensing server must be accessible over -the network. You can implement license caching behaviors to manage access when -there is no network connectivity. </li> -<li>The security of your application's licensing controls ultimately relies on -the design of your implementation itself. The service provides the building -blocks that let you securely check licensing, but the actual enforcement and -handling of the license are factors in your control. By following the best -practices in this document, you can help ensure that your implementation will be -secure.</li> -<li>Adding licensing to an application does not affect the way the application -functions when run on a device that does not offer Android Market.</li> -<li>Licensing is currently for paid apps only, since draft apps are -licensed for all users. If your application is already published as a free app, -you won't be able to upload a new version that uses licensing.</li> -</ul> - -<h4>Replacement for Copy Protection</h4> - -<p>Android Market Licensing is a flexible, secure mechanism for controlling -access to your applications. It effectively replaces the Copy Protection -mechanism offered on Android Market and gives you wider distribution -potential for your applications. </p> - -<ul> -<li>A limitation of the legacy Copy Protection mechanism on Android Market is -that applications using it can be installed only on compatible devices that -provide a secure internal storage environment. For example, a copy-protected -application cannot be downloaded from Market to a device that provides root -access, and the application cannot be installed to a device's SD card. </li> -<li>With Android Market licensing, you can move to a license-based model in -which access is not bound to the characteristics of the host device, but to your -publisher account on Android Market and the licensing policy that you define. -Your application can be installed and controlled on any compatible device on -any storage, including SD card.</li> -</ul> - -<p>Although no license mechanism can completely prevent all unauthorized use, -the licensing service lets you control access for most types of normal usage, -across all compatible devices, locked or unlocked, that run Android 1.5 or -higher version of the platform.</p> - -<p>The sections below describe how to add Android Market licensing to your -applications. </p> - -<h2 id="account">Setting Up a Publisher Account</h2> - -<p>Android Market licensing lets you manage access to applications that -users have downloaded from Android Market. To use licensing in an application, -you need to have a publisher account on Android Market so that you can -publish the application to users. </p> - -<p>If you don't already have a publisher account, you need to register for one -using your Google account and agree to the terms of service. Once you are -registered, you can upload applications at your convenience and begin debugging -and testing your licensing implementation. For more information about publishing -on Android Market, see <a -href="{@docRoot}guide/publishing/publishing.html">Publishing Your -Applications</a></p> - -<p>To register as an Android Market developer and set up your publisher account, -visit the Android Market publisher site:</p> - -<p style="margin-left:2em;"><a -href="http://market.android.com/publish">http://market.android.com/publish</a> -</p> - -<p>If you already have a publisher account on Android Market, use your existing -account to set up licensing. You <em>do not</em> need to register for a new -account to support licensing (and doing so is not recommended, especially if you -are adding licensing support to applications that you have already published). -In all cases, if you have published applications, you manage licensing for those -applications through the account on which the applications are published. </p> - -<p>Once your publisher account is set up, use the account to:</p> - -<ul> -<li>Obtain a public key for licensing</li> -<li>Debug and test an application's licensing implementation, prior to -publishing the application</li> -<li>Publish the applications to which you have added licensing support</li> -</ul> - -<h4>Administrative settings for licensing</h4> - -<p>Once you are signed into your publisher account, you can manage several -administrative controls for Android Market licensing. The controls are available -in the Edit Profile page, in the "Licensing" panel, shown below. The controls -let you: </p> - -<ul> -<li>Set up multiple "test accounts", identified by email address. The licensing -server allows users signed into test accounts on a device or emulator to send -license checks and receive static test responses.</li> -<li>Obtain the account's public key for licensing. When you are implementing -licensing in an application, you must copy the public key string into the -application.</li> -<li>Configure static test responses that the server sends, when it receives a -license check for an application uploaded to the publisher account, from a user -signed in to the publisher account or a test account.</li> -</ul> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_public_key.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 2.</strong> The Licensing -panel of your account's Edit Profile page lets you manage administrative -settings for licensing.</div> -</div> - -<p>For more information about how to work with test accounts and static test -responses, see <a href="#test-env">Setting Up a Testing Environment</a>, below. - -<h2 id="dev-setup">Setting Up the Development Environment</h2> - -<p>Once you've set up your publisher account on Android Market, the next step is -to set up your development environment for licensing. </p> - -<p>Setting up your environment for licensing involves these tasks:</p> - -<ol> -<li><a href="#download-sdk">Downloading the latest SDK</a>, if you haven't already done so </li> -<li><a href="#runtime-setup">Setting up the runtime environment</a> for development</li> -<li><a href="#download-lvl">Downloading the Market Licensing component</a> into your SDK </li> -<li><a href="#lvl-setup">Setting up the Licensing Verification Library</a></li> -<li><a href="#add-library">Including the LVL library project in your application</a></li> -</ol> - -<p>The sections below describe these tasks. When you are done with setup, -you can begin <a href="#app-integration">integrating the LVL into your applications</a>.</p> - -<p>To get started, you need to set up a proper runtime environment on which -you can run, debug and test your application's implementation of license -checking and enforcement. </p> - - -<h3 id="download-sdk">Downloading the latest SDK</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Licensing sample application</h2> - -<p>To work with Android Market licensing, you need a functioning Android -application to which you can add licensing support. </p> - -<p style="margin-top:.5em;">If you are new to Android -and don't yet have a functioning application, the LVL component includes a sample -application that you can set up as a new application project. The sample provides -a complete, working example of how licensing works. For more information, see <a -href="#download-lvl">Downloading the LVL</a>.</p> - -</div> -</div> - -<p>If you haven't done so, you need to download the Android SDK before you can -develop Android applications. The SDK provides the tools that you need to build -and debug Android applications, including applications that use Android Market -licensing. For complete information, including installation instructions, see -the <a href="{@docRoot}sdk/index.html">Android SDK</a>. </p> - -<p>If you have already installed the SDK, make sure to update the -SDK tools and ADT Plugin to the latest versions. You can update the SDK tools -using the Android SDK and AVD Manager and ADT through <strong>Help</strong> > -<strong>Software Updates...</strong> in Eclipse. </p> - -<p>After you've installed the latest SDK and tools, set up your development -environment as described below. </p> - - -<h3 id="runtime-setup">Setting up the runtime environment</h3> - -<p>As described earlier, applications check licensing status not by contacting -the licensing server directly, but by binding to a service provided by the -Android Market application and initiating a license check request. The Android -Market service then handles the direct communication with the licensing server -and finally routes the response back to your application. To debug and test -licensing in your application, you need to set up a runtime environment that -includes the necessary Android Market service, so that your application is able -to send license check requests to the licensing server. </p> - -<p>There are two types of runtime environment that you can use: </p> - -<ul> -<li>An Android-powered device that includes the Android Market application, or</li> -<li>An Android emulator running the Google APIs Add-on, API level 8 (release 2) -or higher</li> -</ul> - -<p>The sections below provide more information. </p> - -<h4 id="runtime-device">Running on a device</h4> - -<p>You can use an Android-powered device as the runtime environment for -debugging and testing licensing on your application.</p> - -<p>The device you use must:</p> - -<ul> -<li>Run a standard version of the Android 1.5 or later (API level -3 or higher) platform, <em>and</em> </li> -<li>Run a system image on which the Android Market client application -is preinstalled. </li> -</ul> - -<p>If Android Market is not preinstalled in the system image, your application won't -be able to communicate with the Android Market licensing server. </p> - -<p>For general information about how to set up a device for use in developing -Android applications, see <a -href="{@docRoot}guide/developing/device.html">Developing on a Device</a>.</p> - -<h4 id="runtime-emulator">Running on an Android emulator</h4> - -<p>You can also use an Android emulator as your runtime -environment for debugging and testing licensing.</p> - -<p>Because the standard Android platforms provided in the Android SDK <em>do -not</em> include Android Market, you need to download the Google APIs Add-On -platform, API Level 8 (or higher), from the SDK repository. After downloading -the add-on, you need to create an AVD configuration that uses that system image. -</p> - -<p>The Google APIs Add-On does not include the full Android Market client. -However, it does provide: </p> - -<ul> -<li>An Android Market background service that implements the -ILicensingService remote interface, so that your application can -send license checks over the network to the licensing server. </li> -<li>A set of underlying account services that let you add an a Google account on -the AVD and sign in using your publisher account or test account credentials. -Signing in using your publisher or test account enables you to debug and test -your application without having publish it. For more information see <a -href="#acct-signin">Signing in to an authorized account</a>, below.</li> -</ul> - -<p>Several versions of the add-on are available in the SDK repository, but only -<strong>Google APIs Add-On, API 8 (release 2) or higher</strong> version of the -add-on includes the necessary Android Market services. This means that you -cannot use Google APIs Add-On API 7 or lower as a runtime environment for -developing licensing on an emulator.</p> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_gapis_8.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 3.</strong> Google APIs -Add-On, API 8 (release 2) or higher lets you debug and test your licensing -implementation in an emulator.</div> -</div> - -<p>To set up an emulator for adding licensing to an application, follow -these steps: </p> - -<ol> - <li>Launch the Android SDK and AVD Manager. </li> - <li>In the <strong>Available Packages</strong> panel, select and download the -SDK component "Google APIs (Google Inc.) - API Level 8" (or higher) from the SDK -repository, as shown in the figure above. - <p>When the download is complete, use the Android SDK and AVD Manager to -create a new AVD based on that component, described next.</p></li> - <li>In the <strong>Virtual -Devices</strong> panel of the Android SDK and AVD Manager, click -<strong>New</strong> and set the configuration details for the new AVD. </li> - <li>In the dialog that appears, assign a descriptive name to the AVD and then -use the "Target" menu to choose the "Google APIs (Google Inc.) - API Level 8" as -the system image to run on the new AVD. Set the other configuration details as -needed and then click <strong>Create AVD</strong> to finish. The SDK tools -create the new AVD configuration, which then appears in the list of available -Android Virtual Devices.</li> -</ol> - -<p>If you are not familiar with AVDs or how to use them, see <a -href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> - -<h4 id="project-update">Updating your project configuration</h4> - -<p>After you set up a runtime environment that meets the requirements described -above — either on an actual device or on an emulator — make sure to -update your application project or build scripts as needed, so that your compiled -<code>.apk</code> files that use licensing are deployed into that environment. -In particular, if you are developing in Eclipse, make sure that you set up a -Run/Debug Configuration that targets the appropriate device or AVD. </p> - -<p>You do not need to make any changes to your application's -build configuration, provided that the project is already configured to compile -against a standard Android 1.5 (API level 3) or higher library. For example: - -<ul> -<li>If you have an existing application that is compiled against -the Android 1.5 library, you do not need to make any changes to your -build configuration to support licensing. The build target meets the minimum -requirements for licensing, so you would continue building -against the same version of the Android platform.</li> - -<li>Similarly, if you are building against Android 1.5 (API level 3) but -are using an emulator running the Google APIs Add-On API 8 as the application's -runtime environment, there is no need to change your application's build -configuration. </li> -</ul> - -<p>In general, adding licensing to an application should have no impact -whatsoever on the application's build configuration.</p> - - -<h3 id="download-lvl">Downloading the LVL</h3> - -<p>The License Verification Library (LVL) is a collection of helper classes that -greatly simplify the work that you need to do to add licensing to your -application. In all cases, we recommend that you download the LVL and use it as -the basis for the licensing implementation in your application.</p> - -<p>The LVL is available as a downloadable component of the Android SDK. The -component includes: </p> - -<ul> -<li>The LVL sources, stored inside an Android library project. </li> -<li>An example application called "sample" that depends on the LVL library -project. The example illustrates how an application uses the library helper -classes to check and enforce licensing.</li> -</ul> - -<p>To download the LVL component into your development environment, use the -Android SDK and AVD Manager. Launch the Android SDK and AVD Manager and then -select the "Market Licensing" component, as shown in the figure below. -Accept the terms and click <strong>Install Selected</strong> to begin the download. </p> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_package.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 4.</strong> The Market -Licensing package contains the LVL and the LVL sample application. </div> -</div> - -<p>When the download is complete, the Android SDK and AVD Manager installs both -the LVL library project and the example application into these directories: </p> - -<p style="margin-left:2em"><code><<em>sdk</em>>/extras/google/market_licensing/library/</code> - (the LVL library project)<br /> -<code><<em>sdk</em>>/extras/google/market_licensing/sample/</code> (the example -application)</p> - -<p>If you aren't familiar with how to download components into your SDK, see the -<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> -document. </p> - - -<h3 id="lvl-setup">Setting Up the Licensing Verification Library</h3> - -<p>After downloading the LVL to your computer, you need to set it up in your -development environment, either as an Android library project or by -copying (or importing) the library sources directly into your existing -application package. In general, using the LVL as a library project is recommended, -since it lets you reuse your licensing code across multiple applications and -maintain it more easily over time. Note that the LVL is not designed to be -compiled separately and added to an application as a static .jar file. </p> - -<h4>Moving the library sources to a new location</h4> - -<p>Because you will be customizing the LVL sources to some extent, you should -make sure to <em>move or copy</em> the library sources (the entire -directory at <code><<em>sdk</em>>/market_licensing/library/</code>) -to a working directory outside of the SDK. You should then use the relocated -sources as your working set. If you are using a source-code management -system, add and track the sources that are in the working location rather -than those in default location in the SDK. </p> - -<p>Moving the library sources is important is because, when you later update the -Market licensing package, the SDK installs the new files to the same location as -the older files. Moving your working library files to a safe location ensures -that your work won't be inadvertently overwritten should you download a new -version of the LVL.</p> - -<h4>Creating the LVL as a library project</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Working with library projects</h2> - -<p>The LVL is provided as an Android library project, which means that you can -share its code and resources across multiple applications. </p> - -<p style="margin-top:.5em;">If you aren't familiar with library projects or how -to use them, see <a href="{@docRoot}guide/developing/projects/index.html#LibraryProjects"> -Managing Projects</a>. -</p> -</div> -</div> - -<p>The recommended way of using the LVL is setting it up as a new Android -<em>library project</em>. A library project is a type of development project -that holds shared Android source code and resources. Other Android application -projects can reference the library project and, at build time, include its -compiled sources in their <code>.apk</code> files. In the context of licensing, -this means that you can do most of your licensing development once, in a library -project, then include the library sources in your various application projects. -In this way, you can easily maintain a uniform implementation of licensing -across all of your projects and maintain it centrally. </p> - -<p>The LVL is provided as a configured library project — once you have -downloaded it, you can start using it right away. </p> - -<p>If you are working in Eclipse with ADT, you need to add the LVL to your -workspace as a new development project, in the same way as you would a new -application project. </p> - -<ol> -<li>Use the New Project Wizard to create a new -project from existing sources. Select the LVL's <code>library</code> directory -(the directory containing the library's AndroidManifest.xml file) as the project -root.</li> -<li>When you are creating the library project, you can select any application -name, package, and set other fields as needed. </li> -<li>For the library's build target, select Android 1.5 (API level 3) or higher.</li> -</ol> - -<p> When created, the project is -predefined as a library project in its <code>project.properties</code> file, so -no further configuration is needed. </p> - -<p>For more information about how to create an application project or work with -library projects in Eclipse, see <a -href="{@docRoot}guide/developing/projects/projects-eclipse.html">Managing Projects from -Eclipse with ADT</a></p>. - -<h4>Copying the LVL sources to your application</h4> - -<p>As an alternative to adding the LVL as a library project, you can copy the -library sources directly into your application. To do so, copy (or import) the -LVL's <code>library/src/com</code> directory into your application's -<code>src/</code> directory.</p> - -<p>If you add the LVL sources directly to your application, you can skip the -next section and start working with the library, as described in <a -href="#app-integration"></a>.</p> - - -<h3 id="add-library">Including the LVL library project sources in your -application</h3> - -<p>If you want to use the LVL sources as a library project, you need to add a -reference to the LVL library project in your application project properties. This tells -build tools to include the LVL library project sources in your application at -compile time. The process for adding a reference to a library project depends -on your development environment, as described below.</p> - -<p> If you are developing in Eclipse with ADT, you should already have added the -library project to your workspace, as described in the previous section. If you -haven't done that already, do it now before continuing. </p> - -<p>Next, open the application's project properties window, as shown below. -Select the "Android" properties group and click <strong>Add</strong>, then -choose the LVL library project (com_android_vending_licensing) and click -<strong>OK</strong>. For more information, see -<a href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject"> -Managing Projects from Eclipse with ADT</a></p>. - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_add_library.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 5.</strong> If you are -working in Eclipse with ADT, you can add the LVL library project to your -application from the application's project properties.</div> -</div> - -<p>If you are developing using the SDK command-line tools, navigate to the -directory containing your application project and open the -<code>project.properties</code> file. Add a line to the file that specifies the -<code>android.library.reference.<n></code> key and the path to the -library. For example: </p> - -<pre>android.library.reference.1=path/to/library_project</pre> - -<p>Alternatively, you can use this command to update the project -properties, including the reference to the library project:</p> - -<pre class="no-pretty-print" style="color:black">android update lib-project ---target <em><target_ID></em> \ ---path <em>path/to/my/app_project</em> \ ---library <em>path/to/my/library_project</em> -</pre> - -<p>For more information about working with library projects, -see <a href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject"> -Managing Projects from the Command Line</a></p>. - - -<h2 id="app-integration">Integrating the LVL with Your Application</h2> - -<p>Once you've followed the steps above to set up a publisher account and -development environment, you are ready to begin integrating the LVL with your -application. </p> - -<p>Integrating the LVL with your application code involves these tasks:</p> - -<ol> -<li><a href="#manifest-permission">Adding the licensing permission</a> your application's manifest.</li> -<li><a href="#impl-Policy">Implementing a Policy</a> — you can choose one of the full implementations provided in the LVL or create your own.</li> -<li><a href="#impl-Obfuscator">Implementing an Obfuscator</a>, if your Policy will cache any license response data. </li> -<li><a href="#impl-lc">Adding code to check the license</a> in your application's main Activity</li> -<li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a> (optional and not recommended for most applications)</li> -</ol> - -<p>The sections below describe these tasks. When you are done with the -integration, you should be able to compile your application successfully and you -can begin testing, as described in <a href="#test-env">Setting Up the Test -Environment</a>.</p> - -<p>For an overview of the full set of source files included in the LVL, see <a -href="#lvl-summary">Summary of LVL Classes and Interfaces</a>.</p> - - -<h3 id="manifest-permission">Adding the licensing permission to your -AndroidManifest.xml</h3> - -<p>To use the Android Market application for sending a license check to the -server, your application must request the proper permission, -<code>com.android.vending.CHECK_LICENSE</code>. If your application does -not declare the licensing permission but attempts to initiate a license check, -the LVL throws a security exception.</p> - -<p>To request the licensing permission in your application, declare a <a -href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a> -element as a child of <code><manifest></code>, as follows: </p> - -<p style="margin-left:2em;"><code><uses-permission -android:name="com.android.vending.CHECK_LICENSE"></code></p> - -<p>For example, here's how the LVL sample application declares the permission: -</p> - -<pre><?xml version="1.0" encoding="utf-8"?> - -<manifest xmlns:android="http://schemas.android.com/apk/res/android" ..."> - <!-- Devices >= 3 have version of Android Market that supports licensing. --> - <uses-sdk android:minSdkVersion="3" /> - <!-- Required permission to check licensing. --> - <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> - ... -</manifest> -</pre> - -<p class="note"><strong>Note:</strong> Currently, you cannot declare the -<code>CHECK_LICENSE</code> permission in the LVL library project's manifest, -because the SDK Tools will not merge it into the manifests of dependent -applications. Instead, you must declare the permission in each dependent -application's manifest. </p> - - -<h3 id="impl-Policy">Implementing a Policy</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>ServerManagedPolicy</h2> - -<p>The LVL includes a complete Policy implementation called ServerManagedPolicy -that makes use of license-management settings provided by the Android Market -server. </p> - -<p style="margin-top:.5em;">Use of ServerManagedPolicy as the basis for your -Policy is strongly recommended. For more information, see <a -href="#ServerManagedPolicy">ServerManagedPolicy</a> section, below.</p> - -</div> -</div> - -<p>Android Market licensing service does not itself determine whether a -given user with a given license should be granted access to your application. -Rather, that responsibility is left to a Policy implementation that you provide -in your application.</p> - -<p>Policy is an interface declared by the LVL that is designed to hold your -application's logic for allowing or disallowing user access, based on the result -of a license check. To use the LVL, your application <em>must</em> provide an -implementation of Policy. </p> - -<p>The Policy interface declares two methods, <code>allowAccess()</code> and -<code>processServerResponse()</code>, which are called by a LicenseChecker -instance when processing a response from the license server. It also declares an -enum called <code>LicenseResponse</code>, which specifies the license response -value passed in calls to <code>processServerResponse()</code>. </p> - -<ul> -<li><code>processServerResponse()</code> lets you preprocess the raw response -data received from the licensing server, prior to determining whether to grant -access. - -<p>A typical implementation would extract some or all fields from the license -response and store the data locally to a persistent store, such as through -{@link android.content.SharedPreferences} storage, to ensure that the data is -accessible across application invocations and device power cycles. For example, -a Policy would maintain the timestamp of last successful license check, the -retry count, the license validity period, and similar information in a -persistent store, rather than resetting the values each time the application is -launched.</p> - -<p>When storing response data locally, the Policy must ensure that the data is -obfuscated (see <a href="#impl-Obfuscator">Implementing an Obfuscator</a>, -below).</p></li> - -<li><code>allowAccess()</code> determines whether to grant the user access to -your application, based on any available license response data (from the -licensing server or from cache) or other application-specific information. For -example, your implementation of <code>allowAccess()</code> could take into -account additional criteria, such as usage or other data retrieved from a -backend server. In all cases, an implementation of <code>allowAccess()</code> -should only return <code>true</code> if the user is licensed to use the -application, as determined by the licensing server, or if there is a transient -network or system problem that prevents the license check from completing. In -such cases, your implementation can maintain a count of retry responses and -provisionally allow access until the next license check is complete.</li> - -</ul> - -<p>To simplify the process of adding licensing to your application and to -provide an illustration of how a Policy should be designed, the LVL includes -two full Policy implementations that you can use without modification or -adapt to your needs:</p> - -<ul> -<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible Policy -that uses server-provided settings and cached responses to manage access across -varied network conditions, and</li> -<li><a href="#StrictPolicy">StrictPolicy</a>, which does not cache any response -data and allows access <em>only</em> if the server returns a licensed -response.</li> -</ul> - -<p>For most applications, the use of ServerManagedPolicy is highly -recommended. ServerManagedPolicy is the LVL default and is integrated with -the LVL sample application.</p> - - -<h4 id="custom-policies">Guidelines for custom policies</h4> - -<p>In your licensing implementation, you can use one of the complete policies -provided in the LVL (ServerManagedPolicy or StrictPolicy) or you can create a -custom policy. For any type of custom policy, there are several important design -points to understand and account for in your implementation.</p> - -<p>The licensing server applies general request limits to guard against overuse -of resources that could result in denial of service. When an application exceeds -the request limit, the licensing server returns a 503 response, which gets -passed through to your application as a general server error. This means that no -license response will be available to the user until the limit is reset, which -can affect the user for an indefinite period.</p> - -<p>If you are designing a custom policy, we recommend that the Policy: -<ol> -<!-- <li>Limits the number of points at which your app calls for a license check -to the minimum. </li> --> -<li>Caches (and properly obfuscates) the most recent successful license response -in local persistent storage.</li> -<li>Returns the cached response for all license checks, for as long as the -cached response is valid, rather than making a request to the licensing server. -Setting the response validity according to the server-provided <code>VT</code> -extra is highly recommended. See <a href="#extras">Server Response Extras</a> -for more information.</li> -<li>Uses an exponential backoff period, if retrying any requests the result in -errors. Note that the Android Market client automatically retries failed -requests, so in most cases there is no need for your Policy to retry them.</li> -<li>Provides for a "grace period" that allows the user to access your -application for a limited time or number of uses, while a license check is being -retried. The grace period benefits the user by allowing access until the next -license check can be completed successfully and it benefits you by placing a -hard limit on access to your application when there is no valid license response -available.</li> -</ol> - -<p>Designing your Policy according to the guidelines listed above is critical, -because it ensures the best possible experience for users while giving you -effective control over your application even in error conditions. </p> - -<p>Note that any Policy can use settings provided by the licensing server to -help manage validity and caching, retry grace period, and more. Extracting the -server-provided settings is straightforward and making use of them is highly -recommended. See the ServerManagedPolicy implementation for an example of how to -extract and use the extras. For a list of server settings and information about -how to use them, see <a href="#extras">Server Response Extras</a> in the -Appendix of this document.</p> - -<h4 id="ServerManagedPolicy">ServerManagedPolicy</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Server Response Extras</h2> - -<p>For certain types of licensing responses, the licensing server appends extra -settings to the responses, to help the application manage licensing effectively. -</p> - -<p style="margin-top:.5em;">See <a href="#extras">Server Response Extras</a> for -a list of settings and <code>ServerManagedPolicy.java</code> for information -about how a Policy can use the extras.</p> - -</div> -</div> - -<p>The LVL includes a full and recommended implementation of the Policy -interface called ServerManagedPolicy. The implementation is integrated with the -LVL classes and serves as the default Policy in the library. </p> - -<p>ServerManagedPolicy provides all of the handling for license and retry -responses. It caches all of the response data locally in a -{@link android.content.SharedPreferences} file, obfuscating it with the -application's Obfuscator implementation. This ensures that the license response -data is secure and persists across device power cycles. ServerManagedPolicy -provides concrete implementations of the interface methods -<code>processServerResponse()</code> and <code>allowAccess()</code> and also -includes a set of supporting methods and types for managing license -responses.</p> - -<p>Importantly, a key feature of ServerMangedPolicy is its use of -server-provided settings as the basis for managing licensing across an -application's refund period and through varying network and error conditions. -When an application contacts the Android Market server for a license check, the -server appends several settings as key-value pairs in the extras field of certain -license response types. For example, the server provides recommended values for the -application's license validity period, retry grace period, and maximum allowable -retry count, among others. ServerManagedPolicy extracts the values from the -license response in its <code>processServerResponse()</code> method and checks -them in its <code>allowAccess()</code> method. For a list of the server-provided -settings used by ServerManagedPolicy, see <a href="#extras">Server Response -Extras</a> in the Appendix of this document.</p> - -<p>For convenience, best performance, and the benefit of using license settings -from the Android Market server, <strong>using ServerManagedPolicy as your -licensing Policy is strongly recommended</strong>. </p> - -<p>If you are concerned about the security of license response data that is -stored locally in SharedPreferences, you can use a stronger obfuscation -algorithm or design a stricter Policy that does not store license data. The LVL -includes an example of such a Policy — see <a -href="#StrictPolicy">StrictPolicy</a> for more information.</p> - -<p>To use ServerManagedPolicy, simply import it to your Activity, create an -instance, and pass a reference to the instance when constructing your -LicenseChecker. See <a href="#lc-lcc">Instantiate LicenseChecker and -LicenseCheckerCallback</a> for more information. </p> - -<h4 id="StrictPolicy">StrictPolicy</h4> - -<p>The LVL includes an alternative full implementation of the Policy interface -called StrictPolicy. The StrictPolicy implementation provides a more restrictive -Policy than ServerManagedPolicy, in that it does not allow the user to access -the application unless a license response is received from the server at the -time of access that indicates that the user is licensed.</p> - -<p>The principal feature of StrictPolicy is that it does not store <em>any</em> -license response data locally, in a persistent store. Because no data is stored, -retry requests are not tracked and cached responses can not be used to fulfill -license checks. The Policy allows access only if:</p> - -<ul> -<li>The license response is received from the licensing server, and </li> -<li>The license response indicates that the user is licensed to access the -application. </li> -</ul> - -<p>Using StrictPolicy is appropriate if your primary concern is to ensure that, -in all possible cases, no user will be allowed to access the application unless -the user is confirmed to be licensed at the time of use. Additionally, the -Policy offers slightly more security than ServerManagedPolicy — since -there is no data cached locally, there is no way a malicious user could tamper -with the cached data and obtain access to the application.</p> - -<p>At the same time, this Policy presents a challenge for normal users, since it -means that they won't be able to access the application when there is no network -(cell or wi-fi) connection available. Another side-effect is that your -application will send more license check requests to the server, since using a -cached response is not possible.</p> - -<p>Overall, this policy represents a tradeoff of some degree of user convenience -for absolute security and control over access. Consider the tradeoff carefully -before using this Policy.</p> - -<p>To use StrictPolicy, simply import it to your Activity, create an instance, -and pass a reference to it when constructing your LicenseChecker. See -<a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a> -for more information. </p> - -<h3 id="impl-Obfuscator">Implementing an Obfuscator</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>AESObfuscator</h2> - -<p>The LVL includes a full Obfuscator implementation in the -<code>AESObfuscator.java</code> file. The Obfuscator uses AES encryption to -obfuscate/unobfuscate data. If you are using a Policy (such as -ServerManagedPolicy) that caches license response data, using AESObfuscator as -basis for your Obfuscator implementation is highly recommended. </p> - -</div> -</div> - -<p>A typical Policy implementation needs to save the license response data for -an application to a persistent store, so that it is accessible across -application invocations and device power cycles. For example, a Policy would -maintain the timestamp of the last successful license check, the retry count, -the license validity period, and similar information in a persistent store, -rather than resetting the values each time the application is launched. The -default Policy included in the LVL, ServerManagedPolicy, stores license response -data in a {@link android.content.SharedPreferences} instance, to ensure that the -data is persistent. </p> - -<p>Because the Policy will use stored license response data to determine whether -to allow or disallow access to the application, it <em>must</em> ensure that any -stored data is secure and cannot be reused or manipulated by a root user on a -device. Specifically, the Policy must always obfuscate the data before storing -it, using a key that is unique for the application and device. Obfuscating using -a key that is both application-specific and device-specific is critical, because -it prevents the obfuscated data from being shared among applications and -devices.</p> - -<p>The LVL assists the application with storing its license response data in a -secure, persistent manner. First, it provides an Obfuscator -interface that lets your application supply the obfuscation algorithm of its -choice for stored data. Building on that, the LVL provides the helper class -PreferenceObfuscator, which handles most of the work of calling the -application's Obfuscator class and reading and writing the obfuscated data in a -SharedPreferences instance. </p> - -<p>The LVL provides a full Obfuscator implementation called -AESObfuscator that uses AES encryption to obfuscate data. You can -use AESObfuscator in your application without modification or you -can adapt it to your needs. For more information, see the next section.</p> - - -<h4 id="AESObfuscator">AESObfuscator</h4> - -<p>The LVL includes a full and recommended implementation of the Obfuscator -interface called AESObfuscator. The implementation is integrated with the -LVL sample application and serves as the default Obfuscator in the library. </p> - -<p>AESObfuscator provides secure obfuscation of data by using AES to -encrypt and decrypt the data as it is written to or read from storage. -The Obfuscator seeds the encryption using three data fields provided -by the application: </p> - -<ol> -<li>A salt — an array of random bytes to use for each (un)obfuscation. </li> -<li>An application identifier string, typically the package name of the application.</li> -<li>A device identifier string, derived from as many device-specific sources -as possible, so as to make it as unique.</li> -</ol> - -<p>To use AESObfuscator, first import it to your Activity. Declare a private -static final array to hold the salt bytes and initialize it to 20 randomly -generated bytes.</p> - -<pre> ... - // Generate 20 random bytes, and put them here. - private static final byte[] SALT = new byte[] { - -46, 65, 30, -128, -103, -57, 74, -64, 51, 88, -95, - -45, 77, -117, -36, -113, -11, 32, -64, 89 - }; - ... -</pre> - -<p>Next, declare a variable to hold a device identifier and generate a value for -it in any way needed. For example, the sample application included in the LVL -queries the system settings for the -<code>android.Settings.Secure.ANDROID_ID</code>, which is unique to each device. -</p> - -<p>Note that, depending on the APIs you use, your application might need to -request additional permissions in order to acquire device-specific information. -For example, to query the {@link android.telephony.TelephonyManager} to obtain -the device IMEI or related data, the application will also need to request the -<code>android.permission.READ_PHONE_STATE</code> permission in its manifest.</p> - -<p>Before requesting new permissions for the <em>sole purpose</em> of acquiring -device-specific information for use in your Obfuscator, consider -how doing so might affect your application or its filtering on Android Market -(since some permissions can cause the SDK build tools to add -the associated <code><uses-feature></code>).</p> - -<p>Finally, construct an instance of AESObfuscator, passing the salt, -application identifier, and device identifier. You can construct the instance -directly, while constructing your Policy and LicenseChecker. For example:</p> - -<pre> ... - // Construct the LicenseChecker with a Policy. - mChecker = new LicenseChecker( - this, new ServerManagedPolicy(this, - new AESObfuscator(SALT, getPackageName(), deviceId)), - BASE64_PUBLIC_KEY // Your public licensing key. - ); - ... -</pre> - -<p>For a complete example, see MainActivity in the LVL sample application.</p> - - -<h3 id="impl-lc">Checking the license from your application's main Activity</h3> - -<p>Once you've implemented a Policy for managing access to your application, the -next step is to add a license check to your application, which initiates a query -to the licensing server if needed and manages access to the application based on -the license response. All of the work of adding the license check and handling -the response takes place in your main {@link android.app.Activity} source file. -</p> - -<p>To add the license check and handle the response, you must:</p> - -<ol> - <li><a href="#imports">Add imports</a></li> - <li><a href="#lc-impl">Implement LicenseCheckerCallback</a> as a private inner class</li> - <li><a href="#thread-handler">Create a Handler</a> for posting from LicenseCheckerCallback to the UI thread</li> - <li><a href="#lc-lcc">Instantiate LicenseChecker</a> and LicenseCheckerCallback</li> - <li><a href="#check-access">Call checkAccess()</a> to initiate the license check</li> - <li><a href="#account-key">Embed your public key</a> for licensing</li> - <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method</a> to close IPC connections.</li> -</ol> - -<p>The sections below describe these tasks. </p> - -<h4 id="lc-overview">Overview of license check and response</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Example: MainActivity</h2> - -<p>The sample application included with the LVL provides a full example of how -to initiate a license check and handle the result, in the -<code>MainActivity.java</code> file.</p> - -</div> -</div> - -<p>In most cases, you should add the license check to your application's main -{@link android.app.Activity}, in the <code>onCreate()</code> method. This -ensures that when the user launches your application directly, the license check -will be invoked immediately. In some cases, you can add license checks in other -locations as well. For example, if your application includes multiple Activity -components that other applications can start by {@link android.content.Intent}, -you could add license checks in those Activities.</p> - -<p>A license check consists of two main actions: </p> - -<ul> -<li>A call to a method to initiate the license check — in the LVL, this is -a call to the <code>checkAccess()</code> method of a LicenseChecker object that -you construct.</li> -<li>A callback that returns the result of the license check. In the LVL, this is -a <code>LicenseCheckerCallback</code> interface that you implement. The -interface declares two methods, <code>allow()</code> and -<code>dontAllow()</code>, which are invoked by the library based on to the -result of the license check. You implement those two methods with whatever logic -you need, to allow or disallow the user access to your application. Note that -these methods do not determine <em>whether</em> to allow access — that -determination is the responsibility of your Policy implementation. Rather, these -methods simply provide the application behaviors for <em>how</em> to allow and -disallow access (and handle application errors).</li> -</ul> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_flow.png" style="text-align:left;margin-bottom:0;margin-left:3em;" /> -<div style="margin:.5em 0 1.5em 2em;padding:0"><strong>Figure 6.</strong> Overview of a -typical license check interaction.</div> -</div> - -<p>The diagram above illustrates how a typical license check takes place: </p> - -<ol> -<li>Code in the application's main Activity instantiates LicenseCheckerCallback -and LicenseChecker objects. When constructing LicenseChecker, the code passes in -{@link android.content.Context}, a Policy implementation to use, and the -publisher account's public key for licensing as parameters. </li> -<li>The code then calls the <code>checkAccess()</code> method on the -LicenseChecker object. The method implementation calls the Policy to determine -whether there is a valid license response cached locally, in -{@link android.content.SharedPreferences}. -<ul> -<li>If so, the <code>checkAccess()</code> implementation calls -<code>allow()</code>.</li> -<li>Otherwise, the LicenseChecker initiates a license check request that is sent -to the licensing server.</li> -</ul> -<p class="note"><strong>Note:</strong> The licensing server always returns -<code>LICENSED</code> when you perform a license check of a draft application.</p> -</li> -<li>When a response is received, LicenseChecker creates a LicenseValidator that -verifies the signed license data and extracts the fields of the response, then -passes them to your Policy for further evaluation. - <ul> - <li>If the license is valid, the Policy caches the response in -SharedPreferences and notifies the validator, which then calls the -<code>allow()</code> method on the LicenseCheckerCallback object. </li> - <li>If the license not valid, the Policy notifies the validator, which calls -the <code>dontAllow()</code> method on LicenseCheckerCallback. </li> - </ul> -</li> -<li>In case of a recoverable local or server error, such as when the network is -not available to send the request, LicenseChecker passes a RETRY response to -your Policy's <code>processServerResponse()</code> method. </li> -<li>In case of a application error, such as when the application attempts to -check the license of an invalid package name, LicenseChecker passes an error -response to the LicenseCheckerCallback's <code>applicationError()</code> -method. </li> -</ol> - -<p>Note that, in addition to initiating the license check and handling the -result, which are described in the sections below, your application also needs -to provide a <a href="#impl-Policy">Policy implementation</a> and, if the Policy -stores response data (such as ServerManagedPolicy), an <a -href="#impl-Obfuscator">Obfuscator</a> implementation. </p> - - -<h4 id="imports">Add imports</h4> - -<p>First, open the class file of the application's main Activity and import -LicenseChecker and LicenseCheckerCallback from the LVL package.</p> - -<pre> import com.android.vending.licensing.LicenseChecker; - import com.android.vending.licensing.LicenseCheckerCallback;</pre> - -<p>If you are using the default Policy implementation provided with the LVL, -ServerManagedPolicy, import it also, together with the AESObfuscator. If you are -using a custom Policy or Obfuscator, import those instead. </p> - -<pre> import com.android.vending.licensing.ServerManagedPolicy; - import com.android.vending.licensing.AESObfuscator;</pre> - -<h4 id="lc-impl">Implement LicenseCheckerCallback as a private inner class</h4> - -<p>LicenseCheckerCallback is an interface provided by the LVL for handling -result of a license check. To support licensing using the LVL, you must -implement LicenseCheckerCallback and -its methods to allow or disallow access to the application.</p> - -<p>The result of a license check is always a call to one of the -LicenseCheckerCallback methods, made based on the validation of the response -payload, the server response code itself, and any additional processing provided -by your Policy. Your application can implement the methods in any way needed. In -general, it's best to keep the methods simple, limiting them to managing UI -state and application access. If you want to add further processing of license -responses, such as by contacting a backend server or applying custom constraints, -you should consider incorporating that code into your Policy, rather than -putting it in the LicenseCheckerCallback methods. </p> - -<p>In most cases, you should declare your implementation of -LicenseCheckerCallback as a private class inside your application's main -Activity class. </p> - -<p>Implement the <code>allow()</code> and <code>dontAllow()</code> methods as -needed. To start with, you can use simple result-handling behaviors in the -methods, such as displaying the license result in a dialog. This helps you get -your application running sooner and can assist with debugging. Later, after you -have determined the exact behaviors you want, you can add more complex handling. -</p> - -<p>Some suggestions for handling unlicensed responses in -<code>dontAllow()</code> include: </p> - -<ul> -<li>Display a "Try again" dialog to the user, including a button to initiate a -new license check. </li> -<li>Display a "Purchase this application" dialog, including a button that -deep-links the user to the application's details page on Market, from which the -use can purchase the application. For more information on how to set up such -links, see <a -href="{@docRoot}guide/publishing/publishing.html#marketintent">Using Intents to -Launch the Market Application on a Device</a>. </li> -<li>Display a Toast notification that indicates that the features of the -application are limited because it is not licensed. </li> -</ul> - -<p>The example below shows how the LVL sample application implements -LicenseCheckerCallback, with methods that display the license check result in a -dialog. </p> - -<pre> private class MyLicenseCheckerCallback implements LicenseCheckerCallback { - public void allow() { - if (isFinishing()) { - // Don't update UI if Activity is finishing. - return; - } - // Should allow user access. - displayResult(getString(R.string.allow)); - } - - public void dontAllow() { - if (isFinishing()) { - // Don't update UI if Activity is finishing. - return; - } - displayResult(getString(R.string.dont_allow)); - // Should not allow access. An app can handle as needed, - // typically by informing the user that the app is not licensed - // and then shutting down the app or limiting the user to a - // restricted set of features. - // In this example, we show a dialog that takes the user to Market. - showDialog(0); - } - } -</pre> - -<p>Additionally, you should implement the <code>applicationError()</code> -method, which the LVL calls to let your application handle errors that are not -retryable. For a list of such errors, see <a -href="#server-response-codes">Server Response Codes</a> in the Appendix of this -document. You can implement the method in any way needed. In most cases, the -method should log the error code and call <code>dontAllow()</code>.</p> - -<h4 id="thread-handler">Create a Handler for posting from LicenseCheckerCallback -to the UI thread</h4> - -<p>During a license check, the LVL passes the request to the Android Market -application, which handles communication with the licensing server. The LVL -passes the request over asynchronous IPC (using {@link android.os.Binder}) so -the actual processing and network communication do not take place on a thread -managed by your application. Similarly, when the Android Market application -receives the result, it invokes a callback method over IPC, which in turn -executes in an IPC thread pool in your application's process.</p> - -<p>The LicenseChecker class manages your application's IPC communication with -the Android Market application, including the call that sends the request and -the callback that receives the response. LicenseChecker also tracks open license -requests and manages their timeouts. </p> - -<p>So that it can handle timeouts properly and also process incoming responses -without affecting your application's UI thread, LicenseChecker spawns a -background thread at instantiation. In the thread it does all processing of -license check results, whether the result is a response received from the server -or a timeout error. At the conclusion of processing, the LVL calls your -LicenseCheckerCallback methods from the background thread. </p> - -<p>To your application, this means that:</p> - -<ol> -<li>Your LicenseCheckerCallback methods will be invoked, in many cases, from a -background thread.</li> -<li>Those methods won't be able to update state or invoke any processing in the -UI thread, unless you create a Handler in the UI thread and have your callback -methods post to the Handler.</li> -</ol> - -<p>If you want your LicenseCheckerCallback methods to update the UI thread, -instantiate a {@link android.os.Handler} in the main Activity's -{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, -as shown below. In this example, the LVL sample application's -LicenseCheckerCallback methods (see above) call <code>displayResult()</code> to -update the UI thread through the Handler's -{@link android.os.Handler#post(java.lang.Runnable) post()} method.</p> - -<pre>private Handler mHandler; - - @Override - public void onCreate(Bundle savedInstanceState) { - ... - mHandler = new Handler(); - } -</pre> - -<p>Then, in your LicenseCheckerCallback methods, you can use Handler methods to -post Runnable or Message objects to the Handler. Here's how the sample -application included in the LVL posts a Runnable to a Handler in the UI thread -to display the license status.</p> - -<pre> private void displayResult(final String result) { - mHandler.post(new Runnable() { - public void run() { - mStatusText.setText(result); - setProgressBarIndeterminateVisibility(false); - mCheckLicenseButton.setEnabled(true); - } - }); - } -</pre> - -<h4 id="lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</h4> - -<p>In the main Activity's -{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, -create private instances of LicenseCheckerCallback and LicenseChecker. You must -instantiate LicenseCheckerCallback first, because you need to pass a reference -to that instance when you call the contructor for LicenseChecker. </p> - -<p>When you instantiate LicenseChecker, you need to pass in these parameters:</p> - -<ul> -<li>The application {@link android.content.Context}</li> -<li>A reference to the Policy implementation to use for the license check. In -most cases, you would use the default Policy implementation provided by the LVL, -ServerManagedPolicy. </li> -<li>The String variable holding your publisher account's public key for -licensing. </li> -</ul> - -<p>If you are using ServerManagedPolicy, you won't need to access the class -directly, so you can instantiate it in the LicenseChecker constructor, -as shown in the example below. Note that you need to pass a reference to a new -Obfuscator instance when you construct ServerManagedPolicy.</p> - -<p>The example below shows the instantiation of LicenseChecker and -LicenseCheckerCallback from the <code>onCreate()</code> method of an Activity -class. </p> - -<pre>public class MainActivity extends Activity { - ... - private LicenseCheckerCallback mLicenseCheckerCallback; - private LicenseChecker mChecker; - - @Override - public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - ... - // Construct the LicenseCheckerCallback. The library calls this when done. - mLicenseCheckerCallback = new MyLicenseCheckerCallback(); - - // Construct the LicenseChecker with a Policy. - mChecker = new LicenseChecker( - this, new ServerManagedPolicy(this, - new AESObfuscator(SALT, getPackageName(), deviceId)), - BASE64_PUBLIC_KEY // Your public licensing key. - ); - ... - } -} -</pre> - - -<p>Note that LicenseChecker calls the LicenseCheckerCallback methods from the UI -thread <em>only</em> if there is valid license response cached locally. If the -license check is sent to the server, the callbacks always originate from the -background thread, even for network errors. </p> - - -<h4 id="check-access">Call checkAccess() to initiate the license check</h4> - -<p>In your main Activity, add a call to the <code>checkAccess()</code> method of the -LicenseChecker instance. In the call, pass a reference to your -LicenseCheckerCallback instance as a parameter. If you need to handle any -special UI effects or state management before the call, you might find it useful -to call <code>checkAccess()</code> from a wrapper method. For example, the LVL -sample application calls <code>checkAccess()</code> from a -<code>doCheck()</code> wrapper method:</p> - -<pre> @Override - public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - ... - // Call a wrapper method that initiates the license check - doCheck(); - ... - } - ... - private void doCheck() { - mCheckLicenseButton.setEnabled(false); - setProgressBarIndeterminateVisibility(true); - mStatusText.setText(R.string.checking_license); - mChecker.checkAccess(mLicenseCheckerCallback); - } -</pre> - - -<h4 id="account-key">Embed your public key for licensing</h4> - -<p>For each publisher account, the Android Market service automatically -generates a 2048-bit RSA public/private key pair that is used exclusively for -licensing. The key pair is uniquely associated with the publisher account and is -shared across all applications that are published through the account. Although -associated with a publisher account, the key pair is <em>not</em> the same as -the key that you use to sign your applications (or derived from it).</p> - -<p>The Android Market publisher site exposes the public key for licensing to any -developer signed in to the publisher account, but it keeps the private key -hidden from all users in a secure location. When an application requests a -license check for an application published in your account, the licensing server -signs the license response using the private key of your account's key pair. -When the LVL receives the response, it uses the public key provided by the -application to verify the signature of the license response. </p> - -<p>To add licensing to an application, you must obtain your publisher account's -public key for licensing and copy it into your application. Here's how to find -your account's public key for licensing:</p> - -<ol> -<li>Go to the Android Market <a -href="http://market.android.com/publish">publisher site</a> and sign in. -Make sure that you sign in to the account from which the application you are -licensing is published (or will be published). </li> -<li>In the account home page, locate the "Edit profile" link and click it. </li> -<li>In the Edit Profile page, locate the "Licensing" pane, shown below. Your -public key for licensing is given in the "Public key" text box. </li> -</ol> - -<p>To add the public key to your application, simply copy/paste the key string -from the text box into your application as the value of the String variable -<code>BASE64_PUBLIC_KEY</code>. When you are copying, make sure that you have -selected the entire key string, without omitting any characters. </p> - -<p>Here's an example from the LVL sample application:</p> - -<pre> public class MainActivity extends Activity { - private static final String BASE64_PUBLIC_KEY = "MIIBIjANBgkqhkiG ... "; //truncated for this example - ... - } -</pre> - -<h4 id="handler-cleanup">Call your LicenseChecker's onDestroy() method -to close IPC connections</h4> - -<p>Finally, to let the LVL clean up before your application -{@link android.content.Context} changes, add a call to the LicenseChecker's -<code>onDestroy()</code> method from your Activity's -{@link android.app.Activity#onDestroy()} implementation. The call causes the -LicenseChecker to properly close any open IPC connection to the Android Market -application's ILicensingService and removes any local references to the service -and handler.</p> - -<p>Failing to call the LicenseChecker's <code>onDestroy()</code> method -can lead to problems over the lifecycle of your application. For example, if the -user changes screen orientation while a license check is active, the application -{@link android.content.Context} is destroyed. If your application does not -properly close the LicenseChecker's IPC connection, your application will crash -when the response is received. Similarly, if the user exits your application -while a license check is in progress, your application will crash when the -response is received, unless it has properly called the -LicenseChecker's <code>onDestroy()</code> method to disconnect from the service. -</p> - -<p>Here's an example from the sample application included in the LVL, where -<code>mChecker</code> is the LicenseChecker instance:</p> - -<pre> @Override - protected void onDestroy() { - super.onDestroy(); - mChecker.onDestroy(); - ... - } -</pre> - -<p>If you are extending or modifying LicenseChecker, you might also need to call -the LicenseChecker's <code>finishCheck()</code> method, to clean up any open IPC -connections.</p> - -<h3 id="impl-DeviceLimiter">Implementing a DeviceLimiter</h3> - -<p>In some cases, you might want your Policy to limit the number of actual -devices that are permitted to use a single license. This would prevent a user -from moving a licensed application onto a number of devices and using the -application on those devices under the same account ID. It would also prevent a -user from "sharing" the application by providing the account information -associated with the license to other individuals, who could then sign in to that -account on their devices and access the license to the application. </p> - -<p>The LVL supports per-device licensing by providing a -<code>DeviceLimiter</code> interface, which declares a single method, -<code>allowDeviceAccess()</code>. When a LicenseValidator is handling a response -from the licensing server, it calls <code>allowDeviceAccess()</code>, passing a -user ID string extracted from the response.</p> - -<p>If you do not want to support device limitation, <strong>no work is -required</strong> — the LicenseChecker class automatically uses a default -implementation called NullDeviceLimiter. As the name suggests, NullDeviceLimiter -is a "no-op" class whose <code>allowDeviceAccess()</code> method simply returns -a <code>LICENSED</code> response for all users and devices. </p> - -<div style="border-left:4px solid #FFCF00;margin:1em;padding: 0 0 0 .5em"> -<p><strong>Caution:</strong> Per-device licensing is <em>not recommended for -most applications</em> because:</p> -<ul> -<li>It requires that you provide a backend server to manage a users and devices -mapping, and </li> -<li>It could inadvertently result in a user being denied access to an -application that they have legitimately purchased on another device.</li> -</ul> -</div> - - -<h2 id="test-env">Setting Up the Testing Environment</h2> - -<p>The Android Market publisher site provides configuration tools that let you -and others test licensing on your application before it is published. As you are -implementing licensing, you can make use of the publisher site tools to test -your application's Policy and handling of different licensing responses and -error conditions.</p> - -<p>The main components of the test environment for licensing include: </p> - -<ul> -<li>A "Test response" configuration in your publisher account that lets you -set the static licensing response returned, when the server processes a -license check for an application uploaded to the publisher account, from a user -signed in to the publisher account or a test account.</li> -<li>An optional set of test accounts that will receive the static test -response when they check the license of an application that you have uploaded -(regardless whether the application is published or not).</li> -<li>A runtime environment for the application that includes the Android Market -application or Google APIs Add-On, on which the user is signed in to the -publisher account or one of the test accounts.</li> -</ul> - -<p>Setting up the test environment properly involves:</p> - -<ol> -<li><a href="#test-response">Setting static test responses</a> that are returned by the licensing server.</li> -<li><a href="#test-acct-setup">Setting up test accounts</a> as needed.</li> -<li><a href="#acct-signin">Signing in</a> properly to an emulator or device, before initiating a license check test.</li> -</ol> - -<p>The sections below provide more information.</p> - - -<h3 id="test-response">Setting test responses for license checks</h3> - -<p>Android Market provides a configuration setting in your publisher account -that lets you override the normal processing of a license check and return a -specified static response code. The setting is for testing only and applies -<em>only</em> to license checks for applications that you have uploaded, made by -any user signed in to an emulator or device using the credentials of the -publisher account or a registered test account. For other users, the server -always processes license checks according to normal rules. </p> - -<p>To set a test response for your account, sign in to your publisher account -and click "Edit Profile". In the Edit Profile page, locate the Test Response -menu in the Licensing panel, shown below. You can select from the full set of -valid server response codes to control the response or condition you want to -test in your application.</p> - -<p>In general, you should make sure to test your application's licensing -implementation with every response code available in the Test Response menu. -For a description of the codes, see <a href="#server-response-codes">Server -Response Codes</a> in the Appendix of this document.</p> - -<div style="margin-bottom:2em;" id="licensing_test_response"> - -<img src="{@docRoot}images/licensing_test_response.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 7.</strong> The Licensing -panel of your account's Edit Profile page, showing the Test Accounts field and the -Test Response menu.</div> -</div> - -<p>Note that the test response that you configure applies account-wide — -that is, it applies not to a single application, but to <em>all</em> -applications associated with the publisher account. If you are testing multiple -applications at once, changing the test response will affect all of those -applications on their next license check (if the user is signed into -the emulator or device using the publisher account or a test account).</p> - -<p>Before you can successfully receive a test response for a license check, -you must sign in to the device or emulator on which the application -is installed, and from which it is querying the server. Specifically, you must -sign using either your publisher account or one of the test accounts that you -have set up. For more information about test accounts, see the next section.</p> - -<p>See <a href="#server-response-codes">Server Response Codes</a> for a list of -test responses available and their meanings. </p> - - -<h3 id="test-acct-setup">Setting up test accounts</h3> - -<p>In some cases, you might want to let multiple teams of developers test -licensing on applications that will ultimately be published through your -publisher account, but without giving them access to your publisher account's -sign-in credentials. To meet that need, the Android Market publisher site lets -you set up one or more optional <em>test accounts</em> — accounts that are -authorized to query the licensing server and receive static test responses from -your publisher account.</p> - -<p>Test accounts are standard Google accounts that you register on your -publisher account, such that they will receive the test response for -applications that you have uploaded. Developers can then sign in to their -devices or emulators using the test account credentials and initiate license -checks from installed applications. When the licensing server receives a license -check from a user of a test account, it returns the static test response -configured for the publisher account. </p> - -<p>Necessarily, there are limitations on the access and permissions given to -users signed in through test accounts, including:</p> - -<ul> -<li>Test account users can query the licensing server only for applications that -are already uploaded to the publisher account. </li> -<li>Test account users do not have permission to upload applications to your -publisher account.</li> -<li>Test account users do not have permission to set the publisher account's -static test response.</li> -</ul> - -<p>The table below summarizes the differences in capabilities, between the -publisher account, a test account, and any other account.</p> - -<p class="table-caption" id="acct-types-table"><strong>Table 1.</strong> -Differences in account types for testing licensing.</p> - -<table> -<tr> -<th>Account Type</th> -<th>Can check license before upload?</th> -<th>Can receive test response?</th> -<th>Can set test response?</th> -</tr> - -<tr> -<td>Publisher account</td> -<td>Yes</td> -<td>Yes</td> -<td>Yes</td> -</tr> - -<tr> -<td>Test account</td> -<td>No</td> -<td>Yes</td> -<td>No</td> -</tr> - -<tr> -<td>Other</td> -<td>No</td> -<td>No</td> -<td>No</td> -</tr> -</table> - -<h4 id="reg-test-acct">Registering test accounts on the publisher account</h4> - -<p>To get started, you need to register each test account in your publisher -account. As shown in <a href="#licensing_test_response">Figure 7</a>, above, you -register test accounts in the Licensing panel of your publisher account's Edit -Profile page. Simply enter the accounts as a comma-delimited list and click -<strong>Save</strong> to save your profile changes.</p> - -<p>You can use any Google account as a test account. If you want to own and -control the test accounts, you can create the accounts yourself and distribute -the credentials to your developers or testers.</p> - -<h4 id="test-app-upload">Handling application upload and distribution for test -account users</h4> - -<p>As mentioned above, users of test accounts can only receive static test -responses for applications that are uploaded to the publisher account. Since -those users do not have permission to upload applications, as the publisher you -will need to work with those users to collect apps for upload and distribute -uploaded apps for testing. You can handle collection and distribution in any way -that is convenient. </p> - -<p>Once an application is uploaded and becomes known to the licensing server, -developers and testers can continue modify the application in their local -development environment, without having to upload new versions. You only need to -upload a new version if the local application increments the -<code>versionCode</code> attribute in the manifest file. </p> - -<h4 id="test-key">Distributing your public key to test account users</h4> - -<p>The licensing server handles static test responses in the normal way, -including signing the license response data, adding extras parameters, and so -on. To support developers who are implementing licensing using test accounts, -rather than the publisher account, you will need to distribute -your public key to them. Developers without access to the publisher site do not -have access to your public key, and without the key they won't be able to -verify license responses. </p> - -<p>Note that if you decide to generate a new licensing key pair for your account -for some reason, you need to notify all users of test accounts. For -testers, you can embed the new key in the application package and distribute it -to users. For developers, you will need to distribute the new key to them -directly. </p> - - -<h3 id="acct-signin">Signing in to an authorized account in the runtime -environment</h3> - -<p>The licensing service is designed to determine whether a given user is -licensed to use a given application — during a license check, the Android -Market application gathers the user ID from the primary account on the system -and sends it to the server, together with the package name of the application -and other information. However, if there is no user information available, the -license check cannot succeed, so the Android Market application terminates the -request and returns an error to the application. </p> - -<p>During testing, to ensure that your application can successfully query the -licensing server, you must make sure that you sign in to an account <em>on the -device or emulator</em> using:</p> - -<ul> -<li>The credentials of a publisher account, or</li> -<li>The credentials of a test account that is registered with a publisher -account</li> -</ul> - - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Signing in to a Google account on an emulator</h2> - -<p>If you are testing licensing on an emulator, you need to sign in to a Google -account on the emulator. If you do not see an option to create a new Google -account, the problem might be that your AVD is running a standard Android system -image, rather than the Google APIs Add-On, API 8 (release 2) or higher. </p> - -<p style="margin-top:.5em;">For more information, see <a -href="#runtime-setup">Setting up the runtime environment</a>, above.</p> - -</div> -</div> - -<p>Signing in using a publisher account offers the advantage of letting your -applications receive static test responses even before the applications are -uploaded to the publisher site.</p> - -<p>If you are part of a larger organization or are working with external groups -on applications that will be published through your site, you will more likely -want to distribute test accounts instead, then use those to sign in during -testing. </p> - -<p>To sign in on a device or emulator, follow the steps below. The preferred -approach is to sign in as the primary account — however, if there are -other accounts already in use on the device or emulator, you can create an -additional account and sign in to it using the publisher or test account -credentials. </p> - -<ol> -<li>Open Settings > Accounts & sync</li> -<li>Select <strong>Add Account</strong> and choose to add a "Google" account. -</li> -<li>Select <strong>Next</strong> and then <strong>Sign in</strong>.</li> -<li>Enter the username and password of either the publisher account or a test -account that is registered in the publisher account.</li> -<li>Select <strong>Sign in</strong>. The system signs you in to the new -account.</li> -</ol> - -<p>Once you are signed in, you can begin testing licensing in your application -(if you have completed the LVL integration steps above). When your application -initiates a license check, it will receive a response containing the static test -response configured on the publisher account. </p> - -<p>Note that, if you are using an emulator, you will need to sign in to the -publisher account or test account each time you wipe data when restarting the -emulator.</p> - -<div style="margin:2em 1em 1em 1em;"> - -<img src="{@docRoot}images/licensing_device_signin.png" style="text-align:left;" /> -<div style="margin:.25em 1.25em;padding:0"><strong>Figure 8.</strong> Example of -setting up a Google account on a device or emulator.</div> -</div> - -<h2 id="app-obfuscation">Obfuscating Your Application</h2> - -<p>To ensure the security of your application, particularly for a paid -application that uses licensing and/or custom constraints and protections, it's -very important to obfuscate your application code. Properly obfuscating your -code makes it more difficult for a malicious user to decompile the application's -bytecode, modify it — such as by removing the license check — -and then recompile it.</p> - -<p>Several obfuscator programs are available for Android applications, including -<a href="http://proguard.sourceforge.net/">ProGuard</a>, which also offers -code-optimization features. The use of ProGuard or a similar program to obfuscate -your code is <em>strongly recommended</em> for all applications that use Android -Market Licensing. </p> - -<h2 id="app-publishing">Publishing a Licensed Application</h2> - -<p>When you are finished testing your license implementation, you are ready to -publish the application on Android Market. Follow the normal steps to <a -href="{@docRoot}guide/publishing/preparing.html">prepare</a>, <a -href="{@docRoot}guide/publishing/app-signing.html">sign</a>, and then <a -href="{@docRoot}guide/publishing/publishing.html">publish the application</a>. -</p> - -<h4>Removing Copy Protection</h4> - -<p>After uploading your licensed application, remember to remove copy protection -from the application, if it is currently used. To check and remove copy -protection, sign in to the publisher site and go the application's upload -details page. In the Publishing options section, make sure that the Copy -Protection radio button selection is "Off".</p> - -<h4>Considerations for Free Apps</h4> - -<p>Licensing is currently supported only for paid applications. If you already -published your application as free, you won't be able to upload an updated -version that includes licensing (that is, an application that uses the same -package name and that includes the <a href="#manifest-permission">licensing -permission</a>). Here are some points to keep in mind:</p> - -<ul> -<li>If you want to offer a free version of your application that provides a -reduced feature set (or that offers the full feature set for trial period), the -free version of your application must not include the licensing permission and -must use a different package name than the paid version of the app.</li> -<li>If you want to offer a paid version of your free application that uses -licensing, you can do so under a new package name.</li> -</ul> - -<h2 id="support">Where to Get Support</h2> - -<p>If you have questions or encounter problems while implementing or deploying -publishing in your applications, please use the support resources listed in the -table below. By directing your queries to the correct forum, you can get the -support you need more quickly. </p> - -<p class="table-caption"><strong>Table 2.</strong> Developer support resources -for Android Market Licensing Service.</p> - -<table> - -<tr> -<th>Support Type</th> -<th>Resource</th> -<th>Range of Topics</th> -</tr> -<tr> -<td rowspan="2">Development and testing issues</td> -<td>Google Groups: <a -href="http://groups.google.com/group/android-developers">android-developers</a> -</td> -<td rowspan="2">LVL download and integration, library projects, Policy -questions, user experience ideas, handling of responses, Obfuscator, IPC, test -environment setup</td> -</tr> -<tr> -<td>Stack Overflow: <a -href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/android</a></td> -</tr> -<tr> -<td rowspan="2">Accounts, publishing, and deployment issues</td> -<td><a href="http://www.google.com/support/forum/p/Android+Market">Android -Market Help Forum</a></td> -<td rowspan="2">Publisher accounts, licensing key pair, test accounts, server -responses, test responses, application deployment and results</td> -</tr> -<tr> -<td><a -href="http://market.android.com/support/bin/answer.py?answer=186113">Market -Licensing Support FAQ</a></td> -</tr> -<tr> -<td>LVL issue tracker</td> -<td><a href="http://code.google.com/p/marketlicensing/issues/">Marketlicensing -project issue tracker</a></td> -<td>Bug and issue reports related specifically to the LVL source code classes -and interface implementations</td> -</tr> - -</table> - -<p>For general information about how to post to the groups listed above, see <a -href="{@docRoot}resources/community-groups.html">Developer Forums</a> document -in the Resources tab.</p> - -<h2 id="lvl-summary">Summary of LVL Classes and Interfaces</h2> - -<p>The table below lists all of the source files in the License Verification -Library (LVL) available through the Android SDK. All of the files are part of -the <code>com.android.vending.licensing</code> package.</p> - -<p class="table-caption"><strong>Table A-1.</strong> Summary of LVL library -classes and interfaces.</p> - -<div style="width:99%"> -<table width="100%"> - -<tr> -<th width="15%">Category</th> -<th width="20%">Name</th> -<th width="100%">Description</th> -</tr> - -<tr> -<td rowspan="2">License check and result</td> -<td>LicenseChecker</td> -<td>Class that you instantiate (or subclass) to initiate a license check.</td> -</tr> -<tr> -<td><em>LicenseCheckerCallback</em></td> -<td>Interface that you implement to handle result of the license check.</td> -</tr> - -<tr> -<td rowspan="3" width="15%">Policy</td> -<td width="20%"><em>Policy</em></td> -<td width="100%">Interface that you implement to determine whether to allow -access to the application, based on the license response. </td> -</tr> -<tr> -<td>ServerManagedPolicy</td> -<td width="100%">Default Policy implementation. Uses settings provided by the -licensing server to manage local storage of license data, license validity, -retry.</td> -</tr> -<tr> -<td>StrictPolicy</td> -<td>Alternative Policy implementation. Enforces licensing based on a direct -license response from the server only. No caching or request retry.</td> -</tr> - -<tr> -<td rowspan="2" width="15%">Data obfuscation <br><em>(optional)</em></td> -<td width="20%"><em>Obfuscator</em></td> -<td width="100%">Interface that you implement if you are using a Policy (such as -ServerManagedPolicy) that caches license response data in a persistent store. -Applies an obfuscation algorithm to encode and decode data being written or -read.</td> -</tr> -<tr> -<td>AESObfuscator</td> -<td>Default Obfuscator implementation that uses AES encryption/decryption -algorithm to obfuscate/unobfuscate data.</td> -</tr> - -<tr> -<td rowspan="2" width="15%">Device limitation<br><em>(optional)</em></td> -<td width="20%"><em>DeviceLimiter</em></td> -<td width="100%">Interface that you implement if you want to restrict use of an -application to a specific device. Called from LicenseValidator. Implementing -DeviceLimiter is not recommended for most applications because it requires a -backend server and may cause the user to lose access to licensed applications, -unless designed with care.</td> -</tr> -<tr> -<td>NullDeviceLimiter</td> -<td>Default DeviceLimiter implementation that is a no-op (allows access to all -devices).</td> -</tr> - -<tr> -<td rowspan="6" width="15%">Library core, no integration needed</td> -<td width="20%">ResponseData</td> -<td width="100%">Class that holds the fields of a license response.</td> -</tr> -<tr> -<td>LicenseValidator</td> -<td>Class that decrypts and verifies a response received from the licensing -server.</td> -</tr> -<tr> -<td>ValidationException</td> -<td>Class that indicates errors that occur when validating the integrity of data -managed by an Obfuscator.</td> -</tr> -<tr> -<td>PreferenceObfuscator</td> -<td>Utility class that writes/reads obfuscated data to the system's -{@link android.content.SharedPreferences} store.</td> -</tr> -<tr> -<td><em>ILicensingService</em></td> -<td>One-way IPC interface over which a license check request is passed to the -Android Market client.</td> -</tr> -<tr> -<td><em>ILicenseResultListener</em></td> -<td>One-way IPC callback implementation over which the application receives an -asynchronous response from the licensing server.</td> -</tr> - -</table> -</div> - - -<h2 id="server-response-codes">Server Response Codes</h2> - -<p>The table below lists all of the license response codes supported by the -licensing server. In general, an application should handle all of these response -codes. By default, the LicenseValidator class in the LVL provides all of the -necessary handling of these response codes for you. </p> - -<p class="table-caption"><strong>Table A-2.</strong> Summary of response codes -returned by the Android Market server in a license response.</p> - -<table> - -<tr> -<th>Response Code</th> -<th>Description</th> -<th>Signed?</th> -<th>Extras</th> -<th>Comments</th> -</tr> -<tr> -<td>LICENSED</td> -<td>The application is licensed to the user. The user has purchased the -application or the application only exists as a draft.</td> -<td>Yes</td> -<td><code>VT</code>, <code>GT</code>, <code>GR</code></td> -<td><em>Allow access according to Policy constraints.</em></td> -</tr> -<tr> -<td>LICENSED_OLD_KEY</td> -<td>The application is licensed to the user, but there is an updated application -version available that is signed with a different key. </td> -<td>Yes </td> -<td><code>VT</code>, <code>GT</code>, <code>GR</code>, <code>UT</code></td> -<td><em>Optionally allow access according to Policy constraints.</em> -<p style="margin-top:.5em;">Can indicate that the key pair used by the installed -application version is invalid or compromised. The application can allow access -if needed or inform the user that an upgrade is available and limit further use -until upgrade.</p> -</td> -</tr> -<tr> -<td>NOT_LICENSED</td> -<td>The application is not licensed to the user.</td> -<td>No</td> -<td></td> -<td><em>Do not allow access.</em></td> -</tr> -<tr> -<td>ERROR_CONTACTING_SERVER</td> -<td>Local error — the Android Market application was not able to reach the -licensing server, possibly because of network availability problems. </td> -<td>No</td> -<td></td> -<td><em>Retry the license check according to Policy retry limits.</em></td> -</tr> -<tr> -<td>ERROR_SERVER_FAILURE</td> -<td>Server error — the server could not load the publisher account's key -pair for licensing.</td> -<td>No</td> -<td></td> -<td><em>Retry the license check according to Policy retry limits.</em> -</td> -</tr> -<tr> -<td>ERROR_INVALID_PACKAGE_NAME</td> -<td>Local error — the application requested a license check for a package -that is not installed on the device. </td> -<td>No </td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a development error.</p> -</td> -</tr> -<tr> -<td>ERROR_NON_MATCHING_UID</td> -<td>Local error — the application requested a license check for a package -whose UID (package, user ID pair) does not match that of the requesting -application. </td> -<td>No </td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a development error.</p> -</td> -</tr> -<tr> -<td>ERROR_NOT_MARKET_MANAGED</td> -<td>Server error — the application (package name) was not recognized by -Android Market. </td> -<td>No</td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Can indicate that the application was not published -through Android Market or that there is an development error in the licensing -implementation.</p> -</td> -</tr> - -</table> - -<p class="note"><strong>Note:</strong> As documented in <a href="#test-env"> -Setting Up The Testing Environment</a>, the response code can be manually -overridden for the application developer and any registered test users via the -Android Market publisher site. -<br/><br/> -Additionally, as noted above, applications that are in draft mode (in other -words, applicaitons that have been uploaded but have <em>never</em> been -published) will return LICENSED for all users, even if not listed as a test -user. Since the application has never been offered for download, it is assumed -that any users running it must have obtained it from an authorized channel for -testing purposes.</p> - -<h2 id="extras">Server Response Extras</h2> - -<p>The licensing server includes several settings in certain types of license -responses, to assist the application and its Policy in managing access to the -application across the 24-hour refund period and other conditions. Specifically, -the server provides recommended values for the application's license validity -period, retry grace period, maximum allowable retry count, and other settings. -The server appends the settings as key-value pairs in the license response -"extras" field. </p> - -<p>Any Policy implementation can extract the extras settings from the license -response and use them as needed. The LVL default Policy implementation, <a -href="#ServerManagedPolicy">ServerManagedPolicy</a>, serves as a working -implementation and an illustration of how to obtain, store, and use the -settings. </p> - -<p class="table-caption"><strong>Table A-3.</strong> Summary of -license-management settings supplied by the Android Market server in a license -response.</p> - -<table> -<tr> -<th>Extra</th><th>Description</th> -</tr> - -<tr> - <td>VT</td> - <td>License validity timestamp. Specifies the date/time at which the current -(cached) license response expires and must be rechecked on the licensing server. - </td> -</tr> -<tr> - <td>GT</td> - <td>Grace period timestamp. Specifies the end of the period during which a -Policy may allow access to the application, even though the response status is -RETRY. <p>The value is managed by the server, however a typical value would be 5 -or more days.</p></td> -</tr> -<tr> - <td>GR</td> - <td>Maximum retries count. Specifies how many consecutive RETRY license checks -the Policy should allow, before denying the user access to the application. -<p>The value is managed by the server, however a typical value would be "10" or -higher.</p></td> -</tr> -<tr> - <td>UT</td> - <td>Update timestamp. Specifies the day/time when the most recent update to -this application was uploaded and published. <p>The server returns this extra -only for LICENSED_OLD_KEYS responses, to allow the Policy to determine how much -time has elapsed since an update was published with new licensing keys before -denying the user access to the application. </p></td> -</tr> - -</table> - -<p>The sections below provide more information about the server-provided -settings and how to use them. </p> - -<h4>License validity period</h4> - -<p>The Android Market licensing server sets a license validity period for all -downloaded applications. The period expresses the interval of time over which an -application's license status should be considered as unchanging and cacheable by -a licensing Policy in the application. The licensing server includes the -validity period in its response to all license checks, appending an -end-of-validity timestamp to the response as an extra under the key "VT". A -Policy can extract the VT key value and use it to conditionally allow access to -the application without rechecking the license, until the validity period -expires. </p> - -<p>The license validity signals to a licensing Policy when it must recheck the -licensing status with the licensing server. It is <em>not</em> intended to imply -whether an application is actually licensed for use. That is, when an -application's license validity period expires, this does not mean that the -application is no longer licensed for use — rather, it indicates only that -the Policy must recheck the licensing status with the server. It follows that, -as long as the license validity period is not expired, it is acceptable for the -Policy to cache the initial license status locally and return the cached license -status instead of sending a new license check to the server.</p> - -<p>The licensing server manages the validity period as a means of helping the -application properly enforce licensing across the refund period offered by -Android Market for paid applications. It sets the validity period based on -whether the application was purchased and, if so, how long ago. Specifically, -the server sets a validity period as follows:</p> - -<ul> -<li>For a paid application, the server sets the initial license validity period -so that the license response remains valid for as long as the application is -refundable. A licensing Policy in the application may cache the -result of the initial license check and does not need to recheck the license -until the validity period has expired.</li> -<li>When an application is no longer refundable, the server -sets a longer validity period — typically a number of days. </li> -<li>For a free application, the server sets the validity period to a very high -value (<code>long.MAX_VALUE</code>). This ensures that, provided the Policy has -cached the validity timestamp locally, it will not need to recheck the -license status of the application in the future.</li> -</ul> - -<p>The ServerManagedPolicy implementation uses the extracted timestamp -(<code>mValidityTimestamp</code>) as a primary condition for determining whether -to recheck the license status with the server before allowing the user access to -the application. </p> - -<h4>Retry period and maximum retry count</h4> - -<p>In some cases, system or network conditions can prevent an application's -license check from reaching the licensing server, or prevent the server's -response from reaching the Android Market client application. For example, the -user might launch an application when there is no cell network or data -connection available — such as when on an airplane — or when the -network connection is unstable or the cell signal is weak. </p> - -<p>When network problems prevent or interrupt a license check, the Android -Market client notifies the application by returning a "RETRY" response code to -the Policy's <code>processServerResponse()</code> method. In the case of system -problems, such as when the application is unable to bind with Android Market's -ILicensingService implementation, the LicenseChecker library itself calls the -Policy <code>processServerResonse()</code> method with a "RETRY" response code. -</p> - -<p>In general, the RETRY response code is a signal to the application that an -error has occurred that has prevented a license check from completing. - -<p>The Android Market server helps an application to manage licensing under -error conditions by setting a retry "grace period" and a recommended maximum -retries count. The server includes these values in all license check responses, -appending them as extras under the keys "GT" and "GR". </p> - -<p>The application Policy can extract the GT and GR extras and use them to -conditionally allow access to the application, as follows:</p> - -<ul> -<li>For a license check that results in a RETRY response, the Policy should -cache the RETRY response code and increment a count of RETRY responses.</li> -<li>The Policy should allow the user to access the application, provided that -either the retry grace period is still active or the maximum retries count has -not been reached.</li> -</ul> - -<p>The ServerManagedPolicy uses the server-supplied GT and GR values as -described above. The example below shows the conditional handling of the retry -responses in the <code>allow()</code> method. The count of RETRY responses is -maintained in the <code>processServerResponse()</code> method, not shown. </p> - - -<pre> public boolean allowAccess() { - long ts = System.currentTimeMillis(); - if (mLastResponse == LicenseResponse.LICENSED) { - // Check if the LICENSED response occurred within the validity timeout. - if (ts <= mValidityTimestamp) { - // Cached LICENSED response is still valid. - return true; - } - } else if (mLastResponse == LicenseResponse.RETRY && - ts < mLastResponseTime + MILLIS_PER_MINUTE) { - // Only allow access if we are within the retry period or we haven't used up our - // max retries. - return (ts <= mRetryUntil || mRetryCount <= mMaxRetries); - } - return false; - }</pre> - diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd index 5ed55fe..fe56352 100644 --- a/docs/html/guide/publishing/preparing.jd +++ b/docs/html/guide/publishing/preparing.jd @@ -22,7 +22,7 @@ page.title=Preparing for Release <ol> <li><a href="{@docRoot}guide/publishing/publishing_overview.html">Publishing Overview</a></li> <li><a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a></li> - <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li> + <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a></li> </ol> </div> </div> @@ -39,13 +39,13 @@ similar to the debug build process and can be done using JDK and Android SDK too tasks serve as a final check, ensuring that your application performs as expected under real-world conditions. When you are finished preparing your application for release you have a signed <code>.apk</code> file, which you can distribute directly to users or distribute through an -application marketplace such as Android Market.</p> +application marketplace such as Google Play.</p> <p>This document summarizes the main tasks you need to perform to prepare your application for release. The tasks that are described in this document apply to all Android applications regardless -how they are released or distributed to users. If you are releasing your application through Android -Market, you should also read <a href="{@docRoot}guide/publishing/publishing.html">Publishing on -Android Market</a> to be sure your release-ready application satisfies all Android Market +how they are released or distributed to users. If you are releasing your application through Google +Play, you should also read <a href="{@docRoot}guide/publishing/publishing.html">Publishing on +Google Play</a> to be sure your release-ready application satisfies all Google Play requirements.</p> <p class="note"><strong>Note:</strong> As a best practice, your application should meet all of your @@ -89,9 +89,9 @@ line.</p> <p>To prepare your application for release you typically perform five main tasks (see figure 2). Each main task may include one or more smaller tasks depending on how you are releasing your -application. For example, if you are releasing your application through Android Market you may want +application. For example, if you are releasing your application through Google Play you may want to add special filtering rules to your manifest while you are configuring your application for -release. Similarly, to meet Android Market publishing guidelines you may have to prepare screenshots +release. Similarly, to meet Google Play publishing guidelines you may have to prepare screenshots and create promotional text while you are gathering materials for release.</p> <p>You usually perform the tasks listed in figure 2 after you have throroughly debugged and tested @@ -117,11 +117,14 @@ Android system allows you to sign your applications with a self-signed certifica certificate requirements, see <a href="{@docRoot}guide/publishing/app-signing.html#cert">Obtain a suitable private key</a>.</p> +<p class="caution"><strong>Important:</strong> Your application must be signed with a cryptographic +key whose validity period ends after 22 October 2033.</p> + <p>You may also have to obtain other release keys if your application accesses a service or uses a third-party library that requires you to use a key that is based on your private key. For example, if your application uses the <a -href="http://code.google.com/android/add-ons/google-apis/reference/com/google/android/maps/ MapView. -html">MapView</a> class, which is part of the <a +href="http://code.google.com/android/add-ons/google-apis/reference/com/google/android/maps/MapView.html">MapView</a> +class, which is part of the <a href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps external library</a>, you will need to register your application with the Google Maps service and obtain a Maps API key. For information about getting a Maps API key, see <a @@ -134,9 +137,9 @@ key</a>.</p> href="{@docRoot}guide/practices/ui_guidelines/icon_design_launcher.html">icon guidelines</a>. Your application's icon helps users identify your application on a device's Home screen and in the Launcher window. It also appears in Manage Applications, My Downloads, and -elsewhere. In addition, publishing services such as Android Market display your icon to users.</p> +elsewhere. In addition, publishing services such as Google Play display your icon to users.</p> -<p class="note"><strong>Note:</strong> If you are releasing your application on Android Market, you +<p class="note"><strong>Note:</strong> If you are releasing your application on Google Play, you need to create a high resolution version of your icon. See <a href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870">Graphic @@ -151,7 +154,7 @@ with your application.</p> <h4>Miscellaneous Materials</h4> <p>You might also have to prepare promotional and marketing materials to publicize your application. -For example, if you are releasing your application on Android Market you will need to prepare some +For example, if you are releasing your application on Google Play you will need to prepare some promotional text and you will need to create screenshots of your application. For more information, see <a href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870"> @@ -239,11 +242,11 @@ tasks:</p> </ul> <p>There are several additional manifest elements that you can set if you are releasing your -application on Android Market. For example, the <code>android:minSdkVersion</code> and +application on Google Play. For example, the <code>android:minSdkVersion</code> and <code>android:targetSdkVersion</code> attributes, which are located in the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> <uses-sdk></a> element. For more -information about these and other Android Market settings, see <a -href="{@docRoot}/guide//appendix/market-filters.html">Market Filters</a>.</p> +information about these and other Google Play settings, see <a +href="{@docRoot}/guide//appendix/market-filters.html">Filters on Google Play</a>.</p> <h4>Address compatibility issues</h4> @@ -280,15 +283,15 @@ doing the following:</p> <p>If your application accesses remote servers or services, make sure you are using the production URL or path for the server or service and not a test URL or path.</p> -<h4>Implement Licensing (if you are releasing on Android Market)</h4> +<h4>Implement Licensing (if you are releasing on Google Play)</h4> -<p>If you are releasing a paid application through Android Market, consider adding support for -Android Market Licensing. Licensing lets you control access to your application based on whether the -current user has purchased it. Using Android Market Licensing is optional even if you are -releasing your app through Android Market.</p> +<p>If you are releasing a paid application through Google Play, consider adding support for +Google Play Licensing. Licensing lets you control access to your application based on whether the +current user has purchased it. Using Google Play Licensing is optional even if you are +releasing your app through Google Play.</p> -<p>For more information about Android Market Licensing Service and how to use it in your -application, see <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> +<p>For more information about Google Play Licensing Service and how to use it in your +application, see <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a>.</p> <h2 id="publishing-build">Building Your Application for Release</h2> @@ -349,7 +352,7 @@ a summary of common Android situations that you should consider when you are tes done testing and you are satisfied that the release version of your application behaves correctly, you can release your application to users. For more information, see <a href="{@docRoot}guide/publishing/publishing_overview.html#publishing-release">Releasing Your -Application to Users</a>. If you are publishing your application on Android Market, see -<a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a>.</p> +Application to Users</a>. If you are publishing your application on Google Play, see +<a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a>.</p> diff --git a/docs/html/guide/publishing/publishing.jd b/docs/html/guide/publishing/publishing.jd index fa677e6..b9513ab 100644 --- a/docs/html/guide/publishing/publishing.jd +++ b/docs/html/guide/publishing/publishing.jd @@ -1,4 +1,4 @@ -page.title=Publishing on Android Market +page.title=Publishing on Google Play @jd:body <div id="qv-wrapper"> @@ -7,111 +7,215 @@ page.title=Publishing on Android Market <h2>Quickview</h2> <ul> -<li>You can publish your application using a hosted service such as Android Market or through a web server.</li> -<li>Before you publish, make sure you have prepared your application properly.</li> -<li>Android Market makes it easy for users of Android-powered devices to see and download your application.</li> +<li>Learn how to publish and update apps on Google Play.</li> +<li>Find out how to create links to apps that are published on Google Play.</li> +<li>Learn about Google Play features.</li> </ul> <h2>In this document</h2> <ol> -<li><a href="#overview">About Android Market</a> -<li><a href="#marketupgrade">Publishing Updates on Android Market</a></li> -<li><a href="#marketLicensing">Using Android Market Licensing Service</a></li> -<li><a href="#marketintent">Linking to Your Apps on Android Market</a> +<li><a href="#overview">About Google Play</a> +<li><A href="#marketpublish">Publishing Apps on Google Play</a></li> +<li><a href="#marketupgrade">Publishing Updates on Google Play</a></li> +<li><a href="#marketLicensing">Using Google Play Licensing Service</a></li> +<li><a href="#marketinappbilling">Using Google Play In-app Billing</a></li> +<li><a href="#marketintent">Linking to Your Apps on Google Play</a> <ol> <li><a href="#OpeningDetails">Opening an app's details page</a></li> <li><a href="#PerformingSearch">Performing a search</a></li> - <li><a href="#BuildaButton">Build an Android Market button</a></li> + <li><a href="#BuildaButton">Build a Google Play button</a></li> <li><a href="#UriSummary">Summary of URI formats</a></li> - </ol> + </ol> </li> </ol> <h2>See also</h2> <ol> -<li><a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a></li> -<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a></li> +<li><a href="{@docRoot}guide/publishing/publishing_overview.html">Publishing Overview</a></li> +<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing for Release</a></li> </ol> <div id="qv-extra"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0 5px;"> - <h2 style="color:#669999;">Interested in publishing your app on Android Market?</h2> - <p><a href="http://market.android.com/publish">Go to Android Market</a> to -create a developer account and upload your application. For more information about the -required assets, listing details, and options, see <a -href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading -applications</a>.</p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0 5px;"> + <h2 style="color:#669999;">Already know about Google Play and want to get started?</h2> + <p>Go to <a href="http://play.google.com/apps/publish">Google Play</a>, create a developer +account, and upload your application. For more information about required assets, listing details, +and publishing options, see <a +href="http://market.android.com/support/bin/answer.py?answer=113469">Upload +Applications</a>.</p> </div> </div> </div> </div> -<p>If you've followed the steps outlined in <a -href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a>, the result of the process -is a compiled {@code .apk} file that is signed with your private release key. Your application is -now ready to be published publicly so users can install it.</p> +<p>One of the most effective ways to get your application into users' hands is to +publish it on an application marketplace like Google Play. Publishing on Google Play is a +straightforward process that you can do in just a few simple steps—register, configure, +upload, and publish. Registration takes only a few minutes and needs to be done only once. +The configuration and publishing steps can all be done through the Google Play Android Developer Console +after you register as a Google Play developer.</p> -<p>You can publish your application and allow users to install it any way you choose, including -from your own web server. This document provides information about publishing your Android -application with Android Market.</p> +<p>To start publishing on Google Play, first read this topic and then go to the <a +href="https://play.google.com/apps/publish">Google Play Android Developer Console</a> and register as +a Google Play developer.</p> -<h2 id="overview">About Android Market</h2> +<h2 id="overview">About Google Play</h2> -<p>Android Market is a service that makes it easy for users to find and download Android -applications to their Android-powered devices, either from the Android Market application on their -device or from the Android Market web site (<a -href="http://market.android.com">market.android.com</a>). As a developer, you can use Android Market -to distribute your applications to users on all types of Android-powered devices, all around the -world.</p> +<p>Google Play is a robust publishing platform that helps you publicize, sell, and distribute +your Android applications to users around the world. When you release your applications through +Google Play you have access to a suite of developer tools that let you analyze your sales, +identify market trends, and control who your applications are being distributed to. You also have +access to several revenue-enhancing features, such as <a +href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and +<a href="{@docRoot}guide/market/licensing/index.html">application licensing</a>.</p> -<p>To publish your application on Android Market, you first need to register -with the service using a Google account and agree to the terms of service. -Once you are registered, you can upload your application to the service whenever -you want, update it as many times as you want, and then publish it when you are ready. -Once published, users can see your application, download it, and rate it. </p> +<p>Before you can publish applications on Google Play, you need to <a +href="http://play.google.com/apps/publish">register</a> as a Google Play developer. During the +registration process you will need to create a developer profile, pay a registration fee, and agree +to the <a href="http://www.android.com/us/developer-distribution-agreement.html">Google Play +Developer Distribution Agreement</a>. After you register you can access the Developer +Console, where you can upload applications, configure publishing options, and monitor publishing +data. If you want to sell your applications or use the in-app billing feature, you will also need +to set up a Google Checkout merchant account. For more information about the registration process, +see <a href="https://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=113468"> +Developer Registration</a>.</p> -<p>To register as an Android Market developer and get started with publishing, -visit the Android Market publisher site: </p> +<h2 id="marketpublish">Publishing Apps on Google Play</h2> -<p style="margin-left:3em;"><a -href="http://market.android.com/publish">http://market.android.com/publish</a> -</p> +<p>Publishing your application on Google Play is a simple process that involves three basic +tasks (see figure 1):</p> -<p>If you plan to publish your application on Android Market, you must make sure -that it meets the requirements listed below, which are enforced by the Market -server when you upload the application.</p> +<ul> + <li>Creating various graphical assets that +accompany your app on Google Play.</li> + <li>Using the Google Play <a +href="http://play.google.com/apps/publish">Developer Console</a> to configure publishing options, +specify listing details, and upload your app and graphical assets to Google Play.</li> + <li>Reviewing your publishing settings and changing the release +status of your app from Unpublished to Published.</li> +</ul> -<div class="special"> -<p>Requirements enforced by the Android Market server:</p> -<ol> -<li>Your application must be signed with a cryptographic private key whose -validity period ends after <span style="color:red">22 October 2033</span>. </li> -<li>Your application must define both an <code>android:versionCode</code> and an -<code>android:versionName</code> attribute in the -<a -href="{@docRoot}guide/topics/manifest/manifest-element.html"><code><manifest></code></a> -element of its manifest file. The server uses the <code>android:versionCode</code> as -the basis for identifying the application internally and handling updates, and -it displays the <code>android:versionName</code> to users as the application's -version.</li> -<li>Your application must define both an <code>android:icon</code> and an -<code>android:label</code> attribute in the <a -href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> -element of its manifest file.</li> -</ol> -</div> +<img src="{@docRoot}images/publishing/publishing_android_market.png" + alt="Shows the three steps that are required to publish on Google Play" + height="168" + id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> To publish apps on Google Play you must first <a +href="{@docRoot}guide/publishing/preparing.html">prepare your app for release</a> and then perform +three simple tasks. +</p> +<p class="caution"><strong>Important:</strong> You must <a +href="{@docRoot}guide/publishing/preparing.html">prepare your application for release</a> before you +can publish it on Google Play. When you prepare your application for release you configure it for +release and build it in release mode. Building in release mode signs your application's {@code .apk} +file with your private release key. You cannot publish an application on Google Play unless it is +signed with your own private release key.</p> + +<h3>Preparing promotional materials</h3> + +<p>To fully leverage the marketing and publicity capabilities of Google Play, you need to create +several graphical assets that accompany your app on Google Play, such as screenshots, videos, +promotional graphics, and promotional text. At a minimum you must provide two screenshots of your +application and a high resolution application icon. The screenshots are displayed on the details +page for your application on Google Play, and the high resolution application icon is displayed +in various locations throughout Google Play. The high resolution icon does not replace the +launcher icon for your application, rather, it serves as a supplemental icon and should look +the same as your launcher icon. Promotional video, +graphics, and text are optional, although we strongly recommended that you prepare these for your +app. For more information about the graphic assets that accompany your application, see <a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=1078870">Graphic +Assets for your Application</a>.</p> + +<h3>Configuring options and uploading assets</h3> + +<p>Google Play lets you target your application to a worldwide pool of users and devices. To +reach these users you can use the Developer Console to configure various publishing +options and listing details for your app. For example, you can choose the <a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=138294&topic= +2365624&ctx=topic">countries</a> you want to reach, the listing languages you want to use, and the +<a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=138412&topic= +15867&ctx=topic">price</a> you want to charge in each country. You can also configure listing +details such as the application type, <a +href="https://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=113475&topic= +2365760&ctx=topic">category</a>, and <a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=188189&topic= +2364761&ctx=topic">content rating</a>. In addition, if you want to sell items within your app using +the in-app billing feature, you can use the Developer Console to <a +href="http://grendel.sea.corp.google.com:48014/guide/market/billing/billing_admin.html#billing-list +- setup">create a product list</a> and control which items are available for purchase in your +app.</p> + +<p>When you are finished setting publishing options and listing details, you can upload your assets +and your application to Google Play. You can also upload your application as a draft +(unpublished) application, which lets you do final testing before you publish it for final +release.</p> + +<p>To learn more about Google Play publishing settings, see the following resources:</p> -<h2 id="marketupgrade">Publishing Updates on Android Market</h2> +<ul> + <li><a +href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=113469&topic= +236562&ctx=topic">Upload Applications</a>—provides a summary of the publishing settings +you can configure for an app.</li> + <li><a +href="http://support.google.com/androidmarket/developer/bin/topic.py?hl=en&topic=15867">Selling +Your Apps</a>—provides guidance about pricing, supported currencies, tax rates, and many +other topics related to selling apps.</li> + <li><a +href="https://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=1169947&topic= +15867&ctx=topic">Selling Apps in Multiple Currencies</a>—provides a description of how +pricing, payouts, and exchange rates work.</li> +</ul> -<p>At any time after publishing an application on Android Market, you can upload +<h3>Publishing your application</h3> + +<p>When you are satisfied that your publishing settings are correctly configured and your uploaded +application is ready to be released to the public, you can simply click <strong>Publish</strong> in +the Developer Console to make your app available for download +around the world. Keep in mind, it can take several hours for your app to appear on Google +Play after you click <strong>Publish</strong> in the Developer Console.</p> + +<h3>Controlling Distribution to Devices</h3> + +<p>If your application targets different device configurations, you can control which Android-powered +devices have access to your application on Google Play by +using Google Play filters. Filtering compares device configurations that you declare in your +app's manifest file to the configuration defined by a device. For example, if you declare the camera +filter in your manifest, only those devices that have a camera will see your app on Google +Play. Filters must be configured in your application's manifest file when you are <a +href="{@docRoot}guide/publishing/preparing.html">preparing your app for release</a> (that is, before +you upload your app to Google Play). For more information, see <a +href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>.</p> + +<p>You can also use the multiple APK feature to distribute different {@code .apk} files under the same +application listing and the same package name; however, you should use this option only as a last +resort. Android applications usually run on most compatible devices with a single APK, by supplying +alternative resources for different configurations (for example, different layouts for different screen +sizes) and the Android system selects the appropriate resources for the device at runtime. In a +few cases, however, a single APK is unable to support all device configurations, because alternative +resources make the APK file too big (greater than 50MB) or other technical challenges prevent a +single APK from working on all devices. Although we encourage you to develop and publish a single +APK that supports as many device configurations as possible, doing so is sometimes +not possible. To help you publish your application for as many devices as possible, Google Play +allows you to publish multiple APKs under the same application listing. Google Play then supplies +each APK to the appropriate devices based on configuration support you've declared in the manifest +file of each APK. To use this feature, you need to build your separate {@code .apk} files when you are <a +href="{@docRoot}guide/publishing/preparing.html">preparing your app for release</a> (that is, before +you upload your app to Google Play). For more information, see <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> + +<h2 id="marketupgrade">Publishing Updates on Google Play</h2> + +<p>At any time after publishing an application on Google Play, you can upload and publish an update to the same application package. When you publish an update to an application, users who have already installed the application may receive a notification that an update is @@ -124,85 +228,113 @@ attributes in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html"><code><manifest></code></a> element of the manifest file. Also, the package name must be the same as the existing version and the {@code .apk} file must be signed with the same private key. If the package name and signing -certificate do <em>not</em> match those of the existing version, Market will +certificate do <em>not</em> match those of the existing version, Google Play will consider it a new application, publish it as such, and will not offer it to existing users as an update.</p> +<p>If you plan to publish your application on Google Play, you must make sure + that it meets the requirements listed below, which are enforced by Google Play + when you upload the application.</p> -<h2 id="marketLicensing">Using Android Market Licensing Service</h2> +<h2 id="marketLicensing">Using Google Play Licensing Service</h2> -<p>Android Market offers a licensing service that lets you enforce licensing -policies for paid applications that you publish through Android Market. With -Android Market Licensing, your applications can query Android Market at runtime +<p>Google Play offers a licensing service that lets you enforce licensing +policies for paid applications that you publish through Google Play. With +Google Play Licensing, your applications can query Google Play at runtime to obtain the licensing status for the current user, then allow or disallow further use of the application as appropriate. Using the service, you can apply a flexible -licensing policy on an application-by-application basis—each +licensing policy on an application-by-application basis—each application can enforce its licensing status in the way most appropriate for it. </p> -<p>Any application that you publish through Android Market can use the Android -Market Licensing Service. The service uses no dedicated framework APIs, so you can +<p>Any application that you publish through Google Play can use the Google +Play Licensing Service. The service uses no dedicated framework APIs, so you can add licensing to any application that uses a minimum API Level of 3 or higher.</p> -<p>For complete information about Android Market Licensing Service and how to +<p>For complete information about Google Play Licensing Service and how to use it in your application, read <a -href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a>.</p> + +<h2 id="marketinappbilling">Using Google Play In-app Billing</h2> + +<p><a href="{@docRoot}guide/market/billing/billing_overview.html">Google Play In-app Billing</a> +is a Google Play service that lets you sell digital content in your applications. You can use +the service to sell a wide range of content, including downloadable content such as media files or +photos, and virtual content such as game levels or potions.</p> +<p>When you use Google Play's in-app billing service to sell an item, Google Play handles all +billing details so your application never has to directly process any financial transactions. +Google Play uses the same checkout service that is used for application purchases, so your users +experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for +in-app purchases is the same as the transaction fee for application purchases (30%).</p> +<p>Any application that you publish through Google Play can implement in-app billing. No special +account or registration is required other than a Google Play publisher account and a Google +Checkout Merchant account. Also, because the service uses no dedicated framework APIs, you can add +in-app billing to any application that uses a minimum API level of 4 or higher.</p> -<h2 id="marketintent">Linking to Your Apps on Android Market</h2> +<p>To help you integrate in-app billing into your application, the Android SDK provides a <a +href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample application</a> +that demonstrates a simple implementation of in-app billing. The sample application contains +examples of billing-related classes you can use to implement in-app billing in your application. It +also contains examples of the database, user interface, and business logic you might use to +implement in-app billing. For more information about the in-app billing feature, see the +<a href="{@docRoot}guide/market/billing/index.html">In-app Billing documentation</a>.</p> -<p>To help users discover your published applications, you can use two special Android Market URIs +<h2 id="marketintent">Linking to Your Apps on Google Play</h2> + +<p>To help users discover your published applications, you can use two special Google Play URIs that direct users to your application's details page or perform a search for all of your published -applications in Android Market. You can use these URIs to create a button in your application or a +applications on Google Play. You can use these URIs to create a button in your application or a link on a web page that:</p> <ul> - <li>Opens your application's details page in the Android Market application or web site.</li> - <li>Searches for all your published applications in the Android Market application or web + <li>Opens your application's details page in the Google Play application or web site.</li> + <li>Searches for all your published applications in the Google Play application or web site.</li> </ul> -<p>You can launch the Android Market application or web site in the following ways:</p> +<p>You can launch the Google Play application or web site in the following ways:</p> <ul> <li>Initiate an {@link android.content.Intent} from your application that launches the -Android Market application on the user's device.</li> - <li>Provide a link on a web page that opens the Android Market web site (but will also -open the Android Market application if clicked from a device).</li> +Google Play application on the user's device.</li> + <li>Provide a link on a web page that opens the Google Play web site (but will also +open the Google Play application if clicked from a device).</li> </ul> <p>In both cases, whether you want to initiate the action from your application or from a web page, the URIs are quite similar. The only difference is the URI prefix.</p> -<p>To open the Android Market application from your application, the prefix for the intent's data +<p>To open the Google Play application from your application, the prefix for the intent's data URI is:</p> <p style="margin-left:2em"><code>market://</code></p> -<p>To open Android Market from your web site, the prefix for the link URI is:</p> +<p>To open Google Play store from your web site, the prefix for the link URI is:</p> -<p style="margin-left:2em"><code>http://market.android.com/</code></p> +<p style="margin-left:2em"><code>http://play.google.com/store/</code></p> <p>The following sections describe how to create a complete URI for each action.</p> -<p class="note"><strong>Note:</strong> If you create a link to open Android Market from your web -site and the user selects it from an Android-powered device, the device's Market application will -resolve the link so the user can use the Market application instead of opening the web -site. As such, you should always use {@code http://market.android.com/} URIs when creating a link on +<p class="note"><strong>Note:</strong> If you create a link to open Google Play from your web +site and the user selects it from an Android-powered device, the device's Google Play application will +resolve the link so the user can use the Google Play application on the device instead of opening the web +site. As such, you should always use {@code http://play.google.com/store/apps/...} URIs when +creating a link on a web page. When pointing to your apps from within your Android app, use the -{@code market://} URIs in an intent, so that the Market application always opens.</p> +{@code market://} URIs in an intent, so that the Google Play application always opens.</p> <h3 id="OpeningDetails">Opening an app's details page</h3> <p>As described above, you can open the details page for a specific application either on the -Android Market application or the Android Market web site. The details page allows the user to see +Google Play application or the Google Play web site. The details page allows the user to see the application description, screenshots, reviews and more, and choose to install it.</p> <p>The format for the URI that opens the details page is:</p> -<p style="margin-left:2em"><code><URI_prefix><b>details?id=</b><package_name></code></p> +<p style="margin-left:2em"><code><URI_prefix><b>apps/details?id=</b><package_name></code></p> <p>The <code><package_name></code> is a placeholder for the target application's fully-qualified package name, as declared in the <a @@ -210,26 +342,28 @@ href="{@docRoot}guide/topics/manifest/manifest-element.html#package">{@code package}</a> attribute of the <a href="{@docRoot}guide/topics/manifest/manifest-element.html">{@code <manifest>}</a> element.</p> +<p>For example: <code>http://play.google.com/store/apps/details?id=com.example.myapp</code></p> + <h4>Opening the app details page from your Android app</h4> -<p>To open the Android Market details page from your application, +<p>To open the Google Play details page from your application, create an intent with the {@link android.content.Intent#ACTION_VIEW} action and include a data URI in this format:</p> <p style="margin-left:2em"><code>market://details?id=<package_name></code></p> <p>For example, here's how you can create an intent and open an application's details page in -Android Market:</p> +Google Play:</p> <pre> Intent intent = new Intent(Intent.ACTION_VIEW); -intent.setData(Uri.parse("market://details?id=com.android.example")); +intent.setData(Uri.parse("market://details?id=com.example.android")); startActivity(intent); </pre> -<p>This will open the Android Market application on the device to view the {@code -com.android.example} application.</p> +<p>This will open the Google Play application on the device to view the {@code +com.example.android} application.</p> <h4>Opening the app details page from a web site</h4> @@ -238,32 +372,32 @@ com.android.example} application.</p> format:</p> <p style="margin-left:2em"> - <code>http://market.android.com/details?id=<package_name></code> + <code>http://play.google.com/store/apps/details?id=<package_name></code> </p> -<p>For example, here's a link that opens an application's details page on Android Market:</p> +<p>For example, here's a link that opens an application's details page on Google Play:</p> <pre> -<a href="http://market.android.com/details?id=com.android.example">App Link</a> +<a href="http://play.google.com/store/apps/details?id=com.example.android">App Link</a> </pre> -<p>When clicked from a desktop web browser, this opens the Android Market web site to view the -{@code com.android.example} application. When clicked from an Android-powered device, users are -given the option to use either their web browser or the Android Market application to view the +<p>When clicked from a desktop web browser, this opens the Google Play web site to view the +{@code com.example.android} application. When clicked from an Android-powered device, users are +given the option to use either their web browser or the Google Play application to view the application.</p> <h3 id="PerformingSearch">Performing a search</h3> -<p>To initiate a search in Android Market, the format for the URI is:</p> +<p>To initiate a search on Google Play, the format for the URI is:</p> <p style="margin-left:2em"> <code><URI_prefix><b>search?q=</b><query></code> </p> -<p>The <code><query></code> is a placeholder for the search query to execute in Android -Market. The query can be a raw text string or you can include a parameter that performs a search +<p>The <code><query></code> is a placeholder for the search query to execute in Google +Play. The query can be a raw text string or you can include a parameter that performs a search based on the publisher name:</p> <ul> @@ -279,14 +413,14 @@ by the publisher name: <h4>Searching from your Android app</h4> -<p>To initiate a search on Android Market from your application, create an intent with the +<p>To initiate a search on Google Play from your application, create an intent with the {@link android.content.Intent#ACTION_VIEW} action and include a data URI in this format:</p> <p style="margin-left:2em"><code>market://search?q=<query></code></p> <p>The query may include the {@code pub:} parameter described above.</p> -<p>For example, here's how you can initiate a search in the Android Market application, based on the +<p>For example, here's how you can initiate a search in the Google Play application, based on the publisher name:</p> <pre> @@ -295,49 +429,49 @@ intent.setData(Uri.parse("market://search?q=pub:Your Publisher Name")); startActivity(intent); </pre> -<p>This opens the Android Market application to perform the search. The search result shows all +<p>This opens the Google Play application to perform the search. The search result shows all applications published by the publisher that are compatible with the current device.</p> <h4>Searching from a web site</h4> -<p>To initiate a search on Android Market from your web site, create a link with a URI in this +<p>To initiate a search on Google Play from your web site, create a link with a URI in this format:</p> <p style="margin-left:2em"> - <code>http://market.android.com/search?q=<query></code> + <code>http://play.google.com/store/search?q=<query></code> </p> <p>The query may include the {@code pub:} parameter described above.</p> -<p>For example, here's a link that initiates a search on Android Market, based on the +<p>For example, here's a link that initiates a search on Google Play, based on the publisher name:</p> <pre> -<a href="http://market.android.com/search?q=pub:Your Publisher Name">Search Link</a> +<a href="http://play.google.com/store/search?q=pub:Your Publisher Name">Search Link</a> </pre> -<p>When clicked from a desktop web browser, this opens the Android Market web site and performs the +<p>When clicked from a desktop web browser, this opens the Google Play web site and performs the search. When clicked from an Android-powered device, users are given the option to use either their -web browser or the Android Market application to perform the search.</p> +web browser or the Google Play application to perform the search.</p> -<h3 id="BuildaButton">Build an Android Market button</h3> +<h3 id="BuildaButton">Build a Google Play button</h3> -<p>Use the following form to generate an "Available in Android Market" button that you can use on -your web site. Input either your application's package name or publisher name and the button will -take users to Android Market to either view your application's information or view a list of -your published apps. If users click the button while on an Android-powered device, the Android -Market application will respond to show users your application(s).</p> +<p>Use the following form to create a button for your web site that takes users to your application +on Google Play. Input either your application's package name or your publisher name and the button +will take users to Google Play to either view your application's information or view a list of your +published apps. If users click the button while on an Android-powered device, the Google Play +application will respond to show users your application(s).</p> -<p>This form offers four versions of the official "Available in Android Market" button at -recommended sizes. If you want to create a different size, you can download an EPS file for -the button images from the <a href="http://www.android.com/branding.html">Android Brand -Guidelines</a>.</p> +<p>This form offers two styles of the official brand badge each at recommended sizes. You can pick +between either "Get it on Google Play" or "Android app on Google Play." You should not modify the +badge images in any way. For more usage guidelines, +see the <a href="http://www.android.com/branding.html">Android Brand Guidelines</a>.</p> <style type="text/css"> - + form.button-form { margin-top:2em; } @@ -376,33 +510,44 @@ div.button-row input { // variables for creating 'try it out' demo button var imagePath = "http://www.android.com/images/brand/" -var linkStart = "<a href=\"http://market.android.com/"; +var linkStart = "<a href=\"http://play.google.com/store/"; var imageStart = "\">\n" - + " <img src=\"" + imagePath; -var imageEnd = ".png\"\n" - + " alt=\"Available in Android Market\" />\n</a>"; + + " <img alt=\""; + // leaves opening for the alt text value +var imageSrc = "\"\n src=\"" + imagePath; + // leaves opening for the image file name +var imageEnd = ".png\" />\n</a>"; // variables for creating code snippet -var linkStartCode = "<a href=\"http://market.android.com/"; +var linkStartCode = "<a href=\"http://play.google.com/store/"; var imageStartCode = "\">\n" - + " <img src=\"" + imagePath; -var imageEndCode = ".png\"\n" - + " alt=\"Available in Android Market\" />\n</a>"; + + " <img alt=\""; + // leaves opening for the alt text value +var imageSrcCode = "\"\n src=\"" + imagePath; + // leaves opening for the image file name +var imageEndCode = ".png\" />\n</a>"; /** Generate the HTML snippet and demo based on form values */ function buildButton(form) { - if (form["package"].value != "com.android.example") { + var selectedValue = $('form input[type=radio]:checked').val(); + var altText = selectedValue.indexOf("get_it") != -1 ? "Get it on Google Play" : "Android app on Google Play"; + + if (form["package"].value != "com.example.android") { $("#preview").show(); - $("#snippet").show().html(linkStartCode + "details?id=" + form["package"].value - + imageStartCode + $('form input[type=radio]:checked').val() + imageEndCode); - $("#button-preview").html(linkStart + "details?id=" + form["package"].value - + imageStart + $('form input[type=radio]:checked').val() + imageEnd); + $("#snippet").show().html(linkStartCode + "apps/details?id=" + form["package"].value + + imageStartCode + altText + imageSrcCode + + selectedValue + imageEndCode); + $("#button-preview").html(linkStart + "apps/details?id=" + form["package"].value + + imageStart + altText + imageSrc + + selectedValue + imageEnd); } else if (form["publisher"].value != "Example, Inc.") { $("#preview").show(); $("#snippet").show().html(linkStartCode + "search?q=pub:" + form["publisher"].value - + imageStartCode + $('form input[type=radio]:checked').val() + imageEndCode); - $("#button-preview").html(linkStart + "search?q=pub:" + form["publisher"].value + imageStart + - $('form input[type=radio]:checked').val() + imageEnd); + + imageStartCode + altText + imageSrcCode + + selectedValue + imageEndCode); + $("#button-preview").html(linkStart + "search?q=pub:" + form["publisher"].value + + imageStart + altText + imageSrc + + selectedValue + imageEnd); } else { alert("Please enter your package name or publisher name"); } @@ -466,13 +611,13 @@ $(document).ready(function() { <form class="button-form"> <label class="block" for="package">Package name:</label> <input class="text" type="text" id="package" name="package" - value="com.android.example" - default="com.android.example" - onfocus="onInputFocus(this, 'com.android.example')" - onblur="onInputBlur(this, 'com.android.example')" + value="com.example.android" + default="com.example.android" + onfocus="onInputFocus(this, 'com.example.android')" + onblur="onInputBlur(this, 'com.example.android')" onkeyup="return onTextEntered(event, this.parentNode, this)"/> <a id="package-clear" style="display:none" href="#" - onclick="return clearLabel('package','com.android.example');">clear</a> + onclick="return clearLabel('package','com.example.android');">clear</a> <p style="clear:both;margin:0"> <em>or</em></p> <label class="block" style="margin-top:5px" for="publisher">Publisher name:</label> <input class="text" type="text" id="publisher" name="publisher" @@ -486,23 +631,23 @@ $(document).ready(function() { <br/><br/> <div class="button-row"> - <input type="radio" name="buttonStyle" value="45_avail_market_logo1" id="ns" checked="checked" /> - <label for="ns"><img src="http://www.android.com/images/brand/45_avail_market_logo1.png" -alt="narrow and small logo" /></label> + <input type="radio" name="buttonStyle" value="get_it_on_play_logo_small" id="ns" checked="checked" /> + <label for="ns"><img src="http://www.android.com/images/brand/get_it_on_play_logo_small.png" +alt="Get it on Google Play (small)" /></label> - <input type="radio" name="buttonStyle" value="60_avail_market_logo1" id="nm" /> - <label for="nm"><img src="http://www.android.com/images/brand/60_avail_market_logo1.png" -alt="narrow and large logo" /></label> + <input type="radio" name="buttonStyle" value="get_it_on_play_logo_large" id="nm" /> + <label for="nm"><img src="http://www.android.com/images/brand/get_it_on_play_logo_large.png" +alt="Get it on Google Play (large)" /></label> </div> <div class="button-row"> - <input type="radio" name="buttonStyle" value="45_avail_market_logo2" id="ws" /> - <label for="ws"><img src="http://www.android.com/images/brand/45_avail_market_logo2.png" -alt="wide and small logo" /></label> + <input type="radio" name="buttonStyle" value="android_app_on_play_logo_small" id="ws" /> + <label for="ws"><img src="http://www.android.com/images/brand/android_app_on_play_logo_small.png" +alt="Android app on Google Play (small)" /></label> - <input type="radio" name="buttonStyle" value="60_avail_market_logo2" id="wm" /> - <label for="wm"><img src="http://www.android.com/images/brand/60_avail_market_logo2.png" -alt="wide and large logo" /></label> + <input type="radio" name="buttonStyle" value="android_app_on_play_logo_large" id="wm" /> + <label for="wm"><img src="http://www.android.com/images/brand/android_app_on_play_logo_large.png" +alt="Android app on Google Play (large)" /></label> </div> <input type="button" onclick="return buildButton(this.parentNode)" value="Build my button" @@ -512,7 +657,7 @@ style="padding:5px" /> <div id="preview" style="display:none"> <p>Copy and paste this HTML into your web site:</p> - <textarea id="snippet" cols="80" rows="4" onclick="this.select()" + <textarea id="snippet" cols="100" rows="5" onclick="this.select()" style="font-family:monospace;background-color:#efefef;padding:5px;display:none;margin-bottom:1em"> </textarea > @@ -527,7 +672,7 @@ style="font-family:monospace;background-color:#efefef;padding:5px;display:none;m <h3 id="UriSummary">Summary of URI formats</h3> -<p>The table below provides a summary of the URIs currently supported by the Android Market (both on +<p>The table below provides a summary of the URIs currently supported by the Google Play (both on the web and in the Android application), as discussed in the previous sections.</p> <table> @@ -539,19 +684,19 @@ the web and in the Android application), as discussed in the previous sections.< <tr> <td>Display the details screen for a specific application</td> -<td><code>http://market.android.com/details?id=<package_name></code> +<td><code>http://play.google.com/store/apps/details?id=<package_name></code> <td><code>market://details?id=<package_name></code></td> </tr> <tr> <td>Search for applications using a general string query.</td> -<td><code>http://market.android.com/search?q=<query></code></td> +<td><code>http://play.google.com/store/search?q=<query></code></td> <td><code>market://search?q=<query></code></td> </tr> <tr> <td>Search for applications by publisher name</td> -<td><nobr><code>http://market.android.com/search?q=pub:<publisher_name></code></nobr></td> +<td><nobr><code>http://play.google.com/store/search?q=pub:<publisher_name></code></nobr></td> <td><nobr><code>market://search?q=pub:<publisher_name></code></nobr></td> </tr> diff --git a/docs/html/guide/publishing/publishing_overview.jd b/docs/html/guide/publishing/publishing_overview.jd index a0f6ae3..6fb77e1 100755 --- a/docs/html/guide/publishing/publishing_overview.jd +++ b/docs/html/guide/publishing/publishing_overview.jd @@ -14,16 +14,16 @@ page.title=Publishing Overview <li><a href="#publishing-prepare">Preparing Your Application for Release</a></li> <li><a href="#publishing-release">Releasing Your Application to Users</a> <ol> - <li><a href="#publishing-market">Releasing on Android Market</a></li> + <li><a href="#publishing-market">Releasing on Google Play</a></li> <li><a href="#publishing-website">Releasing on your own website</a></li> <li><a href="#publishing-email">Releasing through email</a></li> </ol> </ol> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/publishing/publishing_preparing.html">Preparing for + <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing for Release</a></li> - <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li> + <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a></li> </ol> </div> </div> @@ -42,7 +42,7 @@ publish an Android application you perform two main tasks:</p> </li> </ul> -<p>Usually, you release your application through an application marketplace, such as Android Market. +<p>Usually, you release your application through an application marketplace, such as Google Play. However, you can also release applications by sending them directly to users or by letting users download them from your own website.</p> @@ -73,7 +73,7 @@ tasks:</p> <code>android:versionCode</code> and <code>android:versionName</code> attributes, which are located in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> - element. You may also have to configure several other settings to meet Android Market + element. You may also have to configure several other settings to meet Google Play requirements or accomodate whatever method you're using to release your application.</p> </li> <li>Building and signing a release version of your application. @@ -114,27 +114,27 @@ application.</p> <h2 id="publishing-release">Releasing Your Application to Users</h2> <p>You can release your Android applications several ways. Usually, you release applications -through an application marketplace, such as Android Market, but you can also release applications -on your own website or by sending an application directly to a user. Android Market is the +through an application marketplace, such as Google Play, but you can also release applications +on your own website or by sending an application directly to a user. Google Play is the recommended marketplace for Android applications and is particularly useful if you want to distribute your applications to a large global audience. The other two release methods—server distribution and email distribution—are useful if you are releasing an application to a small group of users (for example, a work group in an enterprise environment), or if you do not want to make your application available to the general public.</p> -<h3 id="publishing-market">Releasing Your Applications on Android Market</h3> +<h3 id="publishing-market">Releasing Your Applications on Google Play</h3> -<p>Android Market is a robust publishing platform that helps you publicize, sell, and distribute +<p>Google Play is a robust publishing platform that helps you publicize, sell, and distribute your Android applications to users around the world. When you release your applications through -Android Market you have access to a suite of developer tools that let you analyze your sales, +Google Play you have access to a suite of developer tools that let you analyze your sales, identify market trends, and control who your applications are being distributed to. You also have access to several revenue-enhancing features that are not available anywhere else, such as <a href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and <a -href="{@docRoot}guide/publishing/licensing.html">application licensing</a>. This rich array of tools -and features, coupled with numerous end-user community features, makes Android Market the premier +href="{@docRoot}guide/market/licensing.html">application licensing</a>. This rich array of tools +and features, coupled with numerous end-user community features, makes Google Play the premier marketplace for selling and buying Android applications.</p> -<p>Releasing your application on Android Market is a simple process that involves four basic +<p>Releasing your application on Google Play is a simple process that involves three basic steps:</p> <div class="figure" style="width:275px"> @@ -143,52 +143,47 @@ marketplace for selling and buying Android applications.</p> to be installed" /> <p class="img-caption"> <strong>Figure 2.</strong> The <strong>Unknown sources</strong> setting lets you install - applications that are not published on Android Market . + applications that are not published on Google Play . </p> </div> <ul> <li>Preparing promotional materials. - <p>To fully leverage the marketing and publicity capabilities of Android Market, you need to + <p>To fully leverage the marketing and publicity capabilities of Google Play, you need to create promotional materials for your application, such as screenshots, videos, graphics, and promotional text.</p> </li> - <li>Planning publishing options. - <p>Android Market lets you target your application to a worldwide pool of users and devices. - Using various Android Market tools, you can choose the countries you want to reach, the - price you want to charge in each country, and the devices you want to target. You can also - use Android Market's filtering settings to target specific device features and capabilities.</p> - </li> - <li>Configuring publishing options and uploading assets. - <p>After you create your promotional materials and determine which publishing options are - suitable for your application, you can use the Android Market developer console to configure - those options and upload the promotional materials. You can also use the developer console to - upload your application as a draft (unpublished) application, which lets you do final - testing before you publish it for final release.</p> + <li>Configuring options and uploading assets. + <p>Google Play lets you target your application to a worldwide pool of users and devices. + By configuring various Google Play settings, you can choose the countries you want to + reach, the listing languages you want to use, and the price you want to charge in each + country. You can also configure listing details such as the application type, category, and + content rating. When you are done configuring options you can upload your promotional materials + and your application as a draft (unpublished) application.</p> </li> <li>Publishing the release version of your application. - <p>When you are satisfied that your publishing settings are correctly configured and your + <p>If you are satisfied that your publishing settings are correctly configured and your uploaded application is ready to be released to the public, you can simply click <strong>Publish</strong > in the developer console and within minutes your application will be live and available for download around the world.</p> </li> </ul> -<p>For information about Android Market, see <a -href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Android Market</a>. This -topic provides an introduction to Android Market features and provides a step-by-step guide for -distributing your applications on Android Market.</p> +<p>For information about Google Play, see <a +href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Google Play</a>. This +topic provides an introduction to Google Play features and provides a step-by-step guide for +distributing your applications on Google Play.</p> <h3 id="publishing-website">Releasing your application on your own website</h3> -<p>If you do not want to release your application on an application marketplace like Android Market, +<p>If you do not want to release your application on an application marketplace like Google Play, you can release your application by making it available for download on your own website or server. To do this, you must first prepare your application for release (that is, you must build it for release and sign it). Then all you need to do is host the release-ready application on your website and provide a download link for the application. When users browse to your website with their Android-powered devices and download your application, the Android system will automatically start installing the application on the device. However, the installation process will start automatically -only if the user has configured their device to allow the installation of non-Android Market +only if the user has configured their device to allow the installation of non-Google Play applications.</p> <div class="figure" style="width:275px"> @@ -202,7 +197,7 @@ applications.</p> </div> <p>By default, Android-powered devices allow users to install applications only if the applications -have been downloaded from Android Market. To allow the installation of applications from other +have been downloaded from Google Play. To allow the installation of applications from other sources, users need to enable the <strong>Unknown sources</strong> setting on their devices, and they need to make this configuration change before they download your application to their device (see figure 2).</p> @@ -213,7 +208,7 @@ applications from unknown sources.</p> <p>Although it is relatively easy to release your application on your own website, it can be inefficient and cumbersome. For example, if you want to monetize your application you will have to process and track all financial transactions yourself and you will not be able to use -Android Market's in-app billing feature to sell in-app products. In addition, you will not be +Google Play's in-app billing feature to sell in-app products. In addition, you will not be able to use the licensing feature to help prevent unauthorized installation and use of your application.</p> @@ -227,10 +222,10 @@ button in the email message (see figure 3). Users can install your application b button.</p> <p class="note"><strong>Note:</strong> The <strong>Install Now</strong> button appears only if a -user has configured their device to allow the installation of non-Android Market applications and +user has configured their device to allow the installation of non-Google Play applications and they open your email with the native Gmail application.</p> <p>Releasing applications through email is convenient if you are sending your application to only a few trusted users, but it provides few protections from piracy and unauthorized distribution; that is, anyone you send your application to can simply forward it to someone else. -else.
\ No newline at end of file +else. diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd index 79ebf96..da57e3e 100644 --- a/docs/html/guide/publishing/versioning.jd +++ b/docs/html/guide/publishing/versioning.jd @@ -25,7 +25,7 @@ page.title=Versioning Your Applications <ol> <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li> -<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Android Market</a></li> +<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Google Play</a></li> <li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> </ol> diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd index 820c3c0..4a325db 100644 --- a/docs/html/guide/topics/admin/device-admin.jd +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -75,8 +75,8 @@ server. </li> not currently have an automated provisioning solution. Some of the ways a sysadmin might distribute the application to users are as follows: <ul> -<li>Android Market.</li> -<li>Enabling non-market installation.</li> +<li>Google Play.</li> +<li>Enabling installation from another store.</li> <li>Distributing the application through other means, such as email or websites.</li> </ul> diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index 2cb23c1..ba7b67c 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -186,36 +186,34 @@ folder.</p> <p>Here's a summary of the <code><appwidget-provider></code> attributes:</p> <ul> <li>The values for the <code>minWidth</code> and <code>minHeight</code> -attributes specify the minimum - area required by the App Widget's layout. - <p>The default Home screen positions App Widgets in its window based on a -grid of - cells that have a defined height and width. If the values for an App -Widget's minimum width - or height don't match the dimensions of the cells, - then the App Widget dimensions round <em>up</em> to the nearest cell size. - (See the <a -href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">App Widget -Design - Guidelines</a> for more information on the Home screen cell sizes.)</p> - <p>Because the Home screen's layout orientation (and thus, the cell sizes) -can change, - as a rule of thumb, you should assume the worst-case cell size of 74 pixels -for the height - <em>and</em> width of a cell. However, you must subtract 2 from the final -dimension to account - for any integer rounding errors that occur in the pixel count. To find your -minimum width - and height in density-independent pixels (dp), use this formula:<br/> - <code>(number of cells * 74) - 2</code><br/> - Following this formula, you should use 72 dp for a height of one cell, 294 -dp and for a width of four cells.</p> -<p class="note"><strong>Note:</strong> To make your app widget portable across -devices, your app widget's minimum size should never be larger than 4 x 4 cells. -See the <a -href="{@docRoot}guide/practices/ui_guidelines/widget_design.html#sizes">App -Widget Design Guidelines</a> for more discussion of Home screen cell sizes.</p> + attributes specify the minimum amount of space the App Widget consumes + <em>by default</em>. The default Home screen positions App Widgets in its + window based on a grid of cells that have a defined height and width. If + the values for an App Widget's minimum width or height don't match the + dimensions of the cells, then the App Widget dimensions round + <em>up</em> to the nearest cell size. + <p>See the <a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html#anatomy_determining_size"> + App Widget Design Guidelines</a> for more information on sizing your App + Widgets.</p> + + <p class="note"><strong>Note:</strong> To make your app widget portable + across devices, your app widget's minimum size should never be larger + than 4 x 4 cells.</p> </li> + + <li>The <code>minResizeWidth</code> and <code>minResizeHeight</code> attributes + specify the App Widget's absolute minimum size. These values should specify + the size below which the App Widget would be illegible or otherwise unusable. + Using these attributes allows the user to resize the widget to a size that + may be smaller than the default widget size defined by the + <code>minWidth</code> and <code>minHeight</code> attributes. + Introduced in Android 3.1. + + <p>See the <a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html#anatomy_determining_size"> + App Widget Design Guidelines</a> for more information on sizing your App + Widgets.</p> + </li> + <li>The <code>updatePeriodMillis</code> attribute defines how often the App Widget framework should request an update from the {@link android.appwidget.AppWidgetProvider} by calling the @@ -520,15 +518,12 @@ method. From within the Service, you can perform your own updates to the App Widget without worrying about the AppWidgetProvider closing down due to an <a href="{@docRoot}guide/practices/design/responsiveness.html">Application Not Responding</a> (ANR) error. See the <a -href="http://code.google.com/p/wiktionary-android/source/browse/trunk/Wiktionary -/src/com/example/android/wiktionary/WordWidget.java">Wiktionary sample's -AppWidgetProvider</a> for an example of an App Widget running a {@link +href="http://code.google.com/p/wiktionary-android/source/browse/trunk/Wiktionary/src/com/example/android/wiktionary/WordWidget.java">Wiktionary sample's AppWidgetProvider</a> for an example of an App Widget running a {@link android.app.Service}.</p> <p>Also see the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/ -appwidget/ExampleAppWidgetProvider.html"> -ExampleAppWidgetProvider.java</a> sample class.</p> +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.html">ExampleAppWidgetProvider.java</a> +sample class.</p> <h3 id="ProviderBroadcasts">Receiving App Widget broadcast Intents</h3> @@ -685,9 +680,8 @@ cancelled and the App Widget will not be added.</p> <p>See the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/ -appwidget/ExampleAppWidgetConfigure.html"> -ExampleAppWidgetConfigure.java</a> sample class in ApiDemos for an example.</p> +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.html">ExampleAppWidgetConfigure.java</a> +sample class in ApiDemos for an example.</p> <h2 id="preview">Setting a Preview Image</h2> diff --git a/docs/html/guide/topics/data/backup.jd b/docs/html/guide/topics/data/backup.jd index dec2146..4eba4f3 100644 --- a/docs/html/guide/topics/data/backup.jd +++ b/docs/html/guide/topics/data/backup.jd @@ -900,8 +900,8 @@ href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr}</a>.</p> <li>Install your application on a suitable Android system image <ul> <li>If using the emulator, create and use an AVD with Android 2.2 (API Level 8).</li> - <li>If using a device, the device must be running Android 2.2 or greater and have Android -Market built in.</li> + <li>If using a device, the device must be running Android 2.2 or greater and have Google +Play built in.</li> </ul> </li> <li>Ensure that backup is enabled diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd index 661f5cb..a86d905 100644 --- a/docs/html/guide/topics/fundamentals.jd +++ b/docs/html/guide/topics/fundamentals.jd @@ -243,7 +243,7 @@ performing transactions with the provider doesn't need to and instead calls meth android.content.ContentResolver} object. This leaves a layer of abstraction between the content provider and the component requesting information (for security).</p> -<p>There are separate methods for activiting each type of component:</p> +<p>There are separate methods for activating each type of component:</p> <ul> <li>You can start an activity (or give it something new to do) by passing an {@link android.content.Intent} to {@link android.content.Context#startActivity @@ -392,15 +392,15 @@ same features and capabilities. In order to prevent your application from being that lack features needed by your application, it's important that you clearly define a profile for the types of devices your application supports by declaring device and software requirements in your manifest file. Most of these declarations are informational only and the system does not read -them, but external services such as Android Market do read them in order to provide filtering +them, but external services such as Google Play do read them in order to provide filtering for users when they search for applications from their device.</p> <p>For example, if your application requires a camera and uses APIs introduced in Android 2.1 (<a href="{@docRoot}guide/appendix/api-levels.html">API Level</a> 7), you should declare these as requirements in your manifest file. That way, devices that do <em>not</em> have a camera and have an -Android version <em>lower</em> than 2.1 cannot install your application from Android Market.</p> +Android version <em>lower</em> than 2.1 cannot install your application from Google Play.</p> -<p>However, you can also declare that your applicaiton uses the camera, but does not +<p>However, you can also declare that your application uses the camera, but does not <em>require</em> it. In that case, your application must perform a check at runtime to determine if the device has a camera and disable any features that use the camera if one is not available.</p> @@ -458,12 +458,12 @@ element.</dd> </dl> <p>It's important that you declare all such requirements for your application, because, when you -distribute your application on Android Market, Market uses these declarations to filter which +distribute your application on Google Play, the store uses these declarations to filter which applications are available on each device. As such, your application should be available only to devices that meet all your application requirements.</p> -<p>For more information about how Android Market filters applications based on these (and other) -requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a> +<p>For more information about how Google Play filters applications based on these (and other) +requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> document.</p> diff --git a/docs/html/guide/topics/fundamentals/activities.jd b/docs/html/guide/topics/fundamentals/activities.jd index cb453da..b79136c 100644 --- a/docs/html/guide/topics/fundamentals/activities.jd +++ b/docs/html/guide/topics/fundamentals/activities.jd @@ -19,9 +19,10 @@ page.title=Activities </li> <li><a href="#StartingAnActivity">Starting an Activity</a> <ol> - <li><a href="#StartingAnActivityForResult">Starting an Activity for a Result</a></li> + <li><a href="#StartingAnActivityForResult">Starting an activity for a result</a></li> </ol> </li> + <li><a href="#ShuttingDown">Shutting Down an Activity</a></li> <li><a href="#Lifecycle">Managing the Activity Lifecycle</a> <ol> <li><a href="#ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</a></li> @@ -61,8 +62,8 @@ is presented to the user when launching the application for the first time. Each activity can then start another activity in order to perform different actions. Each time a new activity starts, the previous activity is stopped, but the system preserves the activity in a stack (the "back stack"). When a new activity starts, it is pushed onto the back stack and -takes user focus. The back stack abides to the basic "last in, first out" queue mechanism, -so, when the user is done with the current activity and presses the BACK key, it +takes user focus. The back stack abides to the basic "last in, first out" stack mechanism, +so, when the user is done with the current activity and presses the <em>Back</em> button, it is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is discussed more in the <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a> document.)</p> @@ -612,17 +613,9 @@ that when an activity is paused or stopped, the state of the activity is retained. This is true because the {@link android.app.Activity} object is still held in memory when it is paused or stopped—all information about its members and current state is still alive. Thus, any changes -the user made within the activity are retained in memory, so that when the activity returns to the +the user made within the activity are retained so that when the activity returns to the foreground (when it "resumes"), those changes are still there.</p> -<div class="figure" style="width:615px"> -<img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> -<p class="img-caption"><strong>Figure 2.</strong> The two ways in which an activity returns to user -focus with its state intact: either the activity is stopped, then resumed and the activity state -remains intact (left), or the activity is destroyed, then recreated and the activity must restore -the previous activity state (right).</p> -</div> - <p>However, when the system destroys an activity in order to recover memory, the {@link android.app.Activity} object is destroyed, so the system cannot simply resume it with its state intact. Instead, the system must recreate the {@link android.app.Activity} object if the user @@ -630,26 +623,36 @@ navigates back to it. Yet, the user is unaware that the system destroyed the activity and recreated it and, thus, probably expects the activity to be exactly as it was. In this situation, you can ensure that important information about the activity state is preserved by implementing an additional -callback method that allows you to save information about the state of your activity and then -restore it when the the system recreates the activity.</p> +callback method that allows you to save information about the state of your activity: {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()}.</p> -<p>The callback method in which you can save information about the current state of your activity is -{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}. The system calls this method -before making the activity vulnerable to being destroyed and passes it -a {@link android.os.Bundle} object. The {@link android.os.Bundle} is where you can store +<p>The system calls {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} +before making the activity vulnerable to destruction. The system passes this method +a {@link android.os.Bundle} in which you can save state information about the activity as name-value pairs, using methods such as {@link -android.os.Bundle#putString putString()}. Then, if the system kills your activity's -process and the user navigates back to your activity, the system passes the {@link -android.os.Bundle} to {@link android.app.Activity#onCreate onCreate()} so you can restore the -activity state you saved during {@link android.app.Activity#onSaveInstanceState -onSaveInstanceState()}. If there is no state information to restore, then the {@link -android.os.Bundle} passed to {@link android.app.Activity#onCreate onCreate()} is null.</p> +android.os.Bundle#putString putString()} and {@link +android.os.Bundle#putInt putInt()}. Then, if the system kills your application +process and the user navigates back to your activity, the system recreates the activity and passes +the {@link android.os.Bundle} to both {@link android.app.Activity#onCreate onCreate()} and {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}. Using either of these +methods, you can extract your saved state from the {@link android.os.Bundle} and restore the +activity state. If there is no state information to restore, then the {@link +android.os.Bundle} passed to you is null (which is the case when the activity is created for +the first time).</p> + +<img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> The two ways in which an activity returns to user +focus with its state intact: either the activity is destroyed, then recreated and the activity must restore +the previously saved state, or the activity is stopped, then resumed and the activity state +remains intact.</p> <p class="note"><strong>Note:</strong> There's no guarantee that {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} will be called before your activity is destroyed, because there are cases in which it won't be necessary to save the state -(such as when the user leaves your activity using the BACK key, because the user is explicitly -closing the activity). If the method is called, it is always called before {@link +(such as when the user leaves your activity using the <em>Back</em> button, because the user is +explicitly +closing the activity). If the system calls {@link android.app.Activity#onSaveInstanceState +onSaveInstanceState()}, it does so before {@link android.app.Activity#onStop onStop()} and possibly before {@link android.app.Activity#onPause onPause()}.</p> @@ -657,17 +660,17 @@ onPause()}.</p> android.app.Activity#onSaveInstanceState onSaveInstanceState()}, some of the activity state is restored by the {@link android.app.Activity} class's default implementation of {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}. Specifically, the default -implementation calls {@link -android.view.View#onSaveInstanceState onSaveInstanceState()} for every {@link android.view.View} -in the layout, which allows each view to provide information about itself +implementation calls the corresponding {@link +android.view.View#onSaveInstanceState onSaveInstanceState()} method for every {@link +android.view.View} in the layout, which allows each view to provide information about itself that should be saved. Almost every widget in the Android framework implements this method as appropriate, such that any visible changes to the UI are automatically saved and restored when your activity is recreated. For example, the {@link android.widget.EditText} widget saves any text entered by the user and the {@link android.widget.CheckBox} widget saves whether it's checked or not. The only work required by you is to provide a unique ID (with the <a href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">{@code android:id}</a> -attribute) for each widget you want to save its state. If a widget does not have an ID, then it -cannot save its state.</p> +attribute) for each widget you want to save its state. If a widget does not have an ID, then the +system cannot save its state.</p> <div class="sidebox-wrapper"> <div class="sidebox"> @@ -689,7 +692,9 @@ restored, by default).</p> android.app.Activity#onSaveInstanceState onSaveInstanceState()} helps save the state of the UI, if you override the method in order to save additional state information, you should always call the superclass implementation of {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} -before doing any work.</p> +before doing any work. Likewise, you should also call the supercall implementation of {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} if you override it, so the +default implementation can restore view states.</p> <p class="note"><strong>Note:</strong> Because {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} is not guaranteed @@ -701,7 +706,7 @@ to a database) when the user leaves the activity.</p> <p>A good way to test your application's ability to restore its state is to simply rotate the device so that the screen orientation changes. When the screen orientation changes, the system destroys and recreates the activity in order to apply alternative resources that might be available -for the new orientation. For this reason alone, it's very important that your activity +for the new screen configuration. For this reason alone, it's very important that your activity completely restores its state when it is recreated, because users regularly rotate the screen while using applications.</p> @@ -709,22 +714,25 @@ using applications.</p> <h3 id="ConfigurationChanges">Handling configuration changes</h3> <p>Some device configurations can change during runtime (such as screen orientation, keyboard -availability, and language). When such a change occurs, Android restarts the running Activity -({@link android.app.Activity#onDestroy} is called, followed immediately by {@link -android.app.Activity#onCreate onCreate()}). The restart behavior is +availability, and language). When such a change occurs, Android recreates the running activity +(the system calls {@link android.app.Activity#onDestroy}, then immediately calls {@link +android.app.Activity#onCreate onCreate()}). This behavior is designed to help your application adapt to new configurations by automatically reloading your -application with alternative resources that you've provided. If you design your activity to -properly handle this event, it will be more resilient to unexpected events in the activity -lifecycle.</p> +application with alternative resources that you've provided (such as different layouts for +different screen orientations and sizes).</p> + +<p>If you properly design your activity to handle a restart due to a screen orientation change and +restore the activity state as described above, your application will be more resilient to other +unexpected events in the activity lifecycle.</p> -<p>The best way to handle a configuration change, such as a change in the screen orientation, is - to simply preserve the state of your application using {@link +<p>The best way to handle such a restart is + to save and restore the state of your activity using {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} and {@link android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} (or {@link android.app.Activity#onCreate onCreate()}), as discussed in the previous section.</p> -<p>For a detailed discussion about configuration changes that happen at runtime and how you should -handle them, read <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling +<p>For more information about configuration changes that happen at runtime and how you can handle +them, read the guide to <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>.</p> diff --git a/docs/html/guide/topics/fundamentals/fragments.jd b/docs/html/guide/topics/fundamentals/fragments.jd index d6ba646..e0740aa 100644 --- a/docs/html/guide/topics/fundamentals/fragments.jd +++ b/docs/html/guide/topics/fundamentals/fragments.jd @@ -33,7 +33,7 @@ parent.link=activities.html </li> <li><a href="#Lifecycle">Handling the Fragment Lifecycle</a> <ol> - <li><a href="#CoordinadingWithActivity">Coordinating with the activity lifecycle</a></li> + <li><a href="#CoordinatingWithActivity">Coordinating with the activity lifecycle</a></li> </ol> </li> <li><a href="#Example">Example</a></li> @@ -78,7 +78,7 @@ manipulate each fragment independently, such as add or remove them. When you per fragment transaction, you can also add it to a back stack that's managed by the activity—each back stack entry in the activity is a record of the fragment transaction that occurred. The back stack allows the user to reverse a fragment transaction (navigate backwards), -by pressing the BACK button.</p> +by pressing the <em>Back</em> button.</p> <p>When you add a fragment as a part of your activity layout, it lives in a {@link android.view.ViewGroup} inside the activity's view hierarchy and the fragment defines its own view @@ -129,7 +129,7 @@ handset design.</p> <p>For example—to continue with the news application example—the application can embed two fragments in <em>Activity A</em>, when running on a tablet-sized device. However, on a -handset-sized screen, there's not be enough room for both fragments, so <em>Activity A</em> includes +handset-sized screen, there's not enough room for both fragments, so <em>Activity A</em> includes only the fragment for the list of articles, and when the user selects an article, it starts <em>Activity B</em>, which includes the second fragment to read the article. Thus, the application supports both tablets and handsets by reusing fragments in different combinations, as illustrated in @@ -143,7 +143,7 @@ href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets an <h2 id="Creating">Creating a Fragment</h2> -<div class="figure" style="width:314px"> +<div class="figure" style="width:327px"> <img src="{@docRoot}images/fragment_lifecycle.png" alt="" /> <p class="img-caption"><strong>Figure 2.</strong> The lifecycle of a fragment (while its activity is running).</p> @@ -398,7 +398,7 @@ android.app.FragmentManager#findFragmentById findFragmentById()} (for fragments the activity layout) or {@link android.app.FragmentManager#findFragmentByTag findFragmentByTag()} (for fragments that do or don't provide a UI).</li> <li>Pop fragments off the back stack, with {@link -android.app.FragmentManager#popBackStack()} (simulating a BACK command by the user).</li> +android.app.FragmentManager#popBackStack()} (simulating a <em>Back</em> command by the user).</li> <li>Register a listener for changes to the back stack, with {@link android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li> </ul> @@ -439,7 +439,7 @@ to the activity, you must call {@link android.app.FragmentTransaction#commit()}. android.app.FragmentTransaction#commit()}, however, you might want to call {@link android.app.FragmentTransaction#addToBackStack addToBackStack()}, in order to add the transaction to a back stack of fragment transactions. This back stack is managed by the activity and allows -the user to return to the previous fragment state, by pressing the BACK key.</p> +the user to return to the previous fragment state, by pressing the <em>Back</em> button.</p> <p>For example, here's how you can replace one fragment with another, and preserve the previous state in the back stack:</p> @@ -462,14 +462,14 @@ transaction.commit(); layout container identified by the {@code R.id.fragment_container} ID. By calling {@link android.app.FragmentTransaction#addToBackStack addToBackStack()}, the replace transaction is saved to the back stack so the user can reverse the transaction and bring back the -previous fragment by pressing the BACK key.</p> +previous fragment by pressing the <em>Back</em> button.</p> <p>If you add multiple changes to the transaction (such as another {@link android.app.FragmentTransaction#add add()} or {@link android.app.FragmentTransaction#remove remove()}) and call {@link android.app.FragmentTransaction#addToBackStack addToBackStack()}, then all changes applied before you call {@link android.app.FragmentTransaction#commit commit()} are added to the -back stack as a single transaction and the BACK key will reverse them all together.</p> +back stack as a single transaction and the <em>Back</em> button will reverse them all together.</p> <p>The order in which you add changes to a {@link android.app.FragmentTransaction} doesn't matter, except:</p> @@ -657,7 +657,7 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guides. <h2 id="Lifecycle">Handling the Fragment Lifecycle</h2> -<div class="figure" style="width:403px"> +<div class="figure" style="width:350px"> <img src="{@docRoot}images/activity_fragment_lifecycle.png" alt=""/> <p class="img-caption"><strong>Figure 3.</strong> The activity lifecycle's affect on the fragment lifecycle.</p> @@ -696,7 +696,7 @@ document.</p> <p>The most significant difference in lifecycle between an activity and a fragment is how one is stored in its respective back stack. An activity is placed into a back stack of activities that's managed by the system when it's stopped, by default (so that the user can navigate back -to it with the BACK key, as discussed in <a +to it with the <em>Back</em> button, as discussed in <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>). However, a fragment is placed into a back stack managed by the host activity only when you explicitly request that the instance be saved by calling {@link diff --git a/docs/html/guide/topics/fundamentals/loaders.jd b/docs/html/guide/topics/fundamentals/loaders.jd index 3aad204..ddd513b 100644 --- a/docs/html/guide/topics/fundamentals/loaders.jd +++ b/docs/html/guide/topics/fundamentals/loaders.jd @@ -491,7 +491,7 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/Load LoaderCursor</a> — A complete version of the snippet shown above.</li> <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> — An example of how to use throttling to -reduce the number of queries a content provider does then its data changes.</li> +reduce the number of queries a content provider does when its data changes.</li> </ul> <p>For information on downloading and installing the SDK samples, see <a diff --git a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd index 216420c..0880614 100644 --- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd +++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd @@ -34,7 +34,9 @@ to perform other tasks without losing their work</li> <h2>See also</h2> <ol> - <li><a><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> + <li><a href="{@docRoot}design/patterns/navigation.html">Android Design: +Navigation</a></li> + <li><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> <li><a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>} manifest element</a></li> @@ -72,7 +74,7 @@ order in which each activity is opened.</p> suppose you have a two-pane layout using fragments, one of which is a list view (fragment A) and the other being a layout to display an item from the list (fragment B). When the user selects an item from the list, fragment B is replaced by a new fragment (fragment C). In this case, it might be -desireable for the user to navigate back to reveal fragment B, using the BACK key.</p> +desireable for the user to navigate back to reveal fragment B, using the <em>Back</em> button.</p> <p>In order to add fragment B to the back stack so that this is possible, you must call {@link android.app.FragmentTransaction#addToBackStack addToBackStack()} before you {@link android.app.FragmentTransaction#commit()} the transaction that replaces fragment B with fragment @@ -92,41 +94,47 @@ is created and the "main" activity for that application opens as the root activi <p>When the current activity starts another, the new activity is pushed on the top of the stack and takes focus. The previous activity remains in the stack, but is stopped. When an activity -stops, the system retains the current state of its user interface. When the user presses the BACK -key, the current activity is popped from the top of the stack (the activity is destroyed) and the +stops, the system retains the current state of its user interface. When the user presses the +<em>Back</em> +button, the current activity is popped from the top of the stack (the activity is destroyed) and the previous activity resumes (the previous state of its UI is restored). Activities in the stack are never rearranged, only pushed and popped from the stack—pushed onto the stack when started by -the current activity and popped off when the user leaves it using the BACK key. As such, the back +the current activity and popped off when the user leaves it using the <em>Back</em> button. As such, +the back stack operates as a "last in, first out" object structure. Figure 1 visualizes this behavior with a timeline showing the progress between activities along with the current back stack at each point in time.</p> <img src="{@docRoot}images/fundamentals/diagram_backstack.png" alt="" /> <p class="img-caption"><strong>Figure 1.</strong> A representation of how each new activity in a -task adds an item to the back stack. When the user presses the BACK key, the current activity is +task adds an item to the back stack. When the user presses the <em>Back</em> button, the current +activity is destroyed and the previous activity resumes.</p> -<p>If the user continues to press BACK, then each activity in the stack is popped off to reveal the +<p>If the user continues to press <em>Back</em>, then each activity in the stack is popped off to +reveal the previous one, until the user returns to the Home screen (or to whichever activity was running when the task began). When all activities are removed from the stack, the task no longer exists.</p> -<div class="figure" style="width:369px"> +<div class="figure" style="width:287px"> <img src="{@docRoot}images/fundamentals/diagram_multitasking.png" alt="" /> <p -class="img-caption"><strong>Figure 2.</strong> Two tasks: Task A is in the background, waiting -to be resumed, while Task B receives user interaction in the foreground.</p> +class="img-caption"><strong>Figure 2.</strong> Two tasks: Task B receives user interaction +in the foreground, while Task A is in the background, waiting to be resumed.</p> </div> -<div class="figure" style="width:178px"> +<div class="figure" style="width:215px"> <img src="{@docRoot}images/fundamentals/diagram_multiple_instances.png" alt="" /> <p class="img-caption"><strong>Figure 3.</strong> A single activity is instantiated multiple times.</p> </div> <p>A task is a cohesive unit that can move to the "background" when users begin a new task or go -to the Home screen, via the HOME key. While in the background, all the activities in the task are +to the Home screen, via the <em>Home</em> button. While in the background, all the activities in the +task are stopped, but the back stack for the task remains intact—the task has simply lost focus while another task takes place, as shown in figure 2. A task can then return to the "foreground" so users can pick up where they left off. Suppose, for example, that the current task (Task A) has three -activities in its stack—two under the current activity. The user presses the HOME key, then +activities in its stack—two under the current activity. The user presses the <em>Home</em> +button, then starts a new application from the application launcher. When the Home screen appears, Task A goes into the background. When the new application starts, the system starts a task for that application (Task B) with its own stack of activities. After interacting with @@ -135,7 +143,8 @@ started Task A. Now, Task A comes to the foreground—all three activities in its stack are intact and the activity at the top of the stack resumes. At this point, the user can also switch back to Task B by going Home and selecting the application icon -that started that task (or by touching and holding the HOME key to reveal recent tasks and selecting +that started that task (or by touching and holding the <em>Home</em> button to reveal recent tasks +and selecting one). This is an example of multitasking on Android.</p> <p class="note"><strong>Note:</strong> Multiple tasks can be held in the background at once. @@ -145,10 +154,11 @@ See the following section about <a href="#ActivityState">Activity state</a>.</p> <p>Because the activities in the back stack are never rearranged, if your application allows users to start a particular activity from more than one activity, a new instance of -that activity is created and popped onto the stack (rather than bringing any previous instance of +that activity is created and pushed onto the stack (rather than bringing any previous instance of the activity to the top). As such, one activity in your application might be instantiated multiple times (even from different tasks), as shown in figure 3. As such, if the user navigates backward -using the BACK key, each instance of the activity is revealed in the order they were opened (each +using the <em>Back</em> button, each instance of the activity is revealed in the order they were +opened (each with their own UI state). However, you can modify this behavior if you do not want an activity to be instantiated more than once. How to do so is discussed in the later section about <a href="#ManagingTasks">Managing Tasks</a>.</p> @@ -159,19 +169,28 @@ href="#ManagingTasks">Managing Tasks</a>.</p> <ul> <li>When Activity A starts Activity B, Activity A is stopped, but the system retains its state (such as scroll position and text entered into forms). -If the user presses the BACK key while in Activity B, Activity A resumes with its state +If the user presses the <em>Back</em> button while in Activity B, Activity A resumes with its state restored.</li> - <li>When the user leaves a task by pressing the HOME key, the current activity is stopped and + <li>When the user leaves a task by pressing the <em>Home</em> button, the current activity is +stopped and its task goes into the background. The system retains the state of every activity in the task. If the user later resumes the task by selecting the launcher icon that began the task, the task comes to the foreground and resumes the activity at the top of the stack.</li> - <li>If the user presses the BACK key, the current activity is popped from the stack and + <li>If the user presses the <em>Back</em> button, the current activity is popped from the stack +and destroyed. The previous activity in the stack is resumed. When an activity is destroyed, the system <em>does not</em> retain the activity's state.</li> <li>Activities can be instantiated multiple times, even from other tasks.</li> </ul> +<div class="design-announce"> +<p><strong>Navigation Design</strong></p> + <p>For more about how app navigation works on Android, read Android Design's <a +href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> +</div> + + <h2 id="ActivityState">Saving Activity State</h2> <p>As discussed above, the system's default behavior preserves the state of an activity when it is @@ -247,7 +266,8 @@ flags to define how activities are associated with tasks and how the behave in t <p class="caution"><strong>Caution:</strong> Most applications should not interrupt the default behavior for activities and tasks. If you determine that it's necessary for your activity to modify the default behaviors, use caution and be sure to test the usability of the activity during -launch and when navigating back to it from other activities and tasks with the BACK key. Be sure +launch and when navigating back to it from other activities and tasks with the <em>Back</em> button. +Be sure to test for navigation behaviors that might conflict with the user's expected behavior.</p> @@ -271,7 +291,7 @@ B should associate with current task. If both activities define how Activity B should associate with a task, then Activity A's request (as defined in the intent) is honored over Activity B's request (as defined in its manifest).</p> -<p class="note"><strong>Note:</strong> Some the launch modes available in the manifest +<p class="note"><strong>Note:</strong> Some launch modes available for the manifest file are not available as flags for an intent and, likewise, some launch modes available as flags for an intent cannot be defined in the manifest.</p> @@ -311,8 +331,10 @@ android.app.Activity#onNewIntent onNewIntent()}, because it's at the top of the stack remains A-B-C-D. However, if an intent arrives for an activity of type B, then a new instance of B is added to the stack, even if its launch mode is {@code "singleTop"}.</p> <p class="note"><strong>Note:</strong> When a new instance of an activity is created, -the user can press the BACK key to return to the previous activity. But when an existing instance of -an activity handles a new intent, the user cannot press the BACK key to return to the state of +the user can press the <em>Back</em> button to return to the previous activity. But when an existing +instance of +an activity handles a new intent, the user cannot press the <em>Back</em> button to return to the +state of the activity before the new intent arrived in {@link android.app.Activity#onNewIntent onNewIntent()}.</p> </dd> @@ -324,7 +346,7 @@ intent to the existing instance through a call to its {@link android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance. Only one instance of the activity can exist at a time. <p class="note"><strong>Note:</strong> Although the activity starts in a new task, the -BACK key still returns the user to the previous activity.</p></dd> +<em>Back</em> button still returns the user to the previous activity.</p></dd> <dt>{@code "singleInstance"}.</dt> <dd>Same as {@code "singleTask"}, except that the system doesn't launch any other activities into the task holding the instance. The activity is always the single and only member of its task; @@ -342,19 +364,17 @@ already has a task running in the background, that task is brought forward to ha intent.</p> <p>Regardless of whether an activity starts in a new task or in the same task as the activity that -started it, the BACK key always takes the user to the previous activity. However, if you -start an activity from your task (Task A) that specifies the {@code singleTask} launch mode, then -that activity might have an instance in the background that belongs to a task with its own back -stack (Task B). In this -case, when Task B is brought forward to handle a new intent, the BACK key first navigates -backward through the activities in Task B before returning to -the top-most activity in Task A. Figure 4 visualizes this type of scenario.</p> +started it, the <em>Back</em> button always takes the user to the previous activity. However, if you +start an activity that specifies the {@code singleTask} launch mode, then if an instance of +that activity exists in a background task, that whole task is brought to the foreground. At this +point, the back stack now includes all activities from the task brought forward, at the top of the +stack. Figure 4 illustrates this type of scenario.</p> <img src="{@docRoot}images/fundamentals/diagram_backstack_singletask_multiactivity.png" alt="" /> <p class="img-caption"><strong>Figure 4.</strong> A representation of how an activity with launch mode "singleTask" is added to the back stack. If the activity is already a part of a -background task with its own back stack (Task B), then the entire back stack also comes -forward, on top of the current task (Task A).</p> +background task with its own back stack, then the entire back stack also comes +forward, on top of the current task.</p> <p>For more information about using launch modes in the manifest file, see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> @@ -447,7 +467,8 @@ flag, the system looks for a different task to house the new activity. Often, it However, it doesn't have to be. If there's already an existing task with the same affinity as the new activity, the activity is launched into that task. If not, it begins a new task.</p> -<p>If this flag causes an activity to begin a new task and the user presses the HOME key to leave +<p>If this flag causes an activity to begin a new task and the user presses the <em>Home</em> button +to leave it, there must be some way for the user to navigate back to the task. Some entities (such as the notification manager) always start activities in an external task, never as part of their own, so they always put {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to {@link @@ -549,9 +570,10 @@ android.content.Intent#ACTION_MAIN} and a {@link android.content.Intent#CATEGORY_LAUNCHER} filter. Imagine, for example, what could happen if the filter is missing: An intent launches a {@code "singleTask"} activity, initiating a new task, and the user spends some time working in -that task. The user then presses the HOME key. The task is now sent to the background and not -visible. Because it is not represented in the application launcher, the user has no way to return to -the task. +that task. The user then presses the <em>Home</em> button. The task is now sent to the background +and is +not visible. Now the user has no way to return to the task, because it is not represented in the +application launcher. </p> <p>For those cases where you don't want the user to be able to return to an activity, set the diff --git a/docs/html/guide/topics/graphics/hardware-accel.jd b/docs/html/guide/topics/graphics/hardware-accel.jd index c8703a5..f5cd1e6 100644 --- a/docs/html/guide/topics/graphics/hardware-accel.jd +++ b/docs/html/guide/topics/graphics/hardware-accel.jd @@ -42,19 +42,20 @@ parent.link=index.html <li><a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL with the Framework APIs</a></li> - <li><a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a></li> + <li><a href="{@docRoot}guide/topics/renderscript/index.html">Renderscript</a></li> </ol> </div> </div> <p>Beginning in Android 3.0 (API level 11), the Android 2D rendering pipeline is designed to better support hardware acceleration. Hardware acceleration carries out all drawing operations - that are performed on a {@link android.view.View}'s canvas using the GPU.</p> + that are performed on a {@link android.view.View}'s canvas using the GPU. Because of the + increased resources required to enable hardware acceleration, your app will consume more RAM.</p> <p>The easiest way to enable hardware acceleration is to turn it on globally for your entire application. If your application uses only standard views and {@link android.graphics.drawable.Drawable}s, turning it on globally should not cause any adverse - effects. However, because hardware acceleration is not supported for all of the 2D drawing + drawing effects. However, because hardware acceleration is not supported for all of the 2D drawing operations, turning it on might affect some of your applications that use custom views or drawing calls. Problems usually manifest themselves as invisible elements, exceptions, or wrongly rendered pixels. To remedy this, Android gives you the option to enable or disable hardware diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd index 6a2a20f..a786d42 100644 --- a/docs/html/guide/topics/graphics/opengl.jd +++ b/docs/html/guide/topics/graphics/opengl.jd @@ -189,7 +189,7 @@ shown below. <uses-feature android:glEsVersion="0x00020000" android:required="true" /> </pre> - <p>Adding this declaration causes the Android Market to restrict your application from being + <p>Adding this declaration causes Google Play to restrict your application from being installed on devices that do not support OpenGL ES 2.0.</p> </li> <li><strong>Texture compression requirements</strong> - If your application uses texture @@ -200,9 +200,9 @@ formats, see <a href="#textures">Texture compression support</a>. <p>Declaring texture compression requirements in your manifest hides your application from users with devices that do not support at least one of your declared compression types. For more -information on how Android Market filtering works for texture compressions, see the <a +information on how Google Play filtering works for texture compressions, see the <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html#market-texture-filtering"> -Android Market and texture compression filtering</a> section of the {@code +Google Play and texture compression filtering</a> section of the {@code <supports-gl-texture>} documentation.</p> </li> </ul> @@ -470,7 +470,7 @@ the next section. <p class="note"><strong>Note:</strong> Once you decide which texture compression formats your application will support, make sure you declare them in your manifest using <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture> -</a>. Using this declaration enables filtering by external services such as Android Market, so that +</a>. Using this declaration enables filtering by external services such as Google Play, so that your app is installed only on devices that support the formats your app requires. For details, see <a href="{@docRoot}guide/topics/graphics/opengl.html#manifest">OpenGL manifest declarations</a>.</p> diff --git a/docs/html/guide/topics/intents/intents-filters.jd b/docs/html/guide/topics/intents/intents-filters.jd index 3f94553..3ad3c93 100644 --- a/docs/html/guide/topics/intents/intents-filters.jd +++ b/docs/html/guide/topics/intents/intents-filters.jd @@ -247,7 +247,7 @@ several category constants, including these: </tr><tr> <td>{@code CATEGORY_HOME} <td>The activity displays the home screen, the first screen the user sees when - the device is turned on or when the HOME key is pressed. + the device is turned on or when the <em>Home</em> button is pressed. </tr><tr> <td>{@code CATEGORY_LAUNCHER} <td>The activity can be the initial activity of a task and is listed in diff --git a/docs/html/guide/topics/location/index.jd b/docs/html/guide/topics/location/index.jd index 5f98902..8a2e9cd 100644 --- a/docs/html/guide/topics/location/index.jd +++ b/docs/html/guide/topics/location/index.jd @@ -98,7 +98,7 @@ Google APIs add-on, visit</p> href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> <p>For your convenience, the Google APIs add-on is also available as a downloadable component from -the Android SDK and AVD Manager (see <a href="{@docRoot}sdk/adding-components.html">Adding SDK +the Android SDK Manager (see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>).</p> <p class="note"><strong>Note:</strong> In order to display Google Maps data in a diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index e23fb0ec..9dc124b 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -59,7 +59,7 @@ by the system and will never be run. <dt>attributes:</dt> <dd><dl class="attr"> -<dt><a href name="reparent"></a>{@code android:allowTaskReparenting}</dt> +<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> <dd>Whether or not the activity can move from the task that started it to the task it has an affinity for when that task is next brought to the front — "{@code true}" if it can move, and "{@code false}" if it @@ -133,21 +133,21 @@ is meaningful only for activities that start a new task (the root activity); it's ignored for all other activities in the task. <p> -When the value is "{@code true}", every time users start the task again, they -are brought to its root activity, regardless of what they were last doing in -the task and regardless of whether they used BACK or HOME to last leave it. -When the value is "{@code false}", the task may be cleared of activities in +When the value is "{@code true}", every time users start the task again, they +are brought to its root activity regardless of what they were last doing in +the task and regardless of whether they used the <em>Back</em> or <em>Home</em> button to +leave it. When the value is "{@code false}", the task may be cleared of activities in some situations (see the <code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always. </p> <p> Suppose, for example, that someone launches activity P from the home screen, -and from there goes to activity Q. The user next presses HOME, and then returns +and from there goes to activity Q. The user next presses <em>Home</em>, and then returns to activity P. Normally, the user would see activity Q, since that is what they were last doing in P's task. However, if P set this flag to "{@code true}", all of the activities on top of it (Q in this case) were removed when the user pressed -HOME and the task went to the background. So the user sees only P when returning +<em>Home</em> and the task went to the background. So the user sees only P when returning to the task. </p> @@ -272,10 +272,11 @@ is "{@code false}", it cannot be instantiated. </p></dd> <dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt> -<dd>Whether or not the activity should be excluded from the list of recently -launched activities that can be displayed to users — "{@code true}" if -it should be excluded, and "{@code false}" if it should be included. -The default value is "{@code false}". +<dd>Whether or not the task initiated by this activity should be excluded from the list of recently +used applications ("recent apps"). That is, when this activity is the root activity of a new task, +this attribute determines whether the task should not appear in the list of recent apps. "{@code +true}" if the task should be <em>excluded</em> from the list; "{@code false}" if it should be +<em>included</em>. The default value is "{@code false}". </p></dd> <dt><a name="exported"></a>{@code android:exported}</dt> @@ -306,7 +307,7 @@ attribute). <dd>Whether or not an existing instance of the activity should be shut down (finished) whenever the user again launches its task (chooses the task on the home screen) — "{@code true}" if it should be shut down, and "{@code false}" -if not. The default value is "{@code false}". +if not. The default value is "{@code false}". <p> If this attribute and @@ -320,13 +321,15 @@ activity is ignored. The activity is not re-parented, but destroyed. Activity — "{@code true}" if it should be enabled, and "{@code false}" if not. The default value is "{@code false}". + <p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is available to applications, to improve performance for many common 2D graphics operations. When the hardware-accelerated renderer is enabled, most operations in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated. This results in smoother animations, smoother scrolling, and improved responsiveness overall, even for applications that do not explicitly make use -the framework's OpenGL libraries. </p> +the framework's OpenGL libraries. Because of the increased resources required to +enable hardware acceleration, your app will consume more RAM.</p> <p>Note that not all of the OpenGL 2D operations are accelerated. If you enable the hardware-accelerated renderer, test your application to ensure that it can @@ -501,7 +504,7 @@ users and is very different from most other applications. <p>Regardless of the launch mode that you choose, make sure to test the usability of the activity during launch and when navigating back to it from -other activities and tasks using the BACK key. </p> +other activities and tasks using the <em>Back</em> button. </p> <p>For more information on launch modes and their interaction with Intent flags, see the @@ -586,9 +589,9 @@ Permissions</a>. </p></dd> <dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the activity should run. Normally, +<dd>The name of the process in which the activity should run. Normally, all components of an application run in the default process created for the -application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different default for all components. But each component can override the default, allowing you to spread your application across @@ -669,7 +672,7 @@ unspecified}" setting.</td> <p class="note"><strong>Note:</strong> When you declare one of the landscape or portrait values, it is considered a hard requirement for the orientation in which the activity runs. As such, -the value you declare enables filtering by services such as Android Market so your application is +the value you declare enables filtering by services such as Google Play so your application is available only to devices that support the orientation required by your activities. For example, if you declare either {@code "landscape"}, {@code "reverseLandscape"}, or {@code "sensorLandscape"}, then your application will be available only to devices that support @@ -678,7 +681,7 @@ your application requires either portrait or landscape orientation with the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> element. For example, <code><uses-feature android:name="android.hardware.screen.portrait"/></code>. This is purely a filtering behavior -provided by Android Market (and other services that support it) and the platform itself does not +provided by Google Play (and other services that support it) and the platform itself does not control whether your app can be installed when a device supports only certain orientations.</p> </dd> @@ -705,7 +708,7 @@ activity started for the first time. A "{@code true}" setting ensures that the activity can be restarted in the absence of retained state. For example, the activity that displays the home screen uses this setting to make sure that it does not get removed if it -crashes for some reason. +crashes for some reason. </p></dd> <dt><a name="aff"></a>{@code android:taskAffinity}</dt> diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 4f1964c..df6f61a 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -249,7 +249,7 @@ of that name is created. A global process can be shared with other applications, reducing resource usage. </p></dd> -<dt><a href name="restoreany"></a>{@code android:restoreAnyVersion}</dt> +<dt><a name="restoreany"></a>{@code android:restoreAnyVersion}</dt> <dd>Indicate that the application is prepared to attempt a restore of any backed-up data set, even if the backup was stored by a newer version of the application than is currently installed on the device. Setting @@ -260,7 +260,7 @@ incompatible. <em>Use with caution!</em> <p>The default value of this attribute is {@code false}. </p></dd> -<dt><a href name="aff"></a>{@code android:taskAffinity}</dt> +<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> diff --git a/docs/html/guide/topics/manifest/compatible-screens-element.jd b/docs/html/guide/topics/manifest/compatible-screens-element.jd index 5c89869..a27c316 100644 --- a/docs/html/guide/topics/manifest/compatible-screens-element.jd +++ b/docs/html/guide/topics/manifest/compatible-screens-element.jd @@ -27,10 +27,10 @@ specifies a specific screen size-density combination with which the application <p>The Android system <em>does not</em> read the {@code <compatible-screens>} manifest element (neither at install-time nor at runtime). This element is informational only and may be used -by external services (such as Android Market) to better understand the application's compatibility +by external services (such as Google Play) to better understand the application's compatibility with specific screen configurations and enable filtering for users. Any screen configuration that is <em>not</em> declared in this element is a screen with which the application is <em>not</em> -compatible. Thus, external services (such as Android Market) should not provide the application to +compatible. Thus, external services (such as Google Play) should not provide the application to devices with such screens.</p> <p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use this manifest @@ -48,14 +48,14 @@ should use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element only for <em>large</em> and <em>xlarge</em> screen devices, the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element allows you to declare that your application does not -support <em>small</em> and <em>normal</em> screen sizes. External services (such as Android -Market) will filter your application accordingly. You can also use the <a +support <em>small</em> and <em>normal</em> screen sizes. External services (such as Google +Play) will filter your application accordingly. You can also use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element to declare whether the system should resize your application for different screen sizes.</p> - <p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a> -document for more information about how Android Market filters applications using this and + <p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> +document for more information about how Google Play filters applications using this and other manifest elements.</p> </dd> @@ -138,5 +138,5 @@ entry looks like if your application is compatible with only small and normal sc <dt>see also:</dt> <dd><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></dd> -<dd><a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></dd> +<dd><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></dd> </dl> diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd index d737a67..98968d7 100644 --- a/docs/html/guide/topics/manifest/manifest-element.jd +++ b/docs/html/guide/topics/manifest/manifest-element.jd @@ -37,7 +37,7 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd>The root element of the AndroidManifest.xml file. It must contain an <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element -and specify {@code xlmns:android} and {@code package} attributes.</dd> +and specify {@code xmlns:android} and {@code package} attributes.</dd> <dt>attributes:</dt> <dd> @@ -150,9 +150,9 @@ either internal or external storage through the system settings.</td> </tr> </table> -<p class="caution"><strong>Caution:</strong> If your application uses the Android Market's Copy - Protection feature, it cannot be installed to a device's SD card. However, if you use Android - Market's <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a> instead, +<p class="caution"><strong>Caution:</strong> If your application uses Google Play's Copy + Protection feature, it cannot be installed to a device's SD card. However, if you use Google + Play's <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a> instead, your application <em>can</em> be installed to internal or external storage, including SD cards.</p> <p class="note"><strong>Note:</strong> By default, your application will be installed on the diff --git a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd index 6c4a05a..ebdd0b1 100644 --- a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd +++ b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd @@ -18,20 +18,20 @@ parent.link=manifest-intro.html <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Android Market and <code + <p style="color:#669999;padding-top:1em;">Google Play and <code style="color:#669999;"><supports-gl-texture></code> elements</p> - <p style="margin-top:1em;">Android Market filters applications according + <p style="margin-top:1em;">Google Play filters applications according to the texture compression formats that they support, to ensure that they can be installed only on devices that can handle their textures properly. Developers can use texture compression filtering as a way of targeting specific device types, based on GPU platform.</p> <p style="margin-top:1em;" class="caution">For important information about how - Android Market uses <code><supports-gl-texture></code> elements as - the basis for filtering, please read <a href="#market-texture-filtering">Android - Market and texture compression filtering</a>, below.</p> + Google Play uses <code><supports-gl-texture></code> elements as + the basis for filtering, please read <a href="#market-texture-filtering">Google + Play and texture compression filtering</a>, below.</p> </div> </div> @@ -57,7 +57,7 @@ texture compression formats, you can declare multiple <p>Declared <code><supports-gl-texture></code> elements are informational, meaning that the Android system itself does not examine the elements at install time to ensure matching support on the device. However, other services -(such as Android Market) or applications can check your application's +(such as Google Play) or applications can check your application's <code><supports-gl-texture></code> declarations as part of handling or interacting with your application. For this reason, it's very important that you declare all of the texture compression formats (from the list below) that @@ -141,20 +141,20 @@ and others.</td> <dt>see also:</dt> <dd> <ul> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Android Market Filters</a></li> + <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> </ul> </dd> -<h2 id="market-texture-filtering">Android Market and texture compression filtering</h2> +<h2 id="market-texture-filtering">Google Play and texture compression filtering</h2> -<p>Android Market filters the applications that are visible to users, so that +<p>Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with -their devices. One of the ways Market filters applications is by texture +their devices. One of the ways it filters applications is by texture compression compatibility, giving you control over the availability of your application to various devices, based on the capabilities of their GPUs.</p> <p>To determine an application's texture compression compatibility with a given -user's device, Android Market compares:</p> +user's device, Google Play compares:</p> <ul> <li>Texture compression formats that are supported by the application — @@ -164,26 +164,26 @@ an application declares its supported texture compression formats in a device reports the formats it supports as read-only system properties.</li> </ul> -<p>Each time you upload an application to the Android Market Publisher Site, -Android Market scans the application's manifest file and looks for any +<p>Each time you upload an application to the Google Play publisher site, +Google Play scans the application's manifest file and looks for any <code><supports-gl-texture></code> elements. It extracts the format descriptors from the elements and stores them internally as metadata associated with the application <code>.apk</code> and the application version. </p> -<p>When a user searches or browses for applications on Android Market, +<p>When a user searches or browses for applications on Google Play, the service compares the texture compression formats supported by the application with those supported by the user's device. The comparison is based on the format descriptor strings and a match must be exact.</p> <p>If <em>any</em> of an application's supported texture compression formats is -also supported by the device, Android Market allows the user to see the +also supported by the device, Google Play allows the user to see the application and potentially download it. Otherwise, if none of the application's -formats is supported by the device, Android Market filters the application so +formats is supported by the device, Google Play filters the application so that it is not available for download. </p> <p>If an application does not declare any <code><supports-gl-texture></code> elements, -Android Market does not apply any filtering based on GL texture compression format.</p> +Google Play does not apply any filtering based on GL texture compression format.</p> </dl> diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd index 81d6e27..ae14121 100644 --- a/docs/html/guide/topics/manifest/supports-screens-element.jd +++ b/docs/html/guide/topics/manifest/supports-screens-element.jd @@ -80,7 +80,7 @@ should not use it.</p> A small screen is defined as one with a smaller aspect ratio than the "normal" (traditional HVGA) screen. An application that does not support small screens <em>will not be available</em> for - small screen devices from external services (such as Android Market), because there is little + small screen devices from external services (such as Google Play), because there is little the platform can do to make such an application work on a smaller screen. This is {@code "true"} by default. </dd> @@ -156,8 +156,8 @@ smallest screen width qualifier</a> ({@code sw<N>dp}).</p> <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this attribute, so it does not affect how your application behaves at runtime. Instead, it is used -to enable filtering for your application on services such as Android Market. However, -<strong>Android Market currently does not support this attribute for filtering</strong> (on Android +to enable filtering for your application on services such as Google Play. However, +<strong>Google Play currently does not support this attribute for filtering</strong> (on Android 3.2), so you should continue using the other size attributes if your application does not support small screens.</p> diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index 9f80638..5f0a501 100644 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -9,7 +9,7 @@ parent.link=manifest-intro.html <h2>In this document</h2> <ol> - <li><a href="#market-feature-filtering">Android Market and Feature-Based Filtering</a> + <li><a href="#market-feature-filtering">Google Play and Feature-Based Filtering</a> <ol> <li><a href="#declared">Filtering based on explicitly declared features</a></li> <li><a href="#implicit">Filtering based on implicit features</a></li> @@ -45,26 +45,26 @@ href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Android Market and <code style="color:#669999;"><uses-feature></code> elements</p> - <p style="margin-top:1em;">Android Market filters the applications that are visible to users, so + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;">Google Play and <code style="color:#669999;"><uses-feature></code> elements</p> + <p style="margin-top:1em;">Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with their -devices. One of the ways Market filters applications is by feature compatibility.</p> +devices. One of the ways it filters applications is by feature compatibility.</p> -<p style="margin-top:1em;">To do this, Market checks the +<p style="margin-top:1em;">To do this, Google Play checks the <code><uses-feature></code> elements in each application's manifest, to -establish the app's feature needs. Market then shows or hides the application to +establish the app's feature needs. Google Play then shows or hides the application to each user, based on a comparison with the features available on the user's device. </p> <p style="margin-top:1em;">By specifying the features that your application requires, -you enable Android Market to present your application only to users whose +you enable Google Play to present your application only to users whose devices meet the application's feature requirements, rather than presenting it to all users. </p> <p style="margin-top:1em;" class="caution">For important information about how -Android Market uses features as the basis for filtering, please read <a -href="#market-feature-filtering">Android Market and Feature-Based Filtering</a>, +Google Play uses features as the basis for filtering, please read <a +href="#market-feature-filtering">Google Play and Feature-Based Filtering</a>, below.</p> </div> </div> @@ -106,7 +106,7 @@ application requires.</p> <p>Declared <code><uses-feature></code> elements are informational only, meaning that the Android system itself does not check for matching feature support on the device before installing an application. However, other services -(such as Android Market) or applications may check your application's +(such as Google Play) or applications may check your application's <code><uses-feature></code> declarations as part of handling or interacting with your application. For this reason, it's very important that you declare all of the features (from the list below) that your application uses. </p> @@ -207,22 +207,22 @@ can check at run-time whether a higher level of OpenGL ES is available.)</p> <li>{@link android.content.pm.FeatureInfo}</li> <li>{@link android.content.pm.ConfigurationInfo}</li> <li><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a></li> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Android Market Filters</a></li> + <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> </ul> </dd> </dl> -<h2 id="market-feature-filtering">Android Market and Feature-Based Filtering</h2> +<h2 id="market-feature-filtering">Google Play and Feature-Based Filtering</h2> -<p>Android Market filters the applications that are visible to users, so that +<p>Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with -their devices. One of the ways Market filters applications is by feature +their devices. One of the ways it filters applications is by feature compatibility.</p> <p>To determine an application's feature compatibility with a given user's -device, the Android Market service compares:</p> +device, Google Play compares:</p> <ul> <li>Features required by the application — an application declares features in @@ -238,14 +238,14 @@ are listed in the <a href="#features-reference">Features Reference</a> tables at the bottom of this document, and in the class documentation for {@link android.content.pm.PackageManager}.</p> -<p>When the user launches the Market application, the application queries the +<p>When the user launches Google Play, the application queries the Package Manager for the list of features available on the device by calling {@link android.content.pm.PackageManager#getSystemAvailableFeatures()}. The -Market application then passes the features list up to the Android Market -service when establishing the session for the user.</p> +Store application then passes the features list up to Google Play +when establishing the session for the user.</p> -<p>Each time you upload an application to the Android Market Publisher Site, -Android Market scans the application's manifest file. It looks for +<p>Each time you upload an application to the Google Play publisher site, +Google Play scans the application's manifest file. It looks for <code><uses-feature></code> elements and evaluates them in combination with other elements, in some cases, such as <code><uses-sdk></code> and <code><uses-permission></code> elements. After establishing the @@ -253,17 +253,17 @@ application's set of required features, it stores that list internally as metadata associated with the application <code>.apk</code> and the application version. </p> -<p>When a user searches or browses for applications using the Android Market +<p>When a user searches or browses for applications using the Google Play application, the service compares the features needed by each application with the features available on the user's device. If all of an application's required -features are present on the device, Android Market allows the user to see the +features are present on the device, Google Play allows the user to see the application and potentially download it. If any required feature is not -supported by the device, Android Market filters the application so that it is +supported by the device, Google Play filters the application so that it is not visible to the user and not available for download. </p> <p>Because the features you declare in <code><uses-feature></code> -elements directly affect how Android Market filters your application, it's -important to understand how Android Market evaluates the application's manifest +elements directly affect how Google Play filters your application, it's +important to understand how Google Play evaluates the application's manifest and establishes the set of required features. The sections below provide more information. </p> @@ -277,35 +277,35 @@ application absolutely requires the feature and cannot function properly without it (<code>"true"</code>), or whether the application prefers to use the feature if available, but is designed to run without it (<code>"false"</code>).</p> -<p>Android Market handles explicitly declared features in this way: </p> +<p>Google Play handles explicitly declared features in this way: </p> <ul> -<li>If a feature is explicitly declared as being required, Android Market adds +<li>If a feature is explicitly declared as being required, Google Play adds the feature to the list of required features for the application. It then filters the application from users on devices that do not provide that feature. For example: <pre><uses-feature android:name="android.hardware.camera" android:required="true" /></pre></li> -<li>If a feature is explicitly declared as <em>not</em> being required, Android -Market <em>does not</em> add the feature to the list of required features. For +<li>If a feature is explicitly declared as <em>not</em> being required, Google +Play <em>does not</em> add the feature to the list of required features. For that reason, an explicitly declared non-required feature is never considered when filtering the application. Even if the device does not provide the declared -feature, Android Market will still consider the application compatible with the +feature, Google Play will still consider the application compatible with the device and will show it to the user, unless other filtering rules apply. For example: <pre><uses-feature android:name="android.hardware.camera" android:required="false" /></pre></li> <li>If a feature is explicitly declared, but without an -<code>android:required</code> attribute, Android Market assumes that the feature +<code>android:required</code> attribute, Google Play assumes that the feature is required and sets up filtering on it. </li> </ul> <p>In general, if your application is designed to run on Android 1.6 and earlier versions, the <code>android:required</code> attribute is not available in the -API and Android Market assumes that any and all +API and Google Play assumes that any and all <code><uses-feature></code> declarations are required. </p> <p class="note"><strong>Note:</strong> By declaring a feature explicitly and including an <code>android:required="false"</code> attribute, you can -effectively disable all filtering on Android Market for the specified feature. +effectively disable all filtering on Google Play for the specified feature. </p> @@ -317,7 +317,7 @@ function properly, but which is <em>not</em> declared in a speaking, every application should <em>always</em> declare all features that it uses or requires, so the absence of a declaration for a feature used by an application should be considered an error. However, as a safeguard for users and -developers, Android Market looks for implicit features in each application and +developers, Google Play looks for implicit features in each application and sets up filters for those features, just as it would do for an explicitly declared feature. </p> @@ -337,25 +337,25 @@ element name or an unrecognized string value for the </li> </ul> -<p>To account for the cases above, Android Market attempts to discover an +<p>To account for the cases above, Google Play attempts to discover an application's implied feature requirements by examining <em>other elements</em> declared in the manifest file, specifically, <code><uses-permission></code> elements.</p> -<p>If an application requests hardware-related permissions, Android Market +<p>If an application requests hardware-related permissions, Google Play <em>assumes that the application uses the underlying hardware features and therefore requires those features</em>, even though there might be no corresponding to <code><uses-feature></code> declarations. For such -permissions, Android Market adds the underlying hardware features to the +permissions, Google Play adds the underlying hardware features to the metadata that it stores for the application and sets up filters for them.</p> <p>For example, if an application requests the <code>CAMERA</code> permission but does not declare a <code><uses-feature></code> element for -<code>android.hardware.camera</code>, Android Market considers that the +<code>android.hardware.camera</code>, Google Play considers that the application requires a camera and should not be shown to users whose devices do not offer a camera.</p> -<p>If you don't want Android Market to filter based on a specific implied +<p>If you don't want Google Play to filter based on a specific implied feature, you can disable that behavior. To do so, declare the feature explicitly in a <code><uses-feature></code> element and include an <code>android:required="false"</code> attribute. For example, to disable @@ -366,30 +366,30 @@ the feature as shown below.</p> <p class="caution">It's important to understand that the permissions that you request in <code><uses-permission></code> elements can directly affect how -Android Market filters your application. The reference section <a +Google Play filters your application. The reference section <a href="#permissions">Permissions that Imply Feature Requirements</a>, below, lists the full set of permissions that imply feature requirements and therefore trigger filtering.</p> <h3 id="bt-permission-handling">Special handling for Bluetooth feature</h3> -<p>Android Market applies slightly different rules than described above, when +<p>Google Play applies slightly different rules than described above, when determining filtering for Bluetooth.</p> <p>If an application declares a Bluetooth permission in a <code><uses-permission></code> element, but does not explicitly declare -the Bluetooth feature in a <code><uses-feature></code> element, Android -Market checks the version(s) of the Android platform on which the application is +the Bluetooth feature in a <code><uses-feature></code> element, Google +Play checks the version(s) of the Android platform on which the application is designed to run, as specified in the <code><uses-sdk></code> element. </p> -<p>As shown in the table below, Android Market enables filtering for the +<p>As shown in the table below, Google Play enables filtering for the Bluetooth feature only if the application declares its lowest or targeted -platform as Android 2.0 (API level 5) or higher. However, note that Android -market applies the normal rules for filtering when the application explicitly +platform as Android 2.0 (API level 5) or higher. However, note that Google +Play applies the normal rules for filtering when the application explicitly declares the Bluetooth feature in a <code><uses-feature></code> element. </p> -<p class="caption"><strong>Table 1.</strong> How Android Market determines the +<p class="caption"><strong>Table 1.</strong> How Google Play determines the Bluetooth feature requirement for an application that requests a Bluetooth permission but does not declare the Bluetooth feature in a <code><uses-feature></code> element.</p> @@ -403,14 +403,14 @@ permission but does not declare the Bluetooth feature in a <tr> <td><nobr><=4 (or uses-sdk is not declared)</nobr></td> <td><=4</td> -<td>Android Market <em>will not</em> filter the application from any devices +<td>Google Play <em>will not</em> filter the application from any devices based on their reported support for the <code>android.hardware.bluetooth</code> feature.</td> </tr> <tr> <td><=4</td> <td>>=5</td> -<td rowspan="2">Android Market filters the application from any devices that +<td rowspan="2">Google Play filters the application from any devices that do not support the <code>android.hardware.bluetooth</code> feature (including older releases).</td> </tr> @@ -421,13 +421,13 @@ older releases).</td> </table> <p>The examples below illustrate the different filtering effects, based on how -Android Market handles the Bluetooth feature. </p> +Google Play handles the Bluetooth feature. </p> <dl> <dt>In first example, an application that is designed to run on older API levels declares a Bluetooth permission, but does not declare the Bluetooth feature in a <code><uses-feature></code> element.</dt> -<dd><em>Result:</em> Android Market does not filter the application from any device.</dd> +<dd><em>Result:</em> Google Play does not filter the application from any device.</dd> </dl> <pre><manifest ...> @@ -439,7 +439,7 @@ declares a Bluetooth permission, but does not declare the Bluetooth feature in a <dl> <dt>In the second example, below, the same application also declares a target API level of "5". </dt> -<dd><em>Result:</em> Android Market now assumes that the feature is required and +<dd><em>Result:</em> Google Play now assumes that the feature is required and will filter the application from all devices that do not report Bluetooth support, including devices running older versions of the platform. </dd> </dl> @@ -465,7 +465,7 @@ including devices running older versions of the platform. </dd> <dl> <dt>Finally, in the case below, the same application adds an <code>android:required="false"</code> attribute.</dt> -<dd><em>Result:</em> Android Market disables filtering based on Bluetooth +<dd><em>Result:</em> Google Play disables filtering based on Bluetooth feature support, for all devices.</dd> </dl> @@ -481,10 +481,10 @@ feature support, for all devices.</dd> <h3 id="testing">Testing the features required by your application</h3> <p>You can use the <code>aapt</code> tool, included in the Android SDK, to -determine how Android Market will filter your application, based on its declared +determine how Google Play will filter your application, based on its declared features and permissions. To do so, run <code>aapt</code> with the <code>dump badging</code> command. This causes <code>aapt</code> to parse your -application's manifest and apply the same rules as used by Android Market to +application's manifest and apply the same rules as used by Google Play to determine the features that your application requires. </p> <p>To use the tool, follow these steps: </p> @@ -501,7 +501,7 @@ If you are using SDK Tools r8 or higher, you can find <code>aapt</code> in the <p class="note"><strong>Note:</strong> You must use the version of <code>aapt</code> that is provided for the latest Platform-Tools component available. If you do not have the latest Platform-Tools component, download it using the <a -href="{@docRoot}sdk/adding-components.html">Android SDK and AVD Manager</a>. +href="{@docRoot}sdk/adding-components.html">Android SDK Manager</a>. </p></li> <li>Run <code>aapt</code> using this syntax: </li> </ol> @@ -529,7 +529,7 @@ densities: '160' <h2 id=features-reference>Features Reference</h2> <p>The tables below provide reference information about hardware and software -features and the permissions that can imply them on Android Market. </p> +features and the permissions that can imply them on Google Play. </p> <h3 id="hw-features">Hardware features</h3> @@ -873,12 +873,12 @@ level 5). Because of this, some apps were able to use the API before they had the ability to declare that they require the API via the <code><uses-feature></code> system. </p> -<p>To prevent those apps from being made available unintentionally, Android -Market assumes that certain hardware-related permissions indicate that the +<p>To prevent those apps from being made available unintentionally, Google +Play assumes that certain hardware-related permissions indicate that the underlying hardware features are required by default. For instance, applications that use Bluetooth must request the <code>BLUETOOTH</code> permission in a -<code><uses-permission></code> element — for legacy apps, Android -Market assumes that the permission declaration means that the underlying +<code><uses-permission></code> element — for legacy apps, Google +Play assumes that the permission declaration means that the underlying <code>android.hardware.bluetooth</code> feature is required by the application and sets up filtering based on that feature. </p> diff --git a/docs/html/guide/topics/manifest/uses-library-element.jd b/docs/html/guide/topics/manifest/uses-library-element.jd index d94ad9f..2f8eb50 100644 --- a/docs/html/guide/topics/manifest/uses-library-element.jd +++ b/docs/html/guide/topics/manifest/uses-library-element.jd @@ -33,7 +33,7 @@ parent.link=manifest-intro.html </p> <p> This element also affects the installation of the application on a particular device and - the availability of the application in Android Market: + the availability of the application on Google Play: </p> <dl> <dt><em>Installation</em></dt> @@ -42,11 +42,11 @@ parent.link=manifest-intro.html {@code true}, the {@link android.content.pm.PackageManager} framework won't let the user install the application unless the library is present on the user's device. </dd> - <dt><em>Market</em></dt> + <dt><em>Google Play</em></dt> <dd> - Android Market filters applications based on the libraries installed on the + Google Play filters applications based on the libraries installed on the user's device. For more information about filtering, see the topic - <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>. + <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>. </dd> </dl> <p> diff --git a/docs/html/guide/topics/manifest/uses-permission-element.jd b/docs/html/guide/topics/manifest/uses-permission-element.jd index 967fc5a..6c71fb4 100644 --- a/docs/html/guide/topics/manifest/uses-permission-element.jd +++ b/docs/html/guide/topics/manifest/uses-permission-element.jd @@ -8,21 +8,21 @@ parent.link=manifest-intro.html <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;"><code style="color:#669999;"><uses-permission></code> and filtering on Android Market. </p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;"><code style="color:#669999;"><uses-permission></code> and filtering on Google Play. </p> <p style="margin-top:1em;">In some cases, the permissions that you request through <code><uses-permission></code> can affect how -your application is filtered by Android Market.</p> +your application is filtered by Google Play.</p> <p style="margin-top:1em;">If you request a hardware-related permission — -<code>CAMERA</code>, for example — Android Market assumes that your +<code>CAMERA</code>, for example — Google Play assumes that your application requires the underlying hardware feature and filters the application from devices that do not offer it.</p> <p style="margin-top:1em;">To control filtering, always explicitly declare hardware features in <code><uses-feature></code> elements, rather than -relying on Android Market to "discover" the requirements in +relying on Google Play to "discover" the requirements in <code><uses-permission></code> elements. Then, if you want to disable filtering for a particular feature, you can add a <code>android:required="false"</code> attribute to the diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd index b371f34..8fa39d1 100644 --- a/docs/html/guide/topics/manifest/uses-sdk-element.jd +++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd @@ -33,16 +33,16 @@ major version or the sum of the major and minor versions).</p> <div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Android Market and <uses-sdk> attributes</p> - <p>Android Market filters the applications that are visible to users, so + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;">Google Play and <uses-sdk> attributes</p> + <p style="padding-top:1em;">Google Play filters the applications that are visible to users, so that users can only see and download applications that are compatible with their -devices. One of the ways Market filters applications is by Android -version-compatibility. To do this, Market checks the <code><uses-sdk></code> +devices. One of the ways it filters applications is by Android +version-compatibility. To do this, Google Play checks the <code><uses-sdk></code> attributes in each application's manifest to establish its version-compatibility range, then shows or hides the application based on a comparison with the API Level of the user's Android system version. For more information, see <a -href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> +href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>.</p> </div> </div> @@ -60,7 +60,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> attribute, the system assumes a default value of "1", which indicates that your application is compatible with all versions of Android. If your application is <em>not</em> compatible with all versions (for instance, it uses APIs introduced - in API Level 3) and you have not declared the proper <code>android:minSdkVersion</code>, + in API Level 3) and you have not declared the proper <code>minSdkVersion</code>, then when installed on a system with an API Level less than 3, the application will crash during runtime when attempting to access the unavailable APIs. For this reason, be certain to declare the appropriate API Level in the @@ -68,18 +68,32 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> </dd> <dt><a name="target"></a>{@code android:targetSdkVersion}</dt> - <dd>An integer designating the API Level that the application is targetting. - - <p>With this attribute set, the application says that it is able to run on - older versions (down to {@code minSdkVersion}), but was explicitly tested to - work with the version specified here. Specifying this target version allows the - platform to disable compatibility settings that are not required for the target - version (which may otherwise be turned on in order to maintain - forward-compatibility) or enable newer features that are not available to older - applications. This does not mean that you can program different features for - different versions of the platform—it simply informs the platform that you - have tested against the target version and the platform should not perform any - extra work to maintain forward-compatibility with the target version.</p> + <dd>An integer designating the API Level that the application targets. If not set, the default +value equals that given to {@code minSdkVersion}. + + <p>This attribute informs the system that you have tested against the target version and the +system should not enable any compatibility behaviors to maintain your app's forward-compatibility +with the target version. The application is still able to run on older versions (down to {@code +minSdkVersion}).</p> + + <p>As Android evolves with each new version, some behaviors and even appearances might change. +However, if the API level of the platform is higher than the version declared by your app's {@code +targetSdkVersion}, the system may enable compatibility behaviors to ensure that your app +continues to work the way you expect. You can disable such compatibility +behaviors by specifying {@code targetSdkVersion} to match the API +level of the platform on which it's running. For example, setting this value to "11" or higher +allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or +higher and also disables <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen +compatibility mode</a> when running on larger screens (because support for API level 11 implicitly +supports larger screens).</p> + + <p>There are many compatibility behaviors that the system may enable based on the value you set +for this attribute. Several of these behaviors are described by the corresponding platform versions +in the {@link android.os.Build.VERSION_CODES} reference.</p> + + <p>To maintain your application along with each Android release, you should increase +the value of this attribute to match the latest API level, then thoroughly test your application on +the corresponding platform version.</p> <p>Introduced in: API Level 4</p> </dd> @@ -89,25 +103,25 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> designed to run. <p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this - attribute when installing an application and when revalidating the application + attribute when installing an application and when re-validating the application after a system update. In either case, if the application's - <code>android:maxSdkVersion</code> attribute is lower than the API Level used by + <code>maxSdkVersion</code> attribute is lower than the API Level used by the system itself, then the system will not allow the application to be - installed. In the case of revalidation after system update, this effectively + installed. In the case of re-validation after system update, this effectively removes your application from the device. <p>To illustrate how this attribute can affect your application after system updates, consider the following example: </p> - <p>An application declaring <code>android:maxSdkVersion="5"</code> in its - manifest is published on Android Market. A user whose device is running Android + <p>An application declaring <code>maxSdkVersion="5"</code> in its + manifest is published on Google Play. A user whose device is running Android 1.6 (API Level 4) downloads and installs the app. After a few weeks, the user receives an over-the-air system update to Android 2.0 (API Level 5). After the update is installed, the system checks the application's - <code>android:maxSdkVersion</code> and successfully revalidates it. The + <code>maxSdkVersion</code> and successfully re-validates it. The application functions as normal. However, some time later, the device receives another system update, this time to Android 2.0.1 (API Level 6). After the - update, the system can no longer revalidate the application because the system's + update, the system can no longer re-validate the application because the system's own API Level (6) is now higher than the maximum supported by the application (5). The system prevents the application from being visible to the user, in effect removing it from the device.</p> @@ -120,7 +134,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> provided it uses only standard APIs and follows development best practices. Second, note that in some cases, declaring the attribute can <strong>result in your application being removed from users' devices after a system - update</strong> to a higher API Level. Most devices on which your appplication + update</strong> to a higher API Level. Most devices on which your application is likely to be installed will receive periodic system updates over the air, so you should consider their effect on your application before setting this attribute.</p> @@ -128,8 +142,8 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> <p style="margin-bottom:1em;">Introduced in: API Level 4</p> <div class="special">Future versions of Android (beyond Android 2.0.1) will no -longer check or enforce the <code>android:maxSdkVersion</code> attribute during -installation or revalidation. Android Market will continue to use the attribute +longer check or enforce the <code>maxSdkVersion</code> attribute during +installation or re-validation. Google Play will continue to use the attribute as a filter, however, when presenting users with applications available for download. </div> </dd> diff --git a/docs/html/guide/topics/media/camera.jd b/docs/html/guide/topics/media/camera.jd index b962f96..7d72491 100644 --- a/docs/html/guide/topics/media/camera.jd +++ b/docs/html/guide/topics/media/camera.jd @@ -131,11 +131,11 @@ for example: <p>For a list of camera features, see the manifest <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#hw-features">Features Reference</a>.</p> - <p>Adding camera features to your manifest causes Android Market to prevent your application from + <p>Adding camera features to your manifest causes Google Play to prevent your application from being installed to devices that do not include a camera or do not support the camera features you -specify. For more information about using feature-based filtering with Android Market, see <a -href="{@docRoot}guide/topics/manifest/uses-feature-element.html#market-feature-filtering">Android -Market and Feature-Based Filtering</a>.</p> +specify. For more information about using feature-based filtering with Google Play, see <a +href="{@docRoot}guide/topics/manifest/uses-feature-element.html#market-feature-filtering">Google +Play and Feature-Based Filtering</a>.</p> <p>If your application <em>can use</em> a camera or camera feature for proper operation, but does not <em>require</em> it, you should specify this in the manifest by including the {@code android:required} attribute, and setting it to {@code false}:</p> @@ -442,7 +442,7 @@ use or does not exist will cause your application to be shut down by the system. the first, back-facing camera on a device with more than one camera.</p> <h3 id="check-camera-features">Checking camera features</h3> -<p>Once you obtain access to a camera, you can get further information about its capabilties using +<p>Once you obtain access to a camera, you can get further information about its capabilities using the {@link android.hardware.Camera#getParameters() Camera.getParameters()} method and checking the returned {@link android.hardware.Camera.Parameters} object for supported capabilities. When using API Level 9 or higher, use the {@link android.hardware.Camera#getCameraInfo(int, @@ -677,8 +677,8 @@ button {@link android.view.View.OnClickListener}.</p> <pre> // Add a listener to the Capture button Button captureButton = (Button) findViewById(id.button_capture); - captureButton.setOnClickListener( - new View.OnClickListener() { +captureButton.setOnClickListener( + new View.OnClickListener() { @Override public void onClick(View v) { // get an image from the camera @@ -1037,7 +1037,7 @@ private static Uri getOutputMediaFileUri(int type){ } /** Create a File for saving an image or video */ -private static Uri getOutputMediaFile(int type){ +private static File getOutputMediaFile(int type){ // To be safe, you should check that the SDCard is mounted // using Environment.getExternalStorageState() before doing this. @@ -1260,7 +1260,7 @@ supported.</p> <p>If your application requires certain camera features in order to function properly, you can require them through additions to your application manifest. When you declare the use of specific -camera features, such as flash and auto-focus, the Android Market restricts your application from +camera features, such as flash and auto-focus, Google Play restricts your application from being installed on devices which do not support these features. For a list of camera features that can be declared in your app manifest, see the manifest <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#hw-features"> Features diff --git a/docs/html/guide/topics/media/mediaplayer.jd b/docs/html/guide/topics/media/mediaplayer.jd index b3ca7dd..002d113 100644 --- a/docs/html/guide/topics/media/mediaplayer.jd +++ b/docs/html/guide/topics/media/mediaplayer.jd @@ -251,7 +251,7 @@ href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Ch "background media" even when the user leaves your activity, much in the same way that the built-in Music application behaves. In this case, what you need is a {@link android.media.MediaPlayer MediaPlayer} controlled by a {@link android.app.Service}, as -discussed in <a href="mpandservices">Using a Service with MediaPlayer</a>.</p> +discussed in <a href="#mpandservices">Using a Service with MediaPlayer</a>.</p> <h2 id="mpandservices">Using a Service with MediaPlayer</h2> diff --git a/docs/html/guide/topics/network/sip.jd b/docs/html/guide/topics/network/sip.jd index 276adb6..600da78 100644 --- a/docs/html/guide/topics/network/sip.jd +++ b/docs/html/guide/topics/network/sip.jd @@ -147,7 +147,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a </ul> <p>To control how your application is filtered from devices that do not support -SIP (for example, in Android Market), add the following to your application's +SIP (for example, on Google Play), add the following to your application's manifest:</p> <ul> diff --git a/docs/html/guide/topics/nfc/nfc.jd b/docs/html/guide/topics/nfc/nfc.jd index 175bc7c..834656a 100644 --- a/docs/html/guide/topics/nfc/nfc.jd +++ b/docs/html/guide/topics/nfc/nfc.jd @@ -318,8 +318,8 @@ other two intents, giving the user a better experience.</p> </pre> </li> - <li>The <code>uses-feature</code> element so that your application shows up in the Android -Market only for devices that have NFC hardware: + <li>The <code>uses-feature</code> element so that your application shows up in Google +Play only for devices that have NFC hardware: <pre> <uses-feature android:name="android.hardware.nfc" android:required="true" /> </pre> @@ -660,13 +660,13 @@ certainty that your application is started when an NFC tag is scanned. An AAR ha of an application embedded inside an NDEF record. You can add an AAR to any NDEF record of your NDEF message, because Android searches the entire NDEF message for AARs. If it finds an AAR, it starts the application based on the package name inside the AAR. If the application is not present on the device, -Android Market is launched to download the application.</p> +Google Play is launched to download the application.</p> <p>AARs are useful if you want to prevent other applications from filtering for the same intent and potentially handling specific tags that you have deployed. AARs are only supported at the application level, because of the package name constraint, and not at the Activity level as with intent filtering. If you want to handle an intent at the Activity level, <a -href="filtering-intents">use intent filters</a>. +href="#filtering-intents">use intent filters</a>. </p> @@ -678,7 +678,7 @@ the intent also matches the AAR, start the Activity.</li> <li>If the Activity that filters for the intent does not match the AAR, if multiple Activities can handle the intent, or if no Activity handles the intent, start the application specified by the AAR.</li> - <li>If no application can start with the AAR, go to the Android Market to download the + <li>If no application can start with the AAR, go to Google Play to download the application based on the AAR.</li> </ol> @@ -795,8 +795,8 @@ depending on what the user is doing in your application.</p> <p>The following sample shows how a simple activity calls {@link android.nfc.NfcAdapter.CreateNdefMessageCallback} in the <code>onCreate()</code> method of an -activity (see <a href="{@docRoot}resources/samples/AndroidBeam/index.html"></a> for the -complete sample). This example also has methods to help you create a MIME record:</p> +activity (see <a href="{@docRoot}resources/samples/AndroidBeamDemo/index.html">AndroidBeamDemo</a> +for the complete sample). This example also has methods to help you create a MIME record:</p> <pre id="code-example"> package com.example.android.beam; @@ -897,7 +897,7 @@ public class Beam extends Activity implements CreateNdefMessageCallback { <p>Note that this code comments out an AAR, which you can remove. If you enable the AAR, the application specified in the AAR always receives the Android Beam message. If the application is not -present, the Android Market is started to download the application. Therefore, the following intent +present, Google Play launches to download the application. Therefore, the following intent filter is not technically necessary for Android 4.0 devices or later if the AAR is used: </p> diff --git a/docs/html/guide/topics/providers/content-provider-basics.jd b/docs/html/guide/topics/providers/content-provider-basics.jd new file mode 100644 index 0000000..de89568 --- /dev/null +++ b/docs/html/guide/topics/providers/content-provider-basics.jd @@ -0,0 +1,1215 @@ +page.title=Content Provider Basics +@jd:body +<div id="qv-wrapper"> +<div id="qv"> + + + <!-- In this document --> +<h2>In this document</h2> +<ol> + <li> + <a href="#Basics">Overview</a> + <ol> + <li> + <a href="#ClientProvider">Accessing a provider</a> + </li> + <li> + <a href="#ContentURIs">Content URIs</a> + </li> + </ol> + </li> + <li> + <a href="#SimpleQuery">Retrieving Data from the Provider</a> + <ol> + <li> + <a href="#RequestPermissions">Requesting read access permission</a> + </li> + <li> + <a href="#Query">Constructing the query</a> + </li> + <li> + <a href="#DisplayResults">Displaying query results</a> + </li> + <li> + <a href="#GettingResults">Getting data from query results</a> + </li> + </ol> + </li> + <li> + <a href="#Permissions">Content Provider Permissions</a> + </li> + <li> + <a href="#Modifications">Inserting, Updating, and Deleting Data</a> + <ol> + <li> + <a href="#Inserting">Inserting data</a> + </li> + <li> + <a href="#Updating">Updating data</a> + </li> + <li> + <a href="#Deleting">Deleting data</a> + </li> + </ol> + </li> + <li> + <a href="#DataTypes">Provider Data Types</a> + </li> + <li> + <a href="#AltForms">Alternative Forms of Provider Access</a> + <ol> + <li> + <a href="#Batch">Batch access</a> + </li> + <li> + <a href="#Intents">Data access via intents</a> + </li> + </ol> + </li> + <li> + <a href="#ContractClasses">Contract Classes</a> + </li> + <li> + <a href="#MIMETypeReference">MIME Type Reference</a> + </li> +</ol> + + <!-- Key Classes --> +<h2>Key classes</h2> + <ol> + <li> + {@link android.content.ContentProvider} + </li> + <li> + {@link android.content.ContentResolver} + </li> + <li> + {@link android.database.Cursor} + </li> + <li> + {@link android.net.Uri} + </li> + </ol> + + <!-- Related Samples --> +<h2>Related Samples</h2> + <ol> + <li> + <a + href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List2.html"> + Cursor (People)</a> + </li> + <li> + <a + href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List7.html"> + Cursor (Phones)</a> + </li> + </ol> + + <!-- See also --> +<h2>See also</h2> + <ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Creating a Content Provider</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/calendar-provider.html"> + Calendar Provider</a> + </li> + </ol> +</div> +</div> + + <!-- Intro paragraphs --> +<p> + A content provider manages access to a central repository of data. A provider + is part of an Android application, which often provides its own UI for working with + the data. However, content providers are primarily intended to be used by other + applications, which access the provider using a provider client object. Together, providers + and provider clients offer a consistent, standard interface to data that also handles + inter-process communication and secure data access. +</p> +<p> + This topic describes the basics of the following: +</p> + <ul> + <li>How content providers work.</li> + <li>The API you use retrieve data from a content provider.</li> + <li>The API you use to insert, update, or delete data in a content provider.</li> + <li>Other API features that facilitate working with providers.</li> + </ul> + + <!-- Basics --> +<h2 id="Basics">Overview</h2> +<p> + A content provider presents data to external applications as one or more tables that are + similar to the tables found in a relational database. A row represents an instance of some type + of data the provider collects, and each row in the column represents an individual piece of + data collected for an instance. +</p> +<p> + For example, one of the built-in providers in the Android platform is the user dictionary, which + stores the spellings of non-standard words that the user wants to keep. Table 1 illustrates what + the data might look like in this provider's table: +</p> +<p class="table-caption"> + <strong>Table 1:</strong> Sample user dictionary table. +</p> +<table id="table1" style="width: 50%;"> + <tr> + <th style="width:20%" align="center" scope="col">word</th> + <th style="width:20%" align="center" scope="col">app id</th> + <th style="width:20%" align="center" scope="col">frequency</th> + <th style="width:20%" align="center" scope="col">locale</th> + <th style="width:20%" align="center" scope="col">_ID</th> + </tr> + <tr> + <td align="center" scope="row">mapreduce</td> + <td align="center">user1</td> + <td align="center">100</td> + <td align="center">en_US</td> + <td align="center">1</td> + </tr> + <tr> + <td align="center" scope="row">precompiler</td> + <td align="center">user14</td> + <td align="center">200</td> + <td align="center">fr_FR</td> + <td align="center">2</td> + </tr> + <tr> + <td align="center" scope="row">applet</td> + <td align="center">user2</td> + <td align="center">225</td> + <td align="center">fr_CA</td> + <td align="center">3</td> + </tr> + <tr> + <td align="center" scope="row">const</td> + <td align="center">user1</td> + <td align="center">255</td> + <td align="center">pt_BR</td> + <td align="center">4</td> + </tr> + <tr> + <td align="center" scope="row">int</td> + <td align="center">user5</td> + <td align="center">100</td> + <td align="center">en_UK</td> + <td align="center">5</td> + </tr> +</table> +<p> + In table 1, each row represents an instance of a word that might not be + found in a standard dictionary. Each column represents some data for that word, such as the + locale in which it was first encountered. The column headers are column names that are stored in + the provider. To refer to a row's locale, you refer to its <code>locale</code> column. For + this provider, the <code>_ID</code> column serves as a "primary key" column that + the provider automatically maintains. +</p> +<p class="note"> + <strong>Note:</strong> A provider isn't required to have a primary key, and it isn't required + to use <code>_ID</code> as the column name of a primary key if one is present. However, + if you want to bind data from a provider to a {@link android.widget.ListView}, one of the + column names has to be <code>_ID</code>. This requirement is explained in more detail in the + section <a href="#DisplayResults">Displaying query results</a>. +</p> +<h3 id="ClientProvider">Accessing a provider</h3> +<p> + An application accesses the data from a content provider with + a {@link android.content.ContentResolver} client object. This object has methods that call + identically-named methods in the provider object, an instance of one of the concrete + subclasses of {@link android.content.ContentProvider}. The + {@link android.content.ContentResolver} methods provide the basic + "CRUD" (create, retrieve, update, and delete) functions of persistent storage. +</p> +<p> + The {@link android.content.ContentResolver} object in the client application's + process and the {@link android.content.ContentProvider} object in the application that owns + the provider automatically handle inter-process communication. + {@link android.content.ContentProvider} also acts as an abstraction layer between its + repository of data and the external appearance of data as tables. +</p> +<p class="note"> + <strong>Note:</strong> To access a provider, your application usually has to request specific + permissions in its manifest file. This is described in more detail in the section + <a href="#Permissions">Content Provider Permissions</a> +</p> +<p> + For example, to get a list of the words and their locales from the User Dictionary Provider, + you call {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) + ContentResolver.query()}. + The {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) + query()} method calls the + {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) + ContentProvider.query()} method defined by the User Dictionary Provider. The following lines + of code show a + {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) + ContentResolver.query()} call: +<p> +<pre> +// Queries the user dictionary and returns results +mCursor = getContentResolver().query( + UserDictionary.Words.CONTENT_URI, // The content URI of the words table + mProjection, // The columns to return for each row + mSelectionClause // Selection criteria + mSelectionArgs, // Selection criteria + mSortOrder); // The sort order for the returned rows +</pre> +<p> + Table 2 shows how the arguments to + {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) + query(Uri,projection,selection,selectionArgs,sortOrder)} match an SQL SELECT statement: +</p> +<p class="table-caption"> + <strong>Table 2:</strong> Query() compared to SQL query. +</p> +<table id="table2" style="width: 75%;"> + <tr> + <th style="width:25%" align="center" scope="col">query() argument</th> + <th style="width:25%" align="center" scope="col">SELECT keyword/parameter</th> + <th style="width:50%" align="center" scope="col">Notes</th> + </tr> + <tr> + <td align="center"><code>Uri</code></td> + <td align="center"><code>FROM <em>table_name</em></code></td> + <td><code>Uri</code> maps to the table in the provider named <em>table_name</em>.</td> + </tr> + <tr> + <td align="center"><code>projection</code></td> + <td align="center"><code><em>col,col,col,...</em></code></td> + <td> + <code>projection</code> is an array of columns that should be included for each row + retrieved. + </td> + </tr> + <tr> + <td align="center"><code>selection</code></td> + <td align="center"><code>WHERE <em>col</em> = <em>value</em></code></td> + <td><code>selection</code> specifies the criteria for selecting rows.</td> + </tr> + <tr> + <td align="center"><code>selectionArgs</code></td> + <td align="center"> + (No exact equivalent. Selection arguments replace <code>?</code> placeholders in the + selection clause.) + </td> + </tr> + <tr> + <td align="center"><code>sortOrder</code></td> + <td align="center"><code>ORDER BY <em>col,col,...</em></code></td> + <td> + <code>sortOrder</code> specifies the order in which rows appear in the returned + {@link android.database.Cursor}. + </td> + </tr> +</table> +<h3 id="ContentURIs">Content URIs</h3> +<p> + A <strong>content URI</strong> is a URI that identifies data in a provider. Content URIs + include the symbolic name of the entire provider (its <strong>authority</strong>) and a + name that points to a table (a <strong>path</strong>). When you call + a client method to access a table in a provider, the content URI for the table is one of + the arguments. +</p> +<p> + In the preceding lines of code, the constant + {@link android.provider.UserDictionary.Words#CONTENT_URI} contains the content URI of + the user dictionary's "words" table. The {@link android.content.ContentResolver} + object parses out the URI's authority, and uses it to "resolve" the provider by + comparing the authority to a system table of known providers. The + {@link android.content.ContentResolver} can then dispatch the query arguments to the correct + provider. +</p> +<p> + The {@link android.content.ContentProvider} uses the path part of the content URI to choose the + table to access. A provider usually has a <strong>path</strong> for each table it exposes. +</p> +<p> + In the previous lines of code, the full URI for the "words" table is: +</p> +<pre> +content://user_dictionary/words +</pre> +<p> + where the <code>user_dictionary</code> string is the provider's authority, and + <code>words</code> string is the table's path. The string + <code>content://</code> (the <strong>scheme</strong>) is always present, + and identifies this as a content URI. +</p> +<p> + Many providers allow you to access a single row in a table by appending an ID value + to the end of the URI. For example, to retrieve a row whose <code>_ID</code> is + <code>4</code> from user dictionary, you can use this content URI: +</p> +<pre> +Uri singleUri = ContentUri.withAppendedId(UserDictionary.Words.CONTENT_URI,4); +</pre> +<p> + You often use id values when you've retrieved a set of rows and then want to update or delete + one of them. +</p> +<p class="note"> + <strong>Note:</strong> The {@link android.net.Uri} and {@link android.net.Uri.Builder} classes + contain convenience methods for constructing well-formed Uri objects from strings. The + {@link android.content.ContentUris} contains convenience methods for appending id values to + a URI. The previous snippet uses {@link android.content.ContentUris#withAppendedId(Uri, long) + withAppendedId()} to append an id to the UserDictionary content URI. +</p> + + + <!-- Retrieving Data from the Provider --> +<h2 id="SimpleQuery">Retrieving Data from the Provider</h2> +<p> + This section describes how to retrieve data from a provider, using the User Dictionary Provider + as an example. +</p> +<p class="note"> + For the sake of clarity, the code snippets in this section call + {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) + ContentResolver.query()} on the "UI thread"". In actual code, however, you should + do queries asynchronously on a separate thread. One way to do this is to use the + {@link android.content.CursorLoader} class, which is described + in more detail in the <a href="{@docRoot}guide/topics/fundamentals/loaders.html"> + Loaders</a> guide. Also, the lines of code are snippets only; they don't show a complete + application. +</p> +<p> + To retrieve data from a provider, follow these basic steps: +</p> +<ol> + <li> + Request the read access permission for the provider. + </li> + <li> + Define the code that sends a query to the provider. + </li> +</ol> +<h3 id="RequestPermissions">Requesting read access permission</h3> +<p> + To retrieve data from a provider, your application needs "read access permission" for the + provider. You can't request this permission at run-time; instead, you have to specify that + you need this permission in your manifest, using the + <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> + <uses-permission></a></code> element and the exact permission name defined by the + provider. When you specify this element in your manifest, you are in effect "requesting" this + permission for your application. When users install your application, they implicitly grant + this request. +</p> +<p> + To find the exact name of the read access permission for the provider you're using, as well + as the names for other access permissions used by the provider, look in the provider's + documentation. +</p> +<p> + The role of permissions in accessing providers is described in more detail in the section + <a href="#Permissions">Content Provider Permissions</a>. +</p> +<p> + The User Dictionary Provider defines the permission + <code>android.permission.READ_USER_DICTIONARY</code> in its manifest file, so an + application that wants to read from the provider must request this permission. +</p> +<!-- Constructing the query --> +<h3 id="Query">Constructing the query</h3> +<p> + The next step in retrieving data a provider is to construct a query. This first snippet + defines some variables for accessing the User Dictionary Provider: +</p> +<pre class="prettyprint"> + +// A "projection" defines the columns that will be returned for each row +String[] mProjection = +{ + UserDictionary.Words._ID, // Contract class constant for the _ID column name + UserDictionary.Words.WORD, // Contract class constant for the word column name + UserDictionary.Words.LOCALE // Contract class constant for the locale column name +}; + +// Defines a string to contain the selection clause +String mSelectionClause = null; + +// Initializes an array to contain selection arguments +String[] mSelectionArgs = {""}; + +</pre> +<p> + The next snippet shows how to use + {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) + ContentResolver.query()}, using the User Dictionary Provider as an example. + A provider client query is similar to an SQL query, and it contains a set of columns to return, + a set of selection criteria, and a sort order. +</p> +<p> + The set of columns that the query should return is called a <strong>projection</strong> + (the variable <code>mProjection</code>). +</p> +<p> + The expression that specifies the rows to retrieve is split into a selection clause and + selection arguments. The selection clause is a combination of logical and Boolean expressions, + column names, and values (the variable <code>mSelection</code>). If you specify the replaceable + parameter <code>?</code> instead of a value, the query method retrieves the value from the + selection arguments array (the variable <code>mSelectionArgs</code>). +</p> +<p> + In the next snippet, if the user doesn't enter a word, the selection clause is set to + <code>null</code>, and the query returns all the words in the provider. If the user enters + a word, the selection clause is set to <code>UserDictionary.Words.Word + " = ?"</code> and + the first element of selection arguments array is set to the word the user enters. +</p> +<pre class="prettyprint"> +/* + * This defines a one-element String array to contain the selection argument. + */ +String[] mSelectionArgs = {""}; + +// Gets a word from the UI +mSearchString = mSearchWord.getText().toString(); + +// Remember to insert code here to check for invalid or malicious input. + +// If the word is the empty string, gets everything +if (TextUtils.isEmpty(mSearchString)) { + // Setting the selection clause to null will return all words + mSelectionClause = null; + mSelectionArgs[0] = ""; + +} else { + // Constructs a selection clause that matches the word that the user entered. + mSelectionClause = " = ?"; + + // Moves the user's input string to the selection arguments. + mSelectionArgs[0] = mSearchString; + +} + +// Does a query against the table and returns a Cursor object +mCursor = getContentResolver().query( + UserDictionary.Words.CONTENT_URI, // The content URI of the words table + mProjection, // The columns to return for each row + mSelectionClause // Either null, or the word the user entered + mSelectionArgs, // Either empty, or the string the user entered + mSortOrder); // The sort order for the returned rows + +// Some providers return null if an error occurs, others throw an exception +if (null == mCursor) { + /* + * Insert code here to handle the error. Be sure not to use the cursor! You may want to + * call android.util.Log.e() to log this error. + * + */ +// If the Cursor is empty, the provider found no matches +} else if (mCursor.getCount() < 1) { + + /* + * Insert code here to notify the user that the search was unsuccessful. This isn't necessarily + * an error. You may want to offer the user the option to insert a new row, or re-type the + * search term. + */ + +} else { + // Insert code here to do something with the results + +} +</pre> +<p> + This query is analogous to the SQL statement: +</p> +<pre> +SELECT _ID, word, frequency, locale FROM words WHERE word = <userinput> ORDER BY word ASC; +</pre> +<p> + In this SQL statement, the actual column names are used instead of contract class constants. +</p> +<h4 id="Injection">Protecting against malicious input</h4> +<p> + If the data managed by the content provider is in an SQL database, including external untrusted + data into raw SQL statements can lead to SQL injection. +</p> +<p> + Consider this selection clause: +</p> +<pre> +// Constructs a selection clause by concatenating the user's input to the column name +String mSelectionClause = "var = " + mUserInput; +</pre> +<p> + If you do this, you're allowing the user to concatenate malicious SQL onto your SQL statement. + For example, the user could enter "nothing; DROP TABLE *;" for <code>mUserInput</code>, which + would result in the selection clause <code>var = nothing; DROP TABLE *;</code>. Since the + selection clause is treated as an SQL statement, this might cause the provider to erase all of + the tables in the underlying SQLite database (unless the provider is set up to catch + <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL injection</a> attempts). +</p> +<p> + To avoid this problem, use a selection clause that uses <code>?</code> as a replaceable + parameter and a separate array of selection arguments. When you do this, the user input + is bound directly to the query rather than being interpreted as part of an SQL statement. + Because it's not treated as SQL, the user input can't inject malicious SQL. Instead of using + concatenation to include the user input, use this selection clause: +</p> +<pre> +// Constructs a selection clause with a replaceable parameter +String mSelectionClause = "var = ?"; +</pre> +<p> + Set up the array of selection arguments like this: +</p> +<pre> +// Defines an array to contain the selection arguments +String[] selectionArgs = {""}; +</pre> +<p> + Put a value in the selection arguments array like this: +</p> +<pre> +// Sets the selection argument to the user's input +selectionArgs[0] = mUserInput; +</pre> +<p> + A selection clause that uses <code>?</code> as a replaceable parameter and an array of + selection arguments array are preferred way to specify a selection, even if the provider isn't + based on an SQL database. +</p> +<!-- Displaying the results --> +<h3 id="DisplayResults">Displaying query results</h3> +<p> + The {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) + ContentResolver.query()} client method always returns a {@link android.database.Cursor} + containing the columns specified by the query's projection for the rows that match the query's + selection criteria. A {@link android.database.Cursor} object provides random read access to the + rows and columns it contains. Using {@link android.database.Cursor} methods, + you can iterate over the rows in the results, determine the data type of each column, get the + data out of a column, and examine other properties of the results. Some + {@link android.database.Cursor} implementations automatically update the object when the + provider's data changes, or trigger methods in an observer object when the + {@link android.database.Cursor} changes, or both. +</p> +<p class="note"> + <strong>Note:</strong> A provider may restrict access to columns based on the nature of the + object making the query. For example, the Contacts Provider restricts access for some columns to + sync adapters, so it won't return them to an activity or service. +</p> +<p> + If no rows match the selection criteria, the provider + returns a {@link android.database.Cursor} object for which + {@link android.database.Cursor#getCount() Cursor.getCount()} is 0 (an empty cursor). +</p> +<p> + If an internal error occurs, the results of the query depend on the particular provider. It may + choose to return <code>null</code>, or it may throw an {@link java.lang.Exception}. +</p> +<p> + Since a {@link android.database.Cursor} is a "list" of rows, a good way to display the + contents of a {@link android.database.Cursor} is to link it to a {@link android.widget.ListView} + via a {@link android.widget.SimpleCursorAdapter}. +</p> +<p> + The following snippet continues the code from the previous snippet. It creates a + {@link android.widget.SimpleCursorAdapter} object containing the {@link android.database.Cursor} + retrieved by the query, and sets this object to be the adapter for a + {@link android.widget.ListView}: +</p> +<pre class="prettyprint"> +// Defines a list of columns to retrieve from the Cursor and load into an output row +String[] mWordListColumns = +{ + UserDictionary.Words.WORD, // Contract class constant containing the word column name + UserDictionary.Words.LOCALE // Contract class constant containing the locale column name +}; + +// Defines a list of View IDs that will receive the Cursor columns for each row +int[] mWordListItems = { R.id.dictWord, R.id.locale}; + +// Creates a new SimpleCursorAdapter +mCursorAdapter = new SimpleCursorAdapter( + getApplicationContext(), // The application's Context object + R.layout.wordlistrow, // A layout in XML for one row in the ListView + mCursor, // The result from the query + mWordListColumns, // A string array of column names in the cursor + mWordListItems, // An integer array of view IDs in the row layout + 0); // Flags (usually none are needed) + +// Sets the adapter for the ListView +mWordList.setAdapter(mCursorAdapter); +</pre> +<p class="note"> + <strong>Note:</strong> To back a {@link android.widget.ListView} with a + {@link android.database.Cursor}, the cursor must contain a column named <code>_ID</code>. + Because of this, the query shown previously retrieves the <code>_ID</code> column for the + "words" table, even though the {@link android.widget.ListView} doesn't display it. + This restriction also explains why most providers have a <code>_ID</code> column for each of + their tables. +</p> + + <!-- Getting data from query results --> +<h3 id="GettingResults">Getting data from query results</h3> +<p> + Rather than simply displaying query results, you can use them for other tasks. For + example, you can retrieve spellings from the user dictionary and then look them up in + other providers. To do this, you iterate over the rows in the {@link android.database.Cursor}: +</p> +<pre class="prettyprint"> + +// Determine the column index of the column named "word" +int index = mCursor.getColumnIndex(UserDictionary.Words.WORD); + +/* + * Only executes if the cursor is valid. The User Dictionary Provider returns null if + * an internal error occurs. Other providers may throw an Exception instead of returning null. + */ + +if (mCursor != null) { + /* + * Moves to the next row in the cursor. Before the first movement in the cursor, the + * "row pointer" is -1, and if you try to retrieve data at that position you will get an + * exception. + */ + while (mCursor.moveToNext()) { + + // Gets the value from the column. + newWord = mCursor.getString(index); + + // Insert code here to process the retrieved word. + + ... + + // end of while loop + } +} else { + + // Insert code here to report an error if the cursor is null or the provider threw an exception. +} +</pre> +<p> + {@link android.database.Cursor} implementations contain several "get" methods for + retrieving different types of data from the object. For example, the previous snippet + uses {@link android.database.Cursor#getString(int) getString()}. They also have a + {@link android.database.Cursor#getType(int) getType()} method that returns a value indicating + the data type of the column. +</p> + + + <!-- Requesting permissions --> +<h2 id="Permissions">Content Provider Permissions</h2> +<p> + A provider's application can specify permissions that other applications must have in order to + access the provider's data. These permissions ensure that the user knows what data + an application will try to access. Based on the provider's requirements, other applications + request the permissions they need in order to access the provider. End users see the requested + permissions when they install the application. +</p> +<p> + If a provider's application doesn't specify any permissions, then other applications have no + access to the provider's data. However, components in the provider's application always have + full read and write access, regardless of the specified permissions. +</p> +<p> + As noted previously, the User Dictionary Provider requires the + <code>android.permission.READ_USER_DICTIONARY</code> permission to retrieve data from it. + The provider has the separate <code>android.permission.WRITE_USER_DICTIONARY</code> + permission for inserting, updating, or deleting data. +</p> +<p> + To get the permissions needed to access a provider, an application requests them with a + <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> + <uses-permission></a></code> element in its manifest file. + When the Android Package Manager installs the application, a user must approve all of the + permissions the application requests. If the user approves all of them, Package Manager + continues the installation; if the user doesn't approve them, Package Manager + aborts the installation. +</p> +<p> + The following + <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> + <uses-permission></a></code> element requests read access to the User Dictionary Provider: +</p> +<pre> + <uses-permission android:name="android.permission.READ_USER_DICTIONARY"> +</pre> +<p> + The impact of permissions on provider access is explained in more detail in the + <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> guide. +</p> + + +<!-- Inserting, Updating, and Deleting Data --> +<h2 id="Modifications">Inserting, Updating, and Deleting Data</h2> +<p> + In the same way that you retrieve data from a provider, you also use the interaction between + a provider client and the provider's {@link android.content.ContentProvider} to modify data. + You call a method of {@link android.content.ContentResolver} with arguments that are passed to + the corresponding method of {@link android.content.ContentProvider}. The provider and provider + client automatically handle security and inter-process communication. +</p> +<h3 id="Inserting">Inserting data</h3> +<p> + To insert data into a provider, you call the + {@link android.content.ContentResolver#insert(Uri,ContentValues) ContentResolver.insert()} + method. This method inserts a new row into the provider and returns a content URI for that row. + This snippet shows how to insert a new word into the User Dictionary Provider: +</p> +<pre class="prettyprint"> +// Defines a new Uri object that receives the result of the insertion +Uri mNewUri; + +... + +// Defines an object to contain the new values to insert +ContentValues mNewValues = new ContentValues(); + +/* + * Sets the values of each column and inserts the word. The arguments to the "put" + * method are "column name" and "value" + */ +mNewValues.put(UserDictionary.Words.APP_ID, "example.user"); +mNewValues.put(UserDictionary.Words.LOCALE, "en_US"); +mNewValues.put(UserDictionary.Words.WORD, "insert"); +mNewValues.put(UserDictionary.Words.FREQUENCY, "100"); + +mNewUri = getContentResolver().insert( + UserDictionary.Word.CONTENT_URI, // the user dictionary content URI + mNewValues // the values to insert +); +</pre> +<p> + The data for the new row goes into a single {@link android.content.ContentValues} object, which + is similar in form to a one-row cursor. The columns in this object don't need to have the + same data type, and if you don't want to specify a value at all, you can set a column + to <code>null</code> using {@link android.content.ContentValues#putNull(String) + ContentValues.putNull()}. +</p> +<p> + The snippet doesn't add the <code>_ID</code> column, because this column is maintained + automatically. The provider assigns a unique value of <code>_ID</code> to every row that is + added. Providers usually use this value as the table's primary key. +</p> +<p> + The content URI returned in <code>newUri</code> identifies the newly-added row, with + the following format: +</p> +<pre> +content://user_dictionary/words/<id_value> +</pre> +<p> + The <code><id_value></code> is the contents of <code>_ID</code> for the new row. + Most providers can detect this form of content URI automatically and then perform the requested + operation on that particular row. +</p> +<p> + To get the value of <code>_ID</code> from the returned {@link android.net.Uri}, call + {@link android.content.ContentUris#parseId(Uri) ContentUris.parseId()}. +</p> +<h3 id="Updating">Updating data</h3> +<p> + To update a row, you use a {@link android.content.ContentValues} object with the updated + values just as you do with an insertion, and selection criteria just as you do with a query. + The client method you use is + {@link android.content.ContentResolver#update(Uri, ContentValues, String, String[]) + ContentResolver.update()}. You only need to add values to the + {@link android.content.ContentValues} object for columns you're updating. If you want to clear + the contents of a column, set the value to <code>null</code>. +</p> +<p> + The following snippet changes all the rows whose locale has the language "en" to a + have a locale of <code>null</code>. The return value is the number of rows that were updated: +</p> +<pre> +// Defines an object to contain the updated values +ContentValues mUpdateValues = new ContentValues(); + +// Defines selection criteria for the rows you want to update +String mSelectionClause = UserDictionary.Words.LOCALE + "LIKE ?"; +String[] mSelectionArgs = {"en_%"}; + +// Defines a variable to contain the number of updated rows +int mRowsUpdated = 0; + +... + +/* + * Sets the updated value and updates the selected words. + */ +mUpdateValues.putNull(UserDictionary.Words.LOCALE); + +mRowsUpdated = getContentResolver().update( + UserDictionary.Words.CONTENT_URI, // the user dictionary content URI + mUpdateValues // the columns to update + mSelectionClause // the column to select on + mSelectionArgs // the value to compare to +); +</pre> +<p> + You should also sanitize user input when you call + {@link android.content.ContentResolver#update(Uri, ContentValues, String, String[]) + ContentResolver.update()}. To learn more about this, read the section + <a href="#Injection">Protecting against malicious input</a>. +</p> +<h3 id="Deleting">Deleting data</h3> +<p> + Deleting rows is similar to retrieving row data: you specify selection criteria for the rows + you want to delete and the client method returns the number of deleted rows. + The following snippet deletes rows whose appid matches "user". The method returns the + number of deleted rows. +</p> +<pre> + +// Defines selection criteria for the rows you want to delete +String mSelectionClause = UserDictionary.Words.APP_ID + " LIKE ?"; +String[] mSelectionArgs = {"user"}; + +// Defines a variable to contain the number of rows deleted +int mRowsDeleted = 0; + +... + +// Deletes the words that match the selection criteria +mRowsDeleted = getContentResolver().delete( + UserDictionary.Words.CONTENT_URI, // the user dictionary content URI + mSelectionClause // the column to select on + mSelectionArgs // the value to compare to +); +</pre> +<p> + You should also sanitize user input when you call + {@link android.content.ContentResolver#delete(Uri, String, String[]) + ContentResolver.delete()}. To learn more about this, read the section + <a href="#Injection">Protecting against malicious input</a>. +</p> +<!-- Provider Data Types --> +<h2 id="DataTypes">Provider Data Types</h2> +<p> + Content providers can offer many different data types. The User Dictionary Provider offers only + text, but providers can also offer the following formats: +</p> + <ul> + <li> + integer + </li> + <li> + long integer (long) + </li> + <li> + floating point + </li> + <li> + long floating point (double) + </li> + </ul> +<p> + Another data type that providers often use is Binary Large OBject (BLOB) implemented as a + 64KB byte array. You can see the available data types by looking at the + {@link android.database.Cursor} class "get" methods. +</p> +<p> + The data type for each column in a provider is usually listed in its documentation. + The data types for the User Dictionary Provider are listed in the reference documentation + for its contract class {@link android.provider.UserDictionary.Words} (contract classes are + described in the section <a href="#ContractClasses">Contract Classes</a>). + You can also determine the data type by calling {@link android.database.Cursor#getType(int) + Cursor.getType()}. +</p> +<p> + Providers also maintain MIME data type information for each content URI they define. You can + use the MIME type information to find out if your application can handle data that the + provider offers, or to choose a type of handling based on the MIME type. You usually need the + MIME type when you are working with a provider that contains complex + data structures or files. For example, the {@link android.provider.ContactsContract.Data} + table in the Contacts Provider uses MIME types to label the type of contact data stored in each + row. To get the MIME type corresponding to a content URI, call + {@link android.content.ContentResolver#getType(Uri) ContentResolver.getType()}. +</p> +<p> + The section <a href="#MIMETypeReference">MIME Type Reference</a> describes the + syntax of both standard and custom MIME types. +</p> + + +<!-- Alternative Forms of Provider Access --> +<h2 id="AltForms">Alternative Forms of Provider Access</h2> +<p> + Three alternative forms of provider access are important in application development: +</p> +<ul> + <li> + <a href="#Batch">Batch access</a>: You can create a batch of access calls with methods in + the {@link android.content.ContentProviderOperation} class, and then apply them with + {@link android.content.ContentResolver#applyBatch(String, ArrayList) + ContentResolver.applyBatch()}. + </li> + <li> + Asynchronous queries: You should do queries in a separate thread. One way to do this is to + use a {@link android.content.CursorLoader} object. The examples in the + <a href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a> guide demonstrate + how to do this. + </li> + <li> + <a href="#Intents">Data access via intents</a>: Although you can't send an intent + directly to a provider, you can send an intent to the provider's application, which is + usually the best-equipped to modify the provider's data. + </li> +</ul> +<p> + Batch access and modification via intents are described in the following sections. +</p> +<h3 id="Batch">Batch access</h3> +<p> + Batch access to a provider is useful for inserting a large number of rows, or for inserting + rows in multiple tables in the same method call, or in general for performing a set of + operations across process boundaries as a transaction (an atomic operation). +</p> +<p> + To access a provider in "batch mode", + you create an array of {@link android.content.ContentProviderOperation} objects and then + dispatch them to a content provider with + {@link android.content.ContentResolver#applyBatch(String, ArrayList) + ContentResolver.applyBatch()}. You pass the content provider's <em>authority</em> to this + method, rather than a particular content URI, which allows each + {@link android.content.ContentProviderOperation} object in the array to work against a + different table. A call to {@link android.content.ContentResolver#applyBatch(String, ArrayList) + ContentResolver.applyBatch()} returns an array of results. +</p> +<p> + The description of the {@link android.provider.ContactsContract.RawContacts} contract class + includes a code snippet that demonstrates batch insertion. The + <a href="{@docRoot}resources/samples/ContactManager/index.html">Contact Manager</a> + sample application contains an example of batch access in its <code>ContactAdder.java</code> + source file. +</p> +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Displaying data using a helper app</h2> +<p> + If your application <em>does</em> have access permissions, you still may want to use an + intent to display data in another application. For example, the Calendar application accepts an + {@link android.content.Intent#ACTION_VIEW} intent, which displays a particular date or event. + This allows you to display calendar information without having to create your own UI. + To learn more about this feature, see the + <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a> guide. +</p> +<p> + The application to which you send the intent doesn't have to be the application + associated with the provider. For example, you can retrieve a contact from the + Contact Provider, then send an {@link android.content.Intent#ACTION_VIEW} intent + containing the content URI for the contact's image to an image viewer. +</p> +</div> +</div> +<h3 id="Intents">Data access via intents</h3> +<p> + Intents can provide indirect access to a content provider. You allow the user to access + data in a provider even if your application doesn't have access permissions, either by + getting a result intent back from an application that has permissions, or by activating an + application that has permissions and letting the user do work in it. +</p> +<h4>Getting access with temporary permissions</h4> +<p> + You can access data in a content provider, even if you don't have the proper access + permissions, by sending an intent to an application that does have the permissions and + receiving back a result intent containing "URI" permissions. + These are permissions for a specific content URI that last until the activity that receives + them is finished. The application that has permanent permissions grants temporary + permissions by setting a flag in the result intent: +</p> +<ul> + <li> + <strong>Read permission:</strong> + {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION} + </li> + <li> + <strong>Write permission:</strong> + {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION} + </li> +</ul> +<p class="note"> + <strong>Note:</strong> These flags don't give general read or write access to the provider + whose authority is contained in the content URI. The access is only for the URI itself. +</p> +<p> + A provider defines URI permissions for content URIs in its manifest, using the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> + android:grantUriPermission</a></code> + attribute of the + {@code <a href="guide/topics/manifest/provider-element.html"><provider></a>} + element, as well as the + {@code <a href="guide/topics/manifest/grant-uri-permission-element.html"> + <grant-uri-permission></a>} child element of the + {@code <a href="guide/topics/manifest/provider-element.html"><provider></a>} + element. The URI permissions mechanism is explained in more detail in the + <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> guide, + in the section "URI Permissions". +</p> +<p> + For example, you can retrieve data for a contact in the Contacts Provider, even if you don't + have the {@link android.Manifest.permission#READ_CONTACTS} permission. You might want to do + this in an application that sends e-greetings to a contact on his or her birthday. Instead of + requesting {@link android.Manifest.permission#READ_CONTACTS}, which gives you access to all of + the user's contacts and all of their information, you prefer to let the user control which + contacts are used by your application. To do this, you use the following process: +</p> +<ol> + <li> + Your application sends an intent containing the action + {@link android.content.Intent#ACTION_PICK} and the "contacts" MIME type + {@link android.provider.ContactsContract.RawContacts#CONTENT_ITEM_TYPE}, using the + method {@link android.app.Activity#startActivityForResult(Intent, int) + startActivityForResult()}. + </li> + <li> + Because this intent matches the intent filter for the + People app's "selection" activity, the activity will come to the foreground. + </li> + <li> + In the selection activity, the user selects a + contact to update. When this happens, the selection activity calls + {@link android.app.Activity#setResult(int, Intent) setResult(resultcode, intent)} + to set up a intent to give back to your application. The intent contains the content URI + of the contact the user selected, and the "extras" flags + {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}. These flags grant URI + permission to your app to read data for the contact pointed to by the + content URI. The selection activity then calls {@link android.app.Activity#finish()} to + return control to your application. + </li> + <li> + Your activity returns to the foreground, and the system calls your activity's + {@link android.app.Activity#onActivityResult(int, int, Intent) onActivityResult()} + method. This method receives the result intent created by the selection activity in + the People app. + </li> + <li> + With the content URI from the result intent, you can read the contact's data + from the Contacts Provider, even though you didn't request permanent read access permission + to the provider in your manifest. You can then get the contact's birthday information + or his or her email address and then send the e-greeting. + </li> +</ol> +<h4>Using another application</h4> +<p> + A simple way to allow the user to modify data to which you don't have access permissions is to + activate an application that has permissions and let the user do the work there. +</p> +<p> + For example, the Calendar application accepts an + {@link android.content.Intent#ACTION_INSERT} intent, which allows you to activate the + application's insert UI. You can pass "extras" data in this intent, which the application + uses to pre-populate the UI. Because recurring events have a complex syntax, the preferred + way of inserting events into the Calendar Provider is to activate the Calendar app with an + {@link android.content.Intent#ACTION_INSERT} and then let the user insert the event there. +</p> +<!-- Contract Classes --> +<h2 id="ContractClasses">Contract Classes</h2> +<p> + A contract class defines constants that help applications work with the content URIs, column + names, intent actions, and other features of a content provider. Contract classes are not + included automatically with a provider; the provider's developer has to define them and then + make them available to other developers. Many of the providers included with the Android + platform have corresponding contract classes in the package {@link android.provider}. +</p> +<p> + For example, the User Dictionary Provider has a contract class + {@link android.provider.UserDictionary} containing content URI and column name constants. The + content URI for the "words" table is defined in the constant + {@link android.provider.UserDictionary.Words#CONTENT_URI UserDictionary.Words.CONTENT_URI}. + The {@link android.provider.UserDictionary.Words} class also contains column name constants, + which are used in the example snippets in this guide. For example, a query projection can be + defined as: +</p> +<pre> +String[] mProjection = +{ + UserDictionary.Words._ID, + UserDictionary.Words.WORD, + UserDictionary.Words.LOCALE +}; +</pre> +<p> + Another contract class is {@link android.provider.ContactsContract} for the Contacts Provider. + The reference documentation for this class includes example code snippets. One of its + subclasses, {@link android.provider.ContactsContract.Intents.Insert}, is a contract + class that contains constants for intents and intent data. +</p> + + +<!-- MIME Type Reference --> +<h2 id="MIMETypeReference">MIME Type Reference</h2> +<p> + Content providers can return standard MIME media types, or custom MIME type strings, or both. +</p> +<p> + MIME types have the format +</p> +<pre> +<em>type</em>/<em>subtype</em> +</pre> +<p> + For example, the well-known MIME type <code>text/html</code> has the <code>text</code> type and + the <code>html</code> subtype. If the provider returns this type for a URI, it means that a + query using that URI will return text containing HTML tags. +</p> +<p> + Custom MIME type strings, also called "vendor-specific" MIME types, have more + complex <em>type</em> and <em>subtype</em> values. The <em>type</em> value is always +</p> +<pre> +vnd.android.cursor.<strong>dir</strong> +</pre> +<p> + for multiple rows, or +</p> +<pre> +vnd.android.cursor.<strong>item</strong> +</pre> +<p> + for a single row. +</p> +<p> + The <em>subtype</em> is provider-specific. The Android built-in providers usually have a simple + subtype. For example, the when the Contacts application creates a row for a telephone number, + it sets the following MIME type in the row: +</p> +<pre> +vnd.android.cursor.item/phone_v2 +</pre> +<p> + Notice that the subtype value is simply <code>phone_v2</code>. +</p> +<p> + Other provider developers may create their own pattern of subtypes based on the provider's + authority and table names. For example, consider a provider that contains train timetables. + The provider's authority is <code>com.example.trains</code>, and it contains the tables + Line1, Line2, and Line3. In response to the content URI +</p> +<p> +<pre> +content://com.example.trains/Line1 +</pre> +<p> + for table Line1, the provider returns the MIME type +</p> +<pre> +vnd.android.cursor.<strong>dir</strong>/vnd.example.line1 +</pre> +<p> + In response to the content URI +</p> +<pre> +content://com.example.trains/Line2/5 +</pre> +<p> + for row 5 in table Line2, the provider returns the MIME type +</p> +<pre> +vnd.android.cursor.<strong>item</strong>/vnd.example.line2 +</pre> +<p> + Most content providers define contract class constants for the MIME types they use. The + Contacts Provider contract class {@link android.provider.ContactsContract.RawContacts}, + for example, defines the constant + {@link android.provider.ContactsContract.RawContacts#CONTENT_ITEM_TYPE} for the MIME type of + a single raw contact row. +</p> +<p> + Content URIs for single rows are described in the section + <a href="#ContentURIs">Content URIs</a>. +</p> diff --git a/docs/html/guide/topics/providers/content-provider-creating.jd b/docs/html/guide/topics/providers/content-provider-creating.jd new file mode 100644 index 0000000..4ebdb50 --- /dev/null +++ b/docs/html/guide/topics/providers/content-provider-creating.jd @@ -0,0 +1,1215 @@ +page.title=Creating a Content Provider +@jd:body +<div id="qv-wrapper"> +<div id="qv"> + + +<h2>In this document</h2> +<ol> + <li> + <a href="#DataStorage">Designing Data Storage</a> + </li> + <li> + <a href="#ContentURI">Designing Content URIs</a> + </li> + <li> + <a href="#ContentProvider">Implementing the ContentProvider Class</a> + <ol> + <li> + <a href="#RequiredAccess">Required Methods</a> + </li> + <li> + <a href="#Query">Implementing the query() method</a> + </li> + <li> + <a href="#Insert">Implementing the insert() method</a> + </li> + <li> + <a href="#Delete">Implementing the delete() method</a> + </li> + <li> + <a href="#Update">Implementing the update() method</a> + </li> + <li> + <a href="#OnCreate">Implementing the onCreate() method</a> + </li> + </ol> + </li> + <li> + <a href="#MIMETypes">Implementing Content Provider MIME Types</a> + <ol> + <li> + <a href="#TableMIMETypes">MIME types for tables</a> + </li> + <li> + <a href="#FileMIMETypes">MIME types for files</a> + </li> + </ol> + </li> + <li> + <a href="#ContractClass">Implementing a Contract Class</a> + </li> + <li> + <a href="#Permissions">Implementing Content Provider Permissions</a> + </li> + <li> + <a href="#ProviderElement">The <provider> Element</a> + </li> + <li> + <a href="#Intents">Intents and Data Access</a> + </li> +</ol> +<h2>Key classes</h2> + <ol> + <li> + {@link android.content.ContentProvider} + </li> + <li> + {@link android.database.Cursor} + </li> + <li> + {@link android.net.Uri} + </li> + </ol> +<h2>Related Samples</h2> + <ol> + <li> + <a + href="{@docRoot}resources/samples/NotePad/index.html"> + Note Pad sample application + </a> + </li> + </ol> +<h2>See also</h2> + <ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/calendar-provider.html"> + Calendar Provider</a> + </li> + </ol> +</div> +</div> + + +<p> + A content provider manages access to a central repository of data. You implement a + provider as one or more classes in an Android application, along with elements in + the manifest file. One of your classes implements a subclass + {@link android.content.ContentProvider}, which is the interface between your provider and + other applications. Although content providers are meant to make data available to other + applications, you may of course have activities in your application that allow the user + to query and modify the data managed by your provider. +</p> +<p> + The rest of this topic is a basic list of steps for building a content provider and a list + of APIs to use. +</p> + + +<!-- Before You Start Building --> +<h2 id="BeforeYouStart">Before You Start Building</h2> +<p> + Before you start building a provider, do the following: +</p> +<ol> + <li> + <strong>Decide if you need a content provider</strong>. You need to build a content + provider if you want to provide one or more of the following features: + <ul> + <li>You want to offer complex data or files to other applications.</li> + <li>You want to allow users to copy complex data from your app into other apps.</li> + <li>You want to provide custom search suggestions using the search framework.</li> + </ul> + <p> + You <em>don't</em> need a provider to use an SQLite database if the use is entirely within + your own application. + </p> + </li> + <li> + If you haven't done so already, read the topic + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a> to learn more about providers. + </li> +</ol> +<p> + Next, follow these steps to build your provider: +</p> +<ol> + <li> + Design the raw storage for your data. A content provider offers data in two ways: + <dl> + <dt> + File data + </dt> + <dd> + Data that normally goes into files, such as + photos, audio, or videos. Store the files in your application's private + space. In response to a request for a file from another application, your + provider can offer a handle to the file. + </dd> + <dt> + "Structured" data + </dt> + <dd> + Data that normally goes into a database, array, or similar structure. + Store the data in a form that's compatible with tables of rows and columns. A row + represents an entity, such as a person or an item in inventory. A column represents + some data for the entity, such a person's name or an item's price. A common way to + store this type of data is in an SQLite database, but you can use any type of + persistent storage. To learn more about the storage types available in the + Android system, see the section <a href="#DataStorage"> + Designing Data Storage</a>. + </dd> + </dl> + </li> + <li> + Define a concrete implementation of the {@link android.content.ContentProvider} class and + its required methods. This class is the interface between your data and the rest of the + Android system. For more information about this class, see the section + <a href="#ContentProvider">Implementing the ContentProvider Class</a>. + </li> + <li> + Define the provider's authority string, its content URIs, and column names. If you want + the provider's application to handle intents, also define intent actions, extras data, + and flags. Also define the permissions that you will require for applications that want + to access your data. You should consider defining all of these values as constants in a + separate contract class; later, you can expose this class to other developers. For more + information about content URIs, see the + section <a href="#ContentURI">Designing Content URIs</a>. + For more information about intents, see the + section <a href="#Intents">Intents and Data Access</a>. + </li> + <li> + Add other optional pieces, such as sample data or an implementation + of {@link android.content.AbstractThreadedSyncAdapter} that can synchronize data between + the provider and cloud-based data. + </li> +</ol> + + +<!-- Designing Data Storage --> +<h2 id="DataStorage">Designing Data Storage</h2> +<p> + A content provider is the interface to data saved in a structured format. Before you create + the interface, you must decide how to store the data. You can store the data in any form you + like, and then design the interface to read and write the data as necessary. +</p> +<p> + These are some of the data storage technologies that are available in Android: +</p> +<ul> + <li> + The Android system includes an SQLite database API that Android's own providers use + to store table-oriented data. The + {@link android.database.sqlite.SQLiteOpenHelper} class helps you create databases, and the + {@link android.database.sqlite.SQLiteDatabase} class is the base class for accessing + databases. + <p> + Remember that you don't have to use a database to implement your repository. A provider + appears externally as a set of tables, similar to a relational database, but this is + not a requirement for the provider's internal implementation. + </p> + </li> + <li> + For storing file data, Android has a variety of file-oriented APIs. + To learn more about file storage, read the topic + <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a>. If you're + designing a provider that offers media-related data such as music or videos, you can + have a provider that combines table data and files. + </li> + <li> + For working with network-based data, use classes in {@link java.net} and + {@link android.net}. You can also synchronize network-based data to a local data + store such as a database, and then offer the data as tables or files. + The <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> sample application demonstrates this type of synchronization. + </li> +</ul> +<h3 id="DataDesign"> + Data design considerations +</h3> +<p> + Here are some tips for designing your provider's data structure: +</p> +<ul> + <li> + Table data should always have a "primary key" column that the provider maintains + as a unique numeric value for each row. You can use this value to link the row to related + rows in other tables (using it as a "foreign key"). Although you can use any name + for this column, using {@link android.provider.BaseColumns#_ID BaseColumns._ID} is the best + choice, because linking the results of a provider query to a + {@link android.widget.ListView} requires one of the retrieved columns to have the name + <code>_ID</code>. + </li> + <li> + If you want to provide bitmap images or other very large pieces of file-oriented data, store + the data in a file and then provide it indirectly rather than storing it directly in a + table. If you do this, you need to tell users of your provider that they need to use a + {@link android.content.ContentResolver} file method to access the data. + </li> + <li> + Use the Binary Large OBject (BLOB) data type to store data that varies in size or has a + varying structure. For example, you can use a BLOB column to store a + <a href="http://code.google.com/p/protobuf">protocol buffer</a> or + <a href="http://www.json.org">JSON structure</a>. + <p> + You can also use a BLOB to implement a <em>schema-independent</em> table. In + this type of table, you define a primary key column, a MIME type column, and one or + more generic columns as BLOB. The meaning of the data in the BLOB columns is indicated + by the value in the MIME type column. This allows you to store different row types in + the same table. The Contacts Provider's "data" table + {@link android.provider.ContactsContract.Data} is an example of a schema-independent + table. + </p> + </li> +</ul> +<!-- Designing Content URIs --> +<h2 id="ContentURI">Designing Content URIs</h2> +<p> + A <strong>content URI</strong> is a URI that identifies data in a provider. Content URIs include + the symbolic name of the entire provider (its <strong>authority</strong>) and a + name that points to a table or file (a <strong>path</strong>). The optional id part points to + an individual row in a table. Every data access method of + {@link android.content.ContentProvider} has a content URI as an argument; this allows you to + determine the table, row, or file to access. +</p> +<p> + The basics of content URIs are described in the topic + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a>. +</p> +<h3>Designing an authority</h3> +<p> + A provider usually has a single authority, which serves as its Android-internal name. To + avoid conflicts with other providers, you should use Internet domain ownership (in reverse) + as the basis of your provider authority. Because this recommendation is also true for Android + package names, you can define your provider authority as an extension of the name + of the package containing the provider. For example, if your Android package name is + <code>com.example.<appname></code>, you should give your provider the + authority <code>com.example.<appname>.provider</code>. +</p> +<h3>Designing a path structure</h3> +<p> + Developers usually create content URIs from the authority by appending paths that point to + individual tables. For example, if you have two tables <em>table1</em> and + <em>table2</em>, you combine the authority from the previous example to yield the + content URIs + <code>com.example.<appname>.provider/table1</code> and + <code>com.example.<appname>.provider/table2</code>. Paths aren't + limited to a single segment, and there doesn't have to be a table for each level of the path. +</p> +<h3>Handling content URI IDs</h3> +<p> + By convention, providers offer access to a single row in a table by accepting a content URI + with an ID value for the row at the end of the URI. Also by convention, providers match the + ID value to the table's <code>_ID</code> column, and perform the requested access against the + row that matches. +</p> +<p> + This convention facilitates a common design pattern for apps accessing a provider. The app + does a query against the provider and displays the resulting {@link android.database.Cursor} + in a {@link android.widget.ListView} using a {@link android.widget.CursorAdapter}. + The definition of {@link android.widget.CursorAdapter} requires one of the columns in the + {@link android.database.Cursor} to be <code>_ID</code> +</p> +<p> + The user then picks one of the displayed rows from the UI in order to look at or modify the + data. The app gets the corresponding row from the {@link android.database.Cursor} backing the + {@link android.widget.ListView}, gets the <code>_ID</code> value for this row, appends it to + the content URI, and sends the access request to the provider. The provider can then do the + query or modification against the exact row the user picked. +</p> +<h3>Content URI patterns</h3> +<p> + To help you choose which action to take for an incoming content URI, the provider API includes + the convenience class {@link android.content.UriMatcher}, which maps content URI "patterns" to + integer values. You can use the integer values in a <code>switch</code> statement that + chooses the desired action for the content URI or URIs that match a particular pattern. +</p> +<p> + A content URI pattern matches content URIs using wildcard characters: +</p> + <ul> + <li> + <strong><code>*</code>:</strong> Matches a string of any valid characters of any length. + </li> + <li> + <strong><code>#</code>:</strong> Matches a string of numeric characters of any length. + </li> + </ul> +<p> + As an example of designing and coding content URI handling, consider a provider with the + authority <code>com.example.app.provider</code> that recognizes the following content URIs + pointing to tables: +</p> +<ul> + <li> + <code>content://com.example.app.provider/table1</code>: A table called <code>table1</code>. + </li> + <li> + <code>content://com.example.app.provider/table2/dataset1</code>: A table called + <code>dataset1</code>. + </li> + <li> + <code>content://com.example.app.provider/table2/dataset2</code>: A table called + <code>dataset2</code>. + </li> + <li> + <code>content://com.example.app.provider/table3</code>: A table called <code>table3</code>. + </li> +</ul> +<p> + The provider also recognizes these content URIs if they have a row ID appended to them, as + for example <code>content://com.example.app.provider/table3/1</code> for the row identified by + <code>1</code> in <code>table3</code>. +</p> +<p> + The following content URI patterns would be possible: +</p> +<dl> + <dt> + <code>content://com.example.app.provider/*</code> + </dt> + <dd> + Matches any content URI in the provider. + </dd> + <dt> + <code>content://com.example.app.provider/table2/*</code>: + </dt> + <dd> + Matches a content URI for the tables <code>dataset1</code> + and <code>dataset2</code>, but doesn't match content URIs for <code>table1</code> or + <code>table3</code>. + </dd> + <dt> + <code>content://com.example.app.provider/table3/#</code>: Matches a content URI + for single rows in <code>table3</code>, such as + <code>content://com.example.app.provider/table3/6</code> for the row identified by + <code>6</code>. + </dt> +</dl> +<p> + The following code snippet shows how the methods in {@link android.content.UriMatcher} work. + This code handles URIs for an entire table differently from URIs for a + single row, by using the content URI pattern + <code>content://<authority>/<path></code> for tables, and + <code>content://<authority>/<path>/<id></code> for single rows. +</p> +<p> + The method {@link android.content.UriMatcher#addURI(String, String, int) addURI()} maps an + authority and path to an integer value. The method android.content.UriMatcher#match(Uri) + match()} returns the integer value for a URI. A <code>switch</code> statement + chooses between querying the entire table, and querying for a single record: +</p> +<pre class="prettyprint"> +public class ExampleProvider extends ContentProvider { +... + // Creates a UriMatcher object. + private static final UriMatcher sUriMatcher; +... + /* + * The calls to addURI() go here, for all of the content URI patterns that the provider + * should recognize. For this snippet, only the calls for table 3 are shown. + */ +... + /* + * Sets the integer value for multiple rows in table 3 to 1. Notice that no wildcard is used + * in the path + */ + sUriMatcher.addURI("com.example.app.provider", "table3", 1); + + /* + * Sets the code for a single row to 2. In this case, the "#" wildcard is + * used. "content://com.example.app.provider/table3/3" matches, but + * "content://com.example.app.provider/table3 doesn't. + */ + sUriMatcher.addURI("com.example.app.provider", "table3/#", 2); +... + // Implements ContentProvider.query() + public Cursor query( + Uri uri, + String[] projection, + String selection, + String[] selectionArgs, + String sortOrder) { +... + /* + * Choose the table to query and a sort order based on the code returned for the incoming + * URI. Here, too, only the statements for table 3 are shown. + */ + switch (sUriMatcher.match(uri)) { + + + // If the incoming URI was for all of table3 + case 1: + + if (TextUtils.isEmpty(sortOrder)) sortOrder = "_ID ASC"; + break; + + // If the incoming URI was for a single row + case 2: + + /* + * Because this URI was for a single row, the _ID value part is + * present. Get the last path segment from the URI; this is the _ID value. + * Then, append the value to the WHERE clause for the query + */ + selection = selection + "_ID = " uri.getLastPathSegment(); + break; + + default: + ... + // If the URI is not recognized, you should do some error handling here. + } + // call the code to actually do the query + } +</pre> +<p> + Another class, {@link android.content.ContentUris}, provides convenience methods for working + with the <code>id</code> part of content URIs. The classes {@link android.net.Uri} and + {@link android.net.Uri.Builder} include convenience methods for parsing existing + {@link android.net.Uri} objects and building new ones. +</p> + +<!-- Implementing the ContentProvider class --> +<h2 id="ContentProvider">Implementing the ContentProvider Class</h2> +<p> + The {@link android.content.ContentProvider} instance manages access + to a structured set of data by handling requests from other applications. All forms + of access eventually call {@link android.content.ContentResolver}, which then calls a concrete + method of {@link android.content.ContentProvider} to get access. +</p> +<h3 id="RequiredAccess">Required methods</h3> +<p> + The abstract class {@link android.content.ContentProvider} defines six abstract methods that + you must implement as part of your own concrete subclass. All of these methods except + {@link android.content.ContentProvider#onCreate() onCreate()} are called by a client application + that is attempting to access your content provider: +</p> +<dl> + <dt> + {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) + query()} + </dt> + <dd> + Retrieve data from your provider. Use the arguments to select the table to + query, the rows and columns to return, and the sort order of the result. + Return the data as a {@link android.database.Cursor} object. + </dd> + <dt> + {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} + </dt> + <dd> + Insert a new row into your provider. Use the arguments to select the + destination table and to get the column values to use. Return a content URI for the + newly-inserted row. + </dd> + <dt> + {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) + update()} + </dt> + <dd> + Update existing rows in your provider. Use the arguments to select the table and rows + to update and to get the updated column values. Return the number of rows updated. + </dd> + <dt> + {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} + </dt> + <dd> + Delete rows from your provider. Use the arguments to select the table and the rows to + delete. Return the number of rows deleted. + </dd> + <dt> + {@link android.content.ContentProvider#getType(Uri) getType()} + </dt> + <dd> + Return the MIME type corresponding to a content URI. This method is described in more + detail in the section <a href="#MIMETypes">Implementing Content Provider MIME Types</a>. + </dd> + <dt> + {@link android.content.ContentProvider#onCreate() onCreate()} + </dt> + <dd> + Initialize your provider. The Android system calls this method immediately after it + creates your provider. Notice that your provider is not created until a + {@link android.content.ContentResolver} object tries to access it. + </dd> +</dl> +<p> + Notice that these methods have the same signature as the identically-named + {@link android.content.ContentResolver} methods. +</p> +<p> + Your implementation of these methods should account for the following: +</p> +<ul> + <li> + All of these methods except {@link android.content.ContentProvider#onCreate() onCreate()} + can be called by multiple threads at once, so they must be thread-safe. To learn + more about multiple threads, see the topic + <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html"> + Processes and Threads</a>. + </li> + <li> + Avoid doing lengthy operations in {@link android.content.ContentProvider#onCreate() + onCreate()}. Defer initialization tasks until they are actually needed. + The section <a href="#OnCreate">Implementing the onCreate() method</a> + discusses this in more detail. + </li> + <li> + Although you must implement these methods, your code does not have to do anything except + return the expected data type. For example, you may want to prevent other applications + from inserting data into some tables. To do this, you can ignore the call to + {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} and return + 0. + </li> +</ul> +<h3 id="Query">Implementing the query() method</h3> +<p> + The + {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) + ContentProvider.query()} method must return a {@link android.database.Cursor} object, or if it + fails, throw an {@link java.lang.Exception}. If you are using an SQLite database as your data + storage, you can simply return the {@link android.database.Cursor} returned by one of the + <code>query()</code> methods of the {@link android.database.sqlite.SQLiteDatabase} class. + If the query does not match any rows, you should return a {@link android.database.Cursor} + instance whose {@link android.database.Cursor#getCount()} method returns 0. + You should return <code>null</code> only if an internal error occurred during the query process. +</p> +<p> + If you aren't using an SQLite database as your data storage, use one of the concrete subclasses + of {@link android.database.Cursor}. For example, the {@link android.database.MatrixCursor} class + implements a cursor in which each row is an array of {@link java.lang.Object}. With this class, + use {@link android.database.MatrixCursor#addRow(Object[]) addRow()} to add a new row. +</p> +<p> + Remember that the Android system must be able to communicate the {@link java.lang.Exception} + across process boundaries. Android can do this for the following exceptions that may be useful + in handling query errors: +</p> +<ul> + <li> + {@link java.lang.IllegalArgumentException} (You may choose to throw this if your provider + receives an invalid content URI) + </li> + <li> + {@link java.lang.NullPointerException} + </li> +</ul> +<h3 id="Insert">Implementing the insert() method</h3> +<p> + The {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} method adds a + new row to the appropriate table, using the values in the {@link android.content.ContentValues} + argument. If a column name is not in the {@link android.content.ContentValues} argument, you + may want to provide a default value for it either in your provider code or in your database + schema. +</p> +<p> + This method should return the content URI for the new row. To construct this, append the new + row's <code>_ID</code> (or other primary key) value to the table's content URI, using + {@link android.content.ContentUris#withAppendedId(Uri, long) withAppendedId()}. +</p> +<h3 id="Delete">Implementing the delete() method</h3> +<p> + The {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} method + does not have to physically delete rows from your data storage. If you are using a sync adapter + with your provider, you should consider marking a deleted row + with a "delete" flag rather than removing the row entirely. The sync adapter can + check for deleted rows and remove them from the server before deleting them from the provider. +</p> +<h3 id="Update">Implementing the update() method</h3> +<p> + The {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) + update()} method takes the same {@link android.content.ContentValues} argument used by + {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()}, and the + same <code>selection</code> and <code>selectionArgs</code> arguments used by + {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} and + {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) + ContentProvider.query()}. This may allow you to re-use code between these methods. +</p> +<h3 id="OnCreate">Implementing the onCreate() method</h3> +<p> + The Android system calls {@link android.content.ContentProvider#onCreate() + onCreate()} when it starts up the provider. You should perform only fast-running initialization + tasks in this method, and defer database creation and data loading until the provider actually + receives a request for the data. If you do lengthy tasks in + {@link android.content.ContentProvider#onCreate() onCreate()}, you will slow down your + provider's startup. In turn, this will slow down the response from the provider to other + applications. +</p> +<p> + For example, if you are using an SQLite database you can create + a new {@link android.database.sqlite.SQLiteOpenHelper} object in + {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}, + and then create the SQL tables the first time you open the database. To facilitate this, the + first time you call {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase + getWritableDatabase()}, it automatically calls the + {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) + SQLiteOpenHelper.onCreate()} method. +</p> +<p> + The following two snippets demonstrate the interaction between + {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()} and + {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) + SQLiteOpenHelper.onCreate()}. The first snippet is the implementation of + {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}: +</p> +<pre class="prettyprint"> +public class ExampleProvider extends ContentProvider + + /* + * Defines a handle to the database helper object. The MainDatabaseHelper class is defined + * in a following snippet. + */ + private MainDatabaseHelper mOpenHelper; + + // Defines the database name + private static final String DBNAME = "mydb"; + + // Holds the database object + private SQLiteDatabase db; + + public boolean onCreate() { + + /* + * Creates a new helper object. This method always returns quickly. + * Notice that the database itself isn't created or opened + * until SQLiteOpenHelper.getWritableDatabase is called + */ + mOpenHelper = new SQLiteOpenHelper( + getContext(), // the application context + DBNAME, // the name of the database) + null, // uses the default SQLite cursor + 1 // the version number + ); + + return true; + } + + ... + + // Implements the provider's insert method + public Cursor insert(Uri uri, ContentValues values) { + // Insert code here to determine which table to open, handle error-checking, and so forth + + ... + + /* + * Gets a writeable database. This will trigger its creation if it doesn't already exist. + * + */ + db = mOpenHelper.getWritableDatabase(); + } +} +</pre> +<p> + The next snippet is the implementation of + {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) + SQLiteOpenHelper.onCreate()}, including a helper class: +</p> +<pre class="prettyprint"> +... +// A string that defines the SQL statement for creating a table +private static final String SQL_CREATE_MAIN = "CREATE TABLE " + + "main " + // Table's name + "(" + // The columns in the table + " _ID INTEGER PRIMARY KEY, " + + " WORD TEXT" + " FREQUENCY INTEGER " + + " LOCALE TEXT )"; +... +/** + * Helper class that actually creates and manages the provider's underlying data repository. + */ +protected static final class MainDatabaseHelper extends SQLiteOpenHelper { + + /* + * Instantiates an open helper for the provider's SQLite data repository + * Do not do database creation and upgrade here. + */ + MainDatabaseHelper(Context context) { + super(context, DBNAME, null, 1); + } + + /* + * Creates the data repository. This is called when the provider attempts to open the + * repository and SQLite reports that it doesn't exist. + */ + public void onCreate(SQLiteDatabase db) { + + // Creates the main table + db.execSQL(SQL_CREATE_MAIN); + } +} +</pre> + + +<!-- Implementing ContentProvider MIME Types --> +<h2 id="MIMETypes">Implementing ContentProvider MIME Types</h2> +<p> + The {@link android.content.ContentProvider} class has two methods for returning MIME types: +</p> +<dl> + <dt> + {@link android.content.ContentProvider#getType(Uri) getType()} + </dt> + <dd> + One of the required methods that you must implement for any provider. + </dd> + <dt> + {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()} + </dt> + <dd> + A method that you're expected to implement if your provider offers files. + </dd> +</dl> +<h3 id="TableMIMETypes">MIME types for tables</h3> +<p> + The {@link android.content.ContentProvider#getType(Uri) getType()} method returns a + {@link java.lang.String} in MIME format that describes the type of data returned by the content + URI argument. The {@link android.net.Uri} argument can be a pattern rather than a specific URI; + in this case, you should return the type of data associated with content URIs that match the + pattern. +</p> +<p> + For common types of data such as as text, HTML, or JPEG, + {@link android.content.ContentProvider#getType(Uri) getType()} should return the standard + MIME type for that data. A full list of these standard types is available on the + <a href="http://www.iana.org/assignments/media-types/index.htm">IANA MIME Media Types</a> + website. +</p> +<p> + For content URIs that point to a row or rows of table data, + {@link android.content.ContentProvider#getType(Uri) getType()} should return + a MIME type in Android's vendor-specific MIME format: +</p> +<ul> + <li> + Type part: <code>vnd</code> + </li> + <li> + Subtype part: + <ul> + <li> + If the URI pattern is for a single row: <code>android.cursor.<strong>item</strong>/</code> + </li> + <li> + If the URI pattern is for more than one row: <code>android.cursor.<strong>dir</strong>/</code> + </li> + </ul> + </li> + <li> + Provider-specific part: <code>vnd.<name></code>.<code><type></code> + <p> + You supply the <code><name></code> and <code><type></code>. + The <code><name></code> value should be globally unique, + and the <code><type></code> value should be unique to the corresponding URI + pattern. A good choice for <code><name></code> is your company's name or + some part of your application's Android package name. A good choice for the + <code><type></code> is a string that identifies the table associated with the + URI. + </p> + + </li> +</ul> +<p> + For example, if a provider's authority is + <code>com.example.app.provider</code>, and it exposes a table named + <code>table1</code>, the MIME type for multiple rows in <code>table1</code> is: +</p> +<pre> +vnd.android.cursor.<strong>dir</strong>/vnd.com.example.provider.table1 +</pre> +<p> + For a single row of <code>table1</code>, the MIME type is: +</p> +<pre> +vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1 +</pre> +<h3 id="FileMIMETypes">MIME types for files</h3> +<p> + If your provider offers files, implement + {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}. + The method returns a {@link java.lang.String} array of MIME types for the files your provider + can return for a given content URI. You should filter the MIME types you offer by the MIME type + filter argument, so that you return only those MIME types that the client wants to handle. +</p> +<p> + For example, consider a provider that offers photo images as files in <code>.jpg</code>, + <code>.png</code>, and <code>.gif</code> format. + If an application calls {@link android.content.ContentResolver#getStreamTypes(Uri, String) + ContentResolver.getStreamTypes()} with the filter string <code>image/*</code> (something that + is an "image"), + then the {@link android.content.ContentProvider#getStreamTypes(Uri, String) + ContentProvider.getStreamTypes()} method should return the array: +</p> +<pre> +{ "image/jpeg", "image/png", "image/gif"} +</pre> +<p> + If the app is only interested in <code>.jpg</code> files, then it can call + {@link android.content.ContentResolver#getStreamTypes(Uri, String) + ContentResolver.getStreamTypes()} with the filter string <code>*\/jpeg</code>, and + {@link android.content.ContentProvider#getStreamTypes(Uri, String) + ContentProvider.getStreamTypes()} should return: +<pre> +{"image/jpeg"} +</pre> +<p> + If your provider doesn't offer any of the MIME types requested in the filter string, + {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()} + should return <code>null</code>. +</p> + + +<!-- Implementing a Contract Class --> +<h2 id="ContractClass">Implementing a Contract Class</h2> +<p> + A contract class is a <code>public final</code> class that contains constant definitions for the + URIs, column names, MIME types, and other meta-data that pertain to the provider. The class + establishes a contract between the provider and other applications by ensuring that the provider + can be correctly accessed even if there are changes to the actual values of URIs, column names, + and so forth. +</p> +<p> + A contract class also helps developers because it usually has mnemonic names for its constants, + so developers are less likely to use incorrect values for column names or URIs. Since it's a + class, it can contain Javadoc documentation. Integrated development environments such as + Eclipse can auto-complete constant names from the contract class and display Javadoc for the + constants. +</p> +<p> + Developers can't access the contract class's class file from your application, but they can + statically compile it into their application from a <code>.jar</code> file you provide. +</p> +<p> + The {@link android.provider.ContactsContract} class and its nested classes are examples of + contract classes. +</p> +<h2 id="Permissions">Implementing Content Provider Permissions</h2> +<p> + Permissions and access for all aspects of the Android system are described in detail in the + topic <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. + The topic <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a> also + described the security and permissions in effect for various types of storage. + In brief, the important points are: +</p> +<ul> + <li> + By default, data files stored on the device's internal storage are private to your + application and provider. + </li> + <li> + {@link android.database.sqlite.SQLiteDatabase} databases you create are private to your + application and provider. + </li> + <li> + By default, data files that you save to external storage are <em>public</em> and + <em>world-readable</em>. You can't use a content provider to restrict access to files in + external storage, because other applications can use other API calls to read and write them. + </li> + <li> + The method calls for opening or creating files or SQLite databases on your device's internal + storage can potentially give both read and write access to all other applications. If you + use an internal file or database as your provider's repository, and you give it + "world-readable" or "world-writeable" access, the permissions you set for your provider in + its manifest won't protect your data. The default access for files and databases in + internal storage is "private", and for your provider's repository you shouldn't change this. + </li> +</ul> +<p> + If you want to use content provider permissions to control access to your data, then you should + store your data in internal files, SQLite databases, or the "cloud" (for example, + on a remote server), and you should keep files and databases private to your application. +</p> +<h3>Implementing permissions</h3> +<p> + All applications can read from or write to your provider, even if the underlying data is + private, because by default your provider does not have permissions set. To change this, + set permissions for your provider in your manifest file, using attributes or child + elements of the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. You can set permissions that apply to the entire provider, + or to certain tables, or even to certain records, or all three. +</p> +<p> + You define permissions for your provider with one or more + <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"> + <permission></a></code> elements in your manifest file. To make the + permission unique to your provider, use Java-style scoping for the + <code><a href="{@docRoot}guide/topics/manifest/permission-element.html#nm"> + android:name</a></code> attribute. For example, name the read permission + <code>com.example.app.provider.permission.READ_PROVIDER</code>. + +</p> +<p> + The following list describes the scope of provider permissions, starting with the + permissions that apply to the entire provider and then becoming more fine-grained. + More fine-grained permissions take precedence over ones with larger scope: +</p> +<dl> + <dt> + Single read-write provider-level permission + </dt> + <dd> + One permission that controls both read and write access to the entire provider, specified + with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> + android:permission</a></code> attribute of the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. + </dd> + <dt> + Separate read and write provider-level permission + </dt> + <dd> + A read permission and a write permission for the entire provider. You specify them + with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn"> + android:readPermission</a></code> and + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn"> + android:writePermission</a></code> attributes of the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. They take precedence over the permission required by + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> + android:permission</a></code>. + </dd> + <dt> + Path-level permission + </dt> + <dd> + Read, write, or read/write permission for a content URI in your provider. You specify + each URI you want to control with a + <code><a href="{@docRoot}guide/topics/manifest/path-permission-element.html"> + <path-permission></a></code> child element of the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. For each content URI you specify, you can specify a + read/write permission, a read permission, or a write permission, or all three. The read and + write permissions take precedence over the read/write permission. Also, path-level + permission takes precedence over provider-level permissions. + </dd> + <dt> + Temporary permission + </dt> + <dd> + A permission level that grants temporary access to an application, even if the application + doesn't have the permissions that are normally required. The temporary + access feature reduces the number of permissions an application has to request in + its manifest. When you turn on temporary permissions, the only applications that need + "permanent" permissions for your provider are ones that continually access all + your data. + <p> + Consider the permissions you need to implement an email provider and app, when you + want to allow an outside image viewer application to display photo attachments from your + provider. To give the image viewer the necessary access without requiring permissions, + set up temporary permissions for content URIs for photos. Design your email app so + that when the user wants to display a photo, the app sends an intent containing the + photo's content URI and permission flags to the image viewer. The image viewer can + then query your email provider to retrieve the photo, even though the viewer doesn't + have the normal read permission for your provider. + </p> + <p> + To turn on temporary permissions, either set the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> + android:grantUriPermissions</a></code> attribute of the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element, or add one or more + <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> + <grant-uri-permission></a></code> child elements to your + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. If you use temporary permissions, you have to call + {@link android.content.Context#revokeUriPermission(Uri, int) + Context.revokeUriPermission()} whenever you remove support for a content URI from your + provider, and the content URI is associated with a temporary permission. + </p> + <p> + The attribute's value determines how much of your provider is made accessible. + If the attribute is set to <code>true</code>, then the system will grant temporary + permission to your entire provider, overriding any other permissions that are required + by your provider-level or path-level permissions. + </p> + <p> + If this flag is set to <code>false</code>, then you must add + <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> + <grant-uri-permission></a></code> child elements to your + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. Each child element specifies the content URI or + URIs for which temporary access is granted. + </p> + <p> + To delegate temporary access to an application, an intent must contain + the {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION} or the + {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION} flags, or both. These + are set with the {@link android.content.Intent#setFlags(int) setFlags()} method. + </p> + <p> + If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> + android:grantUriPermissions</a></code> attribute is not present, it's assumed to be + <code>false</code>. + </p> + </dd> +</dl> + + + +<!-- The Provider Element --> +<h2 id="ProviderElement">The <provider> Element</h2> +<p> + Like {@link android.app.Activity} and {@link android.app.Service} components, + a subclass of {@link android.content.ContentProvider} + must be defined in the manifest file for its application, using the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. The Android system gets the following information from + the element: +<dl> + <dt> + Authority + (<a href="{@docRoot}guide/topics/manifest/provider-element.html#auth">{@code + android:authorities}</a>) + </dt> + <dd> + Symbolic names that identify the entire provider within the system. This + attribute is described in more detail in the section + <a href="#ContentURI">Designing Content URIs</a>. + </dd> + <dt> + Provider class name + (<code> +<a href="{@docRoot}guide/topics/manifest/provider-element.html#nm">android:name</a> + </code>) + </dt> + <dd> + The class that implements {@link android.content.ContentProvider}. This class is + described in more detail in the section + <a href="#ContentProvider">Implementing the ContentProvider Class</a>. + </dd> + <dt> + Permissions + </dt> + <dd> + Attributes that specify the permissions that other applications must have in order to access + the provider's data: + <ul> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> + android:grantUriPermssions</a></code>: Temporary permission flag. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> + android:permission</a></code>: Single provider-wide read/write permission. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn"> + android:readPermission</a></code>: Provider-wide read permission. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn"> + android:writePermission</a></code>: Provider-wide write permission. + </li> + </ul> + <p> + Permissions and their corresponding attributes are described in more + detail in the section + <a href="#Permissions">Implementing Content Provider Permissions</a>. + </p> + </dd> + <dt> + Startup and control attributes + </dt> + <dd> + These attributes determine how and when the Android system starts the provider, the + process characteristics of the provider, and other run-time settings: + <ul> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#enabled"> + android:enabled</a></code>: Flag allowing the system to start the provider. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#exported"> + android:exported</a></code>: Flag allowing other applications to use this provider. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#init"> + android:initOrder</a></code>: The order in which this provider should be started, + relative to other providers in the same process. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#multi"> + android:multiProcess</a></code>: Flag allowing the system to start the provider + in the same process as the calling client. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#proc"> + android:process</a></code>: The name of the process in which the provider should + run. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#sync"> + android:syncable</a></code>: Flag indicating that the provider's data is to be + sync'ed with data on a server. + </li> + </ul> + <p> + The attributes are fully documented in the dev guide topic for the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> + element. + </p> + </dd> + <dt> + Informational attributes + </dt> + <dd> + An optional icon and label for the provider: + <ul> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#icon"> + android:icon</a></code>: A drawable resource containing an icon for the provider. + The icon appears next to the provider's label in the list of apps in + <em>Settings</em> > <em>Apps</em> > <em>All</em>. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#label"> + android:label</a></code>: An informational label describing the provider or its + data, or both. The label appears in the list of apps in + <em>Settings</em> > <em>Apps</em> > <em>All</em>. + </li> + </ul> + <p> + The attributes are fully documented in the dev guide topic for the + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> element. + </p> + </dd> +</dl> + +<!-- Intent Access --> +<h2 id="Intents">Intents and Data Access</h2> +<p> + Applications can access a content provider indirectly with an {@link android.content.Intent}. + The application does not call any of the methods of {@link android.content.ContentResolver} or + {@link android.content.ContentProvider}. Instead, it sends an intent that starts an activity, + which is often part of the provider's own application. The destination activity is in charge of + retrieving and displaying the data in its UI. Depending on the action in the intent, the + destination activity may also prompt the user to make modifications to the provider's data. + An intent may also contain "extras" data that the destination activity displays + in the UI; the user then has the option of changing this data before using it to modify the + data in the provider. +</p> +<p> + +</p> +<p> + You may want to use intent access to help ensure data integrity. Your provider may depend + on having data inserted, updated, and deleted according to strictly defined business logic. If + this is the case, allowing other applications to directly modify your data may lead to + invalid data. If you want developers to use intent access, be sure to document it thoroughly. + Explain to them why intent access using your own application's UI is better than trying to + modify the data with their code. +</p> +<p> + Handling an incoming intent that wishes to modify your provider's data is no different from + handling other intents. You can learn more about using intents by reading the topic + <a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>. +</p> diff --git a/docs/html/guide/topics/providers/content-providers.jd b/docs/html/guide/topics/providers/content-providers.jd index 95331ce..1707f03 100644 --- a/docs/html/guide/topics/providers/content-providers.jd +++ b/docs/html/guide/topics/providers/content-providers.jd @@ -1,922 +1,96 @@ page.title=Content Providers @jd:body - <div id="qv-wrapper"> <div id="qv"> -<h2>In this document</h2> -<ol> -<li><a href="#basics">Content provider basics</a></li> -<li><a href="#querying">Querying a content provider</a></li> -<li><a href="#modifying">Modifying data in a provider</a></li> -<li><a href="#creating">Creating a content provider</a></li> -<li><a href="#urisum">Content URI summary</a></li> -</ol> -<h2>Key classes</h2> +<!-- In this document --> +<h2>Topics</h2> <ol> -<li>{@link android.content.ContentProvider}</li> -<li>{@link android.content.ContentResolver}</li> -<li>{@link android.database.Cursor}</li> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Creating a Content Provider</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a> + </li> </ol> -<h2>See also</h2> -<ol> - <li><a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a></li> -</ol> + <!-- Related Samples --> +<h2>Related Samples</h2> + <ol> + <li> + <a href="{@docRoot}resources/samples/ContactManager/index.html"> + Contact Manager</a> application + </li> + <li> + <a + href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List2.html"> + "Cursor (People)" + </a> + </li> + <li> + <a + href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List7.html"> + "Cursor (Phones)"</a> + </li> + </ol> </div> </div> - -<p> -Content providers store and retrieve data and make it accessible to all -applications. They're the only way to share data across applications; there's -no common storage area that all Android packages can access. -</p> - -<p> -Android ships with a number of content providers for common data types -(audio, video, images, personal contact information, and so on). You can -see some of them listed in the {@link android.provider android.provider} -package. You can query these providers for the data they contain (although, -for some, you must acquire the proper permission to read the data). -</p> - -<p class="note"><strong>Note:</strong> Android 4.0 introduces the Calendar -Provider. For more information, see <a -href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar -Provider</a>.</p> -<p> -If you want to make your own data public, you have two options: You can -create your own content provider (a {@link android.content.ContentProvider} -subclass) or you can add the data to an existing provider — if there's -one that controls the same type of data and you have permission to write to it. -</p> - -<p> -This document is an introduction to using content providers. After a -brief discussion of the fundamentals, it explores how to query a content -provider, how to modify data controlled by a provider, and how to create -a content provider of your own. -</p> - - -<h2><a name="basics"></a>Content Provider Basics</h2> - -<p> -How a content provider actually stores its data under the covers is -up to its designer. But all content providers implement a common interface -for querying the provider and returning results — as well as for -adding, altering, and deleting data. -</p> - -<p> -It's an interface that clients use indirectly, most generally through -{@link android.content.ContentResolver} objects. You get a ContentResolver -by calling <code>{@link android.content.Context#getContentResolver -getContentResolver()}</code> from within the implementation of an Activity -or other application component: -</p> - -<pre>ContentResolver cr = getContentResolver();</pre> - -<p> -You can then use the ContentResolver's methods to interact with whatever -content providers you're interested in. -</p> - -<p> -When a query is initiated, the Android system identifies the content provider -that's the target of the query and makes sure that it is up and running. -The system instantiates all ContentProvider objects; you never need to do it -on your own. In fact, you never deal directly with ContentProvider objects -at all. Typically, there's just a single instance of each type of -ContentProvider. But it can communicate with multiple ContentResolver objects -in different applications and processes. The interaction between processes is -handled by the ContentResolver and ContentProvider classes. -</p> - - -<h3>The data model</h3> - -<p> -Content providers expose their data as a simple table on a database model, -where each row is a record and each column is data of a particular type -and meaning. For example, information about people and their phone numbers -might be exposed as follows: -</p> - -<table> - <tr> - <th scope="col">_ID</th> - <th scope="col">NUMBER</th> - <th scope="col">NUMBER_KEY</th> - <th scope="col">LABEL</th> - <th scope="col">NAME</th> - <th scope="col">TYPE</th> - </tr> - <tr> - <td>13</td> - <td>(425) 555 6677</td> - <td>425 555 6677</td> - <td>Kirkland office</td> - <td>Bully Pulpit</td> - <td>{@code TYPE_WORK}</td> - </tr> - <tr> - <td>44</td> - <td>(212) 555-1234</td> - <td>212 555 1234</td> - <td>NY apartment</td> - <td>Alan Vain</td> - <td>{@code TYPE_HOME}</td> - </tr> - <tr> - <td>45</td> - <td>(212) 555-6657</td> - <td>212 555 6657</td> - <td>Downtown office</td> - <td>Alan Vain</td> - <td>{@code TYPE_MOBILE}</td> - </tr> - <tr> - <td>53</td> - <td>201.555.4433</td> - <td>201 555 4433</td> - <td>Love Nest</td> - <td>Rex Cars</td> - <td>{@code TYPE_HOME}</td> - </tr> -</table> - -<p> -Every record includes a numeric {@code _ID} field that uniquely identifies -the record within the table. IDs can be used to match records in related -tables — for example, to find a person's phone number in one table -and pictures of that person in another. -</p> - -<p> -A query returns a {@link android.database.Cursor} object that can move from -record to record and column to column to read the contents of each field. -It has specialized methods for reading each type of data. So, to read a field, -you must know what type of data the field contains. (There's more on query -results and Cursor objects later.) -</p> - - -<h3><a name="uri"></a>URIs</h3> - -<p> -Each content provider exposes a public URI (wrapped as a {@link android.net.Uri} -object) that uniquely identifies its data set. A content provider that controls -multiple data sets (multiple tables) exposes a separate URI for each one. All -URIs for providers begin with the string "{@code content://}". The {@code content:} -scheme identifies the data as being controlled by a content provider. -</p> - -<p> -If you're defining a content provider, it's a good idea to also define a -constant for its URI, to simplify client code and make future updates cleaner. -Android defines {@code CONTENT_URI} constants for all the providers that come -with the platform. For example, the URI for the table that matches -phone numbers to people and the URI for the table that holds pictures of -people (both controlled by the Contacts content provider) are: -</p> - -<p> -<p style="margin-left: 2em">{@code android.provider.Contacts.Phones.CONTENT_URI} -<br/>{@code android.provider.Contacts.Photos.CONTENT_URI} -</p> - -<p> -The URI constant is used in all interactions with the content provider. -Every {@link android.content.ContentResolver} method takes the URI -as its first argument. It's what identifies which provider the ContentResolver -should talk to and which table of the provider is being targeted. -</p> - - -<h2><a name="querying"></a>Querying a Content Provider</h2> - -<p> -You need three pieces of information to query a content provider: -</p> - -<ul> -<li>The URI that identifies the provider</li> -<li>The names of the data fields you want to receive</li> -<li>The data types for those fields</li> -</ul> - -<p> -If you're querying a particular record, you also need the ID for that record. -</p> - - -<h3>Making the query</h3> - -<p> -To query a content provider, you can use either the -<code>{@link android.content.ContentResolver#query ContentResolver.query()}</code> -method or the <code>{@link android.app.Activity#managedQuery -Activity.managedQuery()}</code> method. -Both methods take the same set of arguments, and both return a -Cursor object. However, {@code managedQuery()} -causes the activity to manage the life cycle of the Cursor. A managed Cursor -handles all of the niceties, such as unloading itself when the activity pauses, -and requerying itself when the activity restarts. You can ask an Activity to -begin managing an unmanaged Cursor object for you by calling -<code>{@link android.app.Activity#startManagingCursor -Activity.startManagingCursor()}</code>. -</p> - -<p> -The first argument to either <code>{@link android.content.ContentResolver#query query()}</code> -or <code>{@link android.app.Activity#managedQuery managedQuery()}</code> is the provider URI -— the {@code CONTENT_URI} constant that identifies a particular -ContentProvider and data set (see <a href="#uri">URIs</a> earlier). -</p> - -<p> -To restrict a query to just one record, you can append the {@code _ID} value for -that record to the URI — that is, place a string matching the ID as the -last segment of the path part of the URI. For example, if the ID is 23, -the URI would be: -</p> - -<p style="margin-left: 2em">{@code content://. . . ./23}</p> - -<p> -There are some helper methods, particularly -<code>{@link android.content.ContentUris#withAppendedId -ContentUris.withAppendedId()}</code> and <code>{@link -android.net.Uri#withAppendedPath Uri.withAppendedPath()}</code>, -that make it easy to append an ID to a URI. Both are static methods that return -a Uri object with the ID added. So, for example, if you were looking for record -23 in the database of people contacts, you might construct a query as follows: -</p> - -<pre> -import android.provider.Contacts.People; -import android.content.ContentUris; -import android.net.Uri; -import android.database.Cursor; - -// Use the ContentUris method to produce the base URI for the contact with _ID == 23. -Uri myPerson = ContentUris.withAppendedId(People.CONTENT_URI, 23); - -// Alternatively, use the Uri method to produce the base URI. -// It takes a string rather than an integer. -Uri myPerson = Uri.withAppendedPath(People.CONTENT_URI, "23"); - -// Then query for this specific record: -Cursor cur = managedQuery(myPerson, null, null, null, null); -</pre> - -<p> -The other arguments to the <code>{@link android.content.ContentResolver#query query()}</code> -and <code>{@link android.app.Activity#managedQuery managedQuery()}</code> methods delimit -the query in more detail. They are: -</p> - -<ul> -<li>The names of the data columns that should be returned. A {@code null} -value returns all columns. Otherwise, only columns that are listed by name -are returned. All the content providers that come with the platform define -constants for their columns. For example, the -{@link android.provider.Contacts.Phones android.provider.Contacts.Phones} class -defines constants for the names of the columns in the phone table illustrated -earlier — {@code _ID}, {@code NUMBER}, {@code NUMBER_KEY}, {@code NAME}, -and so on.</li> - -<li><p>A filter detailing which rows to return, formatted as an SQL {@code WHERE} -clause (excluding the {@code WHERE} itself). A {@code null} value returns -all rows (unless the URI limits the query to a single record).</p></li> - -<li><p>Selection arguments.</p></li> - -<li><p>A sorting order for the rows that are returned, formatted as an SQL -{@code ORDER BY} clause (excluding the {@code ORDER BY} itself). A {@code null} -value returns the records in the default order for the table, which may be -unordered.</p></li> -</ul> - -<p> -Let's look at an example query to retrieve a list of contact names and their -primary phone numbers: -</p> - -<pre> -import android.provider.Contacts.People; -import android.database.Cursor; - -// Form an array specifying which columns to return. -String[] projection = new String[] { - People._ID, - People._COUNT, - People.NAME, - People.NUMBER - }; - -// Get the base URI for the People table in the Contacts content provider. -Uri contacts = People.CONTENT_URI; - -// Make the query. -Cursor managedCursor = managedQuery(contacts, - projection, // Which columns to return - null, // Which rows to return (all rows) - null, // Selection arguments (none) - // Put the results in ascending order by name - People.NAME + " ASC"); -</pre> - -<p> -This query retrieves data from the People table of the Contacts content -provider. It gets the name, primary phone number, and unique record ID for -each contact. It also reports the number of records that are returned as -the {@code _COUNT} field of each record. -</p> - -<p> -The constants for the names of the columns are defined in various interfaces -— {@code _ID} and {@code _COUNT} in -{@link android.provider.BaseColumns BaseColumns}, {@code NAME} in {@link android.provider.Contacts.PeopleColumns PeopleColumns}, and {@code NUMBER} -in {@link android.provider.Contacts.PhonesColumns PhoneColumns}. The -{@link android.provider.Contacts.People Contacts.People} class implements -each of these interfaces, which is why the code example above could refer -to them using just the class name. -</p> - - -<h3>What a query returns</h3> - -<p> -A query returns a set of zero or more database records. The names of the -columns, their default order, and their data types are specific to each -content provider. -But every provider has an {@code _ID} column, which holds a unique numeric -ID for each record. Every provider can also report the number -of records returned as the {@code _COUNT} column; its value -is the same for all rows. -</p> - -<p> -Here is an example result set for the query in the previous section: -</p> - -<table border="1"> - <tbody> - <tr> - <th scope="col">_ID</th> - <th scope="col">_COUNT</th> - <th scope="col">NAME</th> - <th scope="col">NUMBER</th> - </tr> - <tr> - <td>44</td> - <td>3</td> - <td>Alan Vain</td> - <td>212 555 1234</td> - </tr> - <tr> - <td>13</td> - <td>3</td> - <td>Bully Pulpit</td> - <td>425 555 6677</td> - </tr> - <tr> - <td>53</td> - <td>3</td> - <td>Rex Cars</td> - <td>201 555 4433</td> - </tr> - </tbody> -</table> - -<p> -The retrieved data is exposed by a {@link android.database.Cursor Cursor} -object that can be used to iterate backward or forward through the result -set. You can use this object only to read the data. To add, modify, or -delete data, you must use a ContentResolver object. -</p> - - -<h3>Reading retrieved data</h3> - -<p> -The Cursor object returned by a query provides access to a recordset of -results. If you have queried for a specific record by ID, this set will -contain only one value. Otherwise, it can contain multiple values. -(If there are no matches, it can also be empty.) You -can read data from specific fields in the record, but you must know the -data type of the field, because the Cursor object has a separate method -for reading each type of data — such as <code>{@link -android.database.Cursor#getString getString()}</code>, <code>{@link -android.database.Cursor#getInt getInt()}</code>, and <code>{@link -android.database.Cursor#getFloat getFloat()}</code>. -(However, for most types, if you call the method for reading strings, -the Cursor object will give you the String representation of the data.) -The Cursor lets you request the column name from the index of the column, -or the index number from the column name. -</p> - -<p> -The following snippet demonstrates reading names and phone numbers from -the query illustrated earlier: -</p> - -<pre> -import android.provider.Contacts.People; - -private void getColumnData(Cursor cur){ - if (cur.moveToFirst()) { - - String name; - String phoneNumber; - int nameColumn = cur.getColumnIndex(People.NAME); - int phoneColumn = cur.getColumnIndex(People.NUMBER); - String imagePath; - - do { - // Get the field values - name = cur.getString(nameColumn); - phoneNumber = cur.getString(phoneColumn); - - // Do something with the values. - ... - - } while (cur.moveToNext()); - - } -} -</pre> - -<p> -If a query can return binary data, such as an image or sound, the data -may be directly entered in the table or the table entry for that data may be -a string specifying a {@code content:} URI that you can use to get the data. -In general, smaller amounts of data (say, from 20 to 50K or less) are most often -directly entered in the table and can be read by calling -<code>{@link android.database.Cursor#getBlob Cursor.getBlob()}</code>. -It returns a byte array. -</p> - -<p> -If the table entry is a {@code content:} URI, you should never try to open -and read the file directly (for one thing, permissions problems can make this -fail). Instead, you should call -<code>{@link android.content.ContentResolver#openInputStream -ContentResolver.openInputStream()}</code> to get an -{@link java.io.InputStream} object that you can use to read the data. -</p> - - -<h2><a name="modifying"></a>Modifying Data</h2> - -<p> -Data kept by a content provider can be modified by: -</p> - -<ul> -<p><li>Adding new records</li> -<li>Adding new values to existing records</li> -<li>Batch updating existing records</li> -<li>Deleting records</li> -</ul> - -<p> -All data modification is accomplished using {@link android.content.ContentResolver} -methods. Some content providers require a more restrictive permission for writing -data than they do for reading it. If you don't have permission to write to a -content provider, the ContentResolver methods will fail. -</p> - - -<h3>Adding records</h3> - -<p> -To add a new record to a content provider, first set up a map of key-value pairs -in a {@link android.content.ContentValues} object, where each key matches -the name of a column in the content provider and the value is the desired -value for the new record in that column. Then call <code>{@link -android.content.ContentResolver#insert ContentResolver.insert()}</code> and pass -it the URI of the provider and the ContentValues map. This method returns -the full URI of the new record — that is, the provider's URI with -the appended ID for the new record. You can then use this URI to query and -get a Cursor over the new record, and to further modify the record. -Here's an example: -</p> - -<pre> -import android.provider.Contacts.People; -import android.content.ContentResolver; -import android.content.ContentValues; - -ContentValues values = new ContentValues(); - -// Add Abraham Lincoln to contacts and make him a favorite. -values.put(People.NAME, "Abraham Lincoln"); -// 1 = the new contact is added to favorites -// 0 = the new contact is not added to favorites -values.put(People.STARRED, 1); - -Uri uri = getContentResolver().insert(People.CONTENT_URI, values); -</pre> - - -<h3>Adding new values</h3> - -<p> -Once a record exists, you can add new information to it or modify -existing information. For example, the next step in the example above would -be to add contact information — like a phone number or an IM or e-mail -address — to the new entry. -</p> - -<p> -The best way to add to a record in the Contacts database is to append -the name of the table where the new data goes to the URI for the -record, then use the amended URI to add the new data values. Each -Contacts table exposes a name for this purpose as a {@code -CONTENT_DIRECTORY} constant. The following code continues the previous -example by adding a phone number and e-mail address for the record -just created: -</p> - -<pre> -Uri phoneUri = null; -Uri emailUri = null; - -// Add a phone number for Abraham Lincoln. Begin with the URI for -// the new record just returned by insert(); it ends with the _ID -// of the new record, so we don't have to add the ID ourselves. -// Then append the designation for the phone table to this URI, -// and use the resulting URI to insert the phone number. -phoneUri = Uri.withAppendedPath(uri, People.Phones.CONTENT_DIRECTORY); - -values.clear(); -values.put(People.Phones.TYPE, People.Phones.TYPE_MOBILE); -values.put(People.Phones.NUMBER, "1233214567"); -getContentResolver().insert(phoneUri, values); - -// Now add an email address in the same way. -emailUri = Uri.withAppendedPath(uri, People.ContactMethods.CONTENT_DIRECTORY); - -values.clear(); -// ContactMethods.KIND is used to distinguish different kinds of -// contact methods, such as email, IM, etc. -values.put(People.ContactMethods.KIND, Contacts.KIND_EMAIL); -values.put(People.ContactMethods.DATA, "test@example.com"); -values.put(People.ContactMethods.TYPE, People.ContactMethods.TYPE_HOME); -getContentResolver().insert(emailUri, values); -</pre> - -<p> -You can place small amounts of binary data into a table by calling -the version of <code>{@link android.content.ContentValues#put -ContentValues.put()}</code> that takes a byte array. -That would work for a small icon-like image or a short audio clip, for example. -However, if you have a large amount of binary data to add, such as a photograph -or a complete song, put a {@code content:} URI for the data in the table and call -<code>{@link android.content.ContentResolver#openOutputStream -ContentResolver.openOutputStream()}</code> -with the file's URI. (That causes the content provider to store the data -in a file and record the file path in a hidden field of the record.) -</p> - -<p> -In this regard, the {@link android.provider.MediaStore} content -provider, the main provider that dispenses image, audio, and video -data, employs a special convention: The same URI that is used with -{@code query()} or {@code managedQuery()} to get meta-information -about the binary data (such as, the caption of a photograph or the -date it was taken) is used with {@code openInputStream()} -to get the data itself. Similarly, the same URI that is used with -{@code insert()} to put meta-information into a MediaStore record -is used with {@code openOutputStream()} to place the binary data there. -The following code snippet illustrates this convention: -</p> - -<pre> -import android.provider.MediaStore.Images.Media; -import android.content.ContentValues; -import java.io.OutputStream; - -// Save the name and description of an image in a ContentValues map. -ContentValues values = new ContentValues(3); -values.put(Media.DISPLAY_NAME, "road_trip_1"); -values.put(Media.DESCRIPTION, "Day 1, trip to Los Angeles"); -values.put(Media.MIME_TYPE, "image/jpeg"); - -// Add a new record without the bitmap, but with the values just set. -// insert() returns the URI of the new record. -Uri uri = getContentResolver().insert(Media.EXTERNAL_CONTENT_URI, values); - -// Now get a handle to the file for that record, and save the data into it. -// Here, sourceBitmap is a Bitmap object representing the file to save to the database. -try { - OutputStream outStream = getContentResolver().openOutputStream(uri); - sourceBitmap.compress(Bitmap.CompressFormat.JPEG, 50, outStream); - outStream.close(); -} catch (Exception e) { - Log.e(TAG, "exception while writing image", e); -} -</pre> - - -<h3>Batch updating records</h3> - -<p> -To batch update a group of records (for example, to change "NY" to "New York" -in all fields), call the <code>{@link -android.content.ContentResolver#update ContentResolver.update()}</code> -method with the columns and values to change. -</p> - - -<h3><a name="deletingrecord"></a>Deleting a record</h3> - -<p> -To delete a single record, call {<code>{@link -android.content.ContentResolver#delete ContentResolver.delete()}</code> -with the URI of a specific row. -</p> - <p> -To delete multiple rows, call <code>{@link -android.content.ContentResolver#delete ContentResolver.delete()}</code> -with the URI of the type of record to delete (for example, {@code android.provider.Contacts.People.CONTENT_URI}) and an SQL {@code WHERE} -clause defining which rows to delete. (<i><b>Caution</b>: -Be sure to include a valid {@code WHERE} clause if you're deleting a general -type, or you risk deleting more records than you intended!</i>). -</p> - - -<h2><a name="creating"></a>Creating a Content Provider</h2> - -<p> -To create a content provider, you must: -</p> - -<ul> -<li>Set up a system for storing the data. Most content providers -store their data using Android's file storage methods or SQLite databases, -but you can store your data any way you want. Android provides the -{@link android.database.sqlite.SQLiteOpenHelper SQLiteOpenHelper} -class to help you create a database and {@link -android.database.sqlite.SQLiteDatabase SQLiteDatabase} to manage it.</li> - -<li><p>Extend the {@link android.content.ContentProvider} class to provide -access to the data.</p></li> - -<li><p>Declare the content provider in the manifest file for your -application (AndroidManifest.xml).</p></li> -</ul> - -<p> -The following sections have notes on the last two of these tasks. -</p> - - -<h3>Extending the ContentProvider class</h3> - -<p> -You define a {@link android.content.ContentProvider} subclass to -expose your data to others using the conventions expected by -ContentResolver and Cursor objects. Principally, this means -implementing six abstract methods declared in the ContentProvider class: -</p> - -<p style="margin-left: 2em">{@code query()} -<br/>{@code insert()} -<br/>{@code update()} -<br/>{@code delete()} -<br/>{@code getType()} -<br/>{@code onCreate()}</p> - -<p> -The {@code query()} method must return a {@link android.database.Cursor} object -that can iterate over the requested data. Cursor itself is an interface, but -Android provides some ready-made Cursor objects that you can use. For example, -{@link android.database.sqlite.SQLiteCursor} can iterate over data stored in -an SQLite database. You get the Cursor object by calling any of the {@link -android.database.sqlite.SQLiteDatabase SQLiteDatabase} class's {@code query()} -methods. There are other Cursor implementations — such as {@link -android.database.MatrixCursor} — for data not stored in a database. -</p> - -<p> -Because these ContentProvider methods can be called from -various ContentResolver objects in different processes and threads, -they must be implemented in a thread-safe manner. -</p> - -<p> -As a courtesy, you might also want to call <code>{@link android.content.ContentResolver#notifyChange(android.net.Uri,android.database.ContentObserver) -ContentResolver.notifyChange()}</code> to notify listeners when there are -modifications to the data. -</p> - -<p> -Beyond defining the subclass itself, there are other steps you should take -to simplify the work of clients and make the class more accessible: -</p> - -<ul> -<li>Define a {@code public static final} {@link android.net.Uri} -named {@code CONTENT_URI}. This is the string that represents the full -{@code content:} URI that your content provider handles. You must define a -unique string for this value. The best solution is to use the fully-qualified -class name of the content provider (made lowercase). So, for example, the -URI for a TransportationProvider class could be defined as follows: - -<pre>public static final Uri CONTENT_URI = - Uri.parse("content://com.example.codelab.transportationprovider");</pre> - -<p> -If the provider has subtables, also define {@code CONTENT_URI} constants for -each of the subtables. These URIs should all have the same authority (since -that identifies the content provider), and be distinguished only by their paths. -For example: -</p> - -<p style="margin-left: 2em">{@code content://com.example.codelab.transportationprovider/train} -<br/>{@code content://com.example.codelab.transportationprovider/air/domestic} -<br/>{@code content://com.example.codelab.transportationprovider/air/international}</p> - -<p> -For an overview of {@code content:} URIs, see the <a href="#urisum">Content URI -Summary</a> at the end of this document. -</p></li> - -<li><p>Define the column names that the content provider will return to clients. -If you are using an underlying database, these column names are typically -identical to the SQL database column names they represent. Also define -{@code public static} String constants that clients can use to specify -the columns in queries and other instructions. -</p> - -<p> -Be sure to include an integer column named "{@code _id}" -(with the constant {@code _ID}) for -the IDs of the records. You should have this field whether or not you have -another field (such as a URL) that is also unique among all records. If -you're using the SQLite database, the {@code _ID} field should be the -following type: -</p> - -<p style="margin-left: 2em">{@code INTEGER PRIMARY KEY AUTOINCREMENT}</p> - -<p> -The {@code AUTOINCREMENT} descriptor is optional. But without it, SQLite -increments an ID counter field to the next number above the largest -existing number in the column. If you delete the last row, the next row added -will have the same ID as the deleted row. {@code AUTOINCREMENT} avoids this -by having SQLite increment to the next largest value whether deleted or not. -</p> -</li> - -<li><p>Carefully document the data type of each column. Clients need this -information to read the data.</p></li> - -<li><p>If you are handling a new data type, you must define a new MIME type -to return in your implementation of <code>{@link -android.content.ContentProvider#getType ContentProvider.getType()}</code>. -The type depends in part on whether or not the {@code content:} URI submitted -to {@code getType()} limits the request to a specific record. There's one -form of the MIME type for a single record and another for multiple records. -Use the {@link android.net.Uri Uri} methods to help determine what is being -requested. Here is the general format for each type:</p></li> - -<ul> -<li><p>For a single record: {@code vnd.android.cursor.item/vnd.<em>yourcompanyname.contenttype</em>}</p> - -<p>For example, a request for train record 122, like this URI,</p> -<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains/122}</p> - -<p>might return this MIME type:</p> -<p style="margin-left: 2em">{@code vnd.android.cursor.item/vnd.example.rail}</p> -</li> - -<li><p>For multiple records: {@code vnd.android.cursor.dir/vnd.<em>yourcompanyname.contenttype</em>}</p> - -<p>For example, a request for all train records, like the following URI,</p> -<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains}</p> - -<p>might return this MIME type:</p> -<p style="margin-left: 2em">{@code vnd.android.cursor.dir/vnd.example.rail}</p> -</li> -</ul> - -<li><p>If you are exposing byte data that's too big to put in the table itself -— such as a large bitmap file — the field that exposes the -data to clients should actually contain a {@code content:} URI string. -This is the field that gives clients access to the data file. The record -should also have another field, named "{@code _data}" that lists the exact file -path on the device for that file. This field is not intended to be read by -the client, but by the ContentResolver. The client will call <code>{@link -android.content.ContentResolver#openInputStream ContentResolver.openInputStream()}</code> -on the user-facing field holding the URI for the item. The ContentResolver -will request the "{@code _data}" field for that record, and because -it has higher permissions than a client, it should be able to access -that file directly and return a read wrapper for the file to the client.</p></li> - -</ul> - -<p> -For an example of a private content provider implementation, see the -NodePadProvider class in the Notepad sample application that ships with the SDK. -</p> - - -<h3>Declaring the content provider</h3> - -<p> -To let the Android system know about the content provider you've developed, -declare it with a {@code <provider>} element in the application's -AndroidManifest.xml file. Content providers that are not declared in the -manifest are not visible to the Android system -</p> - -<p> -The {@code name} attribute is the fully qualified name of the ContentProvider -subclass. The {@code authorities} attribute is the authority part of the -{@code content:} URI that identifies the provider. -For example if the ContentProvider subclass is AutoInfoProvider, the -{@code <provider>} element might look like this: -</p> - -<pre> -<provider android:name="com.example.autos.AutoInfoProvider" - android:authorities="com.example.autos.autoinfoprovider" - . . . /> -</provider> -</pre> - -<p> -Note that the {@code authorities} attribute omits the path part of a -{@code content:} URI. For example, if AutoInfoProvider controlled subtables -for different types of autos or different manufacturers, -</p> - -<p style="margin-left: 2em">{@code content://com.example.autos.autoinfoprovider/honda} -<br/>{@code content://com.example.autos.autoinfoprovider/gm/compact} -<br/>{@code content://com.example.autos.autoinfoprovider/gm/suv}</p> - -<p> -those paths would not be declared in the manifest. The authority is what -identifies the provider, not the path; your provider can interpret the path -part of the URI in any way you choose. -</p> - -<p> -Other {@code <provider>} attributes can set permissions to read and -write data, provide for an icon and text that can be displayed to users, -enable and disable the provider, and so on. Set the {@code multiprocess} -attribute to "{@code true}" if data does not need to be synchronized between -multiple running versions of the content provider. This permits an instance -of the provider to be created in each client process, eliminating the need -to perform IPC. -</p> - - -<h2><a name="urisum"></a>Content URI Summary</h2> - -<p> -Here is a recap of the important parts of a content URI: -</p> - -<p> -<img src="{@docRoot}images/content_uri.png" alt="Elements of a content URI" -height="80" width="528"> -</p> - -<ol type="A"> -<li>Standard prefix indicating that the data is controlled by a -content provider. It's never modified.</li> - -<li><p>The authority part of the URI; it identifies the content provider. -For third-party applications, this should be a fully-qualified class name -(reduced to lowercase) to ensure uniqueness. The authority is declared in -the {@code <provider>} element's {@code authorities} attribute:</p> - -<pre><provider android:name=".TransportationProvider" - android:authorities="com.example.transportationprovider" - . . . ></pre></li> - -<li><p>The path that the content provider uses to determine what kind of data is -being requested. This can be zero or more segments long. If the content provider -exposes only one type of data (only trains, for example), it can be absent. -If the provider exposes several types, including subtypes, it can be several -segments long — for example, "{@code land/bus}", "{@code land/train}", -"{@code sea/ship}", and "{@code sea/submarine}" to give four possibilities.</p></li> - -<li><p>The ID of the specific record being requested, if any. This is the -{@code _ID} value of the requested record. If the request is not limited to -a single record, this segment and the trailing slash are omitted:</p> - -<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains}</p> -</li> -</ol> - - + Content providers manage access to a structured set of data. They encapsulate the + data, and provide mechanisms for defining data security. Content providers are the standard + interface that connects data in one process with code running in another process. +</p> +<p> + When you want to access data in a content provider, you use the + {@link android.content.ContentResolver} object in your + application's {@link android.content.Context} to communicate with the provider as a client. + The {@link android.content.ContentResolver} object communicates with the provider object, an + instance of a class that implements {@link android.content.ContentProvider}. The provider + object receives data requests from clients, performs the requested action, and + returns the results. +</p> +<p> + You don't need to develop your own provider if you don't intend to share your data with + other applications. However, you do need your own provider to provide custom search + suggestions in your own application. You also need your own provider if you want to copy and + paste complex data or files from your application to other applications. +</p> +<p> + Android itself includes content providers that manage data such as audio, video, images, and + personal contact information. You can see some of them listed in the reference + documentation for the + <code><a href="{@docRoot}reference/android/provider/package-summary.html">android.provider</a> + </code> package. With some restrictions, these providers are accessible to any Android + application. +</p><p> + The following topics describe content providers in more detail: +</p> +<dl> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Content Provider Basics</a></strong> + </dt> + <dd> + How to access data in a content provider when the data is organized in tables. + </dd> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Creating a Content Provider</a></strong> + </dt> + <dd> + How to create your own content provider. + </dd> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/calendar-provider.html"> + Calendar Provider</a></strong> + </dt> + <dd> + How to access the Calendar Provider that is part of the Android platform. + </dd> +</dl> diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd index 8f08f59..e827f00 100644 --- a/docs/html/guide/topics/renderscript/compute.jd +++ b/docs/html/guide/topics/renderscript/compute.jd @@ -1,38 +1,253 @@ page.title=Compute -parent.title=RenderScript +parent.title=Renderscript parent.link=index.html + @jd:body - <div id="qv-wrapper"> - <div id="qv"> +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li> + <a href="#creating">Creating a Compute Renderscript</a> + + <ol> + <li><a href="#creating-renderscript">Creating the Renderscript file</a></li> - <h2>Related Samples</h2> + <li><a href="#calling">Calling the Renderscript code</a></li> + </ol> + </li> + </ol> - <ol> - <li><a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">Hello - Compute</a></li> - <li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li> - </ol> - </div> + <h2>Related Samples</h2> + + <ol> + <li><a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">Hello + Compute</a></li> + + <li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li> + </ol> </div> +</div> + +<p>Renderscript exposes a set of compute APIs that you can use to do intensive computational +operations. You can use the compute APIs in the context of a graphics Renderscript such as +calculating the positions of many objects in a scene. You can also create standalone compute +Renderscripts such as one that does image processing for a photo editor application.</p> + +<p>Compute Renderscripts scale to the amount of +processing cores available on the device. This is enabled through a function named +<code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level). +that automatically partitions work across available processing cores on the device. +For now, compute Renderscripts can only take advantage of CPU +cores, but in the future, they can potentially run on other types of processors such as GPUs and +DSPs.</p> + +<h2 id="creating-renderscript">Creating a Compute Renderscript</h2> + +<p>Implementing a compute Renderscript creating a <code>.rs</code> file that contains +your Renderscript code and calling it at the Android framework level with the +<code>forEach_root()</code> or at the Renderscript runtime level with the +<code>rsForEach()</code> function. The following diagram describes how a typical compute +Renderscript is set up:</p><img src="{@docRoot}images/rs_compute.png"> + +<p class="img-caption"><strong>Figure 1.</strong> Compute Renderscript overview</p> + +<p>The following sections describe how to create a simple compute Renderscript and use it in an +Android application. This example uses the <a href= +"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute Renderscript +sample</a> that is provided in the SDK as a guide (some code has been modified from its original +form for simplicity).</p> + +<h3 id="creating-renderscript">Creating the Renderscript file</h3> + +<p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> files in the +<code><project_root>/src/</code> directory. This code contains the compute logic +and declares all necessary variables and pointers. +Every compute <code>.rs</code> file generally contains the following items:</p> + +<ul> + <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) + that declares the package name of the <code>.java</code> reflection of this Renderscript.</li> + + <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of + Renderscript that you are using (1 is the only value for now).</li> + + <li>A <code>root()</code> function that is the main worker function. The root function is + called by the <code>rsForEach</code> function, which allows the Renderscript code to be called and + executed on multiple cores if they are available. The <code>root()</code> function must return + <code>void</code> and accept the following arguments: + + <ul> + <li>Pointers to memory allocations that are used for the input and output of the compute + Renderscript. Both of these pointers are required for Android 3.2 (API level 13) platform + versions or older. Android 4.0 (API level 14) and later requires one or both of these + allocations.</li> + </ul> + + <p>The following arguments are optional, but both must be supplied if you choose to use + them:</p> + + <ul> + <li>A pointer for user-defined data that the Renderscript might need to carry out + computations in addition to the necessary allocations. This can be a pointer to a simple + primitive or a more complex struct.</li> + + <li>The size of the user-defined data.</li> + </ul> + </li> + + <li>An optional <code>init()</code> function. This allows you to do any initialization + before the <code>root()</code> function runs, such as initializing variables. This + function runs once and is called automatically when the Renderscript starts, before anything + else in your Renderscript.</li> + + <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can + be declared in <code>.rsh</code> files if desired)</li> +</ul> + +<p>The following code shows how the <a href= +"{@docRoot}resources/samples/RenderScript/HelloCompute/src/com/example/android/rs/hellocompute/mono.html"> +mono.rs</a> file is implemented:</p> +<pre> +#pragma version(1) +#pragma rs java_package_name(com.example.android.rs.hellocompute) + +//multipliers to convert a RGB colors to black and white +const static float3 gMonoMult = {0.299f, 0.587f, 0.114f}; + +void root(const uchar4 *v_in, uchar4 *v_out) { + //unpack a color to a float4 + float4 f4 = rsUnpackColor8888(*v_in); + //take the dot product of the color and the multiplier + float3 mono = dot(f4.rgb, gMonoMult); + //repack the float to a color + *v_out = rsPackColorTo8888(mono); +} +</pre> + +<h3 id="calling">Calling the Renderscript code</h3> + +<p>You can do Renderscript to Renderscript calls with <code>rsForEach</code> in situations +such as when a graphics Renderscript needs to do a lot of computational operations. The Renderscript +<a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a> sample shows how +this is setup. The <a href= +"resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">balls.rs</a> +graphics Renderscript calls the <a href= +"resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">balls_physics.rs</a> +compute Renderscript to calculate the location of the balls that are rendered to the screen.</p> + +<p>Another way to use a compute Renderscript is to call it from your Android framework code by +creating a Renderscript object by instantiating the (<code>ScriptC_<em>script_name</em></code>) +class. This class contains a method, <code>forEach_root()</code>, that lets you invoke +<code>rsForEach</code>. You give it the same parameters that you would if you were invoking it +at the Renderscript runtime level. This technique allows your Android application to offload +intensive mathematical calculations to Renderscript. See the <a href= +"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample to see +how a simple Android application can utilize a compute Renderscript.</p> + +<p>To call a compute Renderscript at the Android framework level:</p> + +<ol> + <li>Allocate memory that is needed by the compute Renderscript in your Android framework code. + You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level + 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only + one or both {@link android.renderscript.Allocation}s.</li> + + <li>Create an instance of the <code>ScriptC_<em>script_name</em></code> class.</li> + + <li>Call <code>forEach_root()</code>, passing in the allocations, the + Renderscript, and any optional user-defined data. The output allocation will contain the output + of the compute Renderscript.</li> +</ol> + +<p>In the following example, taken from the <a href= +"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample, processes +a bitmap and outputs a black and white version of it. The +<code>createScript()</code> method carries out the steps described previously. This method the compute +Renderscript, <code>mono.rs</code>, passing in memory allocations that store the bitmap to be processed +as well as the eventual output bitmap. It then displays the processed bitmap onto the screen:</p> +<pre> +package com.example.android.rs.hellocompute; + +import android.app.Activity; +import android.os.Bundle; +import android.graphics.BitmapFactory; +import android.graphics.Bitmap; +import android.renderscript.RenderScript; +import android.renderscript.Allocation; +import android.widget.ImageView; + +public class HelloCompute extends Activity { + private Bitmap mBitmapIn; + private Bitmap mBitmapOut; + + private RenderScript mRS; + private Allocation mInAllocation; + private Allocation mOutAllocation; + private ScriptC_mono mScript; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + mBitmapIn = loadBitmap(R.drawable.data); + mBitmapOut = Bitmap.createBitmap(mBitmapIn.getWidth(), mBitmapIn.getHeight(), + mBitmapIn.getConfig()); + + ImageView in = (ImageView) findViewById(R.id.displayin); + in.setImageBitmap(mBitmapIn); + + ImageView out = (ImageView) findViewById(R.id.displayout); + out.setImageBitmap(mBitmapOut); + + createScript(); + } + private void createScript() { + mRS = RenderScript.create(this); + mInAllocation = Allocation.createFromBitmap(mRS, mBitmapIn, + Allocation.MipmapControl.MIPMAP_NONE, + Allocation.USAGE_SCRIPT); + mOutAllocation = Allocation.createTyped(mRS, mInAllocation.getType()); + mScript = new ScriptC_mono(mRS, getResources(), R.raw.mono); + mScript.forEach_root(mInAllocation, mOutAllocation); + mOutAllocation.copyTo(mBitmapOut); + } + + private Bitmap loadBitmap(int resource) { + final BitmapFactory.Options options = new BitmapFactory.Options(); + options.inPreferredConfig = Bitmap.Config.ARGB_8888; + return BitmapFactory.decodeResource(getResources(), resource, options); + } +} +</pre> + +<p>To call a compute Renderscript from another Renderscript file:</p> +<ol> + <li>Allocate memory that is needed by the compute Renderscript in your Android framework code. + You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level + 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only + one or both {@link android.renderscript.Allocation}s.</li> + + <li>Call <code>rsForEach()</code>, passing in the allocations and any optional user-defined data. + The output allocation will contain the output of the compute Renderscript.</li> +</ol> +<p>The following example, taken from the <a href= +"{@docRoot}resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/balls.html">Renderscript +Balls sample</a>, demonstrates how to do make a script to script call:</p> +<pre> +rs_script script; +rs_allocation in_allocation; +rs_allocation out_allocation; +UserData_t data; +... +rsForEach(script, in_allocation, out_allocation, &data, sizeof(data)); +</pre> - <p>RenderScript exposes a set of compute APIs that you can use to do intensive computational operations. - You can use the compute APIs in the context of a graphics RenderScript such as calculating the - transformation of many geometric objects in a scene. You can also create a standalone compute RenderScript that does not - draw anything to the screen such as bitmap image processing for a photo editor application. - The RenderScript compute APIs are mainly defined in the <code>rs_cl.rsh</code> header</p> - - <p>Compute RenderScripts are simpler to setup and implement as there is no graphics rendering involved. - You can offload computational aspects of your application to RenderScript by creating a native RenderScript - file (.rs) and using the generated reflected layer class to call functions in the <code>.rs</code> file. - - <p>See the <a href="{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> - sample in the Android SDK for more - information on how to create a simple compute RenderScript.</p> - <p> - See the <a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a> - sample in the Android SDK for more - information on how to create a compute RenderScript that is used in a graphics RenderScript. - The compute RenderScript is contained in - <a href="{@docRoot}resources/samples/RenderScript/Balls/src/com/example/android/rs/balls/ball_physics.html">balls_physics.rs</a>. - </p>
\ No newline at end of file +<p>In this example, assume that the script and memory allocations have already been +allocated and bound at the Android framework level and that <code>UserData_t</code> is a struct +declared previously. Passing a pointer to a struct and the size of the struct to <code>rsForEach</code> +is optional, but useful if your compute Renderscript requires additional information other than +the necessary memory allocations.</p> diff --git a/docs/html/guide/topics/renderscript/graphics.jd b/docs/html/guide/topics/renderscript/graphics.jd index 2fefecc..462a990 100644 --- a/docs/html/guide/topics/renderscript/graphics.jd +++ b/docs/html/guide/topics/renderscript/graphics.jd @@ -1,6 +1,7 @@ -page.title=3D Graphics -parent.title=RenderScript +page.title=Graphics +parent.title=Renderscript parent.link=index.html + @jd:body <div id="qv-wrapper"> @@ -11,16 +12,16 @@ parent.link=index.html <li> <a href="#creating-graphics-rs">Creating a Graphics Renderscript</a> <ol> - <li><a href="#creating-native">Creating the native Renderscript file</a></li> + <li><a href="#creating-native">Creating the Renderscript file</a></li> <li><a href="#creating-entry">Creating the Renderscript entry point class</a></li> - <li><a href="#creating-view">Creating the surface view</a></li> - <li><a href="#creating-activity">Creating the activity</a></li> + <li><a href="#creating-view">Creating the view class</a></li> + <li><a href="#creating-activity">Creating the activity class</a></li> </ol> </li> <li> <a href="#drawing">Drawing</a> <ol> - <li><a href="#drawing-rsg">Drawing using the rsgDraw functions</a></li> + <li><a href="#drawing-rsg">Simple drawing</a></li> <li><a href="#drawing-mesh">Drawing with a mesh</a></li> </ol> </li> @@ -31,6 +32,9 @@ parent.link=index.html <li><a href="#shader-sampler">Defining a sampler</a></li> </ol> </li> + <li> + <a href="#fbo">Rendering to a Framebuffer Object</a> + </li> </ol> <h2>Related Samples</h2> @@ -40,8 +44,9 @@ parent.link=index.html <li><a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a></li> - <li><a href="{@docRoot}resources/samples/RenderScript/HelloWorld/index.html">Hello - World</a></li> + <li><a href="{@docRoot}resources/samples/RenderScript/FountainFbo/index.html">FountainFbo</a></li> + + <li><a href="{@docRoot}resources/samples/RenderScript/HelloWorld/index.html">Hello World</a></li> <li><a href="{@docRoot}resources/samples/RenderScript/MiscSamples/index.html">Misc Samples</a></li> @@ -49,310 +54,476 @@ href="{@docRoot}resources/samples/RenderScript/MiscSamples/index.html">Misc Samp </div> </div> - <p>RenderScript provides a number of graphics APIs for 3D rendering, both at the Android - framework level as well as at the native level. For instance, the Android framework APIs let you + <p>Renderscript provides a number of graphics APIs for rendering, both at the Android + framework level as well as at the Renderscript runtime level. For instance, the Android framework APIs let you create meshes and define shaders to customize the graphical rendering pipeline. The native - RenderScript graphics APIs lets you draw the actual meshes to render your scene. In general, you - will need to be familiar with APIs to appropriately render 3D graphics on an Android-powered - device.</p> + Renderscript graphics APIs let you draw the actual meshes to render your scene. You need to + be familiar with both APIs to appropriately render graphics on an Android-powered device.</p> - <h2 id="creating-graphics-rs">Creating a Graphics RenderScript</h2> + <h2 id="creating-graphics-rs">Creating a Graphics Renderscript</h2> - <p>Because of the various layers of code when writing a RenderScript application, it is useful to - create the following files for a scene that you want to render:</p> + <p>Renderscript applications require various layers of code, so it is useful to create the following + files to help keep your application organized:</p> - <ul> - <li>The native RenderScript <code>.rs</code> file. This file contains the logic to do the - graphics rendering.</li> + <dl> + <dt>The Renderscript <code>.rs</code> file</dt> + + <dd>This file contains the logic to do the graphics rendering.</dd> - <li>The RenderScript entry point class that allows your view to interact with the code defined - in the <code>.rs</code> file. This class contains a RenderScript object(instance of + <dt>The Renderscript entry point <code>.java</code> class</dt> + + <dd>This class allows the view class to interact with the code defined in the <code>.rs</code> + file. This class contains a Renderscript object (instance of <code>ScriptC_<em>renderscript_file</em></code>), which allows your Android framework code to - call the native RenderScript code. This class also creates the {@link - android.renderscript.RenderScriptGL} context object, which contains the current rendering state - of the RenderScript such as programs (vertex and fragment shaders, for example) that you want - to define and bind to the graphics pipeline. The context object attaches to the RenderScript - object (instance of <code><em>ScriptC_renderscript_file</em></code>) that does the rendering. - Our example names this class <code>HelloWorldRS</code>.</li> - - <li>Create a class that extends {@link android.renderscript.RSSurfaceView} to provide a surface - to render on. If you want to implement callbacks from events inherited from {@link + call the Renderscript code. In general, this class does much of the setup for Renderscript + such as shader and mesh building and memory allocation and binding. The SDK samples follow the + convention of naming this file ActivityRS.java, + where Activity is the name of your main activity class.</dd> + + <dt>The view <code>.java</code> class</dt> + + <dd>This class extends {@link android.renderscript.RSSurfaceView} or {@link + android.renderscript.RSTextureView} to provide a surface to render on. A {@link + android.renderscript.RSSurfaceView} consumes a whole window, but a {@link + android.renderscript.RSTextureView} allows you to draw Renderscript graphics inside of a + view and add it to a {@link android.view.ViewGroup} alongside + other views. In this class, you create a {@link android.renderscript.RenderScriptGL} context object + with a call to {@link android.renderscript.RSSurfaceView#createRenderScriptGL + RSSurfaceView.createRenderscriptGL()} or {@link android.renderscript.RSTextureView#createRenderScriptGL + RSTextureView.createRenderscriptGL()}. The {@link android.renderscript.RenderScriptGL} context object + contains information about the current rendering state of Renderscript such as the vertex and + fragment shaders. You pass this context object to the Renderscript entry point class, so that + class can modify the rendering context if needed and bind the Renderscript code to the context. Once bound, + the view class can use the Renderscript code to display graphics. + The view class should also implement callbacks for events inherited from {@link android.view.View}, such as {@link android.view.View#onTouchEvent onTouchEvent()} and {@link - android.view.View#onKeyDown onKeyDown()}, do so in this class as well.</li> + android.view.View#onKeyDown onKeyDown()} if you want to detect these types of user interactions. + The SDK samples follow the convention of naming this file ActivityView.java, + where Activity is the name of your main activity class</dd> - <li>Create a class that is the main Activity class, like you would with any Android - application. This class sets your {@link android.renderscript.RSSurfaceView} as the content - view for this Activity.</li> - </ul> + <dt>The activity <code>.java</code> class</dt> + + <dd>This class is the main activity class and sets your {@link android.renderscript.RSSurfaceView} as the main content + view for this activity or uses the {@link android.renderscript.RSTextureView} alongside other views.</dd> + </dl> + <p>Figure 1 describes how these classes interact with one another in a graphics Renderscript:</p> + + <img src="{@docRoot}images/rs_graphics.png"> + <p class="img-caption"><strong>Figure 1.</strong> Graphics Renderscript overview</p> - <p>The following sections describe how to implement these three classes by using the HelloWorld - RenderScript sample that is provided in the SDK as a guide (some code has been modified from its - original form for simplicity).</p> - <h3 id="creating-native">Creating the native RenderScript file</h3> + <p>The following sections describe how to create an application that uses a graphics Renderscript by using + the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Renderscript Fountain + sample</a> that is provided in the SDK as a guide (some code has been modified from its original + form for simplicity).</p> - <p>Your native RenderScript code resides in a <code>.rs</code> file in the - <code><project_root>/src/</code> directory. You can also define <code>.rsh</code> header - files. This code contains the logic to render your graphics and declares all necessary variables + <h3 id="creating-native">Creating the Renderscript file</h3> + + <p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> (headers) files in the + <code><project_root>/src/</code> directory. This code contains the logic to render your + graphics and declares all other necessary items such as variables, structs, and pointers. Every graphics <code>.rs</code> file generally contains the following items:</p> <ul> - <li>A pragma (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) that declares - the package name of the <code>.java</code> reflection of this RenderScript.</li> + <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) that declares + the package name of the <code>.java</code> reflection of this Renderscript.</li> - <li>A pragma (<code>#pragma version(1)</code>) that declares the version of RenderScript that + <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of Renderscript that you are using (1 is the only value for now).</li> - <li>A <code>#include</code> of the rs_graphics.rsh header file.</li> + <li>A <code>#include "rs_graphics.rsh"</code> declaration.</li> - <li>A <code>root()</code> function. This is the main worker function for your RenderScript and - calls RenderScript graphics APIs to draw meshes to the surface. This function is called every - time a frame refresh occurs, which is specified as its return value. A <code>0</code> specified - for the return value says to only render the frame when a property of the scene that you are + <li>A <code>root()</code> function. This is the main worker function for your Renderscript and + calls Renderscript graphics functions to render scenes. This function is called every time a + frame refresh occurs, which is specified as its return value. A <code>0</code> (zero) specified for + the return value says to only render the frame when a property of the scene that you are rendering changes. A non-zero positive integer specifies the refresh rate of the frame in milliseconds. - <p class="note"><strong>Note:</strong> The RenderScript runtime makes its best effort to + <p class="note"><strong>Note:</strong> The Renderscript runtime makes its best effort to refresh the frame at the specified rate. For example, if you are creating a live wallpaper - and set the return value to 50, the runtime renders the wallpaper at 20fps if it has just - enough or more resources to do so, and renders as fast as it can if it does not.</p> - - <p>For more - information on using the RenderScript graphics functions, see the <a href= + and set the return value to 20, the Renderscript runtime renders the wallpaper at 50fps if it has just + enough or more resources to do so. It renders as fast as it can if not enough resources + are available.</p> + + <p>For more information on using the Renderscript graphics functions, see the <a href= "#drawing">Drawing</a> section.</p> </li> - <li>An <code>init()</code> function. This allows you to do any initialization of your - RenderScript before the <code>root()</code> function runs, such as initializing variables. This - function runs once and is called automatically when the RenderScript starts, before anything - else in your RenderScript. Creating this function is optional.</li> + <li>An <code>init()</code> function. This allows you to do initialization of your + Renderscript before the <code>root()</code> function runs, such as assigning values to variables. This + function runs once and is called automatically when the Renderscript starts, before anything + else in your Renderscript. Creating this function is optional.</li> - <li>Any variables, pointers, and structures that you wish to use in your RenderScript code (can + <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can be declared in <code>.rsh</code> files if desired)</li> </ul> - <p>The following code shows how the <code>helloworld.rs</code> file is implemented:</p> + <p>The following code shows how the <code>fountain.rs</code> file is implemented:</p> <pre> #pragma version(1) // Tell which java package name the reflected files should belong to -#pragma rs java_package_name(com.android.rs.helloworld) +#pragma rs java_package_name(com.example.android.rs.fountain) -// Built-in header with graphics APIs +//declare shader binding +#pragma stateFragment(parent) + +// header with graphics APIs, must include explicitly #include "rs_graphics.rsh" -// gTouchX and gTouchY are variables that are reflected for use -// by the Android framework API. This RenderScript uses them to be notified of touch events. -int gTouchX; -int gTouchY; +static int newPart = 0; + +// the mesh to render +rs_mesh partMesh; + +// the point representing where a particle is rendered +typedef struct __attribute__((packed, aligned(4))) Point { + float2 delta; + float2 position; + uchar4 color; +} Point_t; +Point_t *point; + +// main worker function that renders particles onto the screen +int root() { + float dt = min(rsGetDt(), 0.1f); + rsgClearColor(0.f, 0.f, 0.f, 1.f); + const float height = rsgGetHeight(); + const int size = rsAllocationGetDimX(rsGetAllocation(point)); + float dy2 = dt * (10.f); + Point_t * p = point; + for (int ct=0; ct < size; ct++) { + p->delta.y += dy2; + p->position += p->delta; + if ((p->position.y > height) && (p->delta.y > 0)) { + p->delta.y *= -0.3f; + } + p++; + } + + rsgDrawMesh(partMesh); + return 1; +} -// This is invoked automatically when the script is created and initializes the variables -// in the Android framework layer as well. -void init() { - gTouchX = 50.0f; - gTouchY = 50.0f; +// adds particles to the screen to render +static float4 partColor[10]; +void addParticles(int rate, float x, float y, int index, bool newColor) +{ + if (newColor) { + partColor[index].x = rsRand(0.5f, 1.0f); + partColor[index].y = rsRand(1.0f); + partColor[index].z = rsRand(1.0f); + } + float rMax = ((float)rate) * 0.02f; + int size = rsAllocationGetDimX(rsGetAllocation(point)); + uchar4 c = rsPackColorTo8888(partColor[index]); + + Point_t * np = &point[newPart]; + float2 p = {x, y}; + while (rate--) { + float angle = rsRand(3.14f * 2.f); + float len = rsRand(rMax); + np->delta.x = len * sin(angle); + np->delta.y = len * cos(angle); + np->position = p; + np->color = c; + newPart++; + np++; + if (newPart >= size) { + newPart = 0; + np = &point[newPart]; + } + } } +</pre> -int root(int launchID) { + <h3 id="creating-entry">Creating the Renderscript entry point class</h3> - // Clear the background color - rsgClearColor(0.0f, 0.0f, 0.0f, 0.0f); - // Tell the runtime what the font color should be - rsgFontColor(1.0f, 1.0f, 1.0f, 1.0f); - // Introuduce ourselves to the world by drawing a greeting - // at the position user touched on the screen - rsgDrawText("Hello World!", gTouchX, gTouchY); + <p>When you create a Renderscript (<code>.rs</code>) file, it is helpful to create a + corresponding Android framework class that is an entry point into the <code>.rs</code> file. + The most important thing this class does is receive a {@link android.renderscript.RenderScriptGL} rendering context + object from the <a href="#creating-view">view class</a> and binds the actual Renderscript + code to the rendering context. This notifies your view class of the code that it needs + to render graphics. + </p> - // Return value tells RS roughly how often to redraw - // in this case 20 ms - return 20; -} -</pre> + <p>In addition, this class should contain all of the things needed to set up Renderscript. + Some important things that you need to do in this class are:</p> - <h3 id="creating-entry">Creating the RenderScript entry point class</h3> - - <p>When you create a RenderScript (<code>.rs</code>) file, it is helpful to create a - corresponding Android framework class that is an entry point into the <code>.rs</code> file. In - this entry point class, you create a RenderScript object by instantiating a - <code>ScriptC_<em>rs_filename</em></code> and binding it to the RenderScript context. The - RenderScript object is attached to the RenderScript bytecode, which is platform-independent and - gets compiled on the device when the RenderScript application runs. Both the - <code>ScriptC_<em>rs_filename</em></code> class and bytecode is generated by the Android build - tools and is packaged with the <code>.apk</code> file. The bytecode file is located in the - <code><project_root>/res/raw/</code> directory and is named <code>rs_filename.bc</code>. - You refer to the bytecode as a resource (<code>R.raw.<em>rs_filename</em></code>). when creating - the RenderScript object..</p> - - <p>You then bind the RenderScript object to the RenderScript context, so that the surface view - knows what code to use to render graphics. The following code shows how the - <code>HelloWorldRS</code> class is implemented:</p> + <ul> + <li>Create a Renderscript object + <code>ScriptC_<em>rs_filename</em></code>. The Renderscript object is attached to the Renderscript bytecode, which is platform-independent and + gets compiled on the device when the Renderscript application runs. The bytecode is referenced + as a raw resource and is passed into the constructor for the Renderscript object. + For example, this is how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> + sample creates the Renderscript object: + <pre> + RenderScriptGL rs; //obtained from the view class + Resources res; //obtained from the view class + ... + ScriptC_fountain mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); + </pre> + </li> + <li>Allocate any necessary memory and bind it to your Renderscript code via the Renderscript object.</li> + <li>Build any necessary meshes and bind them to the Renderscript code via the Renderscript object.</li> + <li>Create any necessary programs and bind them to the Renderscript code via the Renderscript object.</li> + </ul> + + <p>The following code shows how the <a href= + "{@docRoot}resources/samples/RenderScript/Fountain/src/com/example/android/rs/fountain/FountainRS.html"> + FountainRS</a> class is implemented:</p> <pre> -package com.android.rs.helloworld; +package com.example.android.rs.fountain; import android.content.res.Resources; import android.renderscript.*; +import android.util.Log; -public class HelloWorldRS { - //context and resources are obtained from RSSurfaceView, which calls init() - private Resources mRes; - private RenderScriptGL mRS; - - //Declare the RenderScript object - private ScriptC_helloworld mScript; +public class FountainRS { + public static final int PART_COUNT = 50000; - public HelloWorldRS() { + public FountainRS() { } /** - * This provides us with the RenderScript context and resources - * that allow us to create the RenderScript object + * This provides us with the Renderscript context and resources + * that allow us to create the Renderscript object */ + private Resources mRes; + private RenderScriptGL mRS; + + // Renderscript object + private ScriptC_fountain mScript; + + // Called by the view class to initialize the Renderscript context and renderer public void init(RenderScriptGL rs, Resources res) { mRS = rs; mRes = res; - initRS(); - } - /** - * Calls native RenderScript functions (set_gTouchX and set_gTouchY) - * through the reflected layer class ScriptC_helloworld to pass in - * touch point data. - */ - public void onActionDown(int x, int y) { - mScript.set_gTouchX(x); - mScript.set_gTouchY(y); + + /** + * Create a shader and bind to the Renderscript context + */ + ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); + pfb.setVaryingColor(true); + rs.bindProgramFragment(pfb.create()); + + /** + * Allocate memory for the particles to render and create the mesh to draw + */ + ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); + Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); + smb.addVertexAllocation(points.getAllocation()); + smb.addIndexSetType(Mesh.Primitive.POINT); + Mesh sm = smb.create(); + + /** + * Create and bind the Renderscript object to the Renderscript context + */ + mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); + mScript.set_partMesh(sm); + mScript.bind_point(points); + mRS.bindRootScript(mScript); } + + boolean holdingColor[] = new boolean[10]; + /** - * Binds the RenderScript object to the RenderScript context + * Calls Renderscript functions (invoke_addParticles) + * via the Renderscript object to add particles to render + * based on where a user touches the screen. */ - private void initRS() { - //create the RenderScript object - mScript = new ScriptC_helloworld(mRS, mRes, R.raw.helloworld); - //bind the RenderScript object to the RenderScript context - mRS.bindRootScript(mScript); + public void newTouchPosition(float x, float y, float pressure, int id) { + if (id >= holdingColor.length) { + return; + } + int rate = (int)(pressure * pressure * 500.f); + if (rate > 500) { + rate = 500; + } + if (rate > 0) { + mScript.invoke_addParticles(rate, x, y, id, !holdingColor[id]); + holdingColor[id] = true; + } else { + holdingColor[id] = false; + } + } } - </pre> - <h3 id="creating-view">Creating the surface view</h3> - <p>To create a surface view to render graphics on, create a class that extends {@link - android.renderscript.RSSurfaceView}. This class also creates a RenderScript context object - ({@link android.renderscript.RenderScriptGL} and passes it to the Rendscript entry point class to - bind the two. The following code shows how the <code>HelloWorldView</code> class is - implemented:</p> + <h3 id="creating-view">Creating the view class</h3> + + + <p>To display graphics, you need a view to render on. Create a class that extends {@link + android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. This class + allows you to create a {@link android.renderscript.RenderScriptGL} context object by calling and + pass it to the Rendscript entry point class to bind the two. Once bound, the content is aware + of the code that it needs to use to render graphics with. If your Renderscript code + depends on any type of information that the view is aware of, such as touches from the user, + you can also use this class to relay that information to the Renderscript entry point class. + The following code shows how the <code>FountainView</code> class is implemented:</p> <pre> -package com.android.rs.helloworld; +package com.example.android.rs.fountain; -import android.renderscript.RSSurfaceView; +import android.renderscript.RSTextureView; import android.renderscript.RenderScriptGL; import android.content.Context; import android.view.MotionEvent; -public class HelloWorldView extends RSSurfaceView { - // RenderScript context - private RenderScriptGL mRS; - // RenderScript entry point object that does the rendering - private HelloWorldRS mRender; +public class FountainView extends RSTextureView { - public HelloWorldView(Context context) { + public FountainView(Context context) { super(context); - initRS(); } + // Renderscript context + private RenderScriptGL mRS; + // Renderscript entry point object that calls Renderscript code + private FountainRS mRender; - private void initRS() { + /** + * Create Renderscript context and initialize Renderscript entry point + */ + @Override + protected void onAttachedToWindow() { + super.onAttachedToWindow(); + android.util.Log.e("rs", "onAttachedToWindow"); if (mRS == null) { - // Initialize RenderScript with default surface characteristics. RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig(); - //Create the RenderScript context mRS = createRenderScriptGL(sc); - // Create an instance of the RenderScript entry point class - mRender = new HelloWorldRS(); - // Call the entry point class to bind it to this context + mRender = new FountainRS(); mRender.init(mRS, getResources()); } } - /** - * Rebind everything when the window becomes attached - */ - protected void onAttachedToWindow() { - super.onAttachedToWindow(); - initRS(); - } - - /** - * Stop rendering when window becomes detached - */ + @Override protected void onDetachedFromWindow() { - // Handle the system event and clean up - mRender = null; + super.onDetachedFromWindow(); + android.util.Log.e("rs", "onDetachedFromWindow"); if (mRS != null) { mRS = null; destroyRenderScriptGL(); } } + /** - * Use callbacks to relay data to RenderScript entry point class + * Use callbacks to relay data to Renderscript entry point class */ - public boolean onTouchEvent(MotionEvent ev) { - // Pass touch events from the system to the rendering script - if (ev.getAction() == MotionEvent.ACTION_DOWN) { - mRender.onActionDown((int)ev.getX(), (int)ev.getY()); - return true; + @Override + public boolean onTouchEvent(MotionEvent ev) + { + int act = ev.getActionMasked(); + if (act == ev.ACTION_UP) { + mRender.newTouchPosition(0, 0, 0, ev.getPointerId(0)); + return false; + } else if (act == MotionEvent.ACTION_POINTER_UP) { + // only one pointer going up, we can get the index like this + int pointerIndex = ev.getActionIndex(); + int pointerId = ev.getPointerId(pointerIndex); + mRender.newTouchPosition(0, 0, 0, pointerId); } - - return false; + int count = ev.getHistorySize(); + int pcount = ev.getPointerCount(); + + for (int p=0; p < pcount; p++) { + int id = ev.getPointerId(p); + mRender.newTouchPosition(ev.getX(p), + ev.getY(p), + ev.getPressure(p), + id); + + for (int i=0; i < count; i++) { + mRender.newTouchPosition(ev.getHistoricalX(p, i), + ev.getHistoricalY(p, i), + ev.getHistoricalPressure(p, i), + id); + } + } + return true; } } - </pre> - <h3 id="creating-activity">Creating the Activity</h3> + <h3 id="creating-activity">Creating the activity class</h3> - <p>Applications that use RenderScript still adhere to activity lifecyle, and are part of the same - view hierarchy as traditional Android applications, which is handled by the Android VM. This - Activity class sets its view to be the {@link android.renderscript.RSSurfaceView} and handles - lifecycle callback events appropriately. The following code shows how the <code>HelloWorld</code> - class is implemented:</p> + <p>Applications that use Renderscript still behave like normal Android applications, so you + need an activity class that handles activity lifecycle callback events appropriately. The activity class + also sets your {@link android.renderscript.RSSurfaceView} view class to be the main content view of the + activity or uses your {@link android.renderscript.RSTextureView} + in a {@link android.view.ViewGroup} alongside other views.</p> + + <p>The following code shows how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> + sample declares its activity class:</p> <pre> -public class HelloWorldActivity extends Activity { +package com.example.android.rs.fountain; + +import android.app.Activity; +import android.os.Bundle; +import android.util.Log; + +public class Fountain extends Activity { + + private static final String LOG_TAG = "libRS_jni"; + private static final boolean DEBUG = false; + private static final boolean LOG_ENABLED = false; - //Custom view to use with RenderScript - private HelloWorldView view; + private FountainView mView; + @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); - // Create surface view and set it as the content of our Activity - mView = new HelloWorldView(this); - setContentView(view); + + // Create our Preview view and set it as + // the content of our activity + mView = new FountainView(this); + setContentView(mView); } + @Override protected void onResume() { - // Ideally an app should implement onResume() and onPause() - // to take appropriate action when the activity loses focus + Log.e("rs", "onResume"); + + // Ideally a game should implement onResume() and onPause() + // to take appropriate action when the activity looses focus super.onResume(); - view.resume(); + mView.resume(); } + @Override protected void onPause() { - // Ideally an app should implement onResume() and onPause() - // to take appropriate action when the activity loses focus + Log.e("rs", "onPause"); + + // Ideally a game should implement onResume() and onPause() + // to take appropriate action when the activity looses focus super.onPause(); - view.pause(); + mView.pause(); + + } + + static void log(String message) { + if (LOG_ENABLED) { + Log.v(LOG_TAG, message); + } } } </pre> +<p>Now that you have an idea of what is involved in a Renderscript graphics application, you can +start building your own. It might be easiest to begin with one of the +<a href="{@docRoot}resources/samples/RenderScript/index.html">Renderscript samples</a> as a starting +point if this is your first time using Renderscript.</p> + <h2 id="drawing">Drawing</h2> <p>The following sections describe how to use the graphics functions to draw with Renderscript.</p> - <h3 id="drawing-rsg">Drawing using the rsgDraw functions</h3> - <p>The native RenderScript APIs provide a few convenient functions to easily draw a polygon to - the screen. You call these in your <code>root()</code> function to have them render to the - surface view. These functions are available for simple drawing and should not be used for complex - graphics rendering:</p> + <h3 id="drawing-rsg">Simple drawing</h3> + + <p>The native Renderscript APIs provide a few convenient functions to easily draw a polygon or text to + the screen. You call these in your <code>root()</code> function to have them render to the {@link + android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. These functions are + available for simple drawing and should not be used for complex graphics rendering:</p> <ul> <li><code>rsgDrawRect()</code>: Sets up a mesh and draws a rectangle to the screen. It uses the @@ -360,31 +531,32 @@ public class HelloWorldActivity extends Activity { <li><code>rsgDrawQuad()</code>: Sets up a mesh and draws a quadrilateral to the screen.</li> - <li><code>rsgDrawQuadTexCoords()</code>: Sets up a mesh and draws a textured quadrilateral to - the screen.</li> + <li><code>rsgDrawQuadTexCoords()</code>: Sets up a mesh and draws a quadrilateral to the screen + using the provided coordinates of a texture.</li> + + <li><code>rsgDrawText()</code>: Draws specified text to the screen. Use <code>rsgFontColor()</code> + to set the color of the text.</li> </ul> <h3 id="drawing-mesh">Drawing with a mesh</h3> - <p>When you want to draw complex shapes and textures to the screen, instantiate a {@link - android.renderscript.Mesh} and draw it to the screen with <code>rsgDrawMesh()</code>. A {@link + <p>When you want to render complex scenes to the screen, instantiate a {@link + android.renderscript.Mesh} and draw it with <code>rsgDrawMesh()</code>. A {@link android.renderscript.Mesh} is a collection of allocations that represent vertex data (positions, - normals, texture coordinates) and index data such as triangles and lines. You can build a Mesh in - three different ways:</p> + normals, texture coordinates) and index data that provides information on how to draw triangles + and lines with the provided vertex data. You can build a Mesh in three different ways:</p> <ul> <li>Build the mesh with the {@link android.renderscript.Mesh.TriangleMeshBuilder} class, which - allows you to specify a set of vertices and indices for each triangle that you want to draw. - The downside of doing it this way is there is no way to specify the vertices in your native - RenderScript code.</li> + allows you to specify a set of vertices and indices for each triangle that you want to draw.</li> <li>Build the mesh using an {@link android.renderscript.Allocation} or a set of {@link android.renderscript.Allocation}s with the {@link android.renderscript.Mesh.AllocationBuilder} - class. This allows you to build a mesh with vertices already stored in memory, which allows you - to set the vertices in native or Android code.</li> + class. This approach allows you to build a mesh with vertices already stored in memory, which allows you + to specify the vertices in Renderscript or Android framework code.</li> - <li>Build the mesh with the {@link android.renderscript.Mesh.Builder} class. This is a - convenience method for when you know what data types you want to use to build your mesh, but + <li>Build the mesh with the {@link android.renderscript.Mesh.Builder} class. You should use + this convenience method when you know the data types you want to use to build your mesh, but don't want to make separate memory allocations like with {@link android.renderscript.Mesh.AllocationBuilder}. You can specify the types that you want and this mesh builder automatically creates the memory allocations for you.</li> @@ -398,7 +570,7 @@ public class HelloWorldActivity extends Activity { vertex 0, 1, and 2 (the vertices are drawn counter-clockwise).</p> <pre> int float2VtxSize = 2; -Mesh.TriangleMeshBuilder triangle = new Mesh.TriangleMeshBuilder(renderscriptGL, +Mesh.TriangleMeshBuilder triangles = new Mesh.TriangleMeshBuilder(renderscriptGL, float2VtxSize, Mesh.TriangleMeshBuilder.COLOR); triangles.addVertex(300.f, 300.f); triangles.addVertex(150.f, 450.f); @@ -421,7 +593,7 @@ Mesh smP = smb.create(); script.set_mesh(smP); </pre> - <p>In your native RenderScript code, draw the built mesh to the screen:</p> + <p>In your Renderscript code, draw the built mesh to the screen:</p> <pre> rs_mesh mesh; ... @@ -435,18 +607,18 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. } </pre> - <h2 id="shaders">Shaders</h2> + <h2 id="shader">Programs</h2> <p>You can attach four program objects to the {@link android.renderscript.RenderScriptGL} context to customize the rendering pipeline. For example, you can create vertex and fragment shaders in - GLSL or build a raster program object with provided methods without writing GLSL code. The four - program objects mirror a traditional graphical rendering pipeline:</p> + GLSL or build a raster program object that controls culling. The four programs mirror a + traditional graphical rendering pipeline:</p> <table> <tr> <th>Android Object Type</th> - <th>RenderScript Native Type</th> + <th>Renderscript Native Type</th> <th>Description</th> </tr> @@ -457,17 +629,17 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. <td>rs_program_vertex</td> <td> - <p>The RenderScript vertex program, also known as a vertex shader, describes the stage in + <p>The Renderscript vertex program, also known as a vertex shader, describes the stage in the graphics pipeline responsible for manipulating geometric data in a user-defined way. - The object is constructed by providing RenderScript with the following data:</p> + The object is constructed by providing Renderscript with the following data:</p> <ul> - <li>An Element describing its varying inputs or attributes</li> + <li>An {@link android.renderscript.Element} describing its varying inputs or attributes</li> <li>GLSL shader string that defines the body of the program</li> - <li>a Type that describes the layout of an Allocation containing constant or uniform - inputs</li> + <li>a {@link android.renderscript.Type} that describes the layout of an + Allocation containing constant or uniform inputs</li> </ul> <p>Once the program is created, bind it to the {@link android.renderscript.RenderScriptGL} @@ -475,22 +647,29 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. bindProgramVertex()}. It is then used for all subsequent draw calls until you bind a new program. If the program has constant inputs, the user needs to bind an allocation containing those inputs. The allocation's type must match the one provided during creation. - The RenderScript library then does all the necessary plumbing to send those constants to + </p> + + <p>The Renderscript runtime then does all the necessary plumbing to send those constants to the graphics hardware. Varying inputs to the shader, such as position, normal, and texture - coordinates are matched by name between the input Element and the Mesh object being drawn. - The signatures don't have to be exact or in any strict order. As long as the input name in - the shader matches a channel name and size available on the mesh, the run-time would take - care of connecting the two. Unlike OpenGL, there is no need to link the vertex and fragment - programs.</p> - - <p>To bind shader constructs to the Program, declare a struct containing the necessary - shader constants in your native RenderScript code. This struct is generated into a - reflected class that you can use as a constant input element during the Program's creation. - It is an easy way to create an instance of this struct as an allocation. You would then - bind this Allocation to the Program and the RenderScript system sends the data that is - contained in the struct to the hardware when necessary. To update shader constants, you - change the values in the Allocation and notify the native RenderScript code of the - change.</p> + coordinates are matched by name between the input {@link android.renderscript.Element} + and the mesh object that is being drawn. The signatures don't have to be exact or in any + strict order. As long as the input name in the shader matches a channel name and size + available on the mesh, the Renderscript runtime handles connecting the two. Unlike OpenGL + there is no need to link the vertex and fragment programs.</p> + + <p>To bind shader constants to the program, declare a <code>struct</code> that contains the necessary + shader constants in your Renderscript code. This <code>struct</code> is generated into a + reflected class that you can use as a constant input element during the program's creation. + It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then + bind this {@link android.renderscript.Allocation} to the program and the + Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware + when necessary. To update shader constants, you change the values in the + {@link android.renderscript.Allocation} and notify the Renderscript + code of the change.</p> + + <p>The {@link android.renderscript.ProgramVertexFixedFunction.Builder} class also + lets you build a simple vertex shader without writing GLSL code. + </p> </td> </tr> @@ -500,26 +679,33 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. <td>rs_program_fragment</td> <td> - <p>The RenderScript fragment program, also known as the fragment shader, is responsible for + <p>The Renderscript fragment program, also known as a fragment shader, is responsible for manipulating pixel data in a user-defined way. It's constructed from a GLSL shader string - containing the program body, textures inputs, and a Type object describing the constants - used by the program. Like the vertex programs, when an allocation with constant input + containing the program body, texture inputs, and a {@link android.renderscript.Type} + object that describes the constants + used by the program. Like the vertex programs, when an {@link android.renderscript.Allocation} + with constant input values is bound to the shader, its values are sent to the graphics program automatically. - Note that the values inside the allocation are not explicitly tracked. If they change - between two draw calls using the same program object, notify the runtime of that change by - calling rsgAllocationSyncAll so it could send the new values to hardware. Communication + Note that the values inside the {@link android.renderscript.Allocation} are not explicitly tracked. + If they change between two draw calls using the same program object, notify the runtime of that change by + calling <code>rsgAllocationSyncAll()</code>, so it can send the new values to hardware. Communication between the vertex and fragment programs is handled internally in the GLSL code. For - example, if the fragment program is expecting a varying input called varTex0, the GLSL code + example, if the fragment program is expecting a varying input called <code>varTex0</code>, the GLSL code inside the program vertex must provide it.</p> - <p>To bind shader constants to this program, declare a struct containing the necessary - shader constants in your native RenderScript code. This struct is generated into a - reflected class that you can use as a constant input element during the Program's creation. - It is an easy way to create an instance of this struct as an allocation. You would then - bind this Allocation to the Program and the RenderScript system sends the data that is - contained in the struct to the hardware when necessary. To update shader constants, you - change the values in the Allocation and notify the native RenderScript code of the - change.</p> + <p>To bind shader constructs to the program, declare a <code>struct</code> that contains the necessary + shader constants in your Renderscript code. This <code>struct</code> is generated into a + reflected class that you can use as a constant input element during the program's creation. + It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then + bind this {@link android.renderscript.Allocation} to the program and the + Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware + when necessary. To update shader constants, you change the values in the + {@link android.renderscript.Allocation} and notify the Renderscript + code of the change.</p> + + <p>The {@link android.renderscript.ProgramFragmentFixedFunction.Builder} class also + lets you build a simple fragment shader without writing GLSL code. + </p> </td> </tr> @@ -528,7 +714,7 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. <td>rs_program_store</td> - <td>The RenderScript ProgramStore contains a set of parameters that control how the graphics + <td>The Renderscript store program contains a set of parameters that control how the graphics hardware writes to the framebuffer. It could be used to enable and disable depth writes and testing, setup various blending modes for effects like transparency and define write masks for color components.</td> @@ -539,12 +725,12 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. <td>rs_program_raster</td> - <td>Program raster is primarily used to specify whether point sprites are enabled and to + <td>The Renderscript raster program is primarily used to specify whether point sprites are enabled and to control the culling mode. By default back faces are culled.</td> </tr> </table> - <p>The following example defines a vertex shader in GLSL and binds it to the RenderScript:</p> + <p>The following example defines a vertex shader in GLSL and binds it to a Renderscript context object:</p> <pre> private RenderScriptGL glRenderer; //rendering context private ScriptField_Point mPoints; //vertices @@ -567,49 +753,37 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. ProgramVertex pvs = sb.create(); pvs.bindConstants(mVpConsts.getAllocation(), 0); glRenderer.bindProgramVertex(pvs); - - </pre> + <p>The <a href= "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> RsRenderStatesRS</a> sample has many examples on how to create a shader without writing GLSL.</p> - <h3 id="shader-bindings">Shader bindings</h3> + <h3 id="shader-bindings">Program bindings</h3> - <p>You can also set four pragmas that control the shaders' default bindings to the {@link + <p>You can also declare four pragmas that control default program bindings to the {@link android.renderscript.RenderScriptGL} context when the script is executing:</p> <ul> - <li>stateVertex</li> + <li><code>stateVertex</code></li> - <li>stateFragment</li> + <li><code>stateFragment</code></li> - <li>stateRaster</li> + <li><code>stateRaster</code></li> - <li>stateStore</li> + <li><code>stateStore</code></li> </ul> <p>The possible values for each pragma are <code>parent</code> or <code>default</code>. Using - <code>default</code> binds the shaders to the graphical context with the system defaults. The - default shader is defined below:</p> - <pre> -("varying vec4 varColor;\n"); -("varying vec2 varTex0;\n"); -("void main() {\n"); -(" gl_Position = UNI_MVP * ATTRIB_position;\n"); -(" gl_PointSize = 1.0;\n"); -(" varColor = ATTRIB_color;\n"); -(" varTex0 = ATTRIB_texture0;\n"); -("}\n"); -</pre> + <code>default</code> binds the shaders to the graphical context with the system defaults.</p> <p>Using <code>parent</code> binds the shaders in the same manner as it is bound in the calling script. If this is the root script, the parent state is taken from the bind points that are set by the {@link android.renderscript.RenderScriptGL} bind methods.</p> - <p>For example, you can define this at the top of your native graphics RenderScript code to have - the Vertex and Store shaders inherent the bind properties from their parent scripts:</p> + <p>For example, you can define this at the top of your graphics Renderscript code to have + the vertex and store programs inherent the bind properties from their parent scripts:</p> <pre> #pragma stateVertex(parent) #pragma stateStore(parent) @@ -618,18 +792,202 @@ return 0; //specify a non zero, positive integer to specify the frame refresh. <h3 id="shader-sampler">Defining a sampler</h3> <p>A {@link android.renderscript.Sampler} object defines how data is extracted from textures. - Samplers are bound to Program objects (currently only a Fragment Program) alongside the texture - whose sampling they control. These objects are used to specify such things as edge clamping - behavior, whether mip-maps are used, and the amount of anisotropy required. There might be - situations where hardware does not support the desired behavior of the sampler. In these cases, - the runtime attempts to provide the closest possible approximation. For example, the user - requested 16x anisotropy, but only 8x was set because it's the best available on the - hardware.</p> + Samplers are bound to a {@link android.renderscript.ProgramFragment} alongside the texture + whose sampling they control. These + objects are used to specify such things as edge clamping behavior, whether mip-maps are used, and + the amount of anisotropy required. There might be situations where hardware does not support the + desired behavior of the sampler. In these cases, the Renderscript runtime attempts to provide the + closest possible approximation. For example, the user requested 16x anisotropy, but only 8x was + set because it's the best available on the hardware.</p> <p>The <a href= "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> RsRenderStatesRS</a> sample has many examples on how to create a sampler and bind it to a Fragment program.</p> - -</body> -</html> + + + +<h2 id="fbo">Rendering to a Framebuffer Object</h2> + +<p>Framebuffer objects allow you to render offscreen instead of in the default onscreen +framebuffer. This approach might be useful for situations where you need to post-process a texture before +rendering it to the screen, or when you want to composite two scenes in one such as rendering a rear-view +mirror of a car. There are two buffers associated with a framebuffer object: a color buffer +and a depth buffer. The color buffer (required) contains the actual pixel data of the scene +that you are rendering, and the depth buffer (optional) contains the values necessary to figure +out what vertices are drawn depending on their z-values.</p> + +<p>In general, you need to do the following to render to a framebuffer object:</p> + +<ul> + <li>Create {@link android.renderscript.Allocation} objects for the color buffer and + depth buffer (if needed). Specify the {@link + android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} usage attribute for these + allocations to notify the Renderscript runtime to use these allocations for the framebuffer + object. For the color buffer allocation, you most likely need to declare the {@link + android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE} usage attribute + to use the color buffer as a texture, which is the most common use of the framebuffer object.</li> + + <li>Tell the Renderscript runtime to render to the framebuffer object instead of the default + framebuffer by calling <code>rsgBindColorTarget()</code> and passing it the color buffer + allocation. If applicable, call <code>rsgBindDepthTarget()</code> passing in the depth buffer + allocation as well.</li> + + <li>Render your scene normally with the <code>rsgDraw</code> functions. The scene will be + rendered into the color buffer instead of the default onscreen framebuffer.</li> + + <li>When done, tell the Renderscript runtime stop rendering to the color buffer and back + to the default framebuffer by calling <code>rsgClearAllRenderTargets()</code>.</li> + + <li>Create a fragment shader and bind a the color buffer to it as a texture.</li> + + <li>Render your scene to the default framebuffer. The texture will be used according + to the way you setup your fragment shader.</li> +</ul> + +<p>The following example shows you how to render to a framebuffer object by modifying the +<a href="{@docRoot}guide/resources/renderscript/Fountain/">Fountain</a> Renderscript sample. The end +result is the <a href="{@docRoot}guide/resources/renderscript/FountainFBO/">FountainFBO</a> sample. +The modifications render the exact same scene into a framebuffer object as it does the default +framebuffer. The framebuffer object is then rendered into the default framebuffer in a small +area at the top left corner of the screen.</p> + +<ol> + <li>Modify <code>fountain.rs</code> and add the following global variables. This creates setter + methods when this file is reflected into a <code>.java</code> file, allowing you to allocate + memory in your Android framework code and binding it to the Renderscript runtime. +<pre> +//allocation for color buffer +rs_allocation gColorBuffer; +//fragment shader for rendering without a texture (used for rendering to framebuffer object) +rs_program_fragment gProgramFragment; +//fragment shader for rendering with a texture (used for rendering to default framebuffer) +rs_program_fragment gTextureProgramFragment; +</pre> + </li> + + <li>Modify the root function of <code>fountain.rs</code> to look like the following code. The + modifications are commented: +<pre> +int root() { + float dt = min(rsGetDt(), 0.1f); + rsgClearColor(0.f, 0.f, 0.f, 1.f); + const float height = rsgGetHeight(); + const int size = rsAllocationGetDimX(rsGetAllocation(point)); + float dy2 = dt * (10.f); + Point_t * p = point; + for (int ct=0; ct < size; ct++) { + p->delta.y += dy2; + p->position += p->delta; + if ((p->position.y > height) && (p->delta.y > 0)) { + p->delta.y *= -0.3f; + } + p++; + } + //Tell Renderscript runtime to render to the frame buffer object + rsgBindColorTarget(gColorBuffer, 0); + //Begin rendering on a white background + rsgClearColor(1.f, 1.f, 1.f, 1.f); + rsgDrawMesh(partMesh); + + //When done, tell Renderscript runtime to stop rendering to framebuffer object + rsgClearAllRenderTargets(); + + //Bind a new fragment shader that declares the framebuffer object to be used as a texture + rsgBindProgramFragment(gTextureProgramFragment); + + //Bind the framebuffer object to the fragment shader at slot 0 as a texture + rsgBindTexture(gTextureProgramFragment, 0, gColorBuffer); + //Draw a quad using the framebuffer object as the texture + float startX = 10, startY = 10; + float s = 256; + rsgDrawQuadTexCoords(startX, startY, 0, 0, 1, + startX, startY + s, 0, 0, 0, + startX + s, startY + s, 0, 1, 0, + startX + s, startY, 0, 1, 1); + + //Rebind the original fragment shader to render as normal + rsgBindProgramFragment(gProgramFragment); + + //Render the main scene + rsgDrawMesh(partMesh); + + return 1; +} +</pre> + </li> + + <li>In the <code>FountainRS.java</code> file, modify the <code>init()</code> method to look + like the following code. The modifications are commented: + +<pre> +/* Add necessary members */ +private ScriptC_fountainfbo mScript; +private Allocation mColorBuffer; +private ProgramFragment mProgramFragment; +private ProgramFragment mTextureProgramFragment; + +public void init(RenderScriptGL rs, Resources res) { + mRS = rs; + mRes = res; + + ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); + + Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); + smb.addVertexAllocation(points.getAllocation()); + smb.addIndexSetType(Mesh.Primitive.POINT); + Mesh sm = smb.create(); + + mScript = new ScriptC_fountainfbo(mRS, mRes, R.raw.fountainfbo); + mScript.set_partMesh(sm); + mScript.bind_point(points); + + ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); + pfb.setVaryingColor(true); + mProgramFragment = pfb.create(); + mScript.set_gProgramFragment(mProgramFragment); + + /* Second fragment shader to use a texture (framebuffer object) to draw with */ + pfb.setTexture(ProgramFragmentFixedFunction.Builder.EnvMode.REPLACE, + ProgramFragmentFixedFunction.Builder.Format.RGBA, 0); + + /* Set the fragment shader in the Renderscript runtime */ + mTextureProgramFragment = pfb.create(); + mScript.set_gTextureProgramFragment(mTextureProgramFragment); + + /* Create the allocation for the color buffer */ + Type.Builder colorBuilder = new Type.Builder(mRS, Element.RGBA_8888(mRS)); + colorBuilder.setX(256).setY(256); + mColorBuffer = Allocation.createTyped(mRS, colorBuilder.create(), + Allocation.USAGE_GRAPHICS_TEXTURE | + Allocation.USAGE_GRAPHICS_RENDER_TARGET); + + /* Set the allocation in the Renderscript runtime */ + mScript.set_gColorBuffer(mColorBuffer); + + mRS.bindRootScript(mScript); +} +</pre> + +<p class="note"><strong>Note:</strong> This sample doesn't use a depth buffer, but the following code +shows you how to declare an example depth buffer if you need to use +one for your application. The depth buffer must have the same dimensions as the color buffer: + +<pre> +Allocation mDepthBuffer; + +... + +Type.Builder b = new Type.Builder(mRS, Element.createPixel(mRS, DataType.UNSIGNED_16, + DataKind.PIXEL_DEPTH)); +b.setX(256).setY(256); +mDepthBuffer = Allocation.createTyped(mRS, b.create(), +Allocation.USAGE_GRAPHICS_RENDER_TARGET); + +</pre> +</p> +</li> + + <li>Run and use the sample. The smaller, white quad on the top-left corner is using the + framebuffer object as a texture, which renders the same scene as the main rendering.</li> +</ol> diff --git a/docs/html/guide/topics/renderscript/index.jd b/docs/html/guide/topics/renderscript/index.jd index 148705c..b2d9f84 100644 --- a/docs/html/guide/topics/renderscript/index.jd +++ b/docs/html/guide/topics/renderscript/index.jd @@ -1,4 +1,4 @@ -page.title=RenderScript +page.title=Renderscript @jd:body <div id="qv-wrapper"> @@ -6,14 +6,14 @@ page.title=RenderScript <h2>In this document</h2> <ol> - <li><a href="#overview">RenderScript System Overview</a></li> - <li> + <li><a href="#overview">Renderscript Overview</a></li> + <li><a href="#native">Renderscript Runtime Layer</a></li> + <li><a href="#reflected">Reflected Layer</a> <ol> - <li><a href="#native">Native RenderScript layer</a></li> - - <li><a href="#reflected">Reflected layer</a></li> - - <li><a href="#framework">Android framework layer</a></li> + <li><a href="#func">Functions</a></li> + <li><a href="#var">Variables</a></li> + <li><a href="#pointer">Pointers</a></li> + <li><a href="#struct">Structs</a></li> </ol> </li> @@ -21,540 +21,284 @@ page.title=RenderScript <a href="#mem-allocation">Memory Allocation APIs</a> </li> <li> - <a href="#dynamic">Dynamic Memory Allocations</a> + <a href="#memory">Working with Memory</a> <ol> - <li><a href="#pointers">Declaring pointers</a></li> - - <li><a href="#struct-pointer-reflection">How pointers are reflected</a></li> - - <li><a href="#binding">Allocating and binding memory to the RenderScript</a></li> + <li><a href="#allocating-mem">Allocating and binding memory to the Renderscript</a></li> - <li><a href="#read-write-dynamic">Reading and writing to memory</a></li> + <li><a href="#read-write">Reading and writing to memory</a></li> </ol> </li> - <li> - <a href="#static">Static Memory Allocations</a> - </li> </ol> </div> </div> - <p>RenderScript offers a high performance 3D graphics rendering and compute API at the native - level, which you write in the C (C99 standard). The main advantages of RenderScript are:</p> + <p>Renderscript offers a high performance 3D graphics rendering and compute API at the native + level that you write in C (C99 standard). The main advantages of Renderscript are:</p> <ul> - <li>Portability: RenderScript is designed to run on many types of devices with different CPU - and GPU architectures. It supports all of these architectures without having to target each - device, because the code is compiled and cached on the device at runtime.</li> + <li>Portability: Renderscript is designed to run on many types of devices with different + processor (CPU, GPU, and DSP for instance) architectures. It supports all of these architectures without + having to target each device, because the code is compiled and cached on the device + at runtime.</li> - <li>Performance: RenderScript provides similar performance to OpenGL with the NDK while - offering the portability of the OpenGL APIs provided by the Android framework ({@link - android.opengl}). In addition, it also offers a high performance compute API that is not - offered by OpenGL.</li> + <li>Performance: Renderscript provides similar performance to OpenGL with the NDK and also + provides a high performance compute API that is not offered by OpenGL.</li> - <li>Usability: RenderScript simplifies development when possible, such as eliminating JNI glue code + <li>Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code and simplifying mesh setup.</li> </ul> <p>The main disadvantages are:</p> <ul> - <li>Development complexity: RenderScript introduces a new set of APIs that you have to learn. - RenderScript also handles memory differently compared to OpenGL with the Android framework APIs - or NDK.</li> + <li>Development complexity: Renderscript introduces a new set of APIs that you have to learn. + Renderscript also allocates memory differently compared to OpenGL with the Android framework APIs. + However, these issues are not hard to understand and Renderscript offers many features that + make it easier than OpenGL to initialize rendering.</li> - <li>Debugging visibility: RenderScript can potentially execute (planned feature for later releases) - on processors other than the main CPU (such as the GPU), so if this occurs, debugging becomes more difficult. + <li>Debugging visibility: Renderscript can potentially execute (planned feature for later releases) + on processors other than the main CPU (such as the GPU), so if this occurs, debugging becomes more difficult. </li> - - <li>Less features: RenderScript does not provide as many features as OpenGL such as all the compressed - texture formats or GL extensions.</li> </ul> - <p>You need to consider all of the aspects of RenderScript before deciding when to use it. The following list describes - general guidelines on when to use OpenGL (framework APIs or NDK) or RenderScript:</p> - <ul> - <li>If you are doing simple graphics rendering and performance is not critical, you probably want to use the - Android framework OpenGL APIs, which still provide adequate performance, to eliminate the added coding and debugging complexity of - RenderScript.</li> - - <li>If you want the most flexibility and features while maintaining relatively good debugging - support, you probably want to use OpenGL and the NDK. Applications that require this are high end - or complicated games, for example.</li> - - <li>If you want a solution that is portable, has good performance, - and you don't need the full feature set of OpenGL, RenderScript is a good solution. If you also - need a high performance compute language, then RenderScript offers that as well. - Good candidates for RenderScript are graphics intensive UIs that require 3D rendering, live wallpapers, - or applications that require intensive mathematical computation.</li> - </ul> - <p>For an example of RenderScript in action, install the RenderScript sample applications that + <p>For an example of Renderscript in action, install the Renderscript sample applications that are shipped with the SDK in <code><sdk_root>/samples/android-11/RenderScript</code>. - You can also see a typical use of RenderScript with the 3D carousel view in the Android 3.x + You can also see a typical use of Renderscript with the 3D carousel view in the Android 3.x versions of Google Books and YouTube.</p> - <h2 id="overview">RenderScript System Overview</h2> - - <p>The RenderScript system adopts a control and slave architecture where the low-level native + <h2 id="overview">Renderscript Overview</h2> + <p>The Renderscript runtime operates at the native level and still needs to communicate +with the Android VM, so the way a Renderscript application is setup is different from a pure VM +application. An application that uses Renderscript is still a traditional Android application that +runs in the VM, but you write Renderscript code for the parts of your program that require +it. Using Renderscript can be as simple as offloading a few math calculations or as complicated as +rendering an entire 3D game. No matter what you use it for, Renderscript remains platform +independent, so you do not have to target multiple architectures (for example, +ARM v5, ARM v7, x86).</p> + + <p>The Renderscript system adopts a control and slave architecture where the low-level Renderscript runtime code is controlled by the higher level Android system that runs in a virtual machine (VM). The - Android VM still retains all control of memory and lifecycle management and calls the native - RenderScript code when necessary. The native code is compiled to intermediate bytecode (LLVM) and - packaged inside your application's <code>.apk</code> file. On the device, the bytecode is - compiled (just-in-time) to machine code that is further optimized for the device that it is - running on. The compiled code on the device is cached, so subsequent uses of the RenderScript - enabled application do not recompile the intermediate code. RenderScript has three layers of code - to enable communication between the native and Android framework code:</p> + Android VM still retains all control of memory management and binds memory that it allocates to + the Renderscript runtime, so the Renderscript code can access it. The Android framework makes +asynchronous calls to Renderscript, and the calls are placed in a message queue and processed +as soon as possible. Figure 1 shows how the Renderscript system is structured.</p> + + <img id="figure1" src="{@docRoot}images/rs_overview.png" /> + <p class="img-caption"><strong>Figure 1.</strong> Renderscript system overview</p> + + <p>When using Renderscript, there are three layers of APIs that enable communication between the + Renderscript runtime and Android framework code:</p> <ul> - <li>The native RenderScript layer does the intensive computation or graphics rendering. You - define your native code in <code>.rs</code> and <code>.rsh</code> files.</li> - - <li>The reflected layer is a set of classes that are reflected from the native code. It is basically - a wrapper around the native code that allows the Android framework to interact with native RenderScripts. - The Android build tools automatically generate the classes for this layer during - the build process and eliminates the need to write JNI glue code, like with the NDK.</li> - - <li>The Android framework layer is comprised of the Android framework - APIs, which include the {@link android.renderscript} package. This layer gives high level commands - like, "rotate the view" or "filter the bitmap", by calling the reflected layer, which in turn calls - the native layer. </li> + <li>The Renderscript runtime APIs allow you to do the computation or graphics rendering + that is required by your application.</li> + + <li>The reflected layer APIs are a set of classes that are reflected from your Renderscript +runtime code. It is basically a wrapper around the Renderscript code that allows the Android +framework to interact with the Renderscript runtime. The Android build tools automatically generate the +classes for this layer during the build process. These classes eliminate the need to write JNI glue +code, like with the NDK.</li> + + <li>The Android framework APIs, which include the {@link android.renderscript} package, allow you to + build your application using traditional Android components such as activities and views. When + using Renderscript, this layer calls the reflected layer to access the Renderscript + runtime.</li> </ul> - <h3 id="native">Native RenderScript layer</h3> + <p></p> - <p>The native RenderScript layer consists of your RenderScript code, which is compiled and - executed in a compact and well defined runtime. Your RenderScript code has access to a limited - amount of functions because it cannot access the NDK or standard C functions, since they must be guaranteed to - run on a standard CPU. The RenderScript runtime was designed to run on different types of processors, - which may not be the CPU, so it cannot guarantee support for standard C libraries. What - RenderScript does offer is an API that supports intensive computation and graphics rendering with a collection of math - and graphics APIs.</p> + <h2 id="native">Renderscript Runtime Layer</h2> - <p>Some key features of the native RenderScript libraries include:</p> + <p>Your Renderscript code is compiled and + executed in a compact and well-defined runtime layer. The Renderscript runtime APIs offer support for +intensive computation and graphics rendering that is portable and automatically scalable to the +amount of cores available on a processor. +</p> +<p class="note"><strong>Note:</strong> The standard C functions in the NDK must be + guaranteed to run on a CPU, so Renderscript cannot access these libraries, + because Renderscript is designed to run on different types of processors.</p> - <ul> - <li>A large collection of math functions with both scalar and vector typed overloaded versions - of many common routines. Operations such as adding, multiplying, dot product, and cross product - are available.</li> +<p>You define your Renderscript code in <code>.rs</code> + and <code>.rsh</code> files in the <code>src/</code> directory of your Android project. The code + is compiled to intermediate bytecode by the + <code>llvm</code> compiler that runs as part of an Android build. When your application + runs on a device, the bytecode is then compiled (just-in-time) to machine code by another + <code>llvm</code> compiler that resides on the device. The machine code is optimized for the + device and also cached, so subsequent uses of the Renderscript enabled application does not + recompile the bytecode.</p> - <li>Conversion routines for primitive data types and vectors, matrix routines, date and time - routines, and graphics routines.</li> + <p>Some key features of the Renderscript runtime libraries include:</p> - <li>Logging functions</li> + <ul> <li>Graphics rendering functions</li> <li>Memory allocation request features</li> - <li>Data types and structures to support the RenderScript system such as Vector types for + <li>A large collection of math functions with both scalar and vector typed overloaded versions + of many common routines. Operations such as adding, multiplying, dot product, and cross product + are available as well as atomic arithmetic and comparison functions.</li> + + <li>Conversion routines for primitive data types and vectors, matrix routines, date and time + routines, and graphics routines.</li> + + <li>Data types and structures to support the Renderscript system such as Vector types for defining two-, three-, or four-vectors.</li> + + <li>Logging functions</li> </ul> - <p>The RenderScript header files and LLVM front-end libraries are located in the <code>include/</code> and - <code>clang-include/</code> directories in the - <code><sdk_root>/platforms/android-11/renderscript/</code> directory of the Android SDK. The - headers are automatically included for you, except for the RenderScript graphics specific header file, which + <p>See the Renderscript runtime API reference for more information on the available functions. The + Renderscript header files are automatically included for you, except for the Renderscript graphics header file, which you can include as follows:</p> - <pre> -#include "rs_graphics.rsh" -</pre> - <h3 id="reflected">Reflected layer</h3> +<pre>#include "rs_graphics.rsh"</pre> + + <h2 id="reflected">Reflected Layer</h2> <p>The reflected layer is a set of classes that the Android build tools generate to allow access - to the native RenderScript code from the Android VM. This layer defines entry points for - RenderScript functions and variables, so that you can interact with them with the Android - framework. This layer also provides methods and constructors that allow you to allocate memory - for pointers that are defined in your RenderScript code. The following list describes the major + to the Renderscript runtime from the Android framework. This layer also provides methods +and constructors that allow you to allocate and work with memory for pointers that are defined in +your Renderscript code. The following list describes the major components that are reflected:</p> <ul> <li>Every <code>.rs</code> file that you create is generated into a class named - <code>ScriptC_<em>renderscript_filename</em></code> of type {@link - android.renderscript.ScriptC}. This is the <code>.java</code> version of your <code>.rs</code> - file, which you can call from the Android framework. This class contains the following - reflections: + <code>project_root/gen/package/name/ScriptC_<em>renderscript_filename</em></code> of +type {@link android.renderscript.ScriptC}. This file is the <code>.java</code> version of your +<code>.rs</code> file, which you can call from the Android framework. This class contains the +following items reflected from the <code>.rs</code> file: <ul> - <li>Non-static functions in your <code>.rs</code> file.</li> - - <li>Non-static, global RenderScript variables. Accessor methods are generated for each - variable, so you can read and write the natively declared variables from the Android - framework. The <code>get</code> method comes with a one-way communication restriction. The - last value that is set from the Android framework is always returned during a call to a - <code>get</code> method. If the native RenderScript code changes the value, the change does - not propagate back to the Android framework layer. - If the global variables are initialized - in the native RenderScript code, those values are used to initialize the corresponding - values in the Android framework layer. If global variables are marked as - <code>const</code>, then a <code>set</code> method is not generated.</li> - <li>Global pointers generate a special method named <code>bind_<em>pointer_name</em></code> - instead of a <code>set()</code> method. This method allows you to bind the memory that is - allocated in the Android VM for the pointer to the native RenderScript (you cannot allocate - memory in your <code>.rs</code> file). You can read and write to this memory from both the - Android framework and RenderScript code. For more information, see <a href="mem-mgmt">Working - with Memory and Data</a></li> + <li>Non-static functions</li> + + <li>Non-static, global Renderscript variables. Accessor methods are generated for each + variable, so you can read and write the Renderscript variables from the Android + framework. If a global variable is initialized at the Renderscript runtime layer, those +values are used to initialize the corresponding values in the Android framework layer. If global +variables are marked as <code>const</code>, then a <code>set</code> method is not +generated.</p></li> + + <li>Global pointers</li> </ul> </li> <li>A <code>struct</code> is reflected into its own class named - <code>ScriptField_<em>struct_name</em></code>, which extends {@link + + <code>project_root/gen/package/name/ScriptField_struct_name</em></code>, which extends {@link android.renderscript.Script.FieldBase}. This class represents an array of the <code>struct</code>, which allows you to allocate memory for one or more instances of this <code>struct</code>.</li> </ul> - <h3 id="framework">Android framework layer</h3> - - <p>The Android framework layer consists of the usual Android framework APIs, which include the - RenderScript APIs in {@link android.renderscript}. This layer handles things such as the - Activity lifecycle and memory management of your application. It issues high level commands to - the native RenderScript code through the reflected layer and receives events from the user such - as touch and input events and relays them to your RenderScript code, if needed. - </p> - - <h2 id="mem-allocation">Memory Allocation APIs</h2> - - <p>Before you begin writing your first RenderScript application, you must understand how - memory is allocated for your RenderScript code and how data is shared between the native and VM - spaces. RenderScript allows you to access allocated memory in both the native layer - and Android system layer. All dynamic and static memory is allocated by the Android VM. - The Android VM also does reference counting and garbage collection for you. - You can also explicitly free memory that you no longer need.</p> - - <p class="note"><strong>Note:</strong> To declare temporary memory in your native RenderScript - code without allocating it in the Android VM, you can still do things like instantiate a scratch - buffer using an array.</p> - - <p>The following classes support the memory management features of RenderScript in the Android - VM. You normally do not need to work with these classes directly, because the reflected layer - classes provide constructors and methods that set up the memory allocation for you. There are - some situations where you would want to use these classes directly to allocate memory on your - own, such as loading a bitmap from a resource or when you want to allocate memory for pointers to - primitive types.</p> - - <table id="mem-mgmt-table"> - <tr> - <th>Android Object Type</th> - - <th>Description</th> - </tr> - - <tr> - <td>{@link android.renderscript.Element}</td> - - <td> - <p>An element represents one cell of a memory allocation and can have two forms: Basic or - Complex.</p> - - <p>A basic element contains a single component of data of any valid RenderScript data type. - Examples of basic element data types include a single float value, a float4 vector, or a - single RGB-565 color.</p> - - <p>Complex elements contain a list of basic elements and are created from - <code>struct</code>s that you declare in your RenderScript code. The most basic primitive - type determines the data alignment of the memory. For example, a float4 vector subelement - is alligned to <code>sizeof(float)</code> and not <code>sizeof(float4)</code>. The ordering - of the elements in memory are the order in which they were added, with each component - aligned as necessary.</p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.Type}</td> - <td> - A type is a memory allocation template and consists of an element and one or more - dimensions. It describes the layout of the memory (basically an array of {@link - android.renderscript.Element}s) but does not allocate the memory for the data that it - describes. - - <p>A type consists of five dimensions: X, Y, Z, LOD (level of detail), and Faces (of a cube - map). You can assign the X,Y,Z dimensions to any positive integer value within the - constraints of available memory. A single dimension allocation has an X dimension of - greater than zero while the Y and Z dimensions are zero to indicate not present. For - example, an allocation of x=10, y=1 is considered two dimensional and x=10, y=0 is - considered one dimensional. The LOD and Faces dimensions are booleans to indicate present - or not present.</p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.Allocation}</td> +<h3 id="func">Functions</h3> +<p>Functions are reflected into the script class itself, located in +<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. For +example, if you declare the following function in your Renderscript code:</p> - <td> - <p>An allocation provides the memory for applications based on a description of the memory - that is represented by a {@link android.renderscript.Type}. Allocated memory can exist in - many memory spaces concurrently. If memory is modified in one space, you must explicitly - synchronize the memory, so that it is updated in all the other spaces that it exists - in.</p> - - <p>Allocation data is uploaded in one of two primary ways: type checked and type unchecked. - For simple arrays there are <code>copyFrom()</code> functions that take an array from the - Android system and copy it to the native layer memory store. The unchecked variants allow - the Android system to copy over arrays of structures because it does not support - structures. For example, if there is an allocation that is an array of n floats, the data - contained in a float[n] array or a byte[n*4] array can be copied.</p> - </td> - </tr> - </table> - - <h2 id="dynamic">Working with dynamic memory allocations</h2> - - <p>RenderScript has support for pointers, but you must allocate the memory in your Android framework - code. When you declare a global pointer in your <code>.rs</code> file, you allocate memory - through the appropriate reflected layer class and bind that memory to the native - RenderScript layer. You can read and write to this memory from the Android framework layer as well as the - RenderScript layer, which offers you the flexibility to modify variables in the most appropriate - layer. The following sections show you how to work with pointers, allocate memory for them, and - read and write to the memory.</p> - - <h3 id="pointers">Declaring pointers</h3> - - <p>Because RenderScript is written in C99, declaring a pointer is done in a familiar way. You can - declare pointers to a <code>struct</code> or a primitive type, but a <code>struct</code> cannot - contain pointers or nested arrays. The following code declares a <code>struct</code>, a pointer - to that <code>struct</code>, and a pointer of primitive type <code>int32_t</code> in an <code>.rs</code> file:</p> - <pre> -#pragma version(1) -#pragma rs java_package_name(com.example.renderscript) - -... - -typedef struct Point { - float2 point; - } Point_t; - - Point_t *touchPoints; - int32_t *intPointer; - -... -</pre> - -<p>You cannot allocate memory for these pointers in your RenderScript code, but the Android -build tools generate classes for you that allow you to allocate memory in the Android VM for use by -your RenderScript code. These classes also let you read and write to the memory. The next section -describes how these classes are generated through reflection.</p> - - <h3>How pointers are reflected</h3> - - <p>Global variables have a getter and setter method generated. A global pointer generates a - <code>bind_pointerName()</code> method instead of a set() method. This method allows you to bind - the memory that is allocated in the Android VM to the native RenderScript. For example, the two - pointers in the previous section generate the following accessor methods in the <code>ScriptC_<em>rs_filename</em></code> file:</p> - <pre> - - private ScriptField_Point mExportVar_touchPoints; - public void bind_touchPoints(ScriptField_Point v) { - mExportVar_touchPoints = v; - if (v == null) bindAllocation(null, mExportVarIdx_touchPoints); - else bindAllocation(v.getAllocation(), mExportVarIdx_touchPoints); - } - - public ScriptField_Point get_touchPoints() { - return mExportVar_touchPoints; - } - - private Allocation mExportVar_intPointer; - public void bind_intPointer(Allocation v) { - mExportVar_intPointer = v; - if (v == null) bindAllocation(null, mExportVarIdx_intPointer); - else bindAllocation(v, mExportVarIdx_intPointer); - } - - public Allocation get_intPointer() { - return mExportVar_intPointer; +<pre> +void touch(float x, float y, float pressure, int id) { + if (id >= 10) { + return; } -</pre> - - <h3>Allocating and binding memory to the RenderScript</h3> - - <p>When the build tools generate the reflected layer, you can use the appropriate class - (<code>ScriptField_Point</code>, in our example) to allocate memory for a pointer. To do this, - you call the constructor for the {@link android.renderscript.Script.FieldBase} class and specify - the amount of structures that you want to allocate memory for. To allocate memory for a primitive - type pointer, you must build an allocation manually, using the memory management classes - described in <a href="mem-mgmt-table">Table 1</a>. The example below allocates memory for both - the <code>intPointer</code> and <code>touchPoints</code> pointer and binds it to the - RenderScript:</p> - <pre> -private RenderScriptGL glRenderer; -private ScriptC_example script; -private Resources resources; - -public void init(RenderScriptGL rs, Resources res) { - //get the rendering context and resources from the calling method - glRenderer = rs; - resources = res; - - //allocate memory for the struct pointer, calling the constructor - ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2); - - //Create an element manually and allocate memory for the int pointer - intPointer = Allocation.createSized(glRenderer, Element.I32(glRenderer), 2); - - //create an instance of the RenderScript, pointing it to the bytecode resource - mScript = new ScriptC_example(glRenderer, resources, R.raw.example); - - // bind the struct and int pointers to the RenderScript - mScript.bind_touchPoints(touchPoints); - script.bind_intPointer(intPointer); - - //bind the RenderScript to the rendering context - glRenderer.bindRootScript(script); + touchPos[id].x = x; + touchPos[id].y = y; + touchPressure[id] = pressure; } </pre> - <h3>Reading and writing to memory</h3> - - <p>Although you have to allocate memory within the Android VM, you can work with the memory both - in your native RenderScript code and in your Android code. Once memory is bound, the native - RenderScript can read and write to the memory directly. You can also just use the accessor - methods in the reflected classes to access the memory. If you modify memory in the Android - framework, it gets automatically synchronized to the native layer. If you modify memory in the <code>.rs</code> - file, these changes do not get propagated back to the Android framework. - For example, you can modify the struct in your Android code like this:</p> - <pre> -int index = 0; -boolean copyNow = true; -Float2 point = new Float2(0.0f, 0.0f); -touchPoints.set_point(index, point, copyNow); -</pre>then read it in your native RenderScript code like this: - <pre> -rsDebug("Printing out a Point", touchPoints[0].point.x, touchPoints[0].point.y); -</pre> +<p>then the following code is generated:</p> - <h2>Working with statically allocated memory</h2> - - <p>Non-static, global primitives and structs that you declare in your RenderScript are easier to work with, - because the memory is statically allocated at compile time. Accessor methods to set and get these - variables are generated when the Android build tools generate the reflected layer classes. You - can get and set these variables using the provided accessor methods. - <p class="note"><strong>Note:</strong> The <code>get</code> method comes with a one-way communication restriction. The last value - that is set from the Android framework is always returned during a call to a <code>get</code> - method. If the native RenderScript code changes the value, the change does not propagate back to - the Android framework layer. If the global variables are initialized in the native RenderScript - code, those values are used to initialize the corresponding values in the Android framework - layer. If global variables are marked as <code>const</code>, then a <code>set</code> method is - not generated.</p> - </p> - - <p>For example, if you declare the following primitive in your RenderScript code:</p> - <pre> - uint32_t unsignedInteger = 1; - +<pre> +public void invoke_touch(float x, float y, float pressure, int id) { + FieldPacker touch_fp = new FieldPacker(16); + touch_fp.addF32(x); + touch_fp.addF32(y); + touch_fp.addF32(pressure); + touch_fp.addI32(id); + invoke(mExportFuncIdx_touch, touch_fp); +} </pre> -<p>then the following code is generated in <code>ScriptC_<em>script_name</em>.java</code>:</p> - <pre> - private final static int mExportVarIdx_unsignedInteger = 9; - private long mExportVar_unsignedInteger; - public void set_unsignedInteger(long v) { - mExportVar_unsignedInteger = v; - setVar(mExportVarIdx_unsignedInteger, v); - } +<p> +Functions cannot have a return value, because the Renderscript system is designed to be +asynchronous. When your Android framework code calls into Renderscript, the call is queued and is +executed when possible. This restriction allows the Renderscript system to function without constant +interruption and increases efficiency. If functions were allowed to have return values, the call +would block until the value was returned.</p> - public long get_unsignedInteger() { - return mExportVar_unsignedInteger; - } -</pre> +<p> +If you want the Renderscript code to send a value back to the Android framework, use the +<a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> +function. +</p> - <p class="note"><strong>Note:</strong> The mExportVarIdx_unsignedInteger variable represents the - index of the <code>unsignedInteger</code>'s in an array of statically allocated primitives. You do - not need to work with or be aware of this index.</p> - - <p>For a <code>struct</code>, the Android build tools generate a class named - <code><project_root>/gen/com/example/renderscript/ScriptField_struct_name</code>. This - class represents an array of the <code>struct</code> and allows you to allocate memory for a - specified number of <code>struct</code>s. This class defines:</p> +<h3 id="var">Variables</h3> - <ul> - <li>Overloaded constructors that allow you to allocate memory. The - <code>ScriptField_<em>struct_name</em>(RenderScript rs, int count)</code> constructor allows - you to define the number of structures that you want to allocate memory for with the - <code>count</code> parameter. The <code>ScriptField_<em>struct_name</em>(RenderScript rs, int - count, int usages)</code> constructor defines an extra parameter, <code>usages</code>, that - lets you specify the memory space of this memory allocation. There are four memory space - possibilities: + <p>Variables of supported types are reflected into the script class itself, located in +<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. A set of accessor +methods are generated for each variable. For example, if you declare the following variable in +your Renderscript code:</p> + <pre>uint32_t unsignedInteger = 1;</pre> - <ul> - <li>{@link android.renderscript.Allocation#USAGE_SCRIPT}: Allocates in the script memory - space. This is the default memory space if you do not specify a memory space.</li> + <p>then the following code is generated:</p> - <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE}: Allocates in the - texture memory space of the GPU.</li> +<pre> +private long mExportVar_unsignedInteger; +public void set_unsignedInteger(long v){ + mExportVar_unsignedInteger = v; + setVar(mExportVarIdx_unsignedInteger, v); +} - <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_VERTEX}: Allocates in the vertex - memory space of the GPU.</li> +public long get_unsignedInteger(){ + return mExportVar_unsignedInteger; +} + </pre> - <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_CONSTANTS}: Allocates in the - constants memory space of the GPU that is used by the various program objects.</li> - </ul> - <p>You can specify one or all of these memory spaces by OR'ing them together. Doing so notifies - the RenderScript runtime that you intend on accessing the data in the specified memory spaces. The following - example allocates memory for a custom data type in both the script and vertex memory spaces:</p> + <h3 id="struct">Structs</h3> + <p>Structs are reflected into their own classes, located in + <code><project_root>/gen/com/example/renderscript/ScriptField_struct_name</code>. This + class represents an array of the <code>struct</code> and allows you to allocate memory for a + specified number of <code>struct</code>s. For example, if you declare the following struct:</p> <pre> -ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2, -Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX); +typedef struct Point { + float2 position; + float size; +} Point_t; </pre> - <p>If you modify the memory in one memory space and want to push the updates to the rest of - the memory spaces, call <code>rsgAllocationSyncAll()</code> in your RenderScript code to - synchronize the memory.</p> - </li> - - <li>A static nested class, <code>Item</code>, allows you to create an instance of the - <code>struct</code>, in the form of an object. This is useful if it makes more sense to work - with the <code>struct</code> in your Android code. When you are done manipulating the object, - you can push the object to the allocated memory by calling <code>set(Item i, int index, boolean - copyNow)</code> and setting the <code>Item</code> to the desired position in the array. The - native RenderScript code automatically has access to the newly written memory. - - <li>Accessor methods to get and set the values of each field in a struct. Each of these - accessor methods have an <code>index</code> parameter to specify the <code>struct</code> in the - array that you want to read or write to. Each setter method also has a <code>copyNow</code> - parameter that specifies whether or not to immediately sync this memory to the native - RenderScript layer. To sync any memory that has not been synced, call <code>copyAll()</code>.</li> - - <li>The createElement() method creates an object that describes the memory layout of the struct.</li> - - <li>resize() works much like a <code>realloc</code>, allowing you to expand previously - allocated memory, maintaining the current values that were previously set.</li> - - <li>copyAll() synchronizes memory that was set on the framework level to the native level. When you call - a set accessor method on a member, there is an optional <code>copyNow</code> boolean parameter that you can specify. Specifying - <code>true</code> synchronizes the memory when you call the method. If you specify false, you can call <code>copyAll()</code> - once, and it synchronizes memory for the all the properties that are not synchronized.</li> - </ul> - - <p>The following example shows the reflected class, <code>ScriptField_Point.java</code> that is - generated from the Point <code>struct</code>.</p> - <pre> -package com.example.renderscript; +<p>then the following code is generated in <code>ScriptField_Point.java</code>: +<pre> +package com.example.android.rs.hellocompute; import android.renderscript.*; import android.content.res.Resources; - + /** + * @hide + */ public class ScriptField_Point extends android.renderscript.Script.FieldBase { + static public class Item { - public static final int sizeof = 8; + public static final int sizeof = 12; - Float2 point; + Float2 position; + float size; Item() { - point = new Float2(); + position = new Float2(); } - } private Item mItemArray[]; private FieldPacker mIOBuffer; public static Element createElement(RenderScript rs) { Element.Builder eb = new Element.Builder(rs); - eb.add(Element.F32_2(rs), "point"); + eb.add(Element.F32_2(rs), "position"); + eb.add(Element.F32(rs), "size"); return eb.create(); } @@ -573,9 +317,11 @@ public class ScriptField_Point extends android.renderscript.Script.FieldBase { } private void copyToArray(Item i, int index) { - if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */); + if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count + */); mIOBuffer.reset(index * Item.sizeof); - mIOBuffer.addF32(i.point); + mIOBuffer.addF32(i.position); + mIOBuffer.addF32(i.size); } public void set(Item i, int index, boolean copyNow) { @@ -585,7 +331,6 @@ public class ScriptField_Point extends android.renderscript.Script.FieldBase { copyToArray(i, index); mAllocation.setFromFieldPacker(index, mIOBuffer); } - } public Item get(int index) { @@ -593,24 +338,42 @@ public class ScriptField_Point extends android.renderscript.Script.FieldBase { return mItemArray[index]; } - public void set_point(int index, Float2 v, boolean copyNow) { - if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */)fnati; + public void set_position(int index, Float2 v, boolean copyNow) { + if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */); if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */]; if (mItemArray[index] == null) mItemArray[index] = new Item(); - mItemArray[index].point = v; - if (copyNow) { + mItemArray[index].position = v; + if (copyNow) { mIOBuffer.reset(index * Item.sizeof); mIOBuffer.addF32(v); FieldPacker fp = new FieldPacker(8); fp.addF32(v); mAllocation.setFromFieldPacker(index, 0, fp); } + } + public void set_size(int index, float v, boolean copyNow) { + if (mIOBuffer == null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */); + if (mItemArray == null) mItemArray = new Item[getType().getX() /* count */]; + if (mItemArray[index] == null) mItemArray[index] = new Item(); + mItemArray[index].size = v; + if (copyNow) { + mIOBuffer.reset(index * Item.sizeof + 8); + mIOBuffer.addF32(v); + FieldPacker fp = new FieldPacker(4); + fp.addF32(v); + mAllocation.setFromFieldPacker(index, 1, fp); + } } - public Float2 get_point(int index) { + public Float2 get_position(int index) { if (mItemArray == null) return null; - return mItemArray[index].point; + return mItemArray[index].position; + } + + public float get_size(int index) { + if (mItemArray == null) return 0; + return mItemArray[index].size; } public void copyAll() { @@ -627,13 +390,415 @@ public class ScriptField_Point extends android.renderscript.Script.FieldBase { System.arraycopy(mItemArray, 0, ni, 0, copySize); mItemArray = ni; } - mAllocation.resize(newSize); if (mIOBuffer != null) mIOBuffer = new FieldPacker(Item.sizeof * getType().getX()/* count */); } +} +</pre> + +<p>The generated code is provided to you as a convenience to allocate memory for structs requested +by the Renderscript runtime and to interact with <code>struct</code>s +in memory. Each <code>struct</code>'s class defines the following methods and constructors:</p> + + <ul> + <li>Overloaded constructors that allow you to allocate memory. The + <code>ScriptField_<em>struct_name</em>(RenderScript rs, int count)</code> constructor allows + you to define the number of structures that you want to allocate memory for with the + <code>count</code> parameter. The <code>ScriptField_<em>struct_name</em>(RenderScript rs, int + count, int usages)</code> constructor defines an extra parameter, <code>usages</code>, that + lets you specify the memory space of this memory allocation. There are four memory space + possibilities: + + <ul> + <li>{@link android.renderscript.Allocation#USAGE_SCRIPT}: Allocates in the script memory + space. This is the default memory space if you do not specify a memory space.</li> + + <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE}: Allocates in the + texture memory space of the GPU.</li> + + <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_VERTEX}: Allocates in the vertex + memory space of the GPU.</li> + + <li>{@link android.renderscript.Allocation#USAGE_GRAPHICS_CONSTANTS}: Allocates in the + constants memory space of the GPU that is used by the various program objects.</li> + </ul> + + <p>You can specify multiple memory spaces by using the bitwise <code>OR</code> operator. Doing so + notifies the Renderscript runtime that you intend on accessing the data in the + specified memory spaces. The following example allocates memory for a custom data type + in both the script and vertex memory spaces:</p> + <pre> + ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2, + Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX); + </pre> + + <p>If you modify the memory in one memory space and want to push the updates to the rest of + the memory spaces, call <a href="{@docRoot}reference/renderscript/rs__graphics_8rsh.html"> + <code>rsgAllocationSyncAll()</code></a> in your Renderscript code to + synchronize the memory.</p> + </li> + + <li>A static nested class, <code>Item</code>, allows you to create an instance of the + <code>struct</code>, in the form of an object. This nested class is useful if it makes more sense to work + with the <code>struct</code> in your Android code. When you are done manipulating the object, + you can push the object to the allocated memory by calling <code>set(Item i, int index, + boolean copyNow)</code> and setting the <code>Item</code> to the desired position in +the array. The Renderscript runtime automatically has access to the newly written memory. + + <li>Accessor methods to get and set the values of each field in a struct. Each of these + accessor methods have an <code>index</code> parameter to specify the <code>struct</code> in + the array that you want to read or write to. Each setter method also has a +<code>copyNow</code> parameter that specifies whether or not to immediately sync this memory +to the Renderscript runtime. To sync any memory that has not been synced, call + <code>copyAll()</code>.</li> + + <li>The <code>createElement()</code> method creates a description of the struct in memory. This + description is used to allocate memory consisting of one or many elements.</li> + + <li><code>resize()</code> works much like a <code>realloc()</code> in C, allowing you to +expand previously allocated memory, maintaining the current values that were previously +created.</li> + + <li><code>copyAll()</code> synchronizes memory that was set on the framework level to the +Renderscript runtime. When you call a set accessor method on a member, there is an optional +<code>copyNow</code> boolean parameter that you can specify. Specifying + <code>true</code> synchronizes the memory when you call the method. If you specify false, + you can call <code>copyAll()</code> once, and it synchronizes memory for all the +properties that are not yet synchronized.</li> + </ul> + + <h3 id="pointer">Pointers</h3> + <p>Pointers are reflected into the script class itself, located in +<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. You +can declare pointers to a <code>struct</code> or any of the supported Renderscript types, but a +<code>struct</code> cannot contain pointers or nested arrays. For example, if you declare the +following pointers to a <code>struct</code> and <code>int32_t</code></p> + +<pre> +typedef struct Point { + float2 position; + float size; +} Point_t; + +Point_t *touchPoints; +int32_t *intPointer; +</pre> + <p>then the following code is generated in:</p> + +<pre> +private ScriptField_Point mExportVar_touchPoints; +public void bind_touchPoints(ScriptField_Point v) { + mExportVar_touchPoints = v; + if (v == null) bindAllocation(null, mExportVarIdx_touchPoints); + else bindAllocation(v.getAllocation(), mExportVarIdx_touchPoints); +} + +public ScriptField_Point get_touchPoints() { + return mExportVar_touchPoints; +} + +private Allocation mExportVar_intPointer; +public void bind_intPointer(Allocation v) { + mExportVar_intPointer = v; + if (v == null) bindAllocation(null, mExportVarIdx_intPointer); + else bindAllocation(v, mExportVarIdx_intPointer); +} + +public Allocation get_intPointer() { + return mExportVar_intPointer; +} + </pre> + +<p>A <code>get</code> method and a special method named <code>bind_<em>pointer_name</em></code> +(instead of a <code>set()</code> method) is generated. This method allows you to bind the memory +that is allocated in the Android VM to the Renderscript runtime (you cannot allocate +memory in your <code>.rs</code> file). For more information, see <a href="#memory">Working +with Allocated Memory</a>. +</p> + + + <h2 id="mem-allocation">Memory Allocation APIs</h2> + + <p>Applications that use Renderscript still run in the Android VM. The actual Renderscript code, however, runs natively and + needs access to the memory allocated in the Android VM. To accomplish this, you must + attach the memory that is allocated in the VM to the Renderscript runtime. This +process, called binding, allows the Renderscript runtime to seamlessly work with memory that it +requests but cannot explicitly allocate. The end result is essentially the same as if you had +called <code>malloc</code> in C. The added benefit is that the Android VM can carry out garbage collection as well as +share memory with the Renderscript runtime layer. Binding is only necessary for dynamically allocated memory. Statically +allocated memory is automatically created for your Renderscript code at compile time. See <a href="#figure1">Figure 1</a> +for more information on how memory allocation occurs. +</p> + + <p>To support this memory allocation system, there are a set of APIs that allow the Android VM to +allocate memory and offer similar functionality to a <code>malloc</code> call. These classes +essentially describe how memory should be allocated and also carry out the allocation. To better +understand how these classes work, it is useful to think of them in relation to a simple +<code>malloc</code> call that can look like this: </p> + + <pre>array = (int *)malloc(sizeof(int)*10);</pre> + + <p>The <code>malloc</code> call can be broken up into two parts: the size of the memory being allocated (<code>sizeof(int)</code>), + along with how many units of that memory should be allocated (10). The Android framework provides classes for these two parts as + well as a class to represent <code>malloc</code> itself.</p> + + <p>The {@link android.renderscript.Element} class represents the (<code>sizeof(int)</code>) portion + of the <code>malloc</code> call and encapsulates one cell of a memory allocation, such as a single + float value or a struct. The {@link android.renderscript.Type} class encapsulates the {@link android.renderscript.Element} + and the amount of elements to allocate (10 in our example). You can think of a {@link android.renderscript.Type} as + an array of {@link android.renderscript.Element}s. The {@link android.renderscript.Allocation} class does the actual + memory allocation based on a given {@link android.renderscript.Type} and represents the actual allocated memory.</p> + + <p>In most situations, you do not need to call these memory allocation APIs directly. The reflected layer + classes generate code to use these APIs automatically and all you need to do to allocate memory is call a + constructor that is declared in one of the reflected layer classes and then bind + the resulting memory {@link android.renderscript.Allocation} to the Renderscript. + There are some situations where you would want to use these classes directly to allocate memory on your + own, such as loading a bitmap from a resource or when you want to allocate memory for pointers to + primitive types. You can see how to do this in the + <a href="#allocating-mem">Allocating and binding memory to the Renderscript</a> section. + The following table describes the three memory management classes in more detail:</p> + + <table id="mem-mgmt-table"> + <tr> + <th>Android Object Type</th> + + <th>Description</th> + </tr> + + <tr> + <td>{@link android.renderscript.Element}</td> + + <td> + <p>An element describes one cell of a memory allocation and can have two forms: basic or + complex.</p> + + <p>A basic element contains a single component of data of any valid Renderscript data type. + Examples of basic element data types include a single <code>float</code> value, a <code>float4</code> vector, or a + single RGB-565 color.</p> + + <p>Complex elements contain a list of basic elements and are created from + <code>struct</code>s that you declare in your Renderscript code. For instance an allocation + can contain multiple <code>struct</code>s arranged in order in memory. Each struct is considered as its + own element, rather than each data type within that struct.</p> + </td> + </tr> + + <tr> + <td>{@link android.renderscript.Type}</td> + + <td> + <p>A type is a memory allocation template and consists of an element and one or more + dimensions. It describes the layout of the memory (basically an array of {@link + android.renderscript.Element}s) but does not allocate the memory for the data that it + describes.</p> + + <p>A type consists of five dimensions: X, Y, Z, LOD (level of detail), and Faces (of a cube + map). You can assign the X,Y,Z dimensions to any positive integer value within the + constraints of available memory. A single dimension allocation has an X dimension of + greater than zero while the Y and Z dimensions are zero to indicate not present. For + example, an allocation of x=10, y=1 is considered two dimensional and x=10, y=0 is + considered one dimensional. The LOD and Faces dimensions are booleans to indicate present + or not present.</p> + </td> + </tr> + + <tr> + <td>{@link android.renderscript.Allocation}</td> + + <td> + <p>An allocation provides the memory for applications based on a description of the memory + that is represented by a {@link android.renderscript.Type}. Allocated memory can exist in + many memory spaces concurrently. If memory is modified in one space, you must explicitly + synchronize the memory, so that it is updated in all the other spaces in which it exists. + </p> + + <p>Allocation data is uploaded in one of two primary ways: type checked and type unchecked. + For simple arrays there are <code>copyFrom()</code> functions that take an array from the + Android system and copy it to the native layer memory store. The unchecked variants allow + the Android system to copy over arrays of structures because it does not support + structures. For example, if there is an allocation that is an array of n floats, the data + contained in a float[n] array or a <code>byte[n*4]</code> array can be copied.</p> + </td> + </tr> + </table> + + <h2 id="memory">Working with Memory</h2> + +<p>Non-static, global variables that you declare in your Renderscript are allocated memory at compile time. +You can work with these variables directly in your Renderscript code without having to allocate +memory for them at the Android framework level. The Android framework layer also has access to these variables +with the provided accessor methods that are generated in the reflected layer classes. If these variables are +initialized at the Renderscript runtime layer, those values are used to initialize the corresponding +values in the Android framework layer. If global variables are marked as const, then a <code>set</code> method is +not generated.</p> + + +<p class="note"><strong>Note:</strong> If you are using certain Renderscript structures that contain pointers, such as +<code>rs_program_fragment</code> and <code>rs_allocation</code>, you have to obtain an object of the +corresponding Android framework class first and then call the <code>set</code> method for that +structure to bind the memory to the Renderscript runtime. You cannot directly manipulate these structures +at the Renderscript runtime layer. This restriction is not applicable to user-defined structures +that contain pointers, because they cannot be exported to a reflected layer class +in the first place. A compiler error is generated if you try to declare a non-static, global +struct that contains a pointer. +</p> + +<p>Renderscript also has support for pointers, but you must explicitly allocate the memory in your +Android framework code. When you declare a global pointer in your <code>.rs</code> file, you +allocate memory through the appropriate reflected layer class and bind that memory to the native +Renderscript layer. You can interact with this memory from the Android framework layer as well as +the Renderscript layer, which offers you the flexibility to modify variables in the most +appropriate layer.</p> + + + + <h3 id="allocating-mem">Allocating and binding dynamic memory to the Renderscript</h3> + + <p>To allocate dynamic memory, you need to call the constructor of a + {@link android.renderscript.Script.FieldBase} class, which is the most common way. An alternative is to create an + {@link android.renderscript.Allocation} manually, which is required for things such as primitive type pointers. You should + use a {@link android.renderscript.Script.FieldBase} class constructor whenever available for simplicity. + After obtaining a memory allocation, call the reflected <code>bind</code> method of the pointer to bind the allocated memory to the + Renderscript runtime.</p> + <p>The example below allocates memory for both a primitive type pointer, + <code>intPointer</code>, and a pointer to a struct, <code>touchPoints</code>. It also binds the memory to the + Renderscript:</p> + <pre> +private RenderScriptGL glRenderer; +private ScriptC_example script; +private Resources resources; + +public void init(RenderScriptGL rs, Resources res) { + //get the rendering context and resources from the calling method + glRenderer = rs; + resources = res; + + //allocate memory for the struct pointer, calling the constructor + ScriptField_Point touchPoints = new ScriptField_Point(glRenderer, 2); + + //Create an element manually and allocate memory for the int pointer + intPointer = Allocation.createSized(glRenderer, Element.I32(glRenderer), 2); + + //create an instance of the Renderscript, pointing it to the bytecode resource + mScript = new ScriptC_example(glRenderer, resources, R.raw.example); + //bind the struct and int pointers to the Renderscript + mScript.bind_touchPoints(touchPoints); + script.bind_intPointer(intPointer); + + ... } </pre> -</body> -</html> + <h3>Reading and writing to memory</h3> + <p>You can read and write to statically and dynamically allocated memory both at the Renderscript runtime + and Android framework layer.</p> + +<p>Statically allocated memory comes with a one-way communication restriction +at the Renderscript runtime level. When Renderscript code changes the value of a variable, it is not +communicated back to the Android framework layer for efficiency purposes. The last value +that is set from the Android framework is always returned during a call to a <code>get</code> +method. However, when Android framework code modifies a variable, that change can be communicated to +the Renderscript runtime automatically or synchronized at a later time. If you need to send data +from the Renderscript runtime to the Android framework layer, you can use the +<a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> function +to overcome this limitation. +</p> +<p>When working with dynamically allocated memory, any changes at the Renderscript runtime layer are propagated +back to the Android framework layer if you modified the memory allocation using its associated pointer. +Modifying an object at the Android framework layer immediately propagates that change back to the Renderscript +runtime layer.</p> + + <h4>Reading and writing to global variables</h4> + + <p>Reading and writing to global variables is a straightforward process. You can use the accessor methods + at the Android framework level or set them directly in the Renderscript code. Keep in mind that any + changes that you make in your Renderscript code are not propagated back to the Android framework layer.</p> + + <p>For example, given the following struct declared in a file named <code>rsfile.rs</code>:</p> +<pre> +typedef struct Point { + int x; + int y; +} Point_t; + +Point_t point; + +</pre> +<p>You can assign values to the struct like this directly in <code>rsfile.rs</code>. These values are not +propagated back to the Android framework level:</p> +<pre> +point.x = 1; +point.y = 1; +</pre> + +<p>You can assign values to the struct at the Android framework layer like this. These values are +propagated back to the Renderscript runtime level:</p> +<pre> +ScriptC_rsfile mScript; + +... + +Item i = new ScriptField_Point.Item(); +i.x = 1; +i.y = 1; +mScript.set_point(i); +</pre> + +<p>You can read the values in your Renderscript code like this:</p> + +<pre> +rsDebug("Printing out a Point", point.x, point.y); +</pre> + +<p>You can read the values in the Android framework layer with the following code. Keep in mind that this +code only returns a value if one was set at the Android framework level. You will get a null pointer +exception if you only set the value at the Renderscript runtime level:</p> + +<pre> +Log.i("TAGNAME", "Printing out a Point: " + mScript.get_point().x + " " + mScript.get_point().y); +System.out.println(point.get_x() + " " + point.get_y()); +</pre> + +<h4>Reading and writing global pointers</h4> + +<p>Assuming that memory has been allocated in the Android framework level and bound to the Renderscript runtime, +you can read and write memory from the Android framework level by using the <code>get</code> and <code>set</code> methods for that pointer. +In the Renderscript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated +back to the Android framework layer, unlike with statically allocated memory.</p> + +<p>For example, given the following pointer to a <code>struct</code> in a file named <code>rsfile.rs</code>:</p> +<pre> +typedef struct Point { + int x; + int y; +} Point_t; + +Point_t *point; +</pre> + +<p>Assuming you already allocated memory at the Android framework layer, you can access values in +the <code>struct</code> as normal. Any changes you make to the struct via its pointer variable +are automatically available to the Android framework layer:</p> + +<pre> +point[index].x = 1; +point[index].y = 1; +</pre> + +<p>You can read and write values to the pointer at the Android framework layer as well: +<pre> +ScriptField_Point p = new ScriptField_Point(mRS, 1); + Item i = new ScriptField_Point.Item(); + i.x=100; + i.y = 100; + p.set(i, 0, true); + mScript.bind_point(p); + + points.get_x(0); //read x and y from index 0 + points.get_x(0); +</pre> + +<p>Once memory is already bound, you do not have to rebind the memory to the Renderscript +runtime every time you make a change to a value.</p> diff --git a/docs/html/guide/topics/renderscript/reference.jd b/docs/html/guide/topics/renderscript/reference.jd new file mode 100644 index 0000000..a0a9df2 --- /dev/null +++ b/docs/html/guide/topics/renderscript/reference.jd @@ -0,0 +1,18 @@ +page.title=Runtime API Reference +@jd:body + +<script language="JavaScript"> + +function autoResize(element){ + var newheight; + var newwidth; + + newheight = element.contentWindow.document.body.scrollHeight + 20; + newwidth = element.contentWindow.document.body.scrollWidth; + element.height = (newheight) + "px"; + element.width = (newwidth) + "px"; +} +</script> + + +<iframe SRC="{@docRoot}reference/renderscript/index.html" width="100%" id="iframe" marginheight="0" frameborder="0" onLoad="autoResize(this);"></iframe> diff --git a/docs/html/guide/topics/resources/animation-resource.jd b/docs/html/guide/topics/resources/animation-resource.jd index eaa698f..6473155 100644 --- a/docs/html/guide/topics/resources/animation-resource.jd +++ b/docs/html/guide/topics/resources/animation-resource.jd @@ -335,7 +335,7 @@ set.start(); <dd> <ul> <li><a href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a></li> - <li><a href="http://zoso:8080/resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> for examples + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> for examples on how to use the property animation system.</li> </ul> </dd> diff --git a/docs/html/guide/topics/resources/drawable-resource.jd b/docs/html/guide/topics/resources/drawable-resource.jd index 80de9f9..a34ed6c 100644 --- a/docs/html/guide/topics/resources/drawable-resource.jd +++ b/docs/html/guide/topics/resources/drawable-resource.jd @@ -1248,7 +1248,6 @@ the right edge, a right gravity clips the left edge, and neither clips both edge android:drawable="@drawable/android" android:clipOrientation="horizontal" android:gravity="left" /> -</clip> </pre> <p>The following layout XML applies the clip drawable to a View:</p> <pre> diff --git a/docs/html/guide/topics/resources/index.jd b/docs/html/guide/topics/resources/index.jd index 84eac73..3f0f1ee 100644 --- a/docs/html/guide/topics/resources/index.jd +++ b/docs/html/guide/topics/resources/index.jd @@ -28,18 +28,18 @@ to provide compatibility with different configurations, you must organize resour project's {@code res/} directory, using various sub-directories that group resources by type and configuration.</p> -<div class="figure" style="width:421px"> -<img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="137" alt="" /> +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="167" alt="" /> <p class="img-caption"> -<strong>Figure 1.</strong> Two different devices, both using default -resources.</p> +<strong>Figure 1.</strong> Two different devices, each using the default layout +(the app provides no alternative layouts).</p> </div> -<div class="figure" style="width:421px"> -<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="137" alt="" /> +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> <p class="img-caption"> -<strong>Figure 2.</strong> Two different devices, one using alternative -resources.</p> +<strong>Figure 2.</strong> Two different devices, each using a different layout provided +for different screen sizes.</p> </div> <p>For any type of resource, you can specify <em>default</em> and multiple @@ -54,18 +54,16 @@ append an appropriate configuration qualifier to the directory name.</li> </ul> <p>For example, while your default UI -layout is saved in the {@code res/layout/} directory, you might specify a different UI layout to +layout is saved in the {@code res/layout/} directory, you might specify a different layout to be used when the screen is in landscape orientation, by saving it in the {@code res/layout-land/} directory. Android automatically applies the appropriate resources by matching the device's current configuration to your resource directory names.</p> -<p>Figure 1 demonstrates how a collection of default resources from an application are applied -to two different devices when there are no alternative resources available. Figure 2 shows -the same application with a set of alternative resources that qualify for one of the device -configurations, thus, the two devices uses different resources.</p> +<p>Figure 1 illustrates how the system applies the same layout for +two different devices when there are no alternative resources available. Figure 2 shows +the same application when it adds an alternative layout resource for larger screens.</p> -<p>The information above is just an introduction to how application resources work on Android. -The following documents provide a complete guide to how you can organize your application resources, +<p>The following documents provide a complete guide to how you can organize your application resources, specify alternative resources, access them in your application, and more:</p> <dl> diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd index 9affb15..c2b668d 100755 --- a/docs/html/guide/topics/resources/localization.jd +++ b/docs/html/guide/topics/resources/localization.jd @@ -186,7 +186,7 @@ speak. </p> and can include other types of resources such as animations.
<br>
<code> res/drawable/</code>(required directory holding at least
- one graphic file, for the application's icon in the Market)<br>
+ one graphic file, for the application's icon on Google Play)<br>
<code> res/layout/</code> (required directory holding an XML
file that defines the default layout)<br>
<code> res/anim/</code> (required if you have any
@@ -507,7 +507,7 @@ the new locale. </p> <h2 id="publishing">Publishing Localized Applications</h2>
-<p>The Android Market is
+<p>The Google Play is
the main application distribution system for Android devices. To publish a
localized application, you need to sign your application, version it, and go
through all the other steps described in <a
@@ -521,7 +521,7 @@ different locale, follow these guidelines:</p> href="{@docRoot}guide/publishing/app-signing.html#strategies">Signing
Strategies</a>. </li>
<li>Give each .apk file a different application name. Currently it is
-impossible to put two applications into the Android Market that have exactly the
+impossible to publish two applications on Google Play that have exactly the
same name.</li>
<li>Include a complete set of default resources in each .apk file.</li>
</ul>
@@ -638,7 +638,7 @@ border="0"></td> <tr>
<td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
border="0"></td>
- <td>Upload your .apk file or files to Market, selecting the appropriate
+ <td>Upload your .apk file or files to Google Play, selecting the appropriate
languages as
you upload. (For more details, see <a
href="{@docRoot}guide/publishing/publishing.html">Publishing Your
diff --git a/docs/html/guide/topics/resources/more-resources.jd b/docs/html/guide/topics/resources/more-resources.jd index 972eab9..d37b9f8 100644 --- a/docs/html/guide/topics/resources/more-resources.jd +++ b/docs/html/guide/topics/resources/more-resources.jd @@ -216,27 +216,29 @@ is specified with a number followed by a unit of measure. For example: 10px, 2in, 5sp. The following units of measure are supported by Android:</p> <dl> <dt>{@code dp}</dt> - <dd>Density-independent Pixels - an abstract unit that is based on the physical density of the -screen. These units are relative to a 160 dpi (dots per inch) screen, so <em>{@code 160dp} is -always one inch</em> regardless of the screen density. The ratio of dp-to-pixel will change with the -screen density, but not necessarily in direct proportion. You should use these units when specifying -view dimensions in your layout, so the UI properly scales to render at the same actual size on -different screens. (The compiler accepts both "dip" and "dp", though "dp" is more consistent with -"sp".)</dd> + <dd>Density-independent Pixels - An abstract unit that is based on the physical density of the +screen. These units are relative to a 160 dpi (dots per inch) screen, on which 1dp is roughly equal +to 1px. When running on a higher density screen, the number of pixels used to draw 1dp is scaled up +by a factor appropriate for the screen's dpi. Likewise, when on a lower density screen, the number +of pixels used for 1dp is scaled down. The ratio of dp-to-pixel will change with the screen density, +but not necessarily in direct proportion. Using dp units (instead of px units) is a simple solution +to making the view dimensions in your layout resize properly for different screen densities. In +other words, it provides consistency for the real-world sizes of your UI elements across different +devices.</dd> <dt>{@code sp}</dt> - <dd>Scale-independent Pixels - this is like the dp unit, but it is also scaled by the user's font + <dd>Scale-independent Pixels - This is like the dp unit, but it is also scaled by the user's font size preference. It is recommend you use this unit when specifying font sizes, so they will be adjusted for both the screen density and the user's preference.</dd> <dt>{@code pt}</dt> <dd>Points - 1/72 of an inch based on the physical size of the screen.</dd> <dt>{@code px}</dt> - <dd>Pixels - corresponds to actual pixels on the screen. This unit of measure is not recommended because + <dd>Pixels - Corresponds to actual pixels on the screen. This unit of measure is not recommended because the actual representation can vary across devices; each devices may have a different number of pixels per inch and may have more or fewer total pixels available on the screen.</dd> <dt>{@code mm}</dt> - <dd>Millimeters - based on the physical size of the screen.</dd> + <dd>Millimeters - Based on the physical size of the screen.</dd> <dt>{@code in}</dt> - <dd>Inches - based on the physical size of the screen.</dd> + <dd>Inches - Based on the physical size of the screen.</dd> </dl> <p class="note"><strong>Note:</strong> A dimension is a simple resource that is referenced diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 252c153..b33a097 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -207,10 +207,10 @@ resources.</p> <h2 id="AlternativeResources">Providing Alternative Resources</h2> -<div class="figure" style="width:421px"> -<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="137" alt="" /> +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> <p class="img-caption"> -<strong>Figure 1.</strong> Two different devices, one using alternative resources.</p> +<strong>Figure 1.</strong> Two different devices, each using different layout resources.</p> </div> <p>Almost every application should provide alternative resources to support specific device @@ -231,6 +231,9 @@ for which these resources are to be used (defined in table 2).</li> </ul> <p>You can append more than one <em>{@code <qualifier>}</em>. Separate each one with a dash.</p> + <p class="caution"><strong>Caution:</strong> When appending multiple qualifiers, you must +place them in the same order in which they are listed in table 2. If the qualifiers are ordered +wrong, the resources are ignored.</p> </li> <li>Save the respective alternative resources in this new directory. The resource files must be named exactly the same as the default resource files.</li> @@ -254,20 +257,14 @@ screen density, but the filenames are exactly the same. This way, the resource ID that you use to reference the {@code icon.png} or {@code background.png} image is always the same, but Android selects the version of each resource that best matches the current device, by comparing the device -configuration information with the qualifiers in the alternative resource directory name.</p> +configuration information with the qualifiers in the resource directory name.</p> <p>Android supports several configuration qualifiers and you can add multiple qualifiers to one directory name, by separating each qualifier with a dash. Table 2 lists the valid configuration qualifiers, in order of precedence—if you use multiple -qualifiers for one resource directory, they must be added to the directory name in the order they +qualifiers for a resource directory, you must add them to the directory name in the order they are listed in the table.</p> -<p class="note"><strong>Note:</strong> Some configuration qualifiers were added after Android 1.0, -so not -all versions of Android support all the qualifiers listed in table 2. New qualifiers -indicate the version in which they were added. To avoid any issues, always include a set of default -resources for resources that your application uses. For more information, see the section about <a -href="#Compatibility">Providing the Best Device Compatibility with Resources</a>.</p> <p class="table-caption" id="table2"><strong>Table 2.</strong> Configuration qualifier names.</p> @@ -290,9 +287,8 @@ names.</p> from the SIM card in the device. For example, <code>mcc310</code> is U.S. on any carrier, <code>mcc310-mnc004</code> is U.S. on Verizon, and <code>mcc208-mnc00</code> is France on Orange.</p> - <p>If the device uses a radio connection (GSM phone), the MCC comes - from the SIM, and the MNC comes from the network to which the - device is connected.</p> + <p>If the device uses a radio connection (GSM phone), the MCC and MNC values come + from the SIM card.</p> <p>You can also use the MCC alone (for example, to include country-specific legal resources in your application). If you need to specify based on the language only, then use the <em>language and region</em> qualifier instead (discussed next). If you decide to use the MCC and @@ -752,6 +748,17 @@ href="#KnownIssues">Known Issues</a> for more information.</p> </table> +<p class="note"><strong>Note:</strong> Some configuration qualifiers have been added since Android +1.0, so not all versions of Android support all the qualifiers. Using a new qualifier implicitly +adds the platform version qualifier so that older devices are sure to ignore it. For example, using +a <code>w600dp</code> qualifier will automatically include the <code>v13</code> qualifier, because +the available-width qualifier was new in API level 13. To avoid any issues, always include a set of +default resources (a set of resources with <em>no qualifiers</em>). For more information, see the +section about <a href="#Compatibility">Providing the Best Device Compatibility with +Resources</a>.</p> + + + <h3 id="QualifierRules">Qualifier name rules</h3> <p>Here are some rules about using configuration qualifier names:</p> @@ -1021,8 +1028,8 @@ drawables from {@code drawable-en-port}.</p> logic:</p> -<div class="figure" style="width:280px"> -<img src="{@docRoot}images/resources/res-selection-flowchart.png" alt="" height="590" /> +<div class="figure" style="width:371px"> +<img src="{@docRoot}images/resources/res-selection-flowchart.png" alt="" height="471" /> <p class="img-caption"><strong>Figure 2.</strong> Flowchart of how Android finds the best-matching resource.</p> </div> diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd index ecd2d48..5f5484e 100644 --- a/docs/html/guide/topics/resources/string-resource.jd +++ b/docs/html/guide/topics/resources/string-resource.jd @@ -358,11 +358,14 @@ values, with non-exhaustive examples in parentheses: <pre> int count = getNumberOfsongsAvailable(); Resources res = {@link android.content.Context#getResources()}; -String songsFound = res.{@link android.content.res.Resources#getQuantityString(int,int) -getQuantityString}(R.plurals.numberOfSongsAvailable, count, count); +String songsFound = res.<a +href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)" +>getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count); </pre> -<p>When using the {@link android.content.res.Resources#getQuantityString(int,int) -getQuantityString()} method, you need to pass the {@code count} twice if your string includes + +<p>When using the <a +href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code +getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes <a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string {@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural diff --git a/docs/html/guide/topics/search/search-dialog.jd b/docs/html/guide/topics/search/search-dialog.jd index e06563d..8b8e75b 100644 --- a/docs/html/guide/topics/search/search-dialog.jd +++ b/docs/html/guide/topics/search/search-dialog.jd @@ -544,7 +544,8 @@ public boolean onSearchRequested() { } </pre> -<p>If the user cancels search by pressing the BACK button, the search dialog closes and the activity +<p>If the user cancels search by pressing the <em>Back</em> button, the search dialog closes and the +activity regains input focus. You can register to be notified when the search dialog is closed with {@link android.app.SearchManager#setOnDismissListener(SearchManager.OnDismissListener) setOnDismissListener()} @@ -569,7 +570,8 @@ things happens:</p> android.content.Intent#ACTION_SEARCH} intent with a call to {@link android.app.Activity#onCreate(Bundle) onCreate()} and a new instance of the activity is brought to the top of the activity stack. There are now two instances of your -searchable activity in the activity stack (so pressing the BACK button goes back to the previous +searchable activity in the activity stack (so pressing the <em>Back</em> button goes back to the +previous instance of the searchable activity, rather than exiting the searchable activity).</li> <li>If you set {@code android:launchMode} to <code>"singleTop"</code>, then the searchable activity receives the {@link android.content.Intent#ACTION_SEARCH} intent with a call diff --git a/docs/html/guide/topics/sensors/index.jd b/docs/html/guide/topics/sensors/index.jd index e00a5b1..43903dc 100644 --- a/docs/html/guide/topics/sensors/index.jd +++ b/docs/html/guide/topics/sensors/index.jd @@ -43,7 +43,7 @@ device's temperature sensor and humidity sensor to calculate and report the dewp application might use the geomagnetic field sensor and accelerometer to report a compass bearing.</p> -<p>The Android platform supports four broad categories of sensors:</p> +<p>The Android platform supports three broad categories of sensors:</p> <ul> <li>Motion sensors @@ -81,7 +81,7 @@ following documents:</p> Sensors</a></strong></dt> <dd>Learn how to use the sensors that provide orientation and compass data, such as the orientation sensor and the geomagnetic field sensor.</dd> - <dt><strong><a href="{@docRoot}guide/topics/sensors/environment.html">Environment + <dt><strong><a href="{@docRoot}guide/topics/sensors/sensors_environment.html">Environment Sensors</a></strong></dt> <dd>Learn how to use the sensors that provide environmental data, such as the light, humidity, pressure, temperature, and proximity sensors.</dd> diff --git a/docs/html/guide/topics/sensors/sensors_motion.jd b/docs/html/guide/topics/sensors/sensors_motion.jd index 3f712b2..b6c3cb4 100644 --- a/docs/html/guide/topics/sensors/sensors_motion.jd +++ b/docs/html/guide/topics/sensors/sensors_motion.jd @@ -28,7 +28,7 @@ parent.link=index.html href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html"> API Demos (OS - RotationVectorDemo)</a></li> <li><a -href="{@docRoot}/resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html" +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html" >API Demos (OS - Sensors)</a></li> </ol> <h2>See also</h2> diff --git a/docs/html/guide/topics/sensors/sensors_overview.jd b/docs/html/guide/topics/sensors/sensors_overview.jd index 3c5e94c..543872c 100644 --- a/docs/html/guide/topics/sensors/sensors_overview.jd +++ b/docs/html/guide/topics/sensors/sensors_overview.jd @@ -606,7 +606,7 @@ sensor is present on a device so your app can run successfully. You have two opt that a given sensor is present on a device:</p> <ul> <li>Detect sensors at runtime and enable or disable application features as appropriate.</li> - <li>Use Android Market filters to target devices with specific sensor configurations.</li> + <li>Use Google Play filters to target devices with specific sensor configurations.</li> </ul> <p>Each option is discussed in the following sections.</p> @@ -633,9 +633,9 @@ whether there's a pressure sensor on a device:</p> } </pre> -<h4>Using Android Market filters to target specific sensor configurations</h4> +<h4>Using Google Play filters to target specific sensor configurations</h4> -<p>If you are publishing your application on Android Market you can use the +<p>If you are publishing your application on Google Play you can use the <a href="{@docRoot}guide//topics/manifest/uses-feature-element.html"><code><uses-feature> </code></a> element in your manifest file to filter your application from devices that do not have the appropriate sensor configuration for your application. The @@ -650,7 +650,7 @@ following is an example manifest entry that filters apps that do not have an acc </pre> <p>If you add this element and descriptor to your application's manifest, users will see your -application on Android Market only if their device has an accelerometer.</p> +application on Google Play only if their device has an accelerometer.</p> <p>You should set the descriptor to <code>android:required="true"</code> only if your application relies entirely on a specific sensor. If your application uses a sensor for some functionality, but diff --git a/docs/html/guide/topics/testing/testing_android.jd b/docs/html/guide/topics/testing/testing_android.jd index c8a3f6e..adbc59d 100755 --- a/docs/html/guide/topics/testing/testing_android.jd +++ b/docs/html/guide/topics/testing/testing_android.jd @@ -318,7 +318,7 @@ parent.link=index.html A useful general test case class, especially if you are just starting out with Android testing, is {@link android.test.AndroidTestCase}. It extends both {@link junit.framework.TestCase} and {@link junit.framework.Assert}. It provides the - JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as well as + JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as all of JUnit's Assert methods. In addition, it provides methods for testing permissions, and a method that guards against memory leaks by clearing out certain class references. </p> @@ -401,7 +401,7 @@ parent.link=index.html Mock objects isolate tests from a running system by stubbing out or overriding normal operations. For example, a {@link android.test.mock.MockContentResolver} replaces the normal resolver framework with its own local framework, which is isolated - from the rest of the system. MockContentResolver also also stubs out the + from the rest of the system. MockContentResolver also stubs out the {@link android.content.ContentResolver#notifyChange(Uri, ContentObserver, boolean)} method so that observer objects outside the test environment are not accidentally triggered. </p> diff --git a/docs/html/guide/topics/ui/accessibility/apps.jd b/docs/html/guide/topics/ui/accessibility/apps.jd new file mode 100644 index 0000000..dc91638 --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/apps.jd @@ -0,0 +1,574 @@ +page.title=Making Applications Accessible +parent.title=Accessibility +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#label-ui">Labeling User Interface Elements</a></li> + <li><a href="#focus-nav">Enabling Focus Navigation</a> + <ol> + <li><a href="#focus-enable">Enabling view focus</a></li> + <li><a href="#focus-order">Controlling focus order</a></li> + </ol> + </li> + <li><a href="#custom-views">Building Accessible Custom Views</a> + <ol> + <li><a href="#directional-control">Handling directional controller clicks</a></li> + <li><a href="#accessibility-methods">Implementing accessibility API methods</a></li> + <li><a href="#send-events">Sending accessibility events</a></li> + <li><a href="#populate-events">Populating accessibility events</a></li> + </ol> + </li> + <li><a href="#test">Testing Accessibility</a> + <ol> + <li><a href="#test-audibles">Testing audible feedback</a></li> + <li><a href="#test-navigation">Testing focus navigation</a></li> + </ol> + </li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.view.accessibility.AccessibilityNodeInfo}</li> + <li>{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat}</li> + <li>{@link android.view.View.AccessibilityDelegate}</li> + <li>{@link android.support.v4.view.AccessibilityDelegateCompat}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + <li><a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a> + </li> + <li><a href="{@docRoot}design/index.html">Android Design</a></li> + </ol> + +</div> +</div> + +<p>Applications built for Android are accessible to users with visual, physical or age-related +disabilities when they activate accessibility features and services on a device. By default, +these services make your application more accessible. However, there are further steps you should +take to optimize the accessibility of your application and ensure a pleasant experience for all your +users.</p> + +<p>Making sure your application is accessible to all users is relatively easy, particularly when you +use framework-provided user interface components. If you only use these standard components for your +application, there are just a few steps required to ensure your application is accessible:</p> + +<ol> + <li>Label your {@link android.widget.ImageButton}, {@link android.widget.ImageView}, {@link +android.widget.EditText}, {@link android.widget.CheckBox} and other user interface controls using +the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> + {@code android:contentDescription}</a> attribute.</li> + <li>Make all of your user interface elements accessible with a directional controller, + such as a trackball or D-pad.</li> + <li>Test your application by turning on accessibility services like TalkBack and Explore by + Touch, and try using your application using only directional controls.</li> +</ol> + +<p>Developers who create custom controls that extend from the {@link android.view.View} class have +some additional responsibilities for making sure their components are accessible for users. This +document also discusses how to make custom view controls compatible with accessibility services.</p> + + +<h2 id="label-ui">Labeling User Interface Elements</h2> + +<p>Many user interface controls rely on visual cues to inform users of their meaning. For +example, a note-taking application might use an {@link android.widget.ImageButton} with a +picture of a plus sign to indicate that the user can add a new note. Or, an {@link +android.widget.EditText} component may have a label near it that indicates its purpose. When a user +with impaired vision accesses your application, these visual cues are often useless.</p> + +<p>To provide textual information about interface controls (as an alternative to the visual cues), +use the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> +{@code android:contentDescription}</a> attribute. The text you provide in this attribute is not +visible on the screen, but if a user has enabled accessibility services that provide audible +prompts, then the description in this attribute is read aloud to the user.</p> + +<p>Set the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> +{@code android:contentDescription}</a> attribute for every {@link android.widget.ImageButton}, +{@link android.widget.ImageView}, {@link android.widget.EditText}, {@link android.widget.CheckBox} +in your application's user interface, and on any other input controls that might require additional +information for users who are not able to see it.</p> + +<p>For example, the following {@link android.widget.ImageButton} sets the content description for +the plus button to the {@code add_note} string resource, which could be defined as “Add note" for an +English language interface:</p> + +<pre> +<ImageButton + android:id=”@+id/add_note_button” + android:src=”@drawable/add_note” + android:contentDescription=”@string/add_note”/> +</pre> + +<p>By including the description, speech-based accessibility services can announce "Add note" when a +user moves focus to this button or hovers over it.</p> + +<p class="note"><strong>Note:</strong> For {@link android.widget.EditText} fields, provide an +<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">android:hint</a> +attribute to help users understand what content is expected.</p> + +<h2 id="focus-nav">Enabling Focus Navigation</h2> + +<p>Focus navigation allows users with disabilities to step through user interface controls using a +directional controller. Directional controllers can be physical, such as a clickable trackball, +directional pad (D-pad) or arrow keys, tab key navigation with an attached keyboard or a software +application, such as the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a>, that provides an on-screen directional control.</p> + +<p>A directional controller is a primary means of navigation for many users. +Verify that all user interface (UI) controls in your application are accessible +without using the touchscreen and that clicking with the center button (or OK button) of a +directional controller has the same effect as touching the controls on the touchscreen. For +information on testing directional controls, see <a href="#test-navigation">Testing focus +navigation</a>.</p> + +<h3 id="focus-enable">Enabling view focus</h3> + +<p>A user interface element is accessible using directional controls when its +<a href="{@docRoot}reference/android/view/View.html#attr_android:focusable"> +{@code android:focusable}</a> attribute is set to {@code true}. This setting allows users to focus +on the element using the directional controls and then interact with it. The user interface controls +provided by the Android framework are focusable by default and visually indicate focus by changing +the control’s appearance.</p> + +<p>Android provides several APIs that let you control whether a user interface control is focusable +and even request that a control be given focus:</p> + +<ul> + <li>{@link android.view.View#setFocusable setFocusable()}</li> + <li>{@link android.view.View#isFocusable isFocusable()}</li> + <li>{@link android.view.View#requestFocus requestFocus()}</li> +</ul> + +<p>When working with a view that is not focusable by default, you can make it focusable from the XML +layout file by setting the +<a href="{@docRoot}reference/android/view/View.html#attr_android:focusable"> +{@code android:focusable}</a> attribute to {@code true} or by using the {@link +android.view.View#setFocusable setFocusable()} method.</p> + +<h3 id="focus-order">Controlling focus order</h3> + +<p>When users navigate in any direction using directional controls, focus is passed from one +user interface element (View) to another, as determined by the focus ordering. The ordering of the +focus movement is based on an algorithm that finds the nearest neighbor in a given direction. In +rare cases, the default algorithm may not match the order that you intended for your UI. In these +situations, you can provide explicit overrides to the ordering using the following XML attributes in +the layout file:</p> + +<dl> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" +>{@code android:nextFocusDown}</a></dt> + <dd>Defines the next view to receive focus when the user navigates down.</dd> + <a><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusLeft" +>{@code android:nextFocusLeft}</a></dt> + <dd>Defines the next view to receive focus when the user navigates left.</dd> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusRight" +>{@code android:nextFocusRight}</a></dt> + <dd>Defines the next view to receive focus when the user navigates right.</dd> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" +>{@code android:nextFocusUp}</a></dt> + <dd>Defines the next view to receive focus when the user navigates up.</dd> +</dl> + +<p>The following example XML layout shows two focusable user interface elements where the <a +href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" +>{@code android:nextFocusDown}</a> and <a +href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" +>{@code android:nextFocusUp}</a> attributes have been explicitly set. The {@link android.widget.TextView} is +located to the right of the {@link android.widget.EditText}. However, since these properties have +been set, the {@link android.widget.TextView} element can now be reached by pressing the down arrow +when focus is on the {@link android.widget.EditText} element: </p> + +<pre> +<LinearLayout android:orientation="horizontal" + ... > + <EditText android:id="@+id/edit" + android:nextFocusDown=”@+id/text” + ... /> + <TextView android:id="@+id/text" + android:focusable=”true” + android:text="Hello, I am a focusable TextView" + android:nextFocusUp=”@id/edit” + ... /> +</LinearLayout> +</pre> + +<p>When modifying focus order, be sure that the navigation works as expected in all directions from +each user interface control and when navigating in reverse (to get back to where you came from).</p> + +<p class="note"><strong>Note:</strong> You can modify the focus order of user interface components +at runtime, using methods such as {@link android.view.View#setNextFocusDownId setNextFocusDownId()} +and {@link android.view.View#setNextFocusRightId setNextFocusRightId()}.</p> + + +<h2 id="custom-views">Building Accessible Custom Views</h2> + +<p>If your application requires a <a href="{@docRoot}guide/topics/ui/custom-components.html">custom +view component</a>, you must do some additional work to ensure that your custom view is accessible. +These are the main tasks for ensuring the accessibility of your view:</p> + +<ul> + <li>Handle directional controller clicks</li> + <li>Implement Accessibility API methods</li> + <li>Send {@link android.view.accessibility.AccessibilityEvent} objects specific to your custom view</li> + <li>Populate {@link android.view.accessibility.AccessibilityEvent} and {@link + android.view.accessibility.AccessibilityNodeInfo} for your view</li> +</ul> + + +<h3 id="directional-control">Handling directional controller clicks</h3> + +<p>On most devices, clicking a view using a directional controller sends a {@link +android.view.KeyEvent} with {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} to the view currently +in focus. All standard Android views already handle {@link +android.view.KeyEvent#KEYCODE_DPAD_CENTER} appropriately. When building a custom {@link +android.view.View} control, make sure this event has the same effect as touching the view on the +touchscreen. </p> + +<p>Your custom control should also treat the {@link android.view.KeyEvent#KEYCODE_ENTER} event the +same as {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER}. This approach makes interaction from a +full keyboard much easier for users.</p> + + +<h3 id="accessibility-methods">Implementing accessibility API methods</h3> + +<p>Accessibility events are messages about users interaction with visual interface components in +your application. These messages are handled by <a href="services.html">Accessibility Services</a>, +which use the information in these events to produce supplemental feedback and prompts when users +have enabled accessibility services. As of Android 4.0 (API Level 14) and higher, the methods for +generating accessibility events have been expanded to provide more detailed information beyond the +{@link android.view.accessibility.AccessibilityEventSource} interface introduced in Android 1.6 (API +Level 4). The expanded accessibility methods are part of the {@link android.view.View} class as well +as the {@link android.view.View.AccessibilityDelegate} class. The methods are as follows:</p> + +<dl> + <dt>{@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()}</dt> + <dd>(API Level 4) This method is called when a user takes action on a view. The event is +classified with a user action type such as {@link +android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED TYPE_VIEW_CLICKED}. You typically do +not need to implement this method unless you are creating a custom view.</dd> + + <dt>{@link android.view.View#sendAccessibilityEventUnchecked +sendAccessibilityEventUnchecked()}</dt> + <dd>(API Level 4) This method is used when the calling code needs to directly control the check +for accessibility being enabled on the device ({@link +android.view.accessibility.AccessibilityManager#isEnabled AccessibilityManager.isEnabled()}). If +you do implement this method, you must assume that the calling method has already checked that +accessibility is enabled and the result is {@code true}. You typically do not need to implement this +method for a custom view.</dd> + + <dt>{@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()} </dt> + <dd>(API Level 4) The system calls this method when your custom view generates an +accessibility event. As of API Level 14, the default implementation of this method calls {@link +android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} for this view and +then the {@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()} method for each child of this view. In order to support +accessibility services on revisions of Android <em>prior</em> to 4.0 (API Level 14) you +<em>must</em> override this method and populate {@link +android.view.accessibility.AccessibilityEvent#getText} with descriptive text for your custom +view.</dd> + + <dt>{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()}</dt> + <dd>(API Level 14) This method sets the text output of an {@link +android.view.accessibility.AccessibilityEvent} for your view. This method is also called if the +view is a child of a view which generates an accessibility event. + + <p class="note"><strong>Note:</strong> Modifying additional attributes beyond the text within +this method potentially overwrites properties set by other methods. So, while you are able modify +attributes of the accessibility event with this method, you should limit these changes +to text content only and use the {@link android.view.View#onInitializeAccessibilityEvent +onInitializeAccessibilityEvent()} method to modify other properties of the event.</p> + + <p class="note"><strong>Note:</strong> If your implementation of this event calls for completely +overiding the output text without allowing other parts of your layout to modify its content, then +do not call the super implementation of this method in your code.</p> + </dd> + + <dt>{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}</dt> + <dd>(API Level 14) The system calls this method to obtain additional information about the +state of the view, beyond text content. If your custom view provides interactive control beyond a +simple {@link android.widget.TextView} or {@link android.widget.Button}, you should override this +method and set the additional information about your view into the event using this method, such as +password field type, checkbox type or states that provide user interaction or feedback. If you +do override this method, you must call its super implementation and then only modify properties +that have not been set by the super class.</dd> + + <dt>{@link android.view.View#onInitializeAccessibilityNodeInfo +onInitializeAccessibilityNodeInfo()}</dt> + <dd>(API Level 14) This method provides accessibility services with information about the state of +the view. The default {@link android.view.View} implementation sets a standard set of view +properties, but if your custom view provides interactive control beyond a simple {@link +android.widget.TextView} or {@link android.widget.Button}, you should override this method and set +the additional information about your view into the {@link +android.view.accessibility.AccessibilityNodeInfo} object handled by this method.</dd> + + <dt>{@link android.view.ViewGroup#onRequestSendAccessibilityEvent +onRequestSendAccessibilityEvent()}</dt> + <dd>(API Level 14) The system calls this method when a child of your view has generated an +{@link android.view.accessibility.AccessibilityEvent}. This step allows the the parent view to amend +the accessibility event with additional information. You should implement this method only if your +custom view can have child views and if the parent view can provide context information to the +accessibility event that would be useful to accessibility services.</dd> +</dl> + +<p>In order to support these accessibility methods for a custom view, you should take one of the +following approaches:</p> + +<ul> + <li>If your application targets Android 4.0 (API level 14) and higher, override and implement the +accessibility methods listed above directly in your custom view class.</li> + <li>If your custom view is intended to be compatible with Android 1.6 (API Level 4) and above, add +the Android <a href="{@docRoot}sdk/compatibility-library.html">Support Library</a>, revision 5 or +higher, to your project. Then, within your custom view class, call the +{@link android.support.v4.view.ViewCompat#setAccessibilityDelegate +ViewCompat.setAccessibilityDelegate()} method to implement the accessibility methods +above. For an example of this approach, see the Android Support Library (revision 5 or higher) +sample {@code AccessibilityDelegateSupportActivity} in +({@code <sdk>/extras/android/support/v4/samples/Support4Demos/}) + </li> +</ul> + +<p>In either case, you should implement the following accessibility methods for your custom view +class:</p> + +<ul> + <li>{@link android.view.View#dispatchPopulateAccessibilityEvent + dispatchPopulateAccessibilityEvent()}</li> + <li>{@link android.view.View#onPopulateAccessibilityEvent + onPopulateAccessibilityEvent()}</li> + <li>{@link android.view.View#onInitializeAccessibilityEvent + onInitializeAccessibilityEvent()}</li> + <li>{@link android.view.View#onInitializeAccessibilityNodeInfo + onInitializeAccessibilityNodeInfo()}</li> +</ul> + +<p>For more information about implementing these methods, see <a href="#populate-events">Populating +Accessibility Events</a>.</p> + + +<h3 id="send-events">Sending accessibility events</h3> + +<p>Depending on the specifics of your custom view, it may need to send {@link +android.view.accessibility.AccessibilityEvent} objects at a different times or for events not +handled by the default implementation. The {@link android.view.View} class provides a default +implementation for these event types:</p> + +<ul> + <li>Starting with API Level 4: + <ul> + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_FOCUSED}</li> + </ul> + </li> + <li>Starting with API Level 14: + <ul> + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_SCROLLED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}</li> + </ul> + </li> +</ul> + +<p class="note"><strong>Note:</strong> Hover events are associated with the Explore by +Touch feature, which uses these events as triggers for providing audible prompts for user interface +elements.</p> + +<p>In general, you should send an {@link android.view.accessibility.AccessibilityEvent} whenever the +content of your custom view changes. For example, if you are implementing a custom slider bar that +allows a user to select a numeric value by pressing the left or right arrows, your custom view +should emit an event of type {@link +android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} whenever the slider +value changes. The following sample code demonstrates the use of the {@link +android.view.accessibility.AccessibilityEventSource#sendAccessibilityEvent +sendAccessibilityEvent()} method to report this event.</p> + +<pre> +@Override +public boolean onKeyUp (int keyCode, KeyEvent event) { + if (keyCode == KeyEvent.KEYCODE_DPAD_LEFT) { + mCurrentValue--; + sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED); + return true; + } + ... +} +</pre> + + +<h3 id="populate-events">Populating accessibility events</h3> + +<p>Each {@link android.view.accessibility.AccessibilityEvent} has a set of required properties that +describe the current state of the view. These properties include things such as the view’s class +name, content description and checked state. The specific properties required for each event type +are described in the {@link android.view.accessibility.AccessibilityEvent} reference documentation. +The {@link android.view.View} implementation provides default values for these properties. Many of +these values, including the class name and event timestamp, are provided automatically. If you are +creating a custom view component, you must provide some information about the content and +characteristics of the view. This information may be as simple as a button label, but may also +include additional state information that you want to add to the event.</p> + +<p>The minimum requirement for providing information to accessibility services with a custom +view is to implement {@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()}. This method is called by the system to request +information for an {@link android.view.accessibility.AccessibilityEvent} and makes your custom +view compatible with accessibility services on Android 1.6 (API Level 4) and higher. The +following example code demonstrates a basic implementation of this method.</p> + +<pre> +@Override +public void dispatchPopulateAccessibilityEvent(AccessibilityEvent event) { + super.dispatchPopulateAccessibilityEvent(event); + // Call the super implementation to populate its text to the event, which + // calls onPopulateAccessibilityEvent() on API Level 14 and up. + + // In case this is running on a API revision earlier that 14, check + // the text content of the event and add an appropriate text + // description for this custom view: + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + event.getText().add(text); + } +} +</pre> + +<p>On Android 4.0 (API Level 14) and higher, the {@link +android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} and +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} +methods are the recommended way to populate or modify the information in an {@link +android.view.accessibility.AccessibilityEvent}. Use the +{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} method +specifically for adding or modifying the text content of the event, which is turned into audible +prompts by accessibility services such as TalkBack. Use the +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} method for +populating additional information about the event, such as the selection state of the view.</p> + +<p>In addition, you should also implement the +{@link android.view.View#onInitializeAccessibilityNodeInfo onInitializeAccessibilityNodeInfo()} +method. {@link android.view.accessibility.AccessibilityNodeInfo} objects populated by this method +are used by accessibility services to investigate the view hierarchy that generated an accessibility +event after receiving that event, to obtain a more detailed context information and provide +appropriate feedback to users.</p> + +<p>The example code below shows how override these three methods by using +{@link android.support.v4.view.ViewCompat#setAccessibilityDelegate +ViewCompat.setAccessibilityDelegate()}. Note that this sample code requires that the Android +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> for API Level 4 (revision 5 +or higher) is added to your project.</p> + +<pre> +ViewCompat.setAccessibilityDelegate(new AccessibilityDelegateCompat() { + @Override + public void onPopulateAccessibilityEvent(View host, AccessibilityEvent event) { + super.onPopulateAccessibilityEvent(host, event); + // We call the super implementation to populate its text for the + // event. Then we add our text not present in a super class. + // Very often you only need to add the text for the custom view. + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + event.getText().add(text); + } + } + @Override + public void onInitializeAccessibilityEvent(View host, AccessibilityEvent event) { + super.onInitializeAccessibilityEvent(host, event); + // We call the super implementation to let super classes + // set appropriate event properties. Then we add the new property + // (checked) which is not supported by a super class. + event.setChecked(isChecked()); + } + @Override + public void onInitializeAccessibilityNodeInfo(View host, + AccessibilityNodeInfoCompat info) { + super.onInitializeAccessibilityNodeInfo(host, info); + // We call the super implementation to let super classes set + // appropriate info properties. Then we add our properties + // (checkable and checked) which are not supported by a super class. + info.setCheckable(true); + info.setChecked(isChecked()); + // Quite often you only need to add the text for the custom view. + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + info.setText(text); + } + } +} +</pre> + +<p>On applications targeting Android 4.0 (API Level 14) and higher, these methods can be implemented +directly in your custom view class. For another example of this approach, see the Android +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> (revision 5 or higher) sample +{@code AccessibilityDelegateSupportActivity} in +({@code <sdk>/extras/android/support/v4/samples/Support4Demos/}).</p> + +<p class="note"><strong>Note:</strong> You may find information on implementing accessibility for +custom views written prior to Android 4.0 that describes the use of the +{@link android.view.View#dispatchPopulateAccessibilityEvent dispatchPopulateAccessibilityEvent()} +method for populating AccessibilityEvents. As of the Android 4.0 release, however, the recommended +approach is to use the +{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} and +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} +methods.</p> + + +<h2 id="test">Testing Accessibility</h2> + +<p>Testing the accessibility of your application is an important part of ensuring your users have a +great experience. You can test the most important parts of accessibility by testing your application +with audible feedback enabled and testing navigation within your application using directional +controls.</p> + +<h3 id="test-audibles">Testing audible feedback</h3> +<p>You can simulate the experience for many users by enabling an accessibility service that speaks +as you move around the screen. The Explore by Touch accessibility service, which is available on +devices with Android 4.0 and later. The <a +href="https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback">TalkBack</a> +accessibility service, by the <a href="http://code.google.com/p/eyes-free/">Eyes-Free +Project</a> comes preinstalled on many Android devices.</p> + +<p>To enable TalkBack on revisions of Android prior to Android 4.0:</p> +<ol> + <li>Launch the Settings application.</li> + <li>Navigate to the <strong>Accessibility</strong> category and select it.</li> + <li>Select <strong>Accessibility</strong> to enable it.</li> + <li>Select <strong>TalkBack</strong> to enable it.</li> +</ol> + +<p class="note"><strong>Note:</strong> If the TalkBack accessibility service is not available, you +can install it for free from <a href="http://play.google.com">Google Play</a>.</p> + +<p>To enable Explore by Touch on Android 4.0 and later:</p> +<ol> + <li>Launch the Settings application.</li> + <li>Navigate to the <strong>Accessibility</strong> category and select it.</li> + <li>Select the <strong>TalkBack</strong> to enable it.</li> + <li>Return to the <strong>Accessibility</strong> category and select <strong>Explore by +Touch</strong> to enable it. + <p class="note"><strong>Note:</strong> You must turn on TalkBack <em>first</em>, otherwise this +option is not available.</p> + </li> +</ol> + +<h3 id="test-navigation">Testing focus navigation</h3> + +<p>As part of your accessibility testing, you can test navigation of your application using focus, +even if your test devices does not have a directional controller. The <a +href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> provides a +simulated directional controller that you can easily use to test navigation. You can also use a +software-based directional controller, such as the one provided by the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a> to simulate use of a D-pad.</p> diff --git a/docs/html/guide/topics/ui/accessibility/index.jd b/docs/html/guide/topics/ui/accessibility/index.jd new file mode 100644 index 0000000..414d5f3 --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/index.jd @@ -0,0 +1,55 @@ +page.title=Accessibility +parent.title=User Interface +parent.link=../index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Topics</h2> + <ol> + <li><a href="{@docRoot}guide/topics/ui/accessibility/apps.html">Making Applications Accessible</a> + </li> + <li><a href="{@docRoot}guide/topics/ui/accessibility/services.html">Building Accessibility + Services</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.accessibilityservice.AccessibilityService}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + </ol> + +</div> +</div> + +<p>Many Android users have disabilities that require them to interact with their Android devices in +different ways. These include users who have visual, physical or age-related disabilities that +prevent them from fully seeing or using a touchscreen.</p> + +<p>Android provides accessibility features and services for helping these users navigate their +devices more easily, including text-to-speech, haptic feedback, trackball and D-pad navigation that +augment their experience. Android application developers can take advantage of these services to +make their applications more accessible and also build their own accessibility services.</p> + +<p>The following topics show you how to use the Android framework to make applications more +accessible.</p> + +<dl> + <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/apps.html">Making Applications +Accessible</a></strong> + </dt> + <dd>Development practices and API features to ensure your application is accessible to users with +disabilities.</dd> + + <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/service.html">Building Accessibility +Services</a></strong> + </dt> + <dd>How to use API features to build services that make other applications more accessible for +users.</dd> +</dl>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/accessibility/services.jd b/docs/html/guide/topics/ui/accessibility/services.jd new file mode 100644 index 0000000..0dad4ec --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/services.jd @@ -0,0 +1,290 @@ +page.title=Building Accessibility Services +parent.title=Accessibility +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Topics</h2> + <ol> + <li><a href="#manifest">Manifest Declarations and Permissions</a> + <ol> + <li><a href="service-declaration">Accessibility service declaration</a></li> + <li><a href="#service-config">Accessibility service configuration</a></li> + </ol> + </li> + <li><a href="#methods">AccessibilityService Methods</a></li> + <li><a href="#event-details">Getting Event Details</a></li> + <li><a href="#examples">Example Code</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.accessibilityservice.AccessibilityService}</li> + <li>{@link android.accessibilityservice.AccessibilityServiceInfo}</li> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.view.accessibility.AccessibilityRecord}</li> + <li>{@link android.view.accessibility.AccessibilityNodeInfo}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + </ol> + +</div> +</div> + +<p>An accessibility service is an application that provides user interface enhancements to +assist users with disabilities, or who may temporarily be unable to fully interact with a device. +For example, users who are driving, taking care of a young child or attending a very loud party +might need additional or alternative interface feedback.</p> + +<p>Android provides standard accessibility services, including TalkBack, and developers can +create and distribute their own services. This document explains the basics of building an +accessibility service.</p> + +<p>The ability for you to build and deploy accessibility services was introduced with Android +1.6 (API Level 4) and received significant improvements with Android 4.0 (API Level 14). The Android +Support Library was also updated with the release of Android 4.0 to provide support for these +enhanced accessibility features back to Android 1.6. Developers aiming for widely compatible +accessibility services are encouraged to use the +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> and develop for the more +advanced accessibility features introduced in Android 4.0.</p> + + +<h2 id="manifest">Manifest Declarations and Permissions</h2> + +<p>Applications that provide accessibility services must include specific declarations in their + application manifests in order to be treated as an accessibility service by an Android system. + This section explains the required and optional settings for accessibility services.</p> + + +<h3 id="service-declaration">Accessibility service declaration</h3> + +<p>In order to be treated as an accessibility service, your application must include the +{@code service} element (rather than the {@code activity} element) within the {@code application} +element in its manifest. In addition, within the {@code service} element, you must also include an +accessibility service intent filter, as shown in the following sample:</p> + +<pre> +<application> + <service android:name=".MyAccessibilityService" + android:label="@string/accessibility_service_label"> + <intent-filter> + <action android:name="android.accessibilityservice.AccessibilityService" /> + </intent-filter> + </service> +</application> +</pre> + +<p>These declarations are required for all accessibility services deployed on Android 1.6 (API Level + 4) or higher.</p> + + +<h3 id="service-config">Accessibility service configuration</h3> + +<p>Accessibility services must also provide a configuration which specifies the types of +accessibility events that the service handles and additional information about the service. The +configuration of an accessibility service is contained in the {@link +android.accessibilityservice.AccessibilityServiceInfo} class. Your service can build and set a +configuration using an instance of this class and {@link +android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()} at runtime. +However, not all configuration options are available using this method.</p> + +<p>Beginning with Android 4.0, you can include a {@code <meta-data>} element in your manifest +with a reference to a configuration file, which allows you to set the full range of options for +your accessibility service, as shown in the following example:</p> + +<pre> +<service android:name=".MyAccessibilityService"> + ... + <meta-data + android:name="android.accessibilityservice" + android:resource="@xml/accessibility_service_config" /> +</service> +</pre> + +<p>This meta-data element refers to an XML file that you create in your application’s resource +directory ({@code <project_dir>/res/xml/accessibility_service_config.xml}). The following code +shows example contents for the service configuration file:</p> + +<pre> +<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android" + android:description="@string/accessibility_service_description" + android:packageNames="com.example.android.apis" + android:accessibilityEventTypes="typeAllMask" + android:accessibilityFlags="flagDefault" + android:accessibilityFeedbackType="feedbackSpoken" + android:notificationTimeout="100" + android:canRetrieveWindowContent="true" + android:settingsActivity="com.example.android.accessibility.ServiceSettingsActivity" +/> +</pre> + +<p>One of the most important functions of the accessibility service configuration parameters is to +allow you to specify what types of accessibility events your service can handle. Being able to +specify this information enables accessibility services to cooperate with each other, and allows you +as a developer the flexibility to handle only specific events types from specific applications. The +event filtering can include the following criteria:</p> + +<ul> + <li><strong>Package Names</strong> - Specify the package names of applications whose accessibility +events you want your service to handle. If this parameter is omitted, your accessibility service is +considered available to service accessibility events for any application. This parameter can be set +in the accessibility service configuration files with the {@code android:packageNames} attribute as +a comma-separated list, or set using the {@link +android.accessibilityservice.AccessibilityServiceInfo#packageNames +AccessibilityServiceInfo.packageNames} member.</li> + <li><strong>Event Types</strong> - Specify the types of accessibility events you want your service +to handle. This parameter can be set in the accessibility service configuration files with the +{@code android:accessibilityEventTypes} attribute as a comma-separated list, or set using the +{@link android.accessibilityservice.AccessibilityServiceInfo#eventTypes +AccessibilityServiceInfo.eventTypes} member. </li> +</ul> + +<p>For more information about the XML attributes which can be used in the accessibility service + configuration file, follow these links to the reference documentation:</p> + +<ul> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_description">{@code android:description}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_packageNames">{@code android:packageNames}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityEventTypes">{@code android:accessibilityEventTypes}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFlags">{@code android:accessibilityFlags}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFeedbackType">{@code android:accessibilityFeedbackType}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_notificationTimeout">{@code android:notificationTimeout}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_canRetrieveWindowContent">{@code android:canRetrieveWindowContent}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_settingsActivity">{@code android:settingsActivity}</a></li> +</ul> + +<p>For more information about which configuration settings can be dynamically set at runtime, see +the {@link android.accessibilityservice.AccessibilityServiceInfo} reference documentation.</p> + + +<h2 id="methods">AccessibilityService Methods</h2> + +<p>An application that provides accessibility service must extend the {@link +android.accessibilityservice.AccessibilityService} class and override the following methods from +that class. These methods are presented in the order in which they are called by the Android system, +from when the service is started +({@link android.accessibilityservice.AccessibilityService#onServiceConnected onServiceConnected()}), +while it is running ({@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()}, +{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()}) to when it is +shut down ({@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()}).</p> + +<ul> + <li>{@link android.accessibilityservice.AccessibilityService#onServiceConnected +onServiceConnected()} - (optional) This system calls this method when it successfully connects to +your accessibility service. Use this method to do any one-time setup steps for your service, +including connecting to user feedback system services, such as the audio manager or device vibrator. +If you want to set the configuration of your service at runtime or make one-time adjustments, this +is a convenient location from which to call {@link +android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()}.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()} - (required) This method is called back by the system when it detects an +{@link android.view.accessibility.AccessibilityEvent} that matches the event filtering parameters +specified by your accessibility service. For example, when the user clicks a button or focuses on a +user interface control in an application for which your accessibility service is providing feedback. +When this happens, the system calls this method of your service with the associated {@link +android.view.accessibility.AccessibilityEvent}, which you can then interpret and provide feedback to +the user. This method may be called many times over the lifecycle of your service.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()} - +(required) This method is called when the system wants to interrupt the feedback your service is +providing, usually in response to a user taking action, such as moving focus to a different user +interface control than the one for which you are currently providing feedback. This method may be +called many times over the lifecycle of your service.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()} - (optional) +This method is called when the system is about to shutdown the accessibility service. Use this +method to do any one-time shutdown procedures, including de-allocating user feedback system +services, such as the audio manager or device vibrator.</li> +</ul> + +<p>These callback methods provide the basic structure for your accessibility service. It is up to +you to decide on how to process data provided by the Android system in the form of {@link +android.view.accessibility.AccessibilityEvent} objects and provide feedback to the user.</p> + + +<h2 id="event-details">Getting Event Details</h2> + +<p>The Android system provides information to accessibility services about the user interface +interaction through {@link android.view.accessibility.AccessibilityEvent} objects. Prior to Android +4.0, the information available in an accessibility event, while providing a significant amount of +detail about a user interface control selected by the user, typically provided limited contextual +information. In many cases, this missing context information might be critical to understanding the +meaning of the selected control.</p> + +<p>A typical example of an interface where context is of critical importance is a calendar or day +planner. If a user selects a 4:00 PM time slot in a Monday to Friday day list and the accessibility +service announces “4 PM”, but fails to indicate this is a Friday a Monday, the month or day, this is +hardly ideal feedback for the user. In this case, the context of a user interface control is of +critical importance to a user who wants to schedule a meeting.</p> + +<p>Android 4.0 significantly extends the amount of information that an accessibility service can +obtain about an user interface interaction by composing accessibility events based on the view +hierarchy. A view hierarchy is the set of user interface components that contain the component (its +parents) and the user interface elements that may be contained by that component (its children). In +this way, the Android system can provide much richer detail about accessibility events, allowing +accessibility services to provide more useful feedback to users.</p> + +<p>An accessibility service gets information about an user interface event through an {@link +android.view.accessibility.AccessibilityEvent} passed by the system to the service’s +{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()} callback method. This object provides details about the event, including the +type of object being acted upon, its descriptive text and other details. Starting in Android 4.0 +(and supported in previous releases through the {@link +android.support.v4.view.accessibility.AccessibilityEventCompat} object in the Support Library), you +can obtain additional information about the event using these calls:</p> + +<ul> + <li>{@link android.view.accessibility.AccessibilityEvent#getRecordCount +AccessibilityEvent.getRecordCount()} and {@link +android.view.accessibility.AccessibilityEvent#getRecord getRecord(int)} - These methods allow you to +retrieve the set of {@link android.view.accessibility.AccessibilityRecord} objects which contributed +to the {@link android.view.accessibility.AccessibilityEvent} passed to you by the system, which can +provide more context for your accessibility service.</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#getSource +AccessibilityEvent.getSource()} - This method returns an {@link +android.view.accessibility.AccessibilityNodeInfo} object. This object allows you to request the +parents and children of the component that originated the accessibility event and investigate their +contents and state in order to provide + + <p class="caution"><strong>Important:</strong> The ability to investigate the full view +hierarchy from an {@link android.view.accessibility.AccessibilityEvent} potentially exposes private +user information to your accessibility service. For this reason, your service must request this +level of access through the accessibility <a href="#service-config">service configuration XML</a> +file, by including the {@code canRetrieveWindowContent} attribute and setting it to {@code true}. If +you do not include this setting in your service configuration xml file, calls to {@link +android.view.accessibility.AccessibilityEvent#getSource getSource()} fail.</p> + </li> +</ul> + + +<h2 id="examples">Example Code</h2> + +<p>The API Demo project contains two samples which can be used as a starting point for generating +accessibility services +({@code <sdk>/samples/<platform>/ApiDemos/src/com/example/android/apis/accessibility}): +</p> + +<ul> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/ClockBackService.html">ClockBackService</a> + - This service is based on the original implementation of {@link +android.accessibilityservice.AccessibilityService} and can be used as a base for developing basic +accessibility services that are compatible with Android 1.6 (API Level 4) and higher.</li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/TaskBackService.html">TaskBackService</a> + - This service is based on the enhanced accessibility APIs introduced in Android 4.0 (API Level +14). However, you can use the Android <a href="{@docRoot}sdk/compatibility-library.html">Support +Libary</a> to substitute classes introduced in later API levels (e.g., +{@link android.view.accessibility.AccessibilityRecord}, +{@link android.view.accessibility.AccessibilityNodeInfo} +) with equivalent support package classes (e.g., +{@link android.support.v4.view.accessibility.AccessibilityRecordCompat}, +{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} +) to make this example work with API versions back to Android 1.6 (API Level 4).</li> +</ul> diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index 3c0ef26..bf7369a 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -73,8 +73,10 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/inde API Demos</a></li> </ol> - <h2>See also</h2>item + <h2>See also</h2> <ol> + <li><a +href="{@docRoot}design/patterns/actionbar.html">Android Design: Action Bar</a></li> <li><a href="{@docRoot}guide/topics/ui/menus.html">Menus</a></li> <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and Handsets</a></li> @@ -111,9 +113,10 @@ accessible to the user in a predictable way. href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> directly in the action bar, as "action items." Action items can also provide an "action view," which provides an embedded widget for even more immediate action behaviors. Menu items that are not promoted -to an action item are available in the overflow menu, revealed by either the device MENU button +to an action item are available in the overflow menu, revealed by either the device <em>Menu</em> +button (when available) or by an "overflow menu" button in the action bar (when the device does not -include a MENU button).</p> +include a <em>Menu</em> button).</p> </li> </ul> @@ -123,6 +126,18 @@ href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery landscape handset), showing the logo on the left, navigation tabs, and an action item on the right (plus the overflow menu button).</p> +<p class="note"><strong>Note:</strong> If you're looking for information about the contextual +action bar for displaying contextual action items, see the <a +href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menu</a> guide.</p> + + +<div class="design-announce"> +<p><strong>Action Bar Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> guide.</p> +</div> + + <div class="sidebox-wrapper"> <div class="sidebox"> @@ -215,9 +230,10 @@ later—calling {@link android.app.Activity#getActionBar()} will return null href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a>. To do this, you can declare that the menu item should appear in the action bar as an "action item." An action item can include an icon and/or a text title. If a menu item does not appear as an action item, then the -system places it in the overflow menu. The overflow menu is revealed either by the device MENU +system places it in the overflow menu. The overflow menu is revealed either by the device +<em>Menu</em> button (if provided by the device) or an additional button in the action bar (if the device does not -provide the MENU button).</p> +provide the <em>Menu</em> button).</p> <div class="figure" style="width:359px"> <img src="{@docRoot}images/ui/actionbar-item-withtext.png" height="57" alt="" /> @@ -333,7 +349,7 @@ of the following:</p> <li><strong>Frequently used</strong>: It's an action that your users need seven out of ten visits or they use it several times in a row. <p>Example frequent actions: "New message" in the Messaging app and -"Search" in Android Market.</p> +"Search" on Google Play.</p> </li> <li><strong>Important</strong>: It's an action that you need users to easily discover or, if it's @@ -536,6 +552,12 @@ the email application, but presses the action bar icon to navigate up, rather th <p class="img-caption"><strong>Figure 6.</strong> Example behavior for UP navigation after entering the Email app from the People app.</p> +<div class="design-announce"> +<p><strong>Navigation Design</strong></p> + <p>For more about how <em>Up</em> and <em>Back</em> navigation differ, read Android Design's <a +href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> +</div> + <p>To enable the icon for up navigation (which displays the "up" indicator next to the icon), call {@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled(true)} on your {@link android.app.ActionBar}:</p> @@ -642,7 +664,7 @@ work as designed otherwise.</p> <p>Adding this value requires that you set your build target to Android 4.0 or higher in order to compile. Older versions of Android ignore the {@code "collapseActionView"} value because they don't understand it. Just be sure not to use other APIs in your source code that are not supported in the -version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-elementl.html#min">{@code +version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>, unless you add the appropriate version check at runtime.</p> </div> </div> @@ -843,8 +865,8 @@ you <em>do not</em> need to handle click events from the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.</p> <p>For a sample using the share action provider, see -<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarActionProviderActivity.html" ->ActionBarActionProviderActivity</a>. +<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarShareActionProviderActivity.html" +>ActionBarShareActionProviderActivity</a>. @@ -1405,7 +1427,7 @@ href="#ActionView">action views</a>. (Added in API level 14.)</dd> </style> <!-- style for the action bar tab text --> - <style name="CustomTabTextStyle"> + <style name="CustomTabTextStyle" parent="@android:style/TextAppearance.Holo"> <item name="android:textColor">#2456c2</item> </style> </resources> @@ -1421,8 +1443,7 @@ action bar styles you want to change without re-implementing the styles you want manifest file like this:</p> <pre> -<application android:theme="@style/CustomActivityTheme" - ... /> +<application android:theme="@style/CustomActivityTheme" ... /> </pre> <p>For more information about using style and theme resources in your application, read <a @@ -1441,7 +1462,7 @@ android:backgroundStacked}. If you override these action bar styles, be sure tha parent action bar style such as {@link android.R.style#Widget_Holo_ActionBar Widget.Holo.ActionBar}.</p> -<p>For example, if you want to change the action bar's background, you could use the following +<p>For example, if you want to change the action bar's background, you can use the following styles:</p> <pre> @@ -1449,14 +1470,15 @@ styles:</p> <resources> <!-- the theme applied to the application or activity --> <style name="CustomActivityTheme" parent="@android:style/Theme.Holo"> - <item name="android:actionBarTabTextStyle">@style/customTabTextStyle</item> + <item name="android:actionBarStyle">@style/MyActionBar</item> <!-- other activity and action bar styles here --> </style> - <!-- style for the action bar, simply to change the background --> - <style parent="@android:style/Widget.Holo.ActionBar"> + <!-- style for the action bar backgrounds --> + <style name="MyActionBar" parent="@android:style/Widget.Holo.ActionBar"> <item name="android:background">@drawable/ab_background</item> - <item name="android:backgroundSplit">@drawable/ab_background</item> + <item name="android:backgroundStacked">@drawable/ab_background</item> + <item name="android:backgroundSplit">@drawable/ab_split_background</item> </style> </resources> </pre> diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd index 4dc915f..8af4a1c 100644 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -194,7 +194,7 @@ contains property types that define the size and position for each child view, a appropriate for the view group. As you can see in figure 1, the parent view group defines layout parameters for each child view (including the child view group).</p> -<img src="{@docRoot}images/layoutparams.png" alt="" height="300" align="center"/> +<img src="{@docRoot}images/layoutparams.png" alt="" /> <p class="img-caption"><strong>Figure 1.</strong> Visualization of a view hierarchy with layout parameters associated with each view.</p> diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index 16f14cb..82cbfd1 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -37,6 +37,11 @@ DatePicker</a></li> <li><a href="{@docRoot}resources/tutorials/views/hello-timepicker.html">Hello TimePicker</a></li> </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}design/building-blocks/dialogs.html">Android Design: Dialogs</a></li> + </ol> </div> </div> @@ -70,6 +75,13 @@ of the following subclasses:</p> base {@link android.app.Dialog} object or any of the subclasses listed above and define a new layout. See the section on <a href="#CustomDialog">Creating a Custom Dialog</a> below.</p> +<div class="design-announce"> +<p><strong>Dialog Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/building-blocks/dialogs.html">Dialogs</a> guide.</p> +</div> + + <h2 id="ShowingADialog">Showing a Dialog</h2> diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd index d3060c5..45c9ac9 100644 --- a/docs/html/guide/topics/ui/index.jd +++ b/docs/html/guide/topics/ui/index.jd @@ -51,7 +51,7 @@ as shown in the diagram below. This hierarchy tree can be as simple or complex a can build it up using Android's set of predefined widgets and layouts, or with custom Views that you create yourself.</p> -<img src="{@docRoot}images/viewgroup.png" alt="" width="312" height="211" align="center"/> +<img src="{@docRoot}images/viewgroup.png" alt="" /> <p> In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the @@ -174,7 +174,8 @@ href="ui-events.html">Input Events</a> document.</p> <p>Application menus are another important part of an application's UI. Menus offers a reliable interface that reveals application functions and settings. The most common application menu is revealed by pressing -the MENU key on the device. However, you can also add Context Menus, which may be revealed when the user presses +the <em>Menu</em> button on the device. However, you can also add Context Menus, which may be +revealed when the user presses and holds down on an item.</p> <p>Menus are also structured using a View hierarchy, but you don't define this structure yourself. Instead, diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd index 8b2792d..e251fe9 100644 --- a/docs/html/guide/topics/ui/layout-objects.jd +++ b/docs/html/guide/topics/ui/layout-objects.jd @@ -163,7 +163,7 @@ refer to the ID using the syntax of a relative resource <td> <pre> <?xml version="1.0" encoding="utf-8"?> -<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="wrap_content" android:background="@drawable/blue" diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd index 7b5b3dc..d51a378 100644 --- a/docs/html/guide/topics/ui/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -6,77 +6,129 @@ parent.link=index.html <div id="qv-wrapper"> <div id="qv"> <h2>In this document</h2> - <ol> - <li><a href="#xml">Creating a Menu Resource</a></li> - <li><a href="#Inflating">Inflating a Menu Resource</a> - <li><a href="#options-menu">Creating an Options Menu</a> - <ol> - <li><a href="#ChangingTheMenu">Changing menu items at runtime</a></li> - </ol> - </li> - <li><a href="#context-menu">Creating a Context Menu</a></li> - <li><a href="#submenu">Creating a Submenu</a></li> - <li><a href="#features">Other Menu Features</a> - <ol> - <li><a href="#groups">Menu groups</a></li> - <li><a href="#checkable">Checkable menu items</a></li> - <li><a href="#shortcuts">Shortcut keys</a></li> - <li><a href="#intents">Dynamically adding menu intents</a></li> - </ol> - </li> - </ol> +<ol> + <li><a href="#xml">Defining a Menu in XML</a></li> + <li><a href="#options-menu">Creating an Options Menu</a> + <ol> + <li><a href="#RespondingOptionsMenu">Handling click events</a></li> + <li><a href="#ChangingTheMenu">Changing menu items at runtime</a></li> + </ol> + </li> + <li><a href="#context-menu">Creating Contextual Menus</a> + <ol> + <li><a href="#FloatingContextMenu">Creating a floating context menu</a></li> + <li><a href="#CAB">Using the contextual action mode</a></li> + </ol> + </li> + <li><a href="#PopupMenu">Creating a Popup Menu</a> + <ol> + <li><a href="#PopupEvents">Handling click events</a></li> + </ol> + </li> + <li><a href="#groups">Creating Menu Groups</a> + <ol> + <li><a href="#checkable">Using checkable menu items</a></li> + </ol> + </li> + <li><a href="#intents">Adding Menu Items Based on an Intent</a> + <ol> + <li><a href="#AllowingToAdd">Allowing your activity to be added to other menus</a></li> + </ol> + </li> +</ol> <h2>Key classes</h2> <ol> <li>{@link android.view.Menu}</li> <li>{@link android.view.MenuItem}</li> <li>{@link android.view.ContextMenu}</li> - <li>{@link android.view.SubMenu}</li> + <li>{@link android.view.ActionMode}</li> </ol> <h2>See also</h2> <ol> <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li> <li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a></li> + <li><a +href="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html">Say +Goodbye to the Menu Button</a></li> </ol> </div> </div> -<p>Menus are an important part of an activity's user interface, which provide users a familiar -way to perform actions. Android offers a simple framework for you to add standard -menus to your application.</p> +<p>Menus are a common user interface component in many types of applications. To provide a familiar +and consistent user experience, you should use the {@link android.view.Menu} APIs to present user +actions and other options in your activities.</p> + +<p>Beginning with Android 3.0 (API level 11), Android-powered devices are no longer required to +provide a dedicated <em>Menu</em> button. With this change, Android apps should migrate away from a +dependence on the traditional 6-item menu panel and instead provide an action bar to present common +user actions.</p> + +<p>Although the design and user experience for some menu items have changed, the semantics to define +a set of actions and options is still based on the {@link android.view.Menu} APIs. This +guide shows how to create the three fundamental types of menus or action presentations on all +versions of Android:</p> -<p>There are three types of application menus:</p> <dl> - <dt><strong>Options Menu</strong></dt> - <dd>The primary collection of menu items for an activity, which appears when the user touches -the MENU button. When your application is running on Android 3.0 or later, you can provide -quick access to select menu items by placing them directly in the <a -href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, as "action items."</dd> - <dt><strong>Context Menu</strong></dt> - <dd>A floating list of menu items that appears when the user touches and holds a view -that's registered to provide a context menu. + <dt><strong>Options menu and action bar</strong></dt> + <dd>The <a href="#options-menu">options menu</a> is the primary collection of menu items for an +activity. It's where you should place actions that have a global impact on the app, such as +"Search," "Compose email," and "Settings." + <p>If you're developing for Android 2.3 or lower, users can +reveal the options menu panel by pressing the <em>Menu</em> button.</p> + <p>On Android 3.0 and higher, items from the options menu are presented by the <a +href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a> as a combination of on-screen action +items and overflow options. Beginning with Android 3.0, the <em>Menu</em> button is deprecated (some +devices +don't have one), so you should migrate toward using the action bar to provide access to actions and +other options.</p> + <p>See the section about <a href="#options-menu">Creating an Options Menu</a>.</p> + </dd> + + <dt><strong>Context menu and contextual action mode</strong></dt> + + <dd>A context menu is a <a href="#FloatingContextMenu">floating menu</a> that appears when the +user performs a long-click on an element. It provides actions that affect the selected content or +context frame. + <p>When developing for Android 3.0 and higher, you should instead use the <a +href="#CAB">contextual action mode</a> to enable actions on selected content. This mode displays +action items that affect the selected content in a bar at the top of the screen and allows the user +to select multiple items.</p> + <p>See the section about <a href="#context-menu">Creating Contextual Menus</a>.</p> +</dd> + + <dt><strong>Popup menu</strong></dt> + <dd>A popup menu displays a list of items in a vertical list that's anchored to the view that +invoked the menu. It's good for providing an overflow of actions that relate to specific content or +to provide options for a second part of a command. Actions in a popup menu should +<strong>not</strong> directly affect the corresponding content—that's what contextual actions +are for. Rather, the popup menu is for extended actions that relate to regions of content in your +activity. + <p>See the section about <a href="#PopupMenu">Creating a Popup Menu</a>.</p> </dd> - <dt><strong>Submenu</strong></dt> - <dd>A floating list of menu items that appears when the user touches a menu item that contains -a nested menu.</dd> </dl> -<p>This document shows you how to create each type of menu, using XML to define the content of -the menu and callback methods in your activity to respond when the user selects an item.</p> +<h2 id="xml">Defining a Menu in XML</h2> -<h2 id="xml">Creating a Menu Resource</h2> +<p>For all menu types, Android provides a standard XML format to define menu items. +Instead of building a menu in your activity's code, you should define a menu and all its items in an +XML <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. You can then +inflate the menu resource (load it as a {@link android.view.Menu} object) in your activity or +fragment.</p> -<p>Instead of instantiating a {@link android.view.Menu} in your application code, you should -define a menu and all its items in an XML <a -href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, then inflate the menu -resource (load it as a programmable object) in your application code. Using a menu resource to -define your menu is a good practice because it separates the content for the menu from your -application code. It's also easier to visualize the structure and content of a menu in XML.</p> +<p>Using a menu resource is a good practice for a few reasons:</p> +<ul> + <li>It's easier to visualize the menu structure in XML.</li> + <li>It separates the content for the menu from your application's behavioral code.</li> + <li>It allows you to create alternative menu configurations for different platform versions, +screen sizes, and other configurations by leveraging the <a +href="{@docRoot}guide/topics/resources/index.html">app resources</a> framework.</li> +</ul> -<p>To create a menu resource, create an XML file inside your project's <code>res/menu/</code> +<p>To define the menu, create an XML file inside your project's <code>res/menu/</code> directory and build the menu with the following elements:</p> <dl> <dt><code><menu></code></dt> @@ -90,8 +142,8 @@ element may contain a nested <code><menu></code> element in order to create a <dt><code><group></code></dt> <dd>An optional, invisible container for {@code <item>} elements. It allows you to -categorize menu items so they share properties such as active state and visibility. See the -section about <a href="#groups">Menu groups</a>.</dd> +categorize menu items so they share properties such as active state and visibility. For more +information, see the section about <a href="#groups">Creating Menu Groups</a>.</dd> </dl> @@ -101,14 +153,17 @@ section about <a href="#groups">Menu groups</a>.</dd> <menu xmlns:android="http://schemas.android.com/apk/res/android"> <item android:id="@+id/new_game" android:icon="@drawable/ic_new_game" - android:title="@string/new_game" /> + android:title="@string/new_game" + android:showAsAction="ifRoom"/> <item android:id="@+id/help" android:icon="@drawable/ic_help" android:title="@string/help" /> </menu> </pre> -<p>This example defines a menu with two items. Each item includes the attributes:</p> +<p>The <code><item></code> element supports several attributes you can use to define an item's +appearance and behavior. The items in the above menu include the following attributes:</p> + <dl> <dt>{@code android:id}</dt> <dd>A resource ID that's unique to the item, which allows the application can recognize the item @@ -117,158 +172,175 @@ when the user selects it.</dd> <dd>A reference to a drawable to use as the item's icon.</dd> <dt>{@code android:title}</dt> <dd>A reference to a string to use as the item's title.</dd> + <dt>{@code android:showAsAction}</dt> + <dd>Specifies when and how this item should appear as an action item in the <a +href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>.</dd> </dl> -<p>There are many more attributes you can include in an {@code <item>}, including some that - specify how the item may appear in the <a -href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>. For more information about the XML -syntax and attributes for a menu resource, see the <a -href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> reference.</p> +<p>These are the most important attributes you should use, but there are many more available. +For information about all the supported attributes, see the <a +href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> document.</p> - - -<h2 id="Inflating">Inflating a Menu Resource</h2> - -<p>From your application code, you can inflate a menu resource (convert the XML resource into a -programmable object) using -{@link android.view.MenuInflater#inflate(int,Menu) MenuInflater.inflate()}. For -example, the following code inflates the <code>game_menu.xml</code> file defined above, during the -{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} callback method, to -use the menu as the activity's Options Menu:</p> +<p>You can add a submenu to an item in any menu (except a submenu) by adding a {@code <menu>} +element as the child of an {@code <item>}. Submenus are useful when your application has a lot +of functions that can be organized into topics, like items in a PC application's menu bar (File, +Edit, View, etc.). For example:</p> <pre> -@Override -public boolean onCreateOptionsMenu(Menu menu) { - MenuInflater inflater = getMenuInflater(); - inflater.inflate(R.menu.game_menu, menu); - return true; -} +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/file" + android:title="@string/file" > + <!-- "file" submenu --> + <menu> + <item android:id="@+id/create_new" + android:title="@string/create_new" /> + <item android:id="@+id/open" + android:title="@string/open" /> + </menu> + </item> +</menu> </pre> -<p>The {@link android.app.Activity#getMenuInflater()} method returns a {@link -android.view.MenuInflater} for the activity. With this object, you can call {@link -android.view.MenuInflater#inflate(int,Menu) inflate()}, which inflates a menu resource into a -{@link android.view.Menu} object. In this example, the menu resource defined by -<code>game_menu.xml</code> -is inflated into the {@link android.view.Menu} that was passed into {@link -android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}. (This callback method for -the Options Menu is discussed more in the next section.)</p> +<p>To use the menu in your activity, you need to inflate the menu resource (convert the XML +resource into a programmable object) using {@link android.view.MenuInflater#inflate(int,Menu) +MenuInflater.inflate()}. In the following sections, you'll see how to inflate a menu for each +menu type.</p> <h2 id="options-menu">Creating an Options Menu</h2> -<div class="figure" style="width:200px"> +<div class="figure" style="width:200px;margin:0"> <img src="{@docRoot}images/options_menu.png" height="333" alt="" /> - <p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Options Menu in the -Browser.</p> + <p class="img-caption"><strong>Figure 1.</strong> Options menu in the +Browser, on Android 2.3.</p> </div> -<p>The Options Menu is where you should include basic activity actions and necessary navigation -items (for example, a button to open the application settings). Items in the Options Menu are -accessible in two distinct ways: the MENU button or in the <a -href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> (on devices running Android 3.0 -or higher).</p> - -<p>When running on a device with Android 2.3 and lower, the Options Menu appears at the bottom of -the screen, as shown in figure 1. When opened, the first visible portion of the Options Menu is -the icon menu. It holds the first six menu items. If you add more than six items to the -Options Menu, Android places the sixth item and those after it into the overflow menu, which the -user can open by touching the "More" menu item.</p> - -<p>On Android 3.0 and higher, items from the Options Menu is placed in the Action Bar, which appears -at the top of the activity in place of the traditional title bar. By default all items from the -Options Menu are placed in the overflow menu, which the user can open by touching the menu icon -on the right side of the Action Bar. However, you can place select menu items directly in the -Action Bar as "action items," for instant access, as shown in figure 2.</p> - -<p>When the Android system creates the Options Menu for the first time, it calls your -activity's {@link android.app.Activity#onCreateOptionsMenu(Menu) -onCreateOptionsMenu()} method. Override this method in your activity -and populate the {@link android.view.Menu} that is passed into the method, -{@link android.view.Menu} by inflating a menu resource as described above in <a -href="#Inflating">Inflating a Menu Resource</a>. For example:</p> +<p>The options menu is where you should include actions and other options that are relevant to the +current activity context, such as "Search," "Compose email," and "Settings."</p> + +<p>Where the items in your options menu appear on the screen depends on the version for which you've +developed your application:</p> + +<ul> + <li>If you've developed your application for <strong>Android 2.3.x (API level 10) or +lower</strong>, the contents of your options menu appear at the bottom of the screen when the user +presses the <em>Menu</em> button, as shown in figure 1. When opened, the first visible portion is +the icon +menu, which holds up to six menu items. If your menu includes more than six items, Android places +the sixth item and the rest into the overflow menu, which the user can open by selecting +<em>More</em>.</li> + + <li>If you've developed your application for <strong>Android 3.0 (API level 11) and +higher</strong>, items from the options menu are available in the <a +href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>. By default, the system +places all items in the action overflow, which the user can reveal with the action overflow icon on +the right side of the action bar (or by pressing the device <em>Menu</em> button, if available). To +enable +quick access to important actions, you can promote a few items to appear in the action bar by adding +{@code android:showAsAction="ifRoom"} to the corresponding {@code <item>} elements (see figure +2). <p>For more information about action items and other action bar behaviors, see the <a +href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> guide. </p> +<p class="note"><strong>Note:</strong> Even if you're <em>not</em> developing for Android 3.0 or +higher, you can build your own action bar layout for a similar effect. For an example of how you can +support older versions of Android with an action bar, see the <a +href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a> +sample.</p> +</li> +</ul> + +<img src="{@docRoot}images/ui/actionbar.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> Action bar from the <a +href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app, showing +navigation tabs and a camera action item (plus the action overflow button).</p> + +<p>You can declare items for the options menu from either your {@link android.app.Activity} +subclass or a {@link android.app.Fragment} subclass. If both your activity and fragment(s) +declare items for the options menu, they are combined in the UI. The activity's items appear +first, followed by those of each fragment in the order in which each fragment is added to the +activity. If necessary, you can re-order the menu items with the {@code android:orderInCategory} +attribute in each {@code <item>} you need to move.</p> + +<p>To specify the options menu for an activity, override {@link +android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} (fragments provide their +own {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()} callback). In this +method, you can inflate your menu resource (<a href="#xml">defined in XML</a>) into the {@link +android.view.Menu} provided in the callback. For example:</p> <pre> @Override public boolean onCreateOptionsMenu(Menu menu) { - MenuInflater inflater = getMenuInflater(); + MenuInflater inflater = {@link android.app.Activity#getMenuInflater()}; inflater.inflate(R.menu.game_menu, menu); return true; } </pre> -<div class="figure" style="width:450px"> -<img src="{@docRoot}images/ui/actionbar.png" alt="" /> -<p class="img-caption"><strong>Figure 2.</strong> Action bar from the <a -href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app, including -navigation tabs and a camera action item (plus the overflow menu button).</p> -</div> +<p>You can also add menu items using {@link android.view.Menu#add(int,int,int,int) +add()} and retrieve items with {@link android.view.Menu#findItem findItem()} to revise their +properties with {@link android.view.MenuItem} APIs.</p> -<p>You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int) -add()} to add items to the {@link android.view.Menu}.</p> +<p>If you've developed your application for Android 2.3.x and lower, the system calls {@link +android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} to create the options menu +when the user opens the menu for the first time. If you've developed for Android 3.0 and higher, the +system calls {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} when +starting the activity, in order to show items to the action bar.</p> -<p class="note"><strong>Note:</strong> On Android 2.3 and lower, the system calls {@link -android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} to create the Options Menu -when the user opens it for the first time, but on Android 3.0 and greater, the system creates it as -soon as the activity is created, in order to populate the Action Bar.</p> -<h3 id="RespondingOptionsMenu">Responding to user action</h3> +<h3 id="RespondingOptionsMenu">Handling click events</h3> -<p>When the user selects a menu item from the Options Menu (including action items in the -Action Bar), the system calls your activity's -{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} -method. This method passes the -{@link android.view.MenuItem} that the user selected. You can identify the menu item by calling -{@link android.view.MenuItem#getItemId()}, which returns the unique ID for the menu -item (defined by the {@code android:id} attribute in the menu resource or with an integer -given to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID -against known menu items and perform the appropriate action. For example:</p> +<p>When the user selects an item from the options menu (including action items in the action bar), +the system calls your activity's {@link android.app.Activity#onOptionsItemSelected(MenuItem) +onOptionsItemSelected()} method. This method passes the {@link android.view.MenuItem} selected. You +can identify the item by calling {@link android.view.MenuItem#getItemId()}, which returns the unique +ID for the menu item (defined by the {@code android:id} attribute in the menu resource or with an +integer given to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match +this ID against known menu items to perform the appropriate action. For example:</p> <pre> @Override public boolean onOptionsItemSelected(MenuItem item) { // Handle item selection switch (item.getItemId()) { - case R.id.new_game: - newGame(); - return true; - case R.id.help: - showHelp(); - return true; - default: - return super.onOptionsItemSelected(item); + case R.id.new_game: + newGame(); + return true; + case R.id.help: + showHelp(); + return true; + default: + return super.onOptionsItemSelected(item); } } </pre> -<p>In this example, {@link android.view.MenuItem#getItemId()} queries the ID for the selected menu -item and the switch statement compares the ID against the resource IDs that were assigned to menu -items in the XML resource. When a switch case successfully handles the menu item, it -returns {@code true} to indicate that the item selection was handled. Otherwise, the default -statement passes the menu item to the super class, in -case it can handle the item selected. (If you've directly extended the {@link android.app.Activity} -class, then the super class returns {@code false}, but it's a good practice to -pass unhandled menu items to the super class instead of directly returning {@code false}.)</p> - -<p>Additionally, Android 3.0 adds the ability for you to define the on-click behavior for a menu -item in the <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> XML, -using the {@code android:onClick} attribute. So you don't need to implement {@link -android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}. Using the {@code -android:onClick} attribute, you can specify a method to call when the user selects the menu item. -Your activity must then implement the method specified in the {@code android:onClick} attribute so -that it accepts a single {@link android.view.MenuItem} parameter—when the system calls this -method, it passes the menu item selected.</p> +<p>When you successfully handle a menu item, return {@code true}. If you don't handle the menu +item, you should call the superclass implementation of {@link +android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} (the default +implementation returns false).</p> + +<p>If your activity includes fragments, the system first calls {@link +android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} for the activity then +for each fragment (in the order each fragment was added) until one returns +{@code true} or all fragments have been called.</p> + +<p class="note"><strong>Tip:</strong> Android 3.0 adds the ability for you to define the on-click +behavior for a menu item in XML, using the {@code android:onClick} attribute. The value for the +attribute must be the name of a method defined by the activity using the menu. The method +must be public and accept a single {@link android.view.MenuItem} parameter—when the system +calls this method, it passes the menu item selected. For more information and an example, see the <a +href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> document.</p> <p class="note"><strong>Tip:</strong> If your application contains multiple activities and -some of them provide the same Options Menu, consider creating +some of them provide the same options menu, consider creating an activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} methods. Then extend this class for each activity that should share the -same Options Menu. This way, you have to manage only one set of code for handling menu -actions and each descendant class inherits the menu behaviors.<br/><br/> -If you want to add menu items to one of your descendant activities, +same options menu. This way, you can manage one set of code for handling menu +actions and each descendant class inherits the menu behaviors. +If you want to add menu items to one of the descendant activities, override {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} in that activity. Call {@code super.onCreateOptionsMenu(menu)} so the original menu items are created, then add new menu items with {@link @@ -278,180 +350,477 @@ behavior for individual menu items.</p> <h3 id="ChangingTheMenu">Changing menu items at runtime</h3> -<p>Once the activity is created, the {@link android.app.Activity#onCreateOptionsMenu(Menu) -onCreateOptionsMenu()} method is -called only once, as described above. The system keeps and re-uses the {@link -android.view.Menu} you define in this method until your activity is destroyed. If you want to change -the Options Menu any time after it's first created, you must override the -{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This passes -you the {@link android.view.Menu} object as it currently exists. This is useful if you'd like to -remove, add, disable, or enable menu items depending on the current state of your application.</p> - -<p>On Android 2.3 and lower, the system calls {@link android.app.Activity#onPrepareOptionsMenu(Menu) -onPrepareOptionsMenu()} each time the user opens the Options Menu.</p> +<p>After the system calls {@link android.app.Activity#onCreateOptionsMenu(Menu) +onCreateOptionsMenu()}, it retains an instance of the {@link android.view.Menu} you populate and +will not call {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} +again unless the menu is invalidated for some reason. However, you should use {@link +android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} only to create the initial +menu state and not to make changes during the activity lifecycle.</p> + +<p>If you want to modify the options menu based on +events that occur during the activity lifecycle, you can do so in +the {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This +method passes you the {@link android.view.Menu} object as it currently exists so you can modify it, +such as add, remove, or disable items. (Fragments also provide an {@link +android.app.Fragment#onPrepareOptionsMenu onPrepareOptionsMenu()} callback.)</p> + +<p>On Android 2.3.x and lower, the system calls {@link +android.app.Activity#onPrepareOptionsMenu(Menu) +onPrepareOptionsMenu()} each time the user opens the options menu (presses the <em>Menu</em> +button).</p> -<p>On Android 3.0 and higher, you must call {@link android.app.Activity#invalidateOptionsMenu -invalidateOptionsMenu()} when you want to update the menu, because the menu is always open. The -system will then call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} -so you can update the menu items.</p> +<p>On Android 3.0 and higher, the options menu is considered to always be open when menu items are +presented in the action bar. When an event occurs and you want to perform a menu update, you must +call {@link android.app.Activity#invalidateOptionsMenu invalidateOptionsMenu()} to request that the +system call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}.</p> <p class="note"><strong>Note:</strong> -You should never change items in the Options Menu based on the {@link android.view.View} currently +You should never change items in the options menu based on the {@link android.view.View} currently in focus. When in touch mode (when the user is not using a trackball or d-pad), views cannot take focus, so you should never use focus as the basis for modifying -items in the Options Menu. If you want to provide menu items that are context-sensitive to a {@link +items in the options menu. If you want to provide menu items that are context-sensitive to a {@link android.view.View}, use a <a href="#context-menu">Context Menu</a>.</p> -<p>If you're developing for Android 3.0 or higher, be sure to also read the <a -href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</p> +<h2 id="context-menu">Creating Contextual Menus</h2> -<h2 id="context-menu">Creating a Context Menu</h2> +<div class="figure" style="width:420px;margin-top:-1em"> + <img src="{@docRoot}images/ui/menu-context.png" alt="" /> + <p class="img-caption"><strong>Figure 3.</strong> Screenshots of a floating context menu (left) +and the contextual action bar (right).</p> +</div> -<p>A context menu is conceptually similar to the menu displayed when the user performs a -"right-click" on a PC. You should use a context menu to provide the user access to -actions that pertain to a specific item in the user interface. On Android, a context menu is -displayed when the user performs a "long press" (press and hold) on an item.</p> +<p>A contextual menu offers actions that affect a specific item or context frame in the UI. You +can provide a context menu for any view, but they are most often used for items in a {@link +android.widget.ListView}, {@link android.widget.GridView}, or other view collections in which +the user can perform direct actions on each item.</p> -<p>You can create a context menu for any View, though context menus are most often used for items in -a {@link android.widget.ListView}. When the user performs a long-press on an item in a ListView and -the list is registered to provide a context menu, the list item signals to the user that a context -menu is available by animating its background color—it transitions from -orange to white before opening the context menu. (The Contacts application demonstrates this -feature.)</p> +<p>There are two ways to provide contextual actions:</p> +<ul> + <li>In a <a href="#FloatingContextMenu">floating context menu</a>. A menu appears as a +floating list of menu items (similar to a dialog) when the user performs a long-click (press and +hold) on a view that declares support for a context menu. Users can perform a contextual +action on one item at a time.</li> + + <li>In the <a href="#CAB">contextual action mode</a>. This mode is a system implementation of +{@link android.view.ActionMode} that displays a <em>contextual action bar</em> at the top of the +screen with action items that affect the selected item(s). When this mode is active, users +can perform an action on multiple items at once (if your app allows it).</li> +</ul> -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h3>Register a ListView</h3> -<p>If your activity uses a {@link android.widget.ListView} and -you want all list items to provide a context menu, register all items for a context -menu by passing the {@link android.widget.ListView} to {@link -android.app.Activity#registerForContextMenu(View) registerForContextMenu()}. For -example, if you're using a {@link android.app.ListActivity}, register all list items like this:</p> -<p><code>registerForContextMenu({@link android.app.ListActivity#getListView()});</code></p> -</div> -</div> +<p class="note"><strong>Note:</strong> The contextual action mode is available on Android 3.0 (API +level 11) and higher and is the preferred technique for displaying contextual actions when +available. If your app supports versions lower than 3.0 then you should fall back to a floating +context menu on those devices.</p> -<p>In order for a View to provide a context menu, you must "register" the view for a context -menu. Call {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} and -pass it the {@link android.view.View} you want to give a context menu. When this View then -receives a long-press, it displays a context menu.</p> -<p>To define the context menu's appearance and behavior, override your activity's context menu -callback methods, {@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo) -onCreateContextMenu()} and -{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}.</p> +<h3 id="FloatingContextMenu">Creating a floating context menu</h3> -<p>For example, here's an {@link -android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo) -onCreateContextMenu()} that uses the {@code context_menu.xml} menu resource:</p> +<p>To provide a floating context menu:</p> +<ol> + <li>Register the {@link android.view.View} to which the context menu should be associated by +calling {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} and pass +it the {@link android.view.View}. + <p>If your activity uses a {@link android.widget.ListView} or {@link android.widget.GridView} and +you want each item to provide the same context menu, register all items for a context menu by +passing the {@link android.widget.ListView} or {@link android.widget.GridView} to {@link +android.app.Activity#registerForContextMenu(View) registerForContextMenu()}.</p> +</li> + + <li>Implement the {@link +android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} method +in your {@link android.app.Activity} or {@link android.app.Fragment}. + <p>When the registered view receives a long-click event, the system calls your {@link +android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} +method. This is where you define the menu items, usually by inflating a menu resource. For +example:</p> <pre> @Override public void onCreateContextMenu(ContextMenu menu, View v, ContextMenuInfo menuInfo) { - super.onCreateContextMenu(menu, v, menuInfo); - MenuInflater inflater = getMenuInflater(); - inflater.inflate(R.menu.context_menu, menu); + super.onCreateContextMenu(menu, v, menuInfo); + MenuInflater inflater = getMenuInflater(); + inflater.inflate(R.menu.context_menu, menu); } </pre> -<p>{@link android.view.MenuInflater} is used to inflate the context menu from a <a -href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. (You can also use -{@link android.view.Menu#add(int,int,int,int) add()} to add menu items.) The callback method +<p>{@link android.view.MenuInflater} allows you to inflate the context menu from a <a +href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. The callback method parameters include the {@link android.view.View} that the user selected and a {@link android.view.ContextMenu.ContextMenuInfo} object that provides -additional information about the item selected. You might use these parameters to determine -which context menu should be created, but in this example, all context menus for the activity are -the same.</p> +additional information about the item selected. If your activity has several views that each provide +a different context menu, you might use these parameters to determine which context menu to +inflate.</p> +</li> -<p>Then when the user selects an item from the context menu, the system calls {@link -android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}. Here is an example -of how you can handle selected items:</p> +<li>Implement {@link android.app.Activity#onContextItemSelected(MenuItem) +onContextItemSelected()}. + <p>When the user selects a menu item, the system calls this method so you can perform the +appropriate action. For example:</p> <pre> @Override public boolean onContextItemSelected(MenuItem item) { - AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); - switch (item.getItemId()) { - case R.id.edit: - editNote(info.id); - return true; - case R.id.delete: - deleteNote(info.id); - return true; - default: - return super.onContextItemSelected(item); - } + AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); + switch (item.getItemId()) { + case R.id.edit: + editNote(info.id); + return true; + case R.id.delete: + deleteNote(info.id); + return true; + default: + return super.onContextItemSelected(item); + } } </pre> -<p>The structure of this code is similar to the example for <a href="#options-menu">Creating an -Options Menu</a>, in which {@link android.view.MenuItem#getItemId()} queries the ID for the selected -menu item and a switch statement matches the item to the IDs that are defined in the menu resource. -And like the options menu example, the default statement calls the super class in case it -can handle menu items not handled here, if necessary.</p> +<p>The {@link android.view.MenuItem#getItemId()} method queries the ID for +the selected menu item, which you should assign to each menu item in XML using the {@code +android:id} attribute, as shown in the section about <a href="#xml">Defining a Menu in +XML</a>.</p> + +<p>When you successfully handle a menu item, return {@code true}. If you don't handle the menu item, +you should pass the menu item to the superclass implementation. If your activity includes fragments, +the activity receives this callback first. By calling the superclass when unhandled, the system +passes the event to the respective callback method in each fragment, one at a time (in the order +each fragment was added) until {@code true} or {@code false} is returned. (The default +implementation for {@link android.app.Activity} and {@code android.app.Fragment} return {@code +false}, so you should always call the superclass when unhandled.)</p> +</li> +</ol> + + +<h3 id="CAB">Using the contextual action mode</h3> -<p>In this example, the selected item is an item from a {@link android.widget.ListView}. To -perform an action on the selected item, the application needs to know the list -ID for the selected item (it's position in the ListView). To get the ID, the application calls -{@link android.view.MenuItem#getMenuInfo()}, which returns a {@link -android.widget.AdapterView.AdapterContextMenuInfo} object that includes the list ID for the -selected item in the {@link android.widget.AdapterView.AdapterContextMenuInfo#id id} field. The -local methods <code>editNote()</code> and <code>deleteNote()</code> methods accept this list ID to -perform an action on the data specified by the list ID.</p> +<p>The contextual action mode is a system implementation of {@link android.view.ActionMode} that +focuses user interaction toward performing contextual actions. When a +user enables this mode by selecting an item, a <em>contextual action bar</em> appears at the top of +the screen to present actions the user can perform on the currently selected item(s). While this +mode is enabled, the user can select multiple items (if you allow it), deselect items, and continue +to navigate within the activity (as much as you're willing to allow). The action mode is disabled +and the contextual action bar disappears when the user deselects all items, presses the BACK button, +or selects the <em>Done</em> action on the left side of the bar.</p> -<p class="note"><strong>Note:</strong> Items in a context menu do not support icons or shortcut -keys.</p> +<p class="note"><strong>Note:</strong> The contextual action bar is not necessarily +associated with the <a href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>. They operate +independently, even though the contextual action bar visually overtakes the action bar +position.</p> +<p>If you're developing for Android 3.0 (API level 11) or higher, you +should usually use the contextual action mode to present contextual actions, instead of the <a +href="#FloatingContextMenu">floating context menu</a>.</p> +<p>For views that provide contextual actions, you should usually invoke the contextual action mode +upon one of two events (or both):</p> +<ul> + <li>The user performs a long-click on the view.</li> + <li>The user selects a checkbox or similar UI component within the view.</li> +</ul> + +<p>How your application invokes the contextual action mode and defines the behavior for each +action depends on your design. There are basically two designs:</p> +<ul> + <li>For contextual actions on individual, arbitrary views.</li> + <li>For batch contextual actions on groups of items in a {@link +android.widget.ListView} or {@link android.widget.GridView} (allowing the user to select multiple +items and perform an action on them all).</li> +</ul> -<h2 id="submenu">Creating Submenus</h2> +<p>The following sections describe the setup required for each scenario.</p> -<p>A submenu is a menu that the user can open by selecting an item in another menu. You can add a -submenu to any menu (except a submenu). Submenus are useful when your application has a lot of -functions that can be organized into topics, like items in a PC application's menu bar (File, Edit, -View, etc.).</p> -<p>When creating your <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu -resource</a>, you can create a submenu by adding a {@code <menu>} element as the child of an -{@code <item>}. For example:</p> +<h4 id="CABforViews">Enabling the contextual action mode for individual views</h4> +<p>If you want to invoke the contextual action mode only when the user selects specific +views, you should:</p> +<ol> + <li>Implement the {@link android.view.ActionMode.Callback} interface. In its callback methods, you +can specify the actions for the contextual action bar, respond to click events on action items, and +handle other lifecycle events for the action mode.</li> + <li>Call {@link android.app.Activity#startActionMode startActionMode()} when you want to show the +bar (such as when the user long-clicks the view).</li> +</ol> + +<p>For example:</p> + +<ol> + <li>Implement the {@link android.view.ActionMode.Callback ActionMode.Callback} interface: <pre> -<?xml version="1.0" encoding="utf-8"?> -<menu xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:id="@+id/file" - android:icon="@drawable/file" - android:title="@string/file" > - <!-- "file" submenu --> - <menu> - <item android:id="@+id/create_new" - android:title="@string/create_new" /> - <item android:id="@+id/open" - android:title="@string/open" /> - </menu> - </item> -</menu> +private ActionMode.Callback mActionModeCallback = new ActionMode.Callback() { + + // Called when the action mode is created; startActionMode() was called + @Override + public boolean onCreateActionMode(ActionMode mode, Menu menu) { + // Inflate a menu resource providing context menu items + MenuInflater inflater = mode.getMenuInflater(); + inflater.inflate(R.menu.context_menu, menu); + return true; + } + + // Called each time the action mode is shown. Always called after onCreateActionMode, but + // may be called multiple times if the mode is invalidated. + @Override + public boolean onPrepareActionMode(ActionMode mode, Menu menu) { + return false; // Return false if nothing is done + } + + // Called when the user selects a contextual menu item + @Override + public boolean onActionItemClicked(ActionMode mode, MenuItem item) { + switch (item.getItemId()) { + case R.id.menu_share: + shareCurrentItem(); + mode.finish(); // Action picked, so close the CAB + return true; + default: + return false; + } + } + + // Called when the user exits the action mode + @Override + public void onDestroyActionMode(ActionMode mode) { + mActionMode = null; + } +}; +</pre> + +<p>Notice that these event callbacks are almost exactly the same as the callbacks for the <a +href="#options-menu">options menu</a>, except each of these also pass the {@link +android.view.ActionMode} object associated with the event. You can use {@link +android.view.ActionMode} APIs to make various changes to the CAB, such as revise the title and +subtitle with {@link android.view.ActionMode#setTitle setTitle()} and {@link +android.view.ActionMode#setSubtitle setSubtitle()} (useful to indicate how many items are +selected).</p> + +<p>Also notice that the above sample sets the {@code mActionMode} variable null when the +action mode is destroyed. In the next step, you'll see how it's initialized and how saving +the member variable in your activity or fragment can be useful.</p> +</li> + + <li>Call {@link android.app.Activity#startActionMode startActionMode()} to enable the contextual +action mode when appropriate, such as in response to a long-click on a {@link +android.view.View}:</p> + +<pre> +someView.setOnLongClickListener(new View.OnLongClickListener() { + // Called when the user long-clicks on someView + public boolean onLongClick(View view) { + if (mActionMode != null) { + return false; + } + + // Start the CAB using the ActionMode.Callback defined above + mActionMode = getActivity().startActionMode(mActionModeCallback); + view.setSelected(true); + return true; + } +}); +</pre> + +<p>When you call {@link android.app.Activity#startActionMode startActionMode()}, the system returns +the {@link android.view.ActionMode} created. By saving this in a member variable, you can +make changes to the contextual action bar in response to other events. In the above sample, the +{@link android.view.ActionMode} is used to ensure that the {@link android.view.ActionMode} instance +is not recreated if it's already active, by checking whether the member is null before starting the +action mode.</p> +</li> +</ol> + + + +<h4 id="CABforListView">Enabling batch contextual actions in a ListView or GridView</h4> + +<p>If you have a collection of items in a {@link android.widget.ListView} or {@link +android.widget.GridView} (or another extension of {@link android.widget.AbsListView}) and want to +allow users to perform batch actions, you should:</p> + +<ul> + <li>Implement the {@link android.widget.AbsListView.MultiChoiceModeListener} interface and set it +for the view group with {@link android.widget.AbsListView#setMultiChoiceModeListener +setMultiChoiceModeListener()}. In the listener's callback methods, you can specify the actions +for the contextual action bar, respond to click events on action items, and handle other callbacks +inherited from the {@link android.view.ActionMode.Callback} interface.</li> + + <li>Call {@link android.widget.AbsListView#setChoiceMode setChoiceMode()} with the {@link +android.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL} argument.</li> +</ul> + +<p>For example:</p> + +<pre> +ListView listView = getListView(); +listView.setChoiceMode(ListView.CHOICE_MODE_MULTIPLE_MODAL); +listView.setMultiChoiceModeListener(new MultiChoiceModeListener() { + + @Override + public void onItemCheckedStateChanged(ActionMode mode, int position, + long id, boolean checked) { + // Here you can do something when items are selected/de-selected, + // such as update the title in the CAB + } + + @Override + public boolean onActionItemClicked(ActionMode mode, MenuItem item) { + // Respond to clicks on the actions in the CAB + switch (item.getItemId()) { + case R.id.menu_delete: + deleteSelectedItems(); + mode.finish(); // Action picked, so close the CAB + return true; + default: + return false; + } + } + + @Override + public boolean onCreateActionMode(ActionMode mode, Menu menu) { + // Inflate the menu for the CAB + MenuInflater inflater = mode.getMenuInflater(); + inflater.inflate(R.menu.context, menu); + return true; + } + + @Override + public void onDestroyActionMode(ActionMode mode) { + // Here you can make any necessary updates to the activity when + // the CAB is removed. By default, selected items are deselected/unchecked. + } + + @Override + public boolean onPrepareActionMode(ActionMode mode, Menu menu) { + // Here you can perform updates to the CAB due to + // an {@link android.view.ActionMode#invalidate} request + return false; + } +}); +</pre> + +<p>That's it. Now when the user selects an item with a long-click, the system calls the {@link +android.widget.AbsListView.MultiChoiceModeListener#onCreateActionMode onCreateActionMode()} +method and displays the contextual action bar with the specified actions. While the contextual +action bar is visible, users can select additional items.</p> + +<p>In some cases in which the contextual actions provide common action items, you might +want to add a checkbox or a similar UI element that allows users to select items, because they +might not discover the long-click behavior. When a user selects the checkbox, you +can invoke the contextual action mode by setting the respective list item to the checked +state with {@link android.widget.AbsListView#setItemChecked setItemChecked()}.</p> + + + + +<h2 id="PopupMenu">Creating a Popup Menu</h2> + +<div class="figure" style="width:220px"> +<img src="{@docRoot}images/ui/popupmenu.png" alt="" /> +<p><strong>Figure 4.</strong> A popup menu in the Gmail app, anchored to the overflow +button at the top-right.</p> +</div> + +<p>A {@link android.widget.PopupMenu} is a modal menu anchored to a {@link android.view.View}. +It appears below the anchor view if there is room, or above the view otherwise. It's useful for:</p> +<ul> + <li>Providing an overflow-style menu for actions that <em>relate to</em> specific content (such as +Gmail's email headers, shown in figure 4). + <p class="note"><strong>Note:</strong> This is not the same as a context menu, which is +generally for actions that <em>affect</em> selected content. For actions that affect selected +content, use the <a href="#CAB">contextual action mode</a> or <a +href="#FloatingContextMenu">floating context menu</a>.</p></li> + <li>Providing a second part of a command sentence (such as a button marked "Add" +that produces a popup menu with different "Add" options).</li> + <li>Providing a drop-down similar to {@link android.widget.Spinner} that does not retain +a persistent selection.</li> +</ul> + + +<p class="note"><strong>Note:</strong> {@link android.widget.PopupMenu} is available with API +level 11 and higher.</p> + +<p>If you <a href="#xml">define your menu in XML</a>, here's how you can show the popup menu:</p> +<ol> + <li>Instantate a {@link android.widget.PopupMenu} with its constructor, which takes the +current application {@link android.content.Context} and the {@link android.view.View} to which the +menu should be anchored.</li> + <li>Use {@link android.view.MenuInflater} to inflate your menu resource into the {@link +android.view.Menu} object returned by {@link +android.widget.PopupMenu#getMenu() PopupMenu.getMenu()}. On API level 14 and above, you can use +{@link android.widget.PopupMenu#inflate PopupMenu.inflate()} instead.</li> + <li>Call {@link android.widget.PopupMenu#show() PopupMenu.show()}.</li> +</ol> + +<p>For example, here's a button with the {@link android.R.attr#onClick android:onClick} attribute +that shows a popup menu:</p> + +<pre> +<ImageButton + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:src="@drawable/ic_overflow_holo_dark" + android:contentDescription="@string/descr_overflow_button" + android:onClick="showPopup" /> +</pre> + +<p>The activity can then show the popup menu like this:</p> + +<pre> +public void showPopup(View v) { + PopupMenu popup = new PopupMenu(this, v); + MenuInflater inflater = popup.getMenuInflater(); + inflater.inflate(R.menu.actions, popup.getMenu()); + popup.show(); +} </pre> -<p>When the user selects an item from a submenu, the parent menu's respective on-item-selected -callback method receives the event. For instance, if the above menu is applied as an Options Menu, -then the {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method -is called when a submenu item is selected.</p> +<p>In API level 14 and higher, you can combine the two lines that inflate the menu with {@link +android.widget.PopupMenu#inflate PopupMenu.inflate()}.</p> + +<p>The menu is dismissed when the user selects an item or touches outside the menu +area. You can listen for the dismiss event using {@link +android.widget.PopupMenu.OnDismissListener}.</p> + +<h3 id="PopupEvents">Handling click events</h3> -<p>You can also use {@link android.view.Menu#addSubMenu(int,int,int,int) addSubMenu()} to -dynamically add a {@link android.view.SubMenu} to an existing {@link android.view.Menu}. This -returns the new {@link android.view.SubMenu} object, to which you can add -submenu items, using {@link android.view.Menu#add(int,int,int,int) add()}</p> +<p>To perform an +action when the user selects a menu item, you must implement the {@link +android.widget.PopupMenu.OnMenuItemClickListener} interface and register it with your {@link +android.widget.PopupMenu} by calling {@link android.widget.PopupMenu#setOnMenuItemClickListener +setOnMenuItemclickListener()}. When the user selects an item, the system calls the {@link +android.widget.PopupMenu.OnMenuItemClickListener#onMenuItemClick onMenuItemClick()} callback in +your interface.</p> +<p>For example:</p> +<pre> +public void showMenu(View v) { + PopupMenu popup = new PopupMenu(this, v); -<h2 id="features">Other Menu Features</h2> + // This activity implements OnMenuItemClickListener + popup.setOnMenuItemClickListener(this); + popup.inflate(R.menu.actions); + popup.show(); +} + +@Override +public boolean onMenuItemClick(MenuItem item) { + switch (item.getItemId()) { + case R.id.archive: + archive(item); + return true; + case R.id.delete: + delete(item); + return true; + default: + return false; + } +} +</pre> -<p>Here are some other features that you can apply to most menu items.</p> -<h3 id="groups">Menu groups</h3> +<h2 id="groups">Creating Menu Groups</h2> <p>A menu group is a collection of menu items that share certain traits. With a group, you can:</p> @@ -473,38 +842,41 @@ android.view.Menu#add(int,int,int,int) add()} method.</p> <pre> <?xml version="1.0" encoding="utf-8"?> <menu xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:id="@+id/item1" - android:icon="@drawable/item1" - android:title="@string/item1" /> + <item android:id="@+id/menu_save" + android:icon="@drawable/menu_save" + android:title="@string/menu_save" /> <!-- menu group --> - <group android:id="@+id/group1"> - <item android:id="@+id/groupItem1" - android:title="@string/groupItem1" /> - <item android:id="@+id/groupItem2" - android:title="@string/groupItem2" /> + <group android:id="@+id/group_delete"> + <item android:id="@+id/menu_archive" + android:title="@string/menu_archive" /> + <item android:id="@+id/menu_delete" + android:title="@string/menu_delete" /> </group> </menu> </pre> -<p>The items that are in the group appear the same as the first item that is not in a -group—all three items in the menu are siblings. However, you can modify the traits of the two -items in the group by referencing the group ID and using the methods listed above.</p> +<p>The items that are in the group appear at the same level as the first item—all three items +in the menu are siblings. However, you can modify the traits of the two +items in the group by referencing the group ID and using the methods listed above. The system +will also never separate grouped items. For example, if you declare {@code +android:showAsAction="ifRoom"} for each item, they will either both appear in the action +bar or both appear in the action overflow.</p> -<h3 id="checkable">Checkable menu items</h3> +<h3 id="checkable">Using checkable menu items</h3> <div class="figure" style="width:200px"> <img src="{@docRoot}images/radio_buttons.png" height="333" alt="" /> - <p class="img-caption"><strong>Figure 3.</strong> Screenshot of a submenu with checkable + <p class="img-caption"><strong>Figure 5.</strong> Screenshot of a submenu with checkable items.</p> </div> <p>A menu can be useful as an interface for turning options on and off, using a checkbox for stand-alone options, or radio buttons for groups of -mutually exclusive options. Figure 2 shows a submenu with items that are checkable with radio +mutually exclusive options. Figure 5 shows a submenu with items that are checkable with radio buttons.</p> -<p class="note"><strong>Note:</strong> Menu items in the Icon Menu (from the Options Menu) cannot +<p class="note"><strong>Note:</strong> Menu items in the Icon Menu (from the options menu) cannot display a checkbox or radio button. If you choose to make items in the Icon Menu checkable, you must manually indicate the checked state by swapping the icon and/or text each time the state changes.</p> @@ -550,15 +922,15 @@ user selected it) with {@link android.view.MenuItem#isChecked()} and then set th <pre> @Override public boolean onOptionsItemSelected(MenuItem item) { - switch (item.getItemId()) { - case R.id.vibrate: - case R.id.dont_vibrate: - if (item.isChecked()) item.setChecked(false); - else item.setChecked(true); - return true; - default: - return super.onOptionsItemSelected(item); - } + switch (item.getItemId()) { + case R.id.vibrate: + case R.id.dont_vibrate: + if (item.isChecked()) item.setChecked(false); + else item.setChecked(true); + return true; + default: + return super.onOptionsItemSelected(item); + } } </pre> @@ -575,30 +947,8 @@ you should store the data using <a href="{@docRoot}guide/topics/data/data-storage.html#pref">Shared Preferences</a>.</p> -<h3 id="shortcuts">Shortcut keys</h3> - -<p>To facilitate quick access to items in the Options Menu when the user's device has a hardware -keyboard, you can add quick-access shortcut keys using letters and/or numbers, with the -{@code android:alphabeticShortcut} and {@code android:numericShortcut} attributes in the {@code -<item>} element. You can also use the methods {@link -android.view.MenuItem#setAlphabeticShortcut(char)} and {@link -android.view.MenuItem#setNumericShortcut(char)}. Shortcut keys are <em>not</em> -case sensitive.</p> - -<p>For example, if you apply the "s" character as an alphabetic shortcut to a "save" menu item, then -when the menu is open (or while the user holds the MENU button) and the user presses the "s" key, -the "save" menu item is selected.</p> - -<p>This shortcut key is displayed as a tip in the menu item, below the menu item name -(except for items in the Icon Menu, which are displayed only if the user holds the MENU -button).</p> - -<p class="note"><strong>Note:</strong> Shortcut keys for menu items only work on devices with a -hardware keyboard. Shortcuts cannot be added to items in a Context Menu.</p> - - -<h3 id="intents">Dynamically adding menu intents</h3> +<h2 id="intents">Adding Menu Items Based on an Intent</h2> <p>Sometimes you'll want a menu item to launch an activity using an {@link android.content.Intent} (whether it's an activity in your application or another application). When you know the intent you @@ -671,7 +1021,7 @@ addIntentOptions()}, it overrides any and all menu items by the menu group speci argument.</p> -<h4>Allowing your activity to be added to other menus</h4> +<h3 id="AllowingToAdd">Allowing your activity to be added to other menus</h3> <p>You can also offer the services of your activity to other applications, so your application can be included in the menu of others (reverse the roles described above).</p> @@ -681,7 +1031,7 @@ filter as usual, but be sure to include the {@link android.content.Intent#CATEGO and/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the intent filter category. For example:</p> <pre> -<intent-filter label="Resize Image"> +<intent-filter label="@string/resize_image"> ... <category android:name="android.intent.category.ALTERNATIVE" /> <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd index 7bc1cde..d104b4b 100644 --- a/docs/html/guide/topics/ui/notifiers/notifications.jd +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -16,6 +16,7 @@ user clicks it</li> <h2>In this document</h2> <ol> <li><a href="#Basics">The Basics</a></li> + <li><a href="#HandlingNotifications">Responding to Notifications</a></li> <li><a href="#ManageYourNotifications">Managing your Notifications</a></li> <li><a href="#CreateANotification">Creating a Notification</a> <ol> @@ -33,6 +34,12 @@ user clicks it</li> <li>{@link android.app.Notification}</li> <li>{@link android.app.NotificationManager}</li> </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}design/patterns/notifications.html">Android +Design: Notifications</a></li> + </ol> </div> </div> @@ -61,6 +68,14 @@ when selected by the user.</p> <p class="img-caption"><strong>Figure 2.</strong> The notifications window.</p> +<div class="design-announce"> +<p><strong>Notification Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/patterns/notifications.html">Notifications</a> guide.</p> +</div> + + + <h2 id="Basics">The Basics</h2> <p>An {@link android.app.Activity} or {@link android.app.Service} can initiate a status bar @@ -123,6 +138,134 @@ mNotificationManager.notify(HELLO_ID, notification); </ol> +<h2 id="HandlingNotifications">Responding to Notifications</h2> + +<p>A central part of the user's experience with a notification revolves around +how it interacts with the application's UI flow. You must implement +this correctly to provide a consistent user experience within your app.</p> + +<p>Two typical examples of notifications are provided by Calendar, which can send out +notifications of upcoming events, and Email, which can send out notifications +when new messages arrive. These represent the two recommended patterns for handling +notifications: either launching into an activity that is separate from the +main application, or launching an entirely new instance of the application +showing the appropriate point for the notification.</p> + +<p>The following scenario shows how the activity stack should work +in these two typical notification flows, first handling a Calendar notification: +</p> + +<ol> + <li>User is creating a new event in Calendar. They realize they + need to copy part of an email message into this event. + </li> + <li> + The user chooses Home > Email. + </li> + <li> + While in Email, they receive a notification from Calendar for an upcoming + meeting. + </li> + <li> + So they choose that notification, which takes them to a + dedicated Calendar activity that displays brief details of the + upcoming meeting. + </li> + <li> + The user has seen enough to know they have a meeting coming up, + so they press the <em>Back</em> button. They are now returned to Email, which + is where they were when they took the notification. + </li> +</ol> + +<p>Handling an Email notification:</p> + +<ol> + <li> + The user is currently in Email composing a message, and needs to + check a date in their calendar. + </li> + <li> + The user chooses Home > Calendar. + </li> + <li> + While in Calendar, they receive a notification from Email about a new + message. + </li> + <li> + They select the notification, which brings them to Email with the message + details displayed. This has replaced what they were previously doing + (writing an e-mail), but that message is still saved in their drafts. + </li> + <li> + The user presses <em>Back</em> once to go to the message list (the typical flow in the + Email app), and press <em>Back</em> again to return to Calendar as they left it. + </li> +</ol> + +<p>In an Email style of notification, the UI launched by the notification +shows the main application in a state representing that notification. +For example, when the Email application comes to the foreground from its +notification, it displays either the conversion list or a specific +conversation depending on whether there are multiple or only one new +email. To achieve this, we want to completely replace whatever current +state the application is in with a new activity stack representing the +new notification state.</p> + +<p>The following code illustrates how to show this kind of notification. Of +most interest is the <code>makeMessageIntentStack()</code> method, which constructs +an array of intents representing the app's new activity stack for this state. +(If you are using fragments, you may need to initialize your fragment and +app state so that pressing <em>Back</em> will switch the UI back to its parent state.) +The core of this is the {@link android.content.Intent#makeRestartActivityTask +Intent.makeRestartActivityTask()} method, which constructs the root activity +of the stack with the appropriate flags, such as +{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK Intent.FLAG_ACTIVITY_CLEAR_TASK}.</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + app_notification} + +<p>In a Calendar style of notification, the UI launched by the notification +is a dedicated activity that is not part of the normal application flow. +For example, when the user receives a Calendar notification, choosing that +notification starts a special activity that displays a list +of upcoming calendar events — this view is available only +from the notification, not through the Calendar's normal user +interface.</p> + +<p>The code for posting this type of notification is very straight-forward; it +is like the above, but the {@link android.app.PendingIntent} is for just a single +activity, our dedicated notification activity.</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + interstitial_notification} + +<p>This is not enough, however. Normally Android considers all activities within +an application to be part of that application's UI flow, so simply launching the +activity like this can cause it to be mixed with your normal application back stack +in undesired ways. To make it behave correctly, in the manifest declaration +for the activity the attributes +<code>android:launchMode="singleTask"</code>, +<code>android:taskAffinity=""</code> and +<code>android:excludeFromRecents="true"</code> +must be set. The full activity declaration for this sample is:</p> + +{@sample development/samples/ApiDemos/AndroidManifest.xml interstitial_affinity} + +<p>You must be careful when launching other activities from this initial activity, +because this is not a top-level part of the application, does not appear in +recents, and needs to be relaunched at any point from the notification with new data +to show. This best approach is to make sure any activity launched from it is +launched in its own task. When doing this care must be taken to make sure this +new task interacts well with the current state of your exiting application's +task. This is essentially +the same as switching to the main application as described for the Email style +notification shown before. Given the <code>makeMessageIntentStack()</code> +method previously shown, handling a click then would look something like this:</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessageInterstitial.java + app_launch} + <h2 id="ManageYourNotifications">Managing your Notifications</h2> <p>The {@link android.app.NotificationManager} is a system service that manages all diff --git a/docs/html/guide/topics/usb/accessory.jd b/docs/html/guide/topics/usb/accessory.jd index b0f4881..8b74bc0 100644 --- a/docs/html/guide/topics/usb/accessory.jd +++ b/docs/html/guide/topics/usb/accessory.jd @@ -169,8 +169,9 @@ UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXT include a <code><uses-feature></code> element that declares that your application uses the <code>android.hardware.usb.accessory</code> feature.</li> - <li>If you are using the <a href="addon">add-on library</a>, add the - <code><uses-library></code> element specifying + <li>If you are using the + <a href="http://code.google.com/android/add-ons/google-apis/index.html">add-on library</a>, + add the <code><uses-library></code> element specifying <code>com.android.future.usb.accessory</code> for the library.</li> <li>Set the minimum SDK of the application to API Level 10 if you are using the add-on library diff --git a/docs/html/guide/topics/usb/adk.jd b/docs/html/guide/topics/usb/adk.jd index 6c7ab0d..c8949a3 100644 --- a/docs/html/guide/topics/usb/adk.jd +++ b/docs/html/guide/topics/usb/adk.jd @@ -97,6 +97,9 @@ page.title=Android Open Accessory Development Kit <li><a href="http://www.sparkfun.com/products/10748"> SparkFun</a></li> + <li><a href="http://troido.de/de/shoplsmallgbuy-android-stufflsmallg"> + Troido</a></li> + </ol> </div> </div> @@ -281,16 +284,17 @@ page.title=Android Open Accessory Development Kit <p>On Mac:</p> <ol type="a"> - <li>Right-click on the Arduino application in Finder and select <strong>Show Package - Contents</strong>.</li> + <li>Create, if it does not already exist, an <code>Arduino</code> + directory inside your user account's <code>Documents</code> directory, and within + that, a <code>libraries</code> directory.</li> <li>Copy the <code>firmware/arduino_libs/AndroidAccessory</code> and - <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the complete directories, - not just the files within) to the <code>Contents/Resources/Java/libraries</code> directory - inside the Arduino application.</li> + <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the + complete directories, not just the files within) to your + <code>Documents/Arduino/libraries/</code> directory.</li> - <li>Create a <code>CapSense</code> directory in the - <code>Contents/Resources/Java/libraries</code> directory.</li> + <li>Create a <code>CapSense</code> directory in your + <code>Documents/Arduino/libraries/</code> directory.</li> <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense download to the <code>CapSense</code> directory.</li> @@ -699,7 +703,7 @@ bool AndroidAccessory::switchDevice(byte addr) </pre>If this method returns false, the board waits until a new device is connected. If it is successful, the device displays itself on the USB bus as being in accessory mode when the ADK board re-enumerates the bus. When the device is in accessory mode, the accessory then <a href= -"establish-adk">establishes communication with the device</a>. +"#establish-adk">establishes communication with the device</a>. <h3 id="establish-adk">Establish communication with the device</h3> diff --git a/docs/html/guide/topics/wireless/bluetooth.jd b/docs/html/guide/topics/wireless/bluetooth.jd index 0af1d2c..0567799 100644 --- a/docs/html/guide/topics/wireless/bluetooth.jd +++ b/docs/html/guide/topics/wireless/bluetooth.jd @@ -29,6 +29,7 @@ other devices</li> <li><a href="#Profiles">Working with Profiles</a> <ol> <li><a href="#AT-Commands">Vendor-specific AT commands</a> + <li><a href="#HDP">Health Device Profile</a> </ol></li> </ol> @@ -43,6 +44,7 @@ other devices</li> <h2>Related samples</h2> <ol> <li><a href="{@docRoot}resources/samples/BluetoothChat/index.html">Bluetooth Chat</a></li> + <li><a href="{@docRoot}resources/samples/BluetoothHDP/index.html">Bluetooth HDP (Health Device Profile)</a></li> </ol> </div> @@ -132,11 +134,27 @@ Headset and Hands-Free (v1.5) profiles.</dd> audio can be streamed from one device to another over a Bluetooth connection. "A2DP" stands for Advanced Audio Distribution Profile.</dd> -<dt>{@link android.bluetooth.BluetoothProfile.ServiceListener}</dt> +<dt>{@link android.bluetooth.BluetoothHealth}</dt> +<dd> Represents a Health Device Profile proxy that controls the Bluetooth service.</dd> + +<dt>{@link android.bluetooth.BluetoothHealthCallback}</dt> + +<dd>An abstract class that you use to implement {@link +android.bluetooth.BluetoothHealth} callbacks. You must extend this class and +implement the callback methods to receive updates about changes in the +application’s registration state and Bluetooth channel state.</dd> + +<dt>{@link android.bluetooth.BluetoothHealthAppConfiguration}</dt> + +<dd>Represents an application configuration that the Bluetooth Health third-party +application registers to communicate with a remote Bluetooth health +device.</dd> + +<dt>{@link android.bluetooth.BluetoothProfile.ServiceListener}</dt> <dd>An interface that notifies {@link android.bluetooth.BluetoothProfile} IPC clients when they have been connected to or disconnected from the service (that -is, the internal service that runs a particular profile). </dd> +is, the internal service that runs a particular profile). </dd> </dl> @@ -231,12 +249,20 @@ if (!mBluetoothAdapter.isEnabled()) { <p>A dialog will appear requesting user permission to enable Bluetooth, as shown in Figure 1. If the user responds "Yes," the system will begin to enable Bluetooth and focus will return to your application once the process completes (or fails).</p> -<p>If enabling Bluetooth succeeds, your Activity will receive the {@link + +<p>The {@code REQUEST_ENABLE_BT} constant passed to {@link +android.app.Activity#startActivityForResult(Intent,int) startActivityForResult()} is a locally +defined integer (which must be greater than 0), that the system passes back to you in your +{@link +android.app.Activity#onActivityResult(int,int,Intent) onActivityResult()} implementation as the +<code>requestCode</code> parameter.</p> + +<p>If enabling Bluetooth succeeds, your activity receives the {@link android.app.Activity#RESULT_OK} result code in the {@link android.app.Activity#onActivityResult(int,int,Intent) onActivityResult()} callback. If Bluetooth was not enabled -due to an error (or the user responded "No") then the result code will be {@link -android.app.Activity#RESULT_CANCELED}.</p> +due to an error (or the user responded "No") then the result code is {@link +android.app.Activity#RESULT_CANCELED}.</p> </li> </ol> @@ -413,11 +439,11 @@ startActivity(discoverableIntent); <p>A dialog will be displayed, requesting user permission to make the device discoverable, as shown in Figure 2. If the user responds "Yes," then the device -will become discoverable for the specified amount of time. Your Activity will +will become discoverable for the specified amount of time. Your activity will then receive a call to the {@link android.app.Activity#onActivityResult(int,int,Intent) onActivityResult())} callback, with the result code equal to the duration that the device is discoverable. If the user responded "No" or if an error occurred, the result code will -be Activity.RESULT_CANCELLED.</p> +be {@link android.app.Activity#RESULT_CANCELED}.</p> <p class="note"><strong>Note:</strong> If Bluetooth has not been enabled on the device, then enabling device discoverability will automatically enable Bluetooth.</p> @@ -550,7 +576,7 @@ socket.</p> </ol> <p>The {@link android.bluetooth.BluetoothServerSocket#accept()} call should not -be executed in the main Activity UI thread because it is a blocking call and +be executed in the main activity UI thread because it is a blocking call and will prevent any other interaction with the application. It usually makes sense to do all work with a {@link android.bluetooth.BluetoothServerSocket} or {@link android.bluetooth.BluetoothSocket} in a new @@ -678,7 +704,7 @@ android.bluetooth.BluetoothSocket#connect()} method times out (after about 12 seconds), then it will throw an exception.</p> <p>Because {@link android.bluetooth.BluetoothSocket#connect()} is a blocking call, this connection -procedure should always be performed in a thread separate from the main Activity +procedure should always be performed in a thread separate from the main activity thread.</p> <p class="note">Note: You should always ensure that the device is not performing device discovery when you call {@link @@ -820,7 +846,7 @@ private class ConnectedThread extends Thread { try { // Read from the InputStream bytes = mmInStream.read(buffer); - // Send the obtained bytes to the UI Activity + // Send the obtained bytes to the UI activity mHandler.obtainMessage(MESSAGE_READ, bytes, -1, buffer) .sendToTarget(); } catch (IOException e) { @@ -829,14 +855,14 @@ private class ConnectedThread extends Thread { } } - /* Call this from the main Activity to send data to the remote device */ + /* Call this from the main activity to send data to the remote device */ public void write(byte[] bytes) { try { mmOutStream.write(bytes); } catch (IOException e) { } } - /* Call this from the main Activity to shutdown the connection */ + /* Call this from the main activity to shutdown the connection */ public void cancel() { try { mmSocket.close(); @@ -848,12 +874,12 @@ private class ConnectedThread extends Thread { <p>The constructor acquires the necessary streams and once executed, the thread will wait for data to come through the InputStream. When {@link java.io.InputStream#read(byte[])} returns with -bytes from the stream, the data is sent to the main Activity using a member +bytes from the stream, the data is sent to the main activity using a member Handler from the parent class. Then it goes back and waits for more bytes from the stream.</p> <p>Sending outgoing data is as simple as calling the thread's -<code>write()</code> method from the main Activity and passing in the bytes to +<code>write()</code> method from the main activity and passing in the bytes to be sent. This method then simply calls {@link java.io.OutputStream#write(byte[])} to send the data to the remote device.</p> @@ -889,7 +915,7 @@ Bluetooth Headset Service via interprocess communication (<a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#IPC">IPC</a >). This includes both Bluetooth Headset and Hands-Free (v1.5) profiles. The {@link android.bluetooth.BluetoothHeadset} class includes support for AT commands. -For more discussion of this topic, see <a href="#AT-Commands">Vendor-specific AT commands</a></li> +For more discussion of this topic, see <a href="#AT-Commands">Vendor-specific AT commands</a></li> <li><strong>A2DP</strong>. The Advanced Audio Distribution Profile (A2DP) profile defines how high quality audio can be streamed from one device to @@ -897,13 +923,25 @@ another over a Bluetooth connection. Android provides the {@link android.bluetooth.BluetoothA2dp} class, which is a proxy for controlling the Bluetooth A2DP Service via IPC.</li> + <li><strong>Health Device</strong>. Android 4.0 (API level 14) introduces +support for the Bluetooth Health Device Profile (HDP). This lets you create +applications that use Bluetooth to communicate with health devices that support +Bluetooth, such as heart-rate monitors, blood meters, thermometers, scales, and +so on. For a list of supported devices and their corresponding device data +specialization codes, refer to <strong>Bluetooth Assigned Numbers</strong> at <a +href="http://www.bluetooth.org">www.bluetooth.org</a>. Note that these values +are also referenced in the ISO/IEEE 11073-20601 [7] specification as +MDC_DEV_SPEC_PROFILE_* in the Nomenclature Codes Annex. For more discussion of +HDP, see <a href="#HDP">Health Device Profile</a>.</li> + </ul> <p>Here are the basic steps for working with a profile:</p> <ol> - <li>Get the default adapter, as described in <a href="{@docRoot}guide/topics/wireless/bluetooth. -html#SettingUp">Setting Up Bluetooth</a>.</li> + <li>Get the default adapter, as described in + <a href="{@docRoot}guide/topics/wireless/bluetooth.html#SettingUp">Setting Up + Bluetooth</a>.</li> <li>Use {@link android.bluetooth.BluetoothAdapter#getProfileProxy(android.content.Context, @@ -925,7 +963,9 @@ to the profile proxy object.</li> state of the connection and perform other operations that are relevant to that profile.</li> </ol> -<p> For example, this code snippet shows how to connect to a {@link android.bluetooth.BluetoothHeadset} proxy object so that you can control the + +<p> For example, this code snippet shows how to connect to a {@link +android.bluetooth.BluetoothHeadset} proxy object so that you can control the Headset profile:</p> <pre>BluetoothHeadset mBluetoothHeadset; @@ -955,6 +995,8 @@ private BluetoothProfile.ServiceListener mProfileListener = new BluetoothProfile mBluetoothAdapter.closeProfileProxy(mBluetoothHeadset); </pre> + + <h3 id="AT-Commands">Vendor-specific AT commands</h3> <p>Starting in Android 3.0, applications can register to receive system @@ -964,3 +1006,81 @@ broadcasts that indicate a connected device's battery level and could notify the user or take other action as needed. Create a broadcast receiver for the {@link android.bluetooth.BluetoothHeadset#ACTION_VENDOR_SPECIFIC_HEADSET_EVENT} intent to handle vendor-specific AT commands for the headset.</p> + +<h3 id="HDP">Health Device Profile</h3> + +<p>Android 4.0 (API level 14) introduces support for the Bluetooth Health Device +Profile (HDP). This lets you create applications that use Bluetooth to +communicate with health devices that support Bluetooth, such as heart-rate +monitors, blood meters, thermometers, and scales. The Bluetooth Health API +includes the classes {@link android.bluetooth.BluetoothHealth}, {@link +android.bluetooth.BluetoothHealthCallback}, and {@link +android.bluetooth.BluetoothHealthAppConfiguration}, which are described in <a +href="#TheBasics">The Basics</a>. </p> + +<p>In using the Bluetooth Health API, it's helpful to understand these key HDP concepts:</p> +<table> + <tr> + <th>Concept</th> + <th>Description</th> + </tr> + <tr> + <td><strong>Source</strong></td> + + <td>A role defined in HDP. A <em>source</em> is a health device that +transmits medical data (weight scale, glucose meter, thermometer, etc.) to a +smart device such as an Android phone or tablet. </td> + </tr> + <tr> + <td><strong>Sink</strong></td> + + <td>A role defined in HDP. In HDP, a <em>sink</em> is the smart device that +receives the medical data. In an Android HDP application, the sink is +represented by a {@link android.bluetooth.BluetoothHealthAppConfiguration} +object.</td> + </tr> + <tr> + <td><strong>Registration</strong></td> + <td>Refers to registering a sink for a particular health device.</td> + </tr> + <tr> + <td><strong>Connection</strong></td> + + <td>Refers to opening a channel between a health device and a smart device +such as an Android phone or tablet.</td> + </tr> +</table> + +<h4>Creating an HDP Application</h4> + +<p>Here are the basic steps involved in creating an Android HDP application:</p> +<ol> + + <li>Get a reference to the {@link android.bluetooth.BluetoothHealth} proxy +object. <p>Similar to regular headset and A2DP profile devices, you must call +{@link android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} +with a {@link android.bluetooth.BluetoothProfile.ServiceListener} and the {@link +android.bluetooth.BluetoothProfile.ServiceListener#HEALTH} profile type to +establish a connection with the profile proxy object.</p> </li> + + <li>Create a {@link android.bluetooth.BluetoothHealthCallback} and register an +application configuration +({@link android.bluetooth.BluetoothHealthAppConfiguration}) +that acts as a health +sink.</li> + + <li>Establish a connection to a health device. Some devices will initiate the +connection. It is unnecessary to carry out this step for those devices.</li> + + <li>When connected successfully to a health device, read/write to the health +device using the file descriptor. <p>The received data needs to be interpreted +using a health manager which implements the IEEE 11073-xxxxx +specifications.</p></li> + + <li>When done, close the health channel and unregister the application. The +channel also closes when there is extended inactivity.</li> +</ol> + +<p>For a complete code sample that illustrates these steps, see <a +href="{@docRoot}resources/samples/BluetoothHDP/index.html">Bluetooth HDP (Health +Device Profile)</a>. </p> diff --git a/docs/html/guide/topics/wireless/wifip2p.jd b/docs/html/guide/topics/wireless/wifip2p.jd new file mode 100644 index 0000000..82c9abd --- /dev/null +++ b/docs/html/guide/topics/wireless/wifip2p.jd @@ -0,0 +1,611 @@ +page.title=Wi-Fi Direct + +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li><a href="#api">API Overview</a></li> + <li><a href="#creating-br">Creating a Broadcast Receiver for Wi-Fi Direct Intents</a></li> + + <li> + <a href="#creating-app">Creating a Wi-Fi Direct Application</a> + + <ol> + <li><a href="#setup">Initial setup</a></li> + + <li><a href="#discovering">Discovering peers</a></li> + + <li><a href="#connecting">Connecting to peers</a></li> + + <li><a href="#transferring">Transferring data</a></li> + </ol> + </li> + </ol> + <h2>Related Samples</h2> + <ol> + <li><a href="{@docRoot}resources/samples/WiFiDirectDemo/index.html">Wi-Fi Direct Demo</a></li> + </ol> + </div> + </div> + + <p>Wi-Fi Direct allows Android 4.0 (API level 14) or later devices with the appropriate hardware + to connect directly to each other via Wi-Fi without an intermediate access point. + Using these APIs, you can discover and connect to other devices when each device supports Wi-Fi Direct, + then communicate over a speedy connection across distances much longer than a Bluetooth connection. + This is useful for applications that share data among users, such as a multiplayer game or + a photo sharing application.</p> + + <p>The Wi-Fi Direct APIs consist of the following main parts:</p> + + <ul> + <li>Methods that allow you to discover, request, and connect to peers are defined + in the {@link android.net.wifi.p2p.WifiP2pManager} class.</li> + + <li>Listeners that allow you to be notified of the success or failure of {@link + android.net.wifi.p2p.WifiP2pManager} method calls. When calling {@link + android.net.wifi.p2p.WifiP2pManager} methods, each method can receive a specific listener + passed in as a parameter.</li> + + <li>Intents that notify you of specific events detected by the Wi-Fi Direct framework, + such as a dropped connection or a newly discovered peer.</li> + </ul> + + <p>You often use these three main components of the APIs together. For example, you can + provide a {@link android.net.wifi.p2p.WifiP2pManager.ActionListener} to a call to {@link + android.net.wifi.p2p.WifiP2pManager#discoverPeers discoverPeers()}, so that you can be + notified with the {@link android.net.wifi.p2p.WifiP2pManager.ActionListener#onSuccess + ActionListener.onSuccess()} and {@link android.net.wifi.p2p.WifiP2pManager.ActionListener#onFailure + ActionListener.onFailure()} + methods. A {@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_PEERS_CHANGED_ACTION} intent is + also broadcast if the {@link android.net.wifi.p2p.WifiP2pManager#discoverPeers discoverPeers()} + method discovers that the peers list has changed.</p> + + <h2 id="api">API Overview</h2> + +<p>The {@link android.net.wifi.p2p.WifiP2pManager} class provides methods to allow you to interact with + the Wi-Fi hardware on your device to do things like discover and connect to peers. The following actions + are available:</p> + +<p class="table-caption"><strong>Table 1.</strong>Wi-Fi Direct Methods</p> + + <table> + <tr> + <th>Method</th> + <th>Description</th> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#initialize initialize()}</td> + <td>Registers the application with the Wi-Fi framework. This must be called before calling any other Wi-Fi Direct method.</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#connect connect()}</td> + <td>Starts a peer-to-peer connection with a device with the specified configuration.</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#cancelConnect cancelConnect()}</td> + <td>Cancels any ongoing peer-to-peer group negotiation.</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#requestConnectionInfo requestConnectInfo()}</td> + <td>Requests a device's connection information.</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#createGroup createGroup()}</td> + <td>Creates a peer-to-peer group with the current device as the group owner.</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#removeGroup removeGroup()}</td> + <td>Removes the current peer-to-peer group.</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#requestGroupInfo requestGroupInfo()}</td> + <td>Requests peer-to-peer group information.</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager.PeerListListener#discoverPeers discoverPeers()}</td> + <td>Initiates peer discovery </td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#requestPeers requestPeers()}</td> + <td>Requests the current list of discovered peers.</td> + </tr> + </table> + + + <p>{@link android.net.wifi.p2p.WifiP2pManager} methods let you pass in a listener, + so that the Wi-Fi Direct framework can notify your + activity of the status of a call. The available listener interfaces and the + corresponding {@link android.net.wifi.p2p.WifiP2pManager} method calls that use the listeners + are described in the following table:</p> + + <p class="table-caption"><strong>Table 2.</strong> Wi-Fi Direct Listeners</p> + + <table> + <tr> + <th>Listener interface</th> + <th>Associated actions</th> + </tr> + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager.ActionListener}</td> + <td>{@link android.net.wifi.p2p.WifiP2pManager#connect connect()}, {@link + android.net.wifi.p2p.WifiP2pManager#cancelConnect cancelConnect()}, {@link + android.net.wifi.p2p.WifiP2pManager#createGroup createGroup()}, {@link + android.net.wifi.p2p.WifiP2pManager#removeGroup removeGroup()}, and {@link + android.net.wifi.p2p.WifiP2pManager.PeerListListener#discoverPeers discoverPeers()}</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager.ChannelListener}</td> + <td>{@link android.net.wifi.p2p.WifiP2pManager#initialize initialize()}</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager.ConnectionInfoListener}</td> + <td>{@link android.net.wifi.p2p.WifiP2pManager#requestConnectionInfo requestConnectInfo()}</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager.GroupInfoListener}</td> + <td>{@link android.net.wifi.p2p.WifiP2pManager#requestGroupInfo requestGroupInfo()}</td> + </tr> + + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager.PeerListListener}</td> + <td>{@link android.net.wifi.p2p.WifiP2pManager#requestPeers requestPeers()}</td> + </tr> + </table> + +<p>The Wi-Fi Direct APIs define intents that are broadcast when certain Wi-Fi Direct events happen, + such as when a new peer is discovered or when a device's Wi-Fi state changes. You can register + to receive these intents in your application by <a href="#creating-br">creating a broadcast + receiver</a> that handles these intents:</p> + +<p class="table-caption"><strong>Table 3.</strong> Wi-Fi Direct Intents</p> + + <table> + <tr> + <th>Intent</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_CONNECTION_CHANGED_ACTION}</td> + <td>Broadcast when the state of the device's Wi-Fi connection changes.</td> + </tr> + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_PEERS_CHANGED_ACTION}</td> + <td>Broadcast when you call {@link + android.net.wifi.p2p.WifiP2pManager.PeerListListener#discoverPeers discoverPeers()}. You + usually want to call {@link android.net.wifi.p2p.WifiP2pManager.PeerListListener#requestPeers + requestPeers()} to get an updated list of peers if you handle this intent in your + application.</td> + </tr> + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_CHANGED_ACTION}</td> + <td>Broadcast when Wi-Fi Direct is enabled or disabled on the device.</td> + </tr> + <tr> + <td>{@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_THIS_DEVICE_CHANGED_ACTION}</td> + <td>Broadcast when a device's details have changed, such as the device's name.</td> + </tr> + </table> + + + + <h2 id="creating-br">Creating a Broadcast Receiver for Wi-Fi Direct Intents</h2> + + <p>A broadcast receiver allows you to receive intents broadcast by the Android system, + so that your application can respond to events that you are interested in. The basic steps + for creating a broadcast receiver to handle Wi-Fi Direct intents are as follows:</p> + + <ol> + <li>Create a class that extends the {@link android.content.BroadcastReceiver} class. For the + class' constructor, you most likely want to have parameters for the {@link + android.net.wifi.p2p.WifiP2pManager}, {@link android.net.wifi.p2p.WifiP2pManager.Channel}, and + the activity that this broadcast receiver will be registered in. This allows the broadcast + receiver to send updates to the activity as well as have access to the Wi-Fi hardware and a + communication channel if needed.</li> + + <li>In the broadcast receiver, check for the intents that you are interested in + <code>{@link android.content.BroadcastReceiver#onReceive onReceive()}</code>. + Carry out any necessary actions depending on the intent that is + received. For example, if the broadcast receiver receives a {@link + android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_PEERS_CHANGED_ACTION} intent, you can call the + {@link android.net.wifi.p2p.WifiP2pManager#requestPeers requestPeers()} method to get a list of + the currently discovered peers.</li> + </ol> + + <p>The following code shows you how to create a typical broadcast receiver. The broadcast + receiver takes a {@link android.net.wifi.p2p.WifiP2pManager} object and an activity as + arguments and uses these two classes to appropriately carry out the needed actions when the + broadcast receiver receives an intent:</p> + +<pre> +/** + * A BroadcastReceiver that notifies of important Wi-Fi p2p events. + */ +public class WiFiDirectBroadcastReceiver extends BroadcastReceiver { + + private WifiP2pManager manager; + private Channel channel; + private MyWiFiActivity activity; + + public WiFiDirectBroadcastReceiver(WifiP2pManager manager, Channel channel, + MyWifiActivity activity) { + super(); + this.manager = manager; + this.channel = channel; + this.activity = activity; + } + + @Override + public void onReceive(Context context, Intent intent) { + String action = intent.getAction(); + + if (WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION.equals(action)) { + // Check to see if Wi-Fi is enabled and notify appropriate activity + } else if (WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION.equals(action)) { + // Call WifiP2pManager.requestPeers() to get a list of current peers + } else if (WifiP2pManager.WIFI_P2P_CONNECTION_CHANGED_ACTION.equals(action)) { + // Respond to new connection or disconnections + } else if (WifiP2pManager.WIFI_P2P_THIS_DEVICE_CHANGED_ACTION.equals(action)) { + // Respond to this device's wifi state changing + } + } +} +</pre> + + <h2 id="creating-app">Creating a Wi-Fi Direct Application</h2> + + <p>Creating a Wi-Fi Direct application involves creating and registering a + broadcast receiver for your application, discovering peers, connecting to a peer, and + transferring data to a peer. The following sections describe how to do this.</p> + + <h3 id="setup">Initial setup</h3> + <p>Before using the Wi-Fi Direct APIs, you must ensure that your application can access + the hardware and that the device supports the Wi-Fi Direct protocol. If Wi-Fi Direct is supported, + you can obtain an instance of {@link android.net.wifi.p2p.WifiP2pManager}, create and register + your broadcast receiver, and begin using the Wi-Fi Direct APIs.</p> + <ol> + <li> + <p>Request permission to use the Wi-Fi hardware on the device and also declare + your application to have the correct minimum SDK version in the Android manifest:</p> + <pre> +<uses-sdk android:minSdkVersion="14" /> +<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> +<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /> +<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> +<uses-permission android:name="android.permission.INTERNET" /> +<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> +</pre> + </li> + + <li>Check to see if Wi-Fi Direct is on and supported. A good place to check this is in your + broadcast receiver when it receives the {@link + android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_STATE_CHANGED_ACTION} intent. Notify your + activity of the Wi-Fi Direct state and react accordingly: +<pre> +@Override +public void onReceive(Context context, Intent intent) { + ... + String action = intent.getAction(); + if (WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION.equals(action)) { + int state = intent.getIntExtra(WifiP2pManager.EXTRA_WIFI_STATE, -1); + if (state == WifiP2pManager.WIFI_P2P_STATE_ENABLED) { + // Wifi Direct is enabled + } else { + // Wi-Fi Direct is not enabled + } + } + ... +} +</pre> + </li> + + <li>In your activity's {@link android.app.Activity#onCreate onCreate()} method, obtain an instance of {@link + android.net.wifi.p2p.WifiP2pManager} and register your application with the Wi-Fi Direct + framework by calling {@link android.net.wifi.p2p.WifiP2pManager#initialize initialize()}. This + method returns a {@link android.net.wifi.p2p.WifiP2pManager.Channel}, which is used to connect + your application to the Wi-Fi Direct framework. You should also create an instance of your + broadcast receiver with the {@link + android.net.wifi.p2p.WifiP2pManager} and {@link android.net.wifi.p2p.WifiP2pManager.Channel} + objects along with a reference to your activity. This allows your broadcast receiver to notify + your activity of interesting events and update it accordingly. It also lets you manipulate the device's + Wi-Fi state if necessary: +<pre> +WifiP2pManager mManager; +Channel mChannel; +BroadcastReceiver mReceiver; +... +@Override +protected void onCreate(Bundle savedInstanceState){ + ... + mManager = (WifiP2pManager) getSystemService(Context.WIFI_P2P_SERVICE); + mChannel = mManager.initialize(this, getMainLooper(), null); + mReceiver = new WiFiDirectBroadcastReceiver(manager, channel, this); + ... +} +</pre> + </li> + + <li>Create an intent filter and add the same intents that your + broadcast receiver checks for: + <pre> +IntentFilter mIntentFilter; +... +@Override +protected void onCreate(Bundle savedInstanceState){ + ... + mIntentFilter = new IntentFilter(); + mIntentFilter.addAction(WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION); + mIntentFilter.addAction(WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION); + mIntentFilter.addAction(WifiP2pManager.WIFI_P2P_CONNECTION_CHANGED_ACTION); + mIntentFilter.addAction(WifiP2pManager.WIFI_P2P_THIS_DEVICE_CHANGED_ACTION); + ... +} +</pre> + </li> + + <li>Register the broadcast receiver in the {@link android.app.Activity#onResume()} method + of your activity and unregister it in the {@link android.app.Activity#onPause()} method of your activity: + <pre> +/* register the broadcast receiver with the intent values to be matched */ +@Override +protected void onResume() { + super.onResume(); + registerReceiver(mReceiver, mIntentFilter); +} +/* unregister the broadcast receiver */ +@Override +protected void onPause() { + super.onPause(); + unregisterReceiver(mReceiver); +} +</pre> + + <p>When you have obtained a {@link android.net.wifi.p2p.WifiP2pManager.Channel} and + set up a broadcast receiver, your application can make Wi-Fi Direct method calls and receive + Wi-Fi Direct intents.</p> + </li> + + <p>You can now implement your application and use the Wi-Fi Direct features by calling the + methods in {@link android.net.wifi.p2p.WifiP2pManager}. The next sections describe how to do common actions + such as discovering and connecting to peers.</p> + </ol> + + <h3 id="discovering">Discovering peers</h3> + + <p>To discover peers that are available to connect to, call {@link + android.net.wifi.p2p.WifiP2pManager#discoverPeers discoverPeers()} to detect + available peers that are in range. The call to this function is asynchronous and a success or + failure is communicated to your application with {@link + android.net.wifi.p2p.WifiP2pManager.ActionListener#onSuccess onSuccess()} and {@link + android.net.wifi.p2p.WifiP2pManager.ActionListener#onFailure onFailure()} if you created a + {@link android.net.wifi.p2p.WifiP2pManager.ActionListener}. The + {@link android.net.wifi.p2p.WifiP2pManager.ActionListener#onSuccess onSuccess()} method only notifies you + that the discovery process succeeded and does not provide any information about the actual peers + that it discovered, if any:</p> + <pre> +manager.discoverPeers(channel, new WifiP2pManager.ActionListener() { + @Override + public void onSuccess() { + ... + } + + @Override + public void onFailure(int reasonCode) { + ... + } +}); + +</pre> + +<p>If the discovery process succeeds and detects peers, the system broadcasts the {@link + android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_PEERS_CHANGED_ACTION} intent, which you can listen + for in a broadcast receiver to obtain a list of peers. When your application receives the {@link + android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_PEERS_CHANGED_ACTION} intent, you can request a + list of the discovered peers with {@link + android.net.wifi.p2p.WifiP2pManager#requestPeers requestPeers()}. The following code shows how to set this up:</p> + <pre> +PeerListListener myPeerListListener; +... +if (WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION.equals(action)) { + + // request available peers from the wifi p2p manager. This is an + // asynchronous call and the calling activity is notified with a + // callback on PeerListListener.onPeersAvailable() + if (manager != null) { + manager.requestPeers(channel, myPeerListListener); + } +} +</pre> + + <p>The {@link android.net.wifi.p2p.WifiP2pManager#requestPeers requestPeers()} method is also + asynchronous and can notify your activity when a list of peers is available with {@link + android.net.wifi.p2p.WifiP2pManager.PeerListListener#onPeersAvailable onPeersAvailable()}, which is defined in the + the {@link android.net.wifi.p2p.WifiP2pManager.PeerListListener} interface. The {@link + android.net.wifi.p2p.WifiP2pManager.PeerListListener#onPeersAvailable onPeersAvailable()} method + provides you with an {@link android.net.wifi.p2p.WifiP2pDeviceList}, which you can iterate + through to find the peer that you want to connect to.</p> + + <h3 id="connecting">Connecting to peers</h3> + + <p>When you have figured out the device that you want to connect to after obtaining a list of + possible peers, call the {@link android.net.wifi.p2p.WifiP2pManager#connect connect()} method to + connect to the device. This method call requires a {@link android.net.wifi.p2p.WifiP2pConfig} + object that contains the information of the device to connect to. + You can be notified of a connection success or failure through the {@link + android.net.wifi.p2p.WifiP2pManager.ActionListener}. The following code + shows you how to create a connection to a desired device:</p> + <pre> +//obtain a peer from the WifiP2pDeviceList +WifiP2pDevice device; +WifiP2pConfig config = new WifiP2pConfig(); +config.deviceAddress = device.deviceAddress; +manager.connect(channel, config, new ActionListener() { + + @Override + public void onSuccess() { + //success logic + } + + @Override + public void onFailure(int reason) { + //failure logic + } +}); + +</pre> + + + <h3 id="transferring">Transferring data</h3> + <p>Once a connection is established, you can transfer data between the devices with + sockets. The basic steps of transferring data are as follows:</p> + + <ol> + <li>Create a {@link java.net.ServerSocket}. This socket waits for a connection from a client on a specified + port and blocks until it happens, so do this in a background thread.</li> + + <li>Create a client {@link java.net.Socket}. The client uses the IP address and port of + the server socket to connect to the server device.</li> + + <li>Send data from the client to the server. When the client + socket successfully connects to the server socket, you can send data from the client to the server + with byte streams. </li> + + <li>The server socket waits for a client connection (with the {@link java.net.ServerSocket#accept()} method). This + call blocks until a client connects, so call this is another thread. When a connection happens, the server device can receive + the data from the client. Carry out any actions with this data, such as saving it to a file + or presenting it to the user.</li> + </ol> + + <p>The following example, modified from the <a href= + "{@docRoot}resources/samples/WiFiDirectDemo/index.html">Wi-Fi Direct Demo</a> sample, shows you how + to create this client-server socket communication and transfer JPEG images from a client + to a server with a service. For a complete working example, compile and run the <a href= + "{@docRoot}resources/samples/WiFiDirectDemo/index.html">Wi-Fi Direct Demo</a> sample.</p> +<pre> +public static class FileServerAsyncTask extends AsyncTask<Void, Void, String> { + + private Context context; + private TextView statusText; + + public FileServerAsyncTask(Context context, View statusText) { + this.context = context; + this.statusText = (TextView) statusText; + } + + @Override + protected String doInBackground(Void... params) { + try { + + /** + * Create a server socket and wait for client connections. This + * call blocks until a connection is accepted from a client + */ + ServerSocket serverSocket = new ServerSocket(8888); + Socket client = serverSocket.accept(); + + /** + * If this code is reached, a client has connected and transferred data + * Save the input stream from the client as a JPEG file + */ + final File f = new File(Environment.getExternalStorageDirectory() + "/" + + context.getPackageName() + "/wifip2pshared-" + System.currentTimeMillis() + + ".jpg"); + + File dirs = new File(f.getParent()); + if (!dirs.exists()) + dirs.mkdirs(); + f.createNewFile(); + InputStream inputstream = client.getInputStream(); + copyFile(inputstream, new FileOutputStream(f)); + serverSocket.close(); + return f.getAbsolutePath(); + } catch (IOException e) { + Log.e(WiFiDirectActivity.TAG, e.getMessage()); + return null; + } + } + + /** + * Start activity that can handle the JPEG image + */ + @Override + protected void onPostExecute(String result) { + if (result != null) { + statusText.setText("File copied - " + result); + Intent intent = new Intent(); + intent.setAction(android.content.Intent.ACTION_VIEW); + intent.setDataAndType(Uri.parse("file://" + result), "image/*"); + context.startActivity(intent); + } + } +} +</pre> + + <p>On the client, connect to the server socket with a client socket and transfer data. This example + transfers a JPEG file on the client device's file system.</p> + +<pre> +Context context = this.getApplicationContext(); +String host; +int port; +int len; +Socket socket = new Socket(); +byte buf[] = new byte[1024]; +... +try { + /** + * Create a client socket with the host, + * port, and timeout information. + */ + socket.bind(null); + socket.connect((new InetSocketAddress(host, port)), 500); + + /** + * Create a byte stream from a JPEG file and pipe it to the output stream + * of the socket. This data will be retrieved by the server device. + */ + OutputStream outputStream = socket.getOutputStream(); + ContentResolver cr = context.getContentResolver(); + InputStream inputStream = null; + inputStream = cr.openInputStream(Uri.parse("path/to/picture.jpg")); + while ((len = inputStream.read(buf)) != -1) { + outputStream.write(buf, 0, len); + } + outputStream.close(); + inputStream.close(); +} catch (FileNotFoundException e) { + //catch logic +} catch (IOException e) { + //catch logic +} + +/** + * Clean up any open sockets when done + * transferring or if an exception occurred. + */ +finally { + if (socket != null) { + if (socket.isConnected()) { + try { + socket.close(); + } catch (IOException e) { + //catch logic + } + } + } +} +</pre> diff --git a/docs/html/guide/tutorials/views/hello-mapview.jd b/docs/html/guide/tutorials/views/hello-mapview.jd index 458db4f..5217b6b 100644 --- a/docs/html/guide/tutorials/views/hello-mapview.jd +++ b/docs/html/guide/tutorials/views/hello-mapview.jd @@ -14,8 +14,8 @@ location:</p> href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> <p>The Google APIs add-on requires Android 1.5 SDK or later release. After -installing the add-on in your SDK, set your project properties to use the build -target called "Google APIs Add-on". See the instructions for setting a build +installing the add-on in your SDK, set your project properties to use a <strong>Google +APIs</strong> build target. See the instructions for setting a build target in <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>, diff --git a/docs/html/guide/webapps/webview.jd b/docs/html/guide/webapps/webview.jd index ed28f21..66b5501 100644 --- a/docs/html/guide/webapps/webview.jd +++ b/docs/html/guide/webapps/webview.jd @@ -298,18 +298,18 @@ history of visited web pages. You can navigate backward and forward through the history with {@link android.webkit.WebView#goBack()} and {@link android.webkit.WebView#goForward()}.</p> -<p>For example, here's how your {@link android.app.Activity} can use the device BACK key to navigate -backward:</p> +<p>For example, here's how your {@link android.app.Activity} can use the device <em>Back</em> button +to navigate backward:</p> <pre> @Override public boolean {@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown}(int keyCode, KeyEvent event) { - // Check if the key event was the BACK key and if there's history + // Check if the key event was the Back button and if there's history if ((keyCode == KeyEvent.KEYCODE_BACK) && myWebView.{@link android.webkit.WebView#canGoBack() canGoBack}() { myWebView.{@link android.webkit.WebView#goBack() goBack}(); return true; } - // If it wasn't the BACK key or there's no web page history, bubble up to the default + // If it wasn't the Back key or there's no web page history, bubble up to the default // system behavior (probably exit the activity) return super.onKeyDown(keyCode, event); } |