diff options
Diffstat (limited to 'docs/html/guide/practices/compatibility.jd')
| -rw-r--r-- | docs/html/guide/practices/compatibility.jd | 485 |
1 files changed, 285 insertions, 200 deletions
diff --git a/docs/html/guide/practices/compatibility.jd b/docs/html/guide/practices/compatibility.jd index 9e3d461..db1642e 100644 --- a/docs/html/guide/practices/compatibility.jd +++ b/docs/html/guide/practices/compatibility.jd @@ -1,248 +1,333 @@ -page.title=Android Compatibility +page.title=Device Compatibility excludeFromSuggestions=true @jd:body <div id="qv-wrapper"> <div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#defined">What Does "Compatibility" Mean?</a></li> + <li><a href="#how">Controlling Your App's Availability to Devices</a> + <ol> + <li><a href="#Features">Device features</a></li> + <li><a href="#Versions">Platform version</a></li> + <li><a href="#Screens">Screen configuration</a></li> + </ol> + </li> + <li><a href="#filtering">Controlling Your App's Availability for Business Reasons</a></li> +</ol> <h2>See also</h2> <ol> <li><a href="{@docRoot}google/play/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 -href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> -<li style="margin-top:3px;"><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> +href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></li> +<li><a href="http://source.android.com/compatibility/index.html" class="external-link"> +Android Compatibility</a></li> </ol> </div> </div> -<p>Android is designed to run on many different types of devices. For -developers, the range and number of devices means a huge potential audience: the -more devices that run Android apps, the more users who can access your app. In -exchange, however, it also means that your apps will have to cope with that same -variety of hardware.</p> +<p>Android is designed to run on many different types of devices, from phones +to tablets and televisions. As a developer, +the range of devices provides a huge potential audience for your app. In order for your app +to be successful on all these devices, it should tolerate some feature variability +and provide a flexible user interface that adapts to different screen +configurations.</p> + +<p>To facilitate your effort toward that goal, Android provides a dynamic app framework in which +you can provide configuration-specific <a href="{@docRoot}guide/topics/resources/overview.html" +>app resources</a> in static files (such as different XML layouts +for different screen sizes). Android then loads the appropriate resources based on +the current device configuration. So with some forethought to your app design and some additional +app resources, you can publish a single application package (APK) that provides an optimized user +experience on a variety of devices. -<p>Fortunately, Android has built-in tools and support that make it easy for -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 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> +<p>If necessary, however, you can specify your app's feature requirements and control +which types of devices can install your app from Google Play Store. 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. For more information about how you can make your app adapt +to different devices, read <a href="{@docRoot}training/basics/supporting-devices/index.html" +>Supporting Different Devices</a>.</p> -<h3 id="defined">What does “compatibility” mean?</h3> -<p>A device is “Android compatible” if it can correctly run apps written for the +<h2 id="defined">What Does "Compatibility" Mean?</h2> + +<p>As you read more about Android development, you'll probably encounter the term "compatibility" +in various situations. There are two types of compatibility: <em>device compatibility</em> +and <em>app compatibility</em>. + +<p>Because Android is an open source project, any hardware manufacturer can build a device +that runs the Android operating system. Yet, a <b>device is "Android compatible"</b> only if +it can correctly run apps written for the <em>Android execution environment</em>. The exact details of the Android execution -environment</em> are defined by the Android Compatibility Definition Document, -but the single most important characteristic of a compatible device is the -ability to install and correctly run an Android <code>.apk</code> file.</p> +environment are defined by the <a href="http://source.android.com/compatibility/overview.html" +class="external-link">Android compatibility program</a> and each device must pass the Compatibility +Test Suite (CTS) in order to be considered compatible.</p> -<p>There is exactly one Android API for each <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level</a>, and it’s the same -API no matter what kind of device it’s installed on. No parts of the API are -optional, and you never have to worry about parts of the API missing on some -devices. Every compatible Android device your app will land on will include -every class and every API for that API level.</p> +<p>As an app developer, you don't need to worry about whether a device is Android compatible, because +only devices that are Android compatible include Google Play Store. So you can rest assured that +users who install your app from Google Play Store are using an Android compatible device.</p> -<p>Of course, some APIs won’t work correctly if a particular device lacks the -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 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 -you manage this. You control the availability of your apps, so that they reach -only the devices capable of running them.</p> +<p>However, you do need to consider whether your <b>app is compatible</b> with each potential +device configuration. Because Android runs on a wide range of device configurations, some features are not +available on all devices. For example, some devices may not include a +compass sensor. If your app's core functionality requires the use +of a compass sensor, then your app is compatible only with devices that +include a compass sensor.</p> -<h3 id="how">How does it work?</h3> -<p>You manage your app’s availability through a simple three-step process:</p> -<ol> -<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 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> -<p>This way, users never even see apps that won’t work properly on their -devices. As long as you accurately describe your app’s requirements, you don’t -need to worry about users blaming you for compatibility problems.</p> - -<p>If you’re familiar with web development, you may recognize this model as -“capability detection”. Web developers typically prefer this approach to -“browser detection”, because it’s very difficult to keep up as new browsers and -new versions of current browsers are released. By checking for support for -specific required capabilities instead of the current browser, web developers -get better fine-grained control. That’s the same approach Android uses: since -it’s impossible to keep up with all the Android devices being released, you -instead use the fine-grained controls Android provides.</p> - -<h3>Filtering for technical reasons</h3> - - <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_play.png" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Filtering on Google Play</p> - - <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 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. 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}google/play/filters.html">Filters on Google Play</a> -document.</p> - </div> -</div> +<h2 id="how">Controlling Your App's Availability to Devices</h2> + +<p>Android supports a variety of features your app can leverage through platform APIs. Some +features are hardware-based (such as a compass sensor), some are software-based (such as app +widgets), and some are dependent on the platform version. Not every device supports every feature, +so you may need to control your app's availability to devices based on your app's required +features.</p> -<p>Android includes support for a lot of features, some hardware and some -software. Examples include compass and accelerometer sensors, cameras, and Live -Wallpapers. However, not every device will support every feature. For instance, -some devices don’t have the hardware horsepower to display Live Wallpapers -well.</p> - -<p>To manage this, Android defines <em>feature IDs</em>. Every capability has a -corresponding feature ID defined by the Android platform. For instance, the -feature ID for compass is <code>“android.hardware.sensor.compass”</code>, -while the feature -ID for Live Wallpapers is <code>“android.software.live_wallpapers”</code>. Each of these IDs -also has a corresponding Java-language constant on the -{@link android.content.pm.PackageManager} class that you can use to query whether -feature is supported at runtime. As Android adds support for new features in -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 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> - -<p>This puts you in total control of your app — because you don’t have to -declare these features. Consider an example involving cameras.</p> - -<p>If you’re building a really impressive next-generation augmented-reality app, -your app won’t function at all without a camera. However, if you’re building a -shopping app that only uses the camera for barcode scanning, users without -cameras might still find it useful even if they can’t scan barcodes. While both -apps need to acquire the permission to access the camera, only the first app -needs to state that it requires a camera. (The shopping app can simply check at -runtime and disable the camera-related features if there’s no camera -present.)</p> - -<p>Since only you can say what the best approach is for your app, Android -provides the tools and lets you make your own tradeoff between maximizing -audience size and minimizing development costs.</p> - - -<h3 id="filtering">Filtering for business reasons</h3> - -<p>It’s possible that you may need to restrict your app’s availability for -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, 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 Google Play provides full details, but in a -nutshell, developers can use the Google Play publisher UI to:</p> +<p>To achieve the largest user-base possible for your app, you should strive to support as many +device configurations as possible using a single APK. In most situations, you can do so by +disabling optional features at runtime and <a +href="{@docRoot}guide/topics/resources/providing-resources.html">providing app resources</a> +with alternatives for different configurations (such as different layouts for different +screen sizes). +If necessary, however, you can restrict your app's availability to devices through Google Play +Store based on the following device characteristics:</p> <ul> -<li>List the countries an app is available in.</li> -<li>Select which carrier’s users are able to access the app.</li> + <li><a href="#Features">Device features</a> + <li><a href="#Version">Platform version</a> + <li><a href="#Screens">Screen configuration</a> </ul> -<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 Google Play user interface.</p> -<h3 id="futureproofing">Future-proofing</h3> +<h3 id="Features">Device features</h3> + +<p>In order for you to manage your app’s availability based on device features, +Android defines <em>feature IDs</em> for any hardware or software feature +that may not be available on all devices. For instance, the +feature ID for the compass sensor is {@link +android.content.pm.PackageManager#FEATURE_SENSOR_COMPASS} and the feature ID for app widgets +is {@link android.content.pm.PackageManager#FEATURE_APP_WIDGETS}.</p> + +<p>If necessary, you can prevent users from installing your app when their devices don't provide a +given feature by declaring it with a <a href= +"{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +element in your app's <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest +file</a>.</p> + +<p>For example, if your app does not make sense on a device that lacks a compass sensor, +you can declare the compass sensor as required with the following manifest tag:</p> + +<pre> +<manifest ... > + <uses-feature android:name="android.hardware.sensor.compass" + android:required="true" /> + ... +</manifest> +</pre> + +<p>Google Play Store compares the features your app requires to the features available on +each user's device to determine whether your app is compatible with each device. +If the device does not provide all the features your app requires, the user cannot install +your app.</p> + +<p>However, if your app's primary functionality does not <em>require</em> +a device feature, you should set the <a href= +"{@docRoot}guide/topics/manifest/uses-feature-element.html#required">{@code required}</a> +attribute to {@code "false"} and check +for the device feature at runtime. If the app feature is not available on the current device, +gracefully degrade the corresponding app feature. For example, you can query whether +a feature is available by calling +{@link android.content.pm.PackageManager#hasSystemFeature hasSystemFeature()} like this:</p> + +<pre> +PackageManager pm = getPackageManager(); +if (!pm.hasSystemFeature(PackageManager.FEATURE_SENSOR_COMPASS)) { + // This device does not have a compass, turn off the compass feature + disableCompassFeature(); +} +</pre> + +<p>For information about all the filters you can +use to control the availability of your app to users through Google Play Store, see the +<a href="{@docRoot}google/play/filters.html">Filters on Google Play</a> +document.</p> + +<p class="note"><strong>Note:</strong> Some <a href= +"{@docRoot}guide/topics/security/permissions.html">system permissions</a> implicitly require the +availability of a device feature. For example, if your app requests permission to access to {@link +android.Manifest.permission#BLUETOOTH}, this implicitly requires the {@link +android.content.pm.PackageManager#FEATURE_BLUETOOTH} device feature. You can disable filtering based +on this feature and make your app available to devices without Bluetooth by setting the <a href= +"{@docRoot}guide/topics/manifest/uses-feature-element.html#required">{@code required}</a> attribute +to {@code "false"} in the <a href= +"{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> tag. +For more information about implicitly required device features, read <a href= +"{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions">Permissions that Imply +Feature Requirements</a>.</p> + + + + + + + +<h3 id="Versions">Platform version</h3> + +<p>Different devices may run different versions of the Android platform, +such as Android 4.0 or Android 4.4. Each successive platform version often adds new APIs not +available in the previous version. To indicate which set of APIs are available, each +platform version specifies an <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level</a>. For instance, +Android 1.0 is API level 1 and Android 4.4 is API level 19.</p> + +<p>The API level allows you to declare the minimum version with which your app is +compatible, using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code +<uses-sdk>}</a> manifest tag and its <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> attribute.</p> + +<p>For example, the <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar +Provider</a> APIs were added in Android 4.0 (API level 14). If your app cannot function without +these APIs, you should declare API level 14 as your app's minimum supported +version like this:</p> -<p>There’s one additional quirk that we haven’t yet addressed: protecting apps -from changes made to future versions of Android. If the Android platform -introduces a new feature or changes how existing features are handled, what -happens to existing apps that were written without any knowledge of the new -behavior?</p> +<pre> +<manifest ... > + <uses-sdk android:minSdkVersion="14" android:targetSdkVersion="19" /> + ... +</manifest> +</pre> -<p>Simply put, Android commits to not making existing apps available to devices -where they won’t work properly, even when the platform changes. The best way to -explain this is through examples, so here are two:</p> +<p>The <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +minSdkVersion}</a> attribute declares the minimum version with which your app is compatible +and the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +targetSdkVersion}</a> attribute declares the highest version on which you've optimized +your app.</p> + +<p>Each successive version of Android provides compatibility for apps that were built using +the APIs from previous platform versions, so your app should always be compitible with future +versions of Android while using the documented Android APIs.</p> + +<p class="note"><strong>Note:</strong> +The <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +targetSdkVersion}</a> attribute does not prevent your app from being installed on platform +versions that are higher than the specified value, +but it is important because it indicates to the system whether your +app should inherit behavior changes in newer versions. If you don't update the +<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +targetSdkVersion}</a> to the latest version, the system assumes that your +app requires some backward-compatibility behaviors when running on the latest version. +For example, among the <a href="{@docRoot}about/versions/android-4.4.html#Behaviors" +>behavior changes in Android 4.4</a>, alarms created with the {@link android.app.AlarmManager} APIs +are now inexact by default so the system can batch app alarms and preserve system power, +but the system will retain the previous API behavior for your app if your target API level +is lower than "19".</p> + +<p>However, if your app uses APIs added in a more recent +platform version, but does not require them for its primary functionality, +you should check the API level at runtime and gracefully degrade +the corresponding features when the API level is too low. In this case, +set the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +minSdkVersion}</a> to the lowest value possible for your app's primary functionality, +then compare the current system's version, {@link android.os.Build.VERSION#SDK_INT}, to one the +codename constants in {@link android.os.Build.VERSION_CODES} that corresponds to the +API level you want to check. For example:</p> + +<pre> +if (Build.VERSION.SDK_INT < Build.VERSION_CODES.HONEYCOMB) { + // Running on something older than API level 11, so disable + // the drag/drop features that use {@link android.content.ClipboardManager} APIs + disableDragAndDrop(); +} +</pre> + + + + + + +<h3 id="Screens">Screen configuration</h3> + +<p>Android runs on devices of various sizes, from phones to tablets and TVs. +In order to categorize devices by their screen type, Android defines two characteristics for +each device: screen size (the physical size of the screen) and screen density (the physical +density of the pixels on the screen, known as <acronym title="dots per inch">DPI</acronym>). +To simplify the different configurations, Android generalizes these variants into groups that make +them easier to target:</p> <ul> -<li>Android 1.0 through 1.5 required a 2 megapixel camera with auto-focus. -However, with version 1.6, Android devices were permitted to omit the auto-focus -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 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 -devices, such as set-top boxes. Android 2.2 included a new feature ID for the -microphone which allows developers to filter their apps if necessary, but -— as with camera — apps that obtain permission to record audio are -assumed to require the microphone feature by default. If your app can use a -microphone but doesn’t strictly need it, you can explicitly state that you don’t -require it; but unless you do that, your app won’t be shown to devices without -microphones.</li> + <li>Four generalized sizes: small, normal, large, and xlarge.</li> + <li>And several generalized densities: mdpi (medium), hdpi (hdpi), xhdpi (extra high), + xxhdpi (extra-extra high), and others.</li> </ul> -<p>In other words, whenever Android introduces new features or changes existing -ones, we will always take steps to protect existing applications so that they -don’t end up being available to devices where they won’t work.</p> +<p>By default, your app is compatible with all screen sizes and densities, +because the system makes the appropriate adjustments to your UI layout and image +resources as necessary for each screen. However, you should optimize the user experience for each +screen configuration by adding specialized layouts for different screen sizes and +optimized bitmap images for common screen densities.</p> + +<p>For information about how to create alternative resources for different screens +and how to restrict your app to certain screen sizes when necessary, read <a +href="{@docRoot}training/basics/supporting-devices/screens.html">Supporting Different Screens</a>. +</p> + + -<p>This is implemented, in part, using the <code>aapt</code> tool in the SDK. -To see which features your app explicitly requires or is implicitly assumed to -require, you can use the command <code>aapt dump badging</code>.</p> -<h3 id="conclusion">Conclusion</h3> -<p>The goal of Android is to create a huge installed base for developers to take -advantage of. One of the ways we will achieve this is through different kinds of -hardware running the same software environment. But we also recognize that only -developers know which kinds of devices their apps make sense on. We’ve built in -tools to the SDK and set up policies and requirements to ensure that developers -remain in control of their apps, today and in the future. With the information -you just read, and the resources listed in the sidebar of this document, you -can publish your app with the confidence that only users who can run it will -see it.</p> -<p>For more information about Android device compatibility, please visit:</p> -<p style="margin-left:2em;"><a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></p> +<h2 id="filtering">Controlling Your App's Availability for Business Reasons</h2> -
\ No newline at end of file +<p>In addition to restricting your app's availability based on device characteristics, +it’s possible you may need to restrict your app’s availability for +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. For this type of situation, Google Play Store provides +filtering options in the developer console that allow you to control your app’s +availability for non-technical reasons such as the user's locale or wireless carrier.</p> + +<p>Filtering for technical compatibility (such as required hardware components) +is always based on information contained within your APK file. But +filtering for non-technical reasons (such as geographic locale) is always +handled in the Google Play developer console.</p> + + + + + + +<div class="next-docs"> +<div class="col-6"> + <h2 class="norule">Continue reading about:</h2> + <dl> + <dt><a +href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></dt> + <dd>Information about how Android apps are structured to separate app resources from the + app code, including how you can provide alternative resources for specific device + configurations. + </dd> + <dt><a href="{@docRoot}google/play/filters.html">Filters on Google Play</a></dt> + <dd>Information about the different ways that Google Play Store can prevent your app + from being installed on different devices.</dd> + </dl> +</div> +<div class="col-6"> + <h2 class="norule">You might also be interested in:</h2> + <dl> + <dt><a href="{@docRoot}guide/topics/security/permissions.html" + >System Permissions</a></dt> + <dd>How Android restricts app access to certain APIs with a permission system that requires + the user's consent for your app to use those APIs.</dd> + </dl> +</div> +</div> |