diff options
| author | Scott Main <smain@google.com> | 2012-06-21 17:14:39 -0700 |
|---|---|---|
| committer | Scott Main <smain@google.com> | 2012-06-21 21:27:30 -0700 |
| commit | 50e990c64fa23ce94efa76b9e72df7f8ec3cee6a (patch) | |
| tree | 52605cd25e01763596477956963fabcd087054b0 /docs/html/guide/appendix | |
| parent | a2860267cad115659018d636bf9203a644c680a7 (diff) | |
| download | frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.zip frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.tar.gz frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.tar.bz2 | |
Massive clobber of all HTML files in developer docs for new site design
Change-Id: Idc55a0b368c1d2c1e7d4999601b739dd57f08eb3
Diffstat (limited to 'docs/html/guide/appendix')
| -rw-r--r-- | docs/html/guide/appendix/api-levels.jd | 421 | ||||
| -rw-r--r-- | docs/html/guide/appendix/g-app-intents.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/appendix/glossary.jd | 8 | ||||
| -rw-r--r-- | docs/html/guide/appendix/install-location.jd | 4 | ||||
| -rw-r--r-- | docs/html/guide/appendix/market-filters.jd | 454 | ||||
| -rw-r--r-- | docs/html/guide/appendix/media-formats.jd | 6 |
6 files changed, 10 insertions, 885 deletions
diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd deleted file mode 100644 index bc7d83b..0000000 --- a/docs/html/guide/appendix/api-levels.jd +++ /dev/null @@ -1,421 +0,0 @@ -page.title=Android API Levels -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> -<ol> - <li><a href="#intro">What is API Level?</a></li> - <li><a href="#uses">Uses of API Level in Android</a></li> - <li><a href="#considerations">Development Considerations</a> - <ol> - <li><a href="#fc">Application forward compatibility</a></li> - <li><a href="#bc">Application backward compatibility</a></li> - <li><a href="#platform">Selecting a platform version and API Level</a></li> - <li><a href="#apilevel">Declaring a minimum API Level</a></li> - <li><a href="#testing">Testing against higher API Levels</a></li> - </ol> - </li> - <li><a href="#provisional">Using a Provisional API Level</a></li> - <li><a href="#filtering">Filtering the Documentation</a></li> -</ol> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> manifest element</li> - </ol> - -</div> -</div> - -<p>As you develop your application on Android, it's useful to understand the -platform's general approach to API change management. It's also important to -understand the API Level identifier and the role it plays in ensuring your -application's compatibility with devices on which it may be installed. </p> - -<p>The sections below provide information about API Level and how it affects -your applications. </p> - -<p>For information about how to use the "Filter by API Level" control -available in the API reference documentation, see -<a href="#filtering">Filtering the documentation</a> at the -end of this document. </p> - -<h2 id="intro">What is API Level?</h2> - -<p>API Level is an integer value that uniquely identifies the framework API -revision offered by a version of the Android platform.</p> - -<p>The Android platform provides a framework API that applications can use to -interact with the underlying Android system. The framework API consists of:</p> - -<ul> -<li>A core set of packages and classes</li> -<li>A set of XML elements and attributes for declaring a manifest file</li> -<li>A set of XML elements and attributes for declaring and accessing resources</li> -<li>A set of Intents</li> -<li>A set of permissions that applications can request, as well as permission -enforcements included in the system</li> -</ul> - -<p>Each successive version of the Android platform can include updates to the -Android application framework API that it delivers. </p> - -<p>Updates to the framework API are designed so that the new API remains -compatible with earlier versions of the API. That is, most changes in the API -are additive and introduce new or replacement functionality. As parts of the API -are upgraded, the older replaced parts are deprecated but are not removed, so -that existing applications can still use them. In a very small number of cases, -parts of the API may be modified or removed, although typically such changes are -only needed to ensure API robustness and application or system security. All -other API parts from earlier revisions are carried forward without -modification.</p> - -<p>The framework API that an Android platform delivers is specified using an -integer identifier called "API Level". Each Android platform version supports -exactly one API Level, although support is implicit for all earlier API Levels -(down to API Level 1). The initial release of the Android platform provided -API Level 1 and subsequent releases have incremented the API Level.</p> - -<p>The following table specifies the API Level supported by each version of the -Android platform.</p> - -<table> - <tr><th>Platform Version</th><th>API Level</th><th>VERSION_CODE</th><th>Notes</th></tr> - - <tr><td><a href="{@docRoot}sdk/android-4.0.3.html">Android 4.0.3</a></td> - <td><a href="{@docRoot}sdk/api_diff/15/changes.html" title="Diff Report">15</a></td> - <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH_MR1}</td> - <td rowspan="2"><a href="{@docRoot}sdk/android-4.0-highlights.html">Platform -Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-4.0.html">Android 4.0, 4.0.1, 4.0.2</a></td> - <td><a href="{@docRoot}sdk/api_diff/14/changes.html" title="Diff Report">14</a></td> - <td>{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}</td> - </tr> - - <tr><td><a href="{@docRoot}sdk/android-3.2.html">Android 3.2</a></td> - <td><a href="{@docRoot}sdk/api_diff/13/changes.html" title="Diff Report">13</a></td> - <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}</td> - <td><!-- <a href="{@docRoot}sdk/android-3.2-highlights.html">Platform Highlights</a>--></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-3.1.html">Android 3.1.x</a></td> - <td><a href="{@docRoot}sdk/api_diff/12/changes.html" title="Diff Report">12</a></td> - <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB_MR1}</td> - <td><a href="{@docRoot}sdk/android-3.1-highlights.html">Platform Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-3.0.html">Android 3.0.x</td> - <td><a href="{@docRoot}sdk/api_diff/11/changes.html" title="Diff Report">11</a></td> - <td>{@link android.os.Build.VERSION_CODES#HONEYCOMB}</td> - <td><a href="{@docRoot}sdk/android-3.0-highlights.html">Platform Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-2.3.3.html">Android 2.3.4<br>Android 2.3.3</td> - <td><a href="{@docRoot}sdk/api_diff/10/changes.html" title="Diff Report">10</a></td> - <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD_MR1}</td> - <td rowspan="2"><a href="{@docRoot}sdk/android-2.3-highlights.html">Platform Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-2.3.html">Android 2.3.2<br>Android 2.3.1<br>Android 2.3</td> - <td><a href="{@docRoot}sdk/api_diff/9/changes.html" title="Diff Report">9</a></td> - <td>{@link android.os.Build.VERSION_CODES#GINGERBREAD}</td> - </tr> - - <tr><td><a href="{@docRoot}sdk/android-2.2.html">Android 2.2.x</td> - <td ><a href="{@docRoot}sdk/api_diff/8/changes.html" title="Diff Report">8</a></td> - <td>{@link android.os.Build.VERSION_CODES#FROYO}</td> - <td><a href="{@docRoot}sdk/android-2.2-highlights.html">Platform Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-2.1.html">Android 2.1.x</td> - <td><a href="{@docRoot}sdk/api_diff/7/changes.html" title="Diff Report">7</a></td> - <td>{@link android.os.Build.VERSION_CODES#ECLAIR_MR1}</td> - <td rowspan="3" ><a href="{@docRoot}sdk/android-2.0-highlights.html">Platform Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-2.0.1.html">Android 2.0.1</td> - <td><a href="{@docRoot}sdk/api_diff/6/changes.html" title="Diff Report">6</a></td> - <td>{@link android.os.Build.VERSION_CODES#ECLAIR_0_1}</td> - </tr> - - <tr><td><a href="{@docRoot}sdk/android-2.0.html">Android 2.0</td> - <td><a href="{@docRoot}sdk/api_diff/5/changes.html" title="Diff Report">5</a></td> - <td>{@link android.os.Build.VERSION_CODES#ECLAIR}</td> - </tr> - - <tr><td><a href="{@docRoot}sdk/android-1.6.html">Android 1.6</td> - <td><a href="{@docRoot}sdk/api_diff/4/changes.html" title="Diff Report">4</a></td> - <td>{@link android.os.Build.VERSION_CODES#DONUT}</td> - <td><a href="{@docRoot}sdk/android-1.6-highlights.html">Platform Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-1.5.html">Android 1.5</td> - <td><a href="{@docRoot}sdk/api_diff/3/changes.html" title="Diff Report">3</a></td> - <td>{@link android.os.Build.VERSION_CODES#CUPCAKE}</td> - <td><a href="{@docRoot}sdk/android-1.5-highlights.html">Platform Highlights</a></td></tr> - - <tr><td><a href="{@docRoot}sdk/android-1.1.html">Android 1.1</td> - <td>2</td> - <td>{@link android.os.Build.VERSION_CODES#BASE_1_1}</td><td></td></tr> - - <tr><td>Android 1.0</td> - <td>1</td> - <td>{@link android.os.Build.VERSION_CODES#BASE}</td> - <td></td></tr> -</table> - - -<h2 id="uses">Uses of API Level in Android</h2> - -<p>The API Level identifier serves a key role in ensuring the best possible -experience for users and application developers: - -<ul> -<li>It lets the Android platform describe the maximum framework API revision -that it supports</li> -<li>It lets applications describe the framework API revision that they -require</li> -<li>It lets the system negotiate the installation of applications on the user's -device, such that version-incompatible applications are not installed.</li> -</ul> - -<p>Each Android platform version stores its API Level identifier internally, in -the Android system itself. </p> - -<p>Applications can use a manifest element provided by the framework API — -<code><uses-sdk></code> — to describe the minimum and maximum API -Levels under which they are able to run, as well as the preferred API Level that -they are designed to support. The element offers three key attributes:</p> - -<ul> -<li><code>android:minSdkVersion</code> — Specifies the minimum API Level -on which the application is able to run. The default value is "1".</li> -<li><code>android:targetSdkVersion</code> — Specifies the API Level -on which the application is designed to run. In some cases, this allows the -application to use manifest elements or behaviors defined in the target -API Level, rather than being restricted to using only those defined -for the minimum API Level.</li> -<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level -on which the application is able to run. <strong>Important:</strong> Please read the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> -documentation before using this attribute. </li> -</ul> - -<p>For example, to specify the minimum system API Level that an application -requires in order to run, the application would include in its manifest a -<code><uses-sdk></code> element with a <code>android:minSdkVersion</code> -attribute. The value of <code>android:minSdkVersion</code> would be the integer -corresponding to the API Level of the earliest version of the Android platform -under which the application can run. </p> - -<p>When the user attempts to install an application, or when revalidating an -appplication after a system update, the Android system first checks the -<code><uses-sdk></code> attributes in the application's manifest and -compares the values against its own internal API Level. The system allows the -installation to begin only if these conditions are met:</p> - -<ul> -<li>If a <code>android:minSdkVersion</code> attribute is declared, its value -must be less than or equal to the system's API Level integer. If not declared, -the system assumes that the application requires API Level 1. </li> -<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value -must be equal to or greater than the system's API Level integer. -If not declared, the system assumes that the application -has no maximum API Level. Please read the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> -documentation for more information about how the system handles this attribute.</li> -</ul> - -<p>When declared in an application's manifest, a <code><uses-sdk></code> -element might look like this: </p> - -<pre><manifest> - <uses-sdk android:minSdkVersion="5" /> - ... -</manifest></pre> - -<p>The principal reason that an application would declare an API Level in -<code>android:minSdkVersion</code> is to tell the Android system that it is -using APIs that were <em>introduced</em> in the API Level specified. If the -application were to be somehow installed on a platform with a lower API Level, -then it would crash at run-time when it tried to access APIs that don't exist. -The system prevents such an outcome by not allowing the application to be -installed if the lowest API Level it requires is higher than that of the -platform version on the target device.</p> - -<p>For example, the {@link android.appwidget} package was introduced with API -Level 3. If an application uses that API, it must declare a -<code>android:minSdkVersion</code> attribute with a value of "3". The -application will then be installable on platforms such as Android 1.5 (API Level -3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and -Android 1.0 platforms (API Level 1).</p> - -<p>For more information about how to specify an application's API Level -requirements, see the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> - section of the manifest file documentation.</p> - - -<h2 id="considerations">Development Considerations</h2> - -<p>The sections below provide information related to API level that you should -consider when developing your application.</p> - -<h3 id="fc">Application forward compatibility</h3> - -<p>Android applications are generally forward-compatible with new versions of -the Android platform.</p> - -<p>Because almost all changes to the framework API are additive, an Android -application developed using any given version of the API (as specified by its -API Level) is forward-compatible with later versions of the Android platform and -higher API levels. The application should be able to run on all later versions -of the Android platform, except in isolated cases where the application uses a -part of the API that is later removed for some reason. </p> - -<p>Forward compatibility is important because many Android-powered devices -receive over-the-air (OTA) system updates. The user may install your -application and use it successfully, then later receive an OTA update to a new -version of the Android platform. Once the update is installed, your application -will run in a new run-time version of the environment, but one that has the API -and system capabilities that your application depends on. </p> - -<p>In some cases, changes <em>below</em> the API, such those in the underlying -system itself, may affect your application when it is run in the new -environment. For that reason it's important for you, as the application -developer, to understand how the application will look and behave in each system -environment. To help you test your application on various versions of the Android -platform, the Android SDK includes multiple platforms that you can download. -Each platform includes a compatible system image that you can run in an AVD, to -test your application. </p> - -<h3 id="bc">Application backward compatibility</h3> - -<p>Android applications are not necessarily backward compatible with versions of -the Android platform older than the version against which they were compiled. -</p> - -<p>Each new version of the Android platform can include new framework APIs, such -as those that give applications access to new platform capabilities or replace -existing API parts. The new APIs are accessible to applications when running on -the new platform and, as mentioned above, also when running on later versions of -the platform, as specified by API Level. Conversely, because earlier versions of -the platform do not include the new APIs, applications that use the new APIs are -unable to run on those platforms.</p> - -<p>Although it's unlikely that an Android-powered device would be downgraded to -a previous version of the platform, it's important to realize that there are -likely to be many devices in the field that run earlier versions of the -platform. Even among devices that receive OTA updates, some might lag and -might not receive an update for a significant amount of time. </p> - -<h3 id="platform">Selecting a platform version and API Level</h3> - -<p>When you are developing your application, you will need to choose -the platform version against which you will compile the application. In -general, you should compile your application against the lowest possible -version of the platform that your application can support. - -<p>You can determine the lowest possible platform version by compiling the -application against successively lower build targets. After you determine the -lowest version, you should create an AVD using the corresponding platform -version (and API Level) and fully test your application. Make sure to declare a -<code>android:minSdkVersion</code> attribute in the application's manifest and -set its value to the API Level of the platform version. </p> - -<h3 id="apilevel">Declaring a minimum API Level</h3> - -<p>If you build an application that uses APIs or system features introduced in -the latest platform version, you should set the -<code>android:minSdkVersion</code> attribute to the API Level of the latest -platform version. This ensures that users will only be able to install your -application if their devices are running a compatible version of the Android -platform. In turn, this ensures that your application can function properly on -their devices. </p> - -<p>If your application uses APIs introduced in the latest platform version but -does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then -it will run properly on devices running the latest version of the platform, but -<em>not</em> on devices running earlier versions of the platform. In the latter -case, the application will crash at runtime when it tries to use APIs that don't -exist on the earlier versions.</p> - -<h3 id="testing">Testing against higher API Levels</h3> - -<p>After compiling your application, you should make sure to test it on the -platform specified in the application's <code>android:minSdkVersion</code> -attribute. To do so, create an AVD that uses the platform version required by -your application. Additionally, to ensure forward-compatibility, you should run -and test the application on all platforms that use a higher API Level than that -used by your application. </p> - -<p>The Android SDK includes multiple platform versions that you can use, -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 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 -Manager</strong>.</p> - -<p>To run your application against different platform versions in the emulator, -create an AVD for each platform version that you want to test. For more -information about AVDs, see <a -href="{@docRoot}guide/developing/devices/index.html">Creating and Managing Virtual Devices</a>. If -you are using a physical device for testing, ensure that you know the API Level -of the Android platform it runs. See the table at the top of this document for -a list of platform versions and their API Levels. </p> - -<h2 id="provisional">Using a Provisional API Level</h2> - -<p>In some cases, an "Early Look" Android SDK platform may be available. To let -you begin developing on the platform although the APIs may not be final, the -platform's API Level integer will not be specified. You must instead use the -platform's <em>provisional API Level</em> in your application manifest, in order -to build applications against the platform. A provisional API Level is not an -integer, but a string matching the codename of the unreleased platform version. -The provisional API Level will be specified in the release notes for the Early -Look SDK release notes and is case-sensitive.</p> - -<p>The use of a provisional API Level is designed to protect developers and -device users from inadvertently publishing or installing applications based on -the Early Look framework API, which may not run properly on actual devices -running the final system image.</p> - -<p>The provisional API Level will only be valid while using the Early Look SDK -and can only be used to run applications in the emulator. An application using -the provisional API Level can never be installed on an Android device. At the -final release of the platform, you must replace any instances of the provisional -API Level in your application manifest with the final platform's actual API -Level integer.</p> - - -<h2 id="filtering">Filtering the Reference Documentation by API Level</h2> - -<p>Reference documentation pages on the Android Developers site offer a "Filter -by API Level" control in the top-right area of each page. You can use the -control to show documentation only for parts of the API that are actually -accessible to your application, based on the API Level that it specifies in -the <code>android:minSdkVersion</code> attribute of its manifest file. </p> - -<p>To use filtering, select the checkbox to enable filtering, just below the -page search box. Then set the "Filter by API Level" control to the same API -Level as specified by your application. Notice that APIs introduced in a later -API Level are then grayed out and their content is masked, since they would not -be accessible to your application. </p> - -<p>Filtering by API Level in the documentation does not provide a view -of what is new or introduced in each API Level — it simply provides a way -to view the entire API associated with a given API Level, while excluding API -elements introduced in later API Levels.</p> - -<p>If you decide that you don't want to filter the API documentation, just -disable the feature using the checkbox. By default, API Level filtering is -disabled, so that you can view the full framework API, regardless of API Level. -</p> - -<p>Also note that the reference documentation for individual API elements -specifies the API Level at which each element was introduced. The API Level -for packages and classes is specified as "Since <api level>" at the -top-right corner of the content area on each documentation page. The API Level -for class members is specified in their detailed description headers, -at the right margin. </p> diff --git a/docs/html/guide/appendix/g-app-intents.jd b/docs/html/guide/appendix/g-app-intents.jd index df9d29b..10ec01e 100644 --- a/docs/html/guide/appendix/g-app-intents.jd +++ b/docs/html/guide/appendix/g-app-intents.jd @@ -4,7 +4,7 @@ page.title=Intents List: Invoking Google Applications on Android Devices <div class="sidebox-wrapper"> <div class="sidebox"> For more information about intents, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>. +href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. </div> </div> diff --git a/docs/html/guide/appendix/glossary.jd b/docs/html/guide/appendix/glossary.jd index 06fdef2..94cb0f0 100644 --- a/docs/html/guide/appendix/glossary.jd +++ b/docs/html/guide/appendix/glossary.jd @@ -42,7 +42,7 @@ page.title=Glossary SDK. It provides tools to browse the device, copy tools on the device, and forward ports for debugging. If you are developing in Eclipse using the ADT Plugin, adb is integrated into your development environment. See - <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> + <a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> for more information. </dd> <dt id="application">Application</dt> @@ -91,7 +91,7 @@ page.title=Glossary with the SDK. It provides screen capture, log dump, and process examination capabilities. If you are developing in Eclipse using the ADT Plugin, DDMS is integrated into your development environment. See <a - href="{@docRoot}guide/developing/debugging/ddms.html">Using DDMS</a> to learn more about the program.</dd> + href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a> to learn more about the program.</dd> <dt id="dialog">Dialog</dt> <dd> A floating window that that acts as a lightweight form. A dialog can have button controls only and is intended to perform a @@ -131,7 +131,7 @@ page.title=Glossary is responsible for resolving the best-available receiver for each Intent, based on the criteria supplied in the Intent and the Intent Filters defined by other applications. For more information, see <a - href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and + href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. <p>Related: <a href="#intentfilter">Intent Filter</a>, <a href="#broadcastreceiver">Broadcast Receiver</a>.</p></dd> @@ -145,7 +145,7 @@ page.title=Glossary available intent filters in all applications and passes the Intent to the application/activity that best matches the Intent and criteria. For more information, see <a - href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and + href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. <p>Related: <a href="#intent">Intent</a>, <a href="#broadcastreceiver">Broadcast Receiver</a>.</p></dd> diff --git a/docs/html/guide/appendix/install-location.jd b/docs/html/guide/appendix/install-location.jd index 63a3817..19c4b39 100644 --- a/docs/html/guide/appendix/install-location.jd +++ b/docs/html/guide/appendix/install-location.jd @@ -174,7 +174,7 @@ 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 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 + <a href="{@docRoot}guide/google/play/licensing.html">Application Licensing</a> instead, your application <em>can</em> be installed to internal or external storage, including SD cards.</dd> </dl> @@ -198,7 +198,7 @@ applications that should allow installation on external storage, because games d provide additional services when inactive. When external storage becomes unavailable and a game process is killed, there should be no visible effect when the storage becomes available again and the user restarts the game (assuming that the game properly saved its state during the normal -<a href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activity lifecycle</a>).</p> +<a href="{@docRoot}guide/components/activities.html#Lifecycle">Activity lifecycle</a>).</p> <p>If your application requires several megabytes for the APK file, you should carefully consider whether to enable the application to install on the external storage so that diff --git a/docs/html/guide/appendix/market-filters.jd b/docs/html/guide/appendix/market-filters.jd deleted file mode 100644 index 3e502d7..0000000 --- a/docs/html/guide/appendix/market-filters.jd +++ /dev/null @@ -1,454 +0,0 @@ -page.title=Filters on Google Play -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>Quickview</h2> -<ul> -<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 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> - </ol> - </li> - <li><a href="#other-filters">Other Filters</a></li> - <li><a href="#MultiApks">Publishing Multiple APKs with Different Filters</a></li> -</ol> - -<h2>See also</h2> - <ol> -<li><a -href="{@docRoot}guide/practices/compatibility.html">Android Compatibility</a></li> -<li><code><a -href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture></a></code></li> -<li><code><a -href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> -<li><code><a -href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code></li> -<li><code><a -href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code></li> -<li><code><a -href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></li> -<li><code><a -href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></li> -<li><code><a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></code></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_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://play.google.com/apps/publish">Go to Google Play</a> to create a publisher -account and upload your app.</p></div> -</div> - -</div> -</div> - - -<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 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 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 on Google Play</h2> - -<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 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, 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 Google Play..</p> - -<p class="note"><strong>Note:</strong> When users browse the <a -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 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 -change between versions. For example, if a user has installed your application and you publish an -update that makes the app invisible to the user, the user will not see that an update is -available.</p> - - -<h2 id="manifest-filters">Filtering based on Manifest Elements</h2> - -<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 -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 Google Play.</p> -<table> - <tr> - <th>Manifest Element</th> - <th>Filter Name</th> - <th>How It Works</th> - </tr> - <tr> - <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> - <!-- ##api level 4## --></td> - <td valign="top">Screen Size</td> - <td valign="top"> - -<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, 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, 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, -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>, Google Play uses the default values for those -attributes, which vary by API Level. Specifically: </p> - -<ul> -<li><p>For applications that set either the <code><a -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, 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> - -<li>When the either the <code><a -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> is set to 4 or higher, the default for all attributes is -<code>"true"</code>. In this way, the application is considered to support all screen sizes by -default.</li> -</ul> - - <p><strong>Example 1</strong><br /> - The manifest declares <code><uses-sdk android:minSdkVersion="3"></code> - 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, 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>: 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>: 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 - href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> - and <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple - Screens</a>.</p> -</td> - </tr> - - <tr> - <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> - <!-- ##api level 3## --></td> - <td valign="top">Device - Configuration: <br /> - keyboard, navigation, touch screen</td> - <td valign="top"><p>An application can - 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>: 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>: 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> - - <tr> - <td rowspan="2" valign="top" style="white-space:nowrap;"><code><a -href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> -</code> - <!-- ##api level 4## --></td> - <td valign="top">Device Features<br /> - (<code>name</code>)</td> - <td valign="top"><p>An application can require certain device features to be -present on the device. This functionality was introduced in Android 2.0 (API -Level 5).</p> - <p><strong>Example 1<br /> - </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>: 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>: 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, 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>, -below.</p> -</td> - </tr> - - <tr> - <td valign="top">OpenGL-ES - Version<br /> -(<code>openGlEsVersion</code>)</td> - <td valign="top"><p>An application can require that the device support a specific - OpenGL-ES version using the <code><uses-feature - android:openGlEsVersion="int"></code> attribute.</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>: 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>: 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>: 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>: 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> - - <tr> - <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></td> - <td valign="top">Software Libraries</td> - <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>: 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>: 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, 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>, 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, -Google Play assumes that the application requires the underlying hardware -features, even though there might be no corresponding to -<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 -the documentation for the <a -href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features"><code><uses-feature></code></a> -element.</p> -</td> - </tr> - - <tr> - <td rowspan="2" valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></td> - <td valign="top">Minimum Framework Version (<code>minSdkVersion</code>)</td> - <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>: 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>: 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> - <tr> - <td valign="top">Maximum Framework Version (<code>maxSdkVersion</code>)</td> - <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>, 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> - </tr> -</table> - - - -<h3 id="advanced-filters">Advanced manifest filters</h3> - -<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 -only. These are designed for certain types of high-performance games and similar applications that -require strict controls on application distribution. <strong>Most applications should never use -these filters</strong>.</p> - -<p id="table2" class="table-caption"><strong>Table 2.</strong> Advanced manifest elements for -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>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 -this manifest element</strong>. Using this element can dramatically -reduce the potential user base for your application, by excluding all combinations of screen size -and density that you have not listed. You should instead use the <a -href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code -<supports-screens>}</a> manifest element (described above in <a href="#table1">table -1</a>) to enable screen compatibility mode for screen configurations you have not accounted for -with alternative resources.</p> - </td> - </tr> - <tr> - <td><nobr><a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code -<supports-gl-texture>}</a></nobr></td> - <td> - <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> -</table> - - - -<h2 id="other-filters">Other Filters</h2> - -<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 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 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> - <tr> - <td valign="top">Priced - Status</td> <td valign="top"><p>Not all users can see paid apps. To show paid apps, a device -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 - 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, 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 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. 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 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, Google -Play will deliver it the APK that you've declared to support that device.</p> - -<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 - <p>By using the <a -href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code -<supports-gl-texture>}</a> element.</p> - </li> - <li>Screen size (and, optionally, screen density) - <p>By using the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code -<supports-screens>}</a> or <a -href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code -<compatible-screens>}</a> element.</p> - </li> - <li>API level - <p>By using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code -<uses-sdk>}</a> element.</p> - </li> -</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 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> - -<p class="caution"><strong>Caution:</strong> Publishing multiple APKs for the same application is -considered an advanced feature and <strong>most application should publish only one -APK that supports a wide range of device configurations</strong>. Publishing multiple APKs -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 Google Play, read <a -href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> diff --git a/docs/html/guide/appendix/media-formats.jd b/docs/html/guide/appendix/media-formats.jd index 137f138..93e8136 100644 --- a/docs/html/guide/appendix/media-formats.jd +++ b/docs/html/guide/appendix/media-formats.jd @@ -268,9 +268,9 @@ no dither applied for 24-bit. <thead> <tr> <th> </th> - <th style="background-color:#f3f3f3;font-weight:normal"><acronym title="Standard definition">SD</a> (Low quality)</th> - <th style="background-color:#f3f3f3;font-weight:normal"><acronym title="Standard definition">SD</a> (High quality)</th> - <th style="background-color:#f3f3f3;font-weight:normal"><acronym title="High definition">HD</a> (Not available on all devices)</th> + <th><acronym title="Standard definition">SD</a> (Low quality)</th> + <th><acronym title="Standard definition">SD</a> (High quality)</th> + <th><acronym title="High definition">HD</a> (Not available on all devices)</th> </tr> </thead> <tbody> |