1page.title=Android Compatibility 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7<h2>See also</h2> 8 <ol> 9<li><a 10href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></li> 11<li><a 12href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing Alternative Resources</a></li> 13<li><a 14href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> 15<li style="margin-top:3px;"><code><a 16href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> 17<li><code><a 18href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code></li> 19<li><code><a 20href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code></li> 21<li><code><a 22href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></li> 23<li><code><a 24href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></li> 25<li><code><a 26href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></code></a></li> 27</ol> 28 29 30</div> </div> 31 32<p>Android is designed to run on many different types of devices. For 33developers, the range and number of devices means a huge potential audience: the 34more devices that run Android apps, the more users who can access your app. In 35exchange, however, it also means that your apps will have to cope with that same 36variety of hardware.</p> 37 38<p>Fortunately, Android has built-in tools and support that make it easy for 39your apps to do that, while at the same time letting you maintain control of 40what types of devices your app is available to. With a bit of forethought and 41some minor changes in your app's manifest file, you can ensure that users 42whose devices can’t run your app will never see it in the Android Market, and 43will not get in trouble by downloading it. This page explains how you can 44control which devices have access to your apps, and how to prepare your apps to 45make sure they reach the right audience.</p> 46 47 48<h3 id="defined">What does “compatibility” mean?</h3> 49 50<p>A device is “Android compatible” if it can correctly run apps written for the 51<em>Android execution environment</em>. The exact details of the Android execution 52environment</em> are defined by the Android Compatibility Definition Document, 53but the single most important characteristic of a compatible device is the 54ability to install and correctly run an Android <code>.apk</code> file.</p> 55 56<p>There is exactly one Android API for each <a 57href="{@docRoot}guide/appendix/api-levels.html">API level</a>, and it’s the same 58API no matter what kind of device it’s installed on. No parts of the API are 59optional, and you never have to worry about parts of the API missing on some 60devices. Every compatible Android device your app will land on will include 61every class and every API for that API level.</p> 62 63<p>Of course, some APIs won’t work correctly if a particular device lacks the 64corresponding hardware or feature. But that’s not a problem: we also designed 65Android to prevent apps from being visible to devices which don’t have features 66the apps require. We’ve built support for this right into the SDK tools, and 67it’s part of the Android platform itself, as well as Android Market.</p> 68 69<p>As a developer, you have complete control of how and where your apps are 70available. Android provides tools as a first-class part of the platform that let 71you manage this. You control the availability of your apps, so that they reach 72only the devices capable of running them.</p> 73 74<h3 id="how">How does it work?</h3> 75 76<p>You manage your app’s availability through a simple three-step process:</p> 77 78<ol> 79<li>You state the features your app requires by declaring <a 80href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a> 81elements its manifest file.</li> 82<li>Devices are required to declare the features they include to Android 83Market.</li> 84<li>Android Market uses your app’s stated requirements to filter it from devices 85that don’t meet those requirements.</li> 86</ol> 87 88<p>This way, users never even see apps that won’t work properly on their 89devices. As long as you accurately describe your app’s requirements, you don’t 90need to worry about users blaming you for compatibility problems.</p> 91 92<p>If you’re familiar with web development, you may recognize this model as 93“capability detection”. Web developers typically prefer this approach to 94“browser detection”, because it’s very difficult to keep up as new browsers and 95new versions of current browsers are released. By checking for support for 96specific required capabilities instead of the current browser, web developers 97get better fine-grained control. That’s the same approach Android uses: since 98it’s impossible to keep up with all the Android devices being released, you 99instead use the fine-grained controls Android provides.</p> 100 101<h3>Filtering for technical reasons</h3> 102 103 <div class="sidebox-wrapper"> 104 <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> 105 <div id="qv-sub-rule"> 106 <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> 107 <p style="color:#669999;">Filtering on Android Market</p> 108 109 <p>Android Market filters the applications that are visible to users, so 110that users can see and download only those applications that are compatible with 111their devices.</p> 112 113 <p style="margin-top:1em;">One of the ways Market filters applications is by 114feature compatibility. To do this, Market checks the 115<code><uses-feature></code> elements in each application's manifest, to 116establish the app's feature needs. Market then shows or hides the application to 117each user, based on a comparison with the features available on the user's 118device. 119 120<p style="margin-top:1em;">For information about other filters that you can 121use to control the availability of your apps, see the 122<a href="{@docRoot}guide/appendix/market-filters.html">Market 123Filters</a> document.</p> 124 </div> 125</div> 126 127<p>Android includes support for a lot of features, some hardware and some 128software. Examples include compass and accelerometer sensors, cameras, and Live 129Wallpapers. However, not every device will support every feature. For instance, 130some devices don’t have the hardware horsepower to display Live Wallpapers 131well.</p> 132 133<p>To manage this, Android defines <em>feature IDs</em>. Every capability has a 134corresponding feature ID defined by the Android platform. For instance, the 135feature ID for compass is <code>“android.hardware.sensor.compass”</code>, 136while the feature 137ID for Live Wallpapers is <code>“android.software.live_wallpapers”</code>. Each of these IDs 138also has a corresponding Java-language constant on the 139{@link android.content.pm.PackageManager} class that you can use to query whether 140feature is supported at runtime. As Android adds support for new features in 141future versions, new feature IDs will be added as well.</p> 142 143<p>When you write your application, you specify which features your app requires 144by listing their feature IDs in <code><uses-feature></code> elements in 145the <code>AndroidManifest.xml</code> file. This is the information that Android 146Market uses to match your app to devices that can run it. For instance, if you 147state that your app requires android.software.live_wallpapers, it won’t be shown 148to devices that don’t support Live Wallpapers.</p> 149 150<p>This puts you in total control of your app — because you don’t have to 151declare these features. Consider an example involving cameras.</p> 152 153<p>If you’re building a really impressive next-generation augmented-reality app, 154your app won’t function at all without a camera. However, if you’re building a 155shopping app that only uses the camera for barcode scanning, users without 156cameras might still find it useful even if they can’t scan barcodes. While both 157apps need to acquire the permission to access the camera, only the first app 158needs to state that it requires a camera. (The shopping app can simply check at 159runtime and disable the camera-related features if there’s no camera 160present.)</p> 161 162<p>Since only you can say what the best approach is for your app, Android 163provides the tools and lets you make your own tradeoff between maximizing 164audience size and minimizing development costs.</p> 165 166 167<h3 id="filtering">Filtering for business reasons</h3> 168 169<p>It’s possible that you may need to restrict your app’s availability for 170business or legal reasons. For instance, an app that displays train schedules 171for the London Underground is unlikely to be useful to users outside the United 172Kingdom. Other apps might not be permitted in certain countries for business or 173legal reasons. For cases such as these, Android Market itself provides 174developers with filtering options that allow them control their app’s 175availability for non-technical reasons.</p> 176 177<p>The help information for Android Market provides full details, but in a 178nutshell, developers can use the Market publisher UI to:</p> 179 180<ul> 181<li>List the countries an app is available in.</li> 182<li>Select which carrier’s users are able to access the app.</li> 183</ul> 184 185<p>Filtering for technical compatibility (such as required hardware components) 186is always based on information contained within your <code>.apk</code> file. But 187filtering for non-technical reasons (such as geographic restrictions) is always 188handled in the Market user interface.</p> 189 190<h3 id="futureproofing">Future-proofing</h3> 191 192<p>There’s one additional quirk that we haven’t yet addressed: protecting apps 193from changes made to future versions of Android. If the Android platform 194introduces a new feature or changes how existing features are handled, what 195happens to existing apps that were written without any knowledge of the new 196behavior?</p> 197 198<p>Simply put, Android commits to not making existing apps available to devices 199where they won’t work properly, even when the platform changes. The best way to 200explain this is through examples, so here are two:</p> 201 202<ul> 203<li>Android 1.0 through 1.5 required a 2 megapixel camera with auto-focus. 204However, with version 1.6, Android devices were permitted to omit the auto-focus 205capability, though a (fixed-focus) camera was still required. Some apps such as 206barcode scanners do not function as well with cameras that do not auto-focus. To 207prevent users from having a bad experience with those apps, existing apps that 208obtain permission to use the Camera were assumed by default to require 209auto-focus. This allowed Android Market to filter those apps from devices that 210lack auto-focus.</li> 211 212<li>Android 2.2, meanwhile, allowed the microphone to be optional on some 213devices, such as set-top boxes. Android 2.2 included a new feature ID for the 214microphone which allows developers to filter their apps if necessary, but 215— as with camera — apps that obtain permission to record audio are 216assumed to require the microphone feature by default. If your app can use a 217microphone but doesn’t strictly need it, you can explicitly state that you don’t 218require it; but unless you do that, your app won’t be shown to devices without 219microphones.</li> 220</ul> 221 222<p>In other words, whenever Android introduces new features or changes existing 223ones, we will always take steps to protect existing applications so that they 224don’t end up being available to devices where they won’t work.</p> 225 226<p>This is implemented, in part, using the <code>aapt</code> tool in the SDK. 227To see which features your app explicitly requires or is implicitly assumed to 228require, you can use the command <code>aapt dump badging</code>.</p> 229 230<h3 id="conclusion">Conclusion</h3> 231 232<p>The goal of Android is to create a huge installed base for developers to take 233advantage of. One of the ways we will achieve this is through different kinds of 234hardware running the same software environment. But we also recognize that only 235developers know which kinds of devices their apps make sense on. We’ve built in 236tools to the SDK and set up policies and requirements to ensure that developers 237remain in control of their apps, today and in the future. With the information 238you just read, and the resources listed in the sidebar of this document, you 239can publish your app with the confidence that only users who can run it will 240see it.</p> 241 242<p>For more information about Android device compatibility, please visit:</p> 243 244<p style="margin-left:2em;"><a href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a></p> 245 246 247
