1 page.title=Market Filters 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7 <h2>Quickview</h2> 8 <ul> <li>Android Market applies filters to that let you control whether your app is shown to a 9 user who is browing or searching for apps.</li> 10 <li>Filtering is determined by elements in an app's manifest file, 11 aspects of the device being used, and other factors.</li> </ul> 12 13 <h2>In this document</h2> 14 15 <ol> <li><a href="#how-filters-work">How Filters Work in Android Market</a></li> 16 <li><a href="#manifest-filters">Filtering based on Manifest File Elements</a></li> 17 <li><a href="#other-filters">Other Filters</a></li> 18 </ol> 19 20 <h2>See also</h2> 21 <ol> 22 <li><a 23 href="{@docRoot}guide/practices/compatibility.html">Compatibility</a></li> 24 <li style="margin-top:2px;"><code><a 25 href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> 26 <li><code><a 27 href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code></li> 28 <li><code><a 29 href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code></li> 30 <li><code><a 31 href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></li> 32 <li><code><a 33 href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></li> 34 <li><code><a 35 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></code></a></li> 36 </ol> 37 38 <div id="qv-extra"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> 39 <div id="qv-sub-rule"> <img src="{@docRoot}assets/images/icon_market.jpg" 40 style="float:left;margin:0;padding:0;"> <p style="color:#669999;">Interested in 41 publishing your app on Android Market?</p> <a id="publish-link" 42 href="http://market.android.com/publish">Go to Android Market »</a> </div> 43 </div> 44 45 </div> </div> 46 47 <p>When a user searches or browses in Android Market, the results are filtered, and 48 some applications might not be visible. For example, if an application requires a 49 trackball (as specified in the manifest file), then Android Market will not show 50 the app on any device that does not have a trackball.</p> <p>The manifest file and 51 the device's hardware and features are only part of how applications are filtered 52 — filtering also depends on the country and carrier, the presence or absence 53 of a SIM card, and other factors. </p> 54 55 <p>Changes to the Android Market filters are independent of changes 56 to the Android platform itself. This document will be updated periodically to reflect 57 any changes that occur. </p> 58 59 <h2 id="how-filters-work">How Filters Work in Android Market</h2> 60 61 <p>Android Market uses the filter restrictions described below to determine 62 whether to show your application to a user who is browsing or searching for 63 applications on a given device. When determining whether to display your app, 64 Market checks the device's hardware and software capabilities, as well as it's 65 carrier, location, and other characteristics. It then compares those against the 66 restrictions and dependencies expressed by the application itself, in its 67 manifest, <code>.apk</code>, and publishing details. If the application is 68 compatible with the device according to the filter rules, Market displays the 69 application to the user. Otherwise, Market hides your application from search 70 results and category browsing. </p> 71 72 <p> You can use the filters described below to control whether Market shows or 73 hides your application to users. You can request any combination of the 74 available filters for your app — for example, you could set a 75 <code>minSdkVersion</code> requirement of <code>"4"</code> and set 76 <code>smallScreens="false"</code> in the app, then when uploading the app to 77 Market you could target European countries (carriers) only. Android Market's 78 filters would prevent the application from being visible on any device that did 79 not match all three of these requirements. </p> 80 81 <p>A filtered app is not visible within Market, even if a user specifically requests 82 the app by clicking a deep link that points directly to the app's ID within Market. 83 All filtering restrictions are associated with an application's version and can 84 change between versions. For example:</p> 85 86 <ul> 87 <li>If you publish a new version of your app with stricter restrictions, the app 88 will not be visible to users for whom it is filtered, even if those users were 89 able see the previous version.</li> 90 <li>If a user has installed your application and you publish an upgrade that 91 makes the app invisible to the user, the user will not see that an upgrade is 92 available. </li> 93 </ul> 94 95 <h2 id="manifest-filters">Filtering based on Manifest Elements</h2> 96 97 <p>Most Market filters are triggered by elements within an application's 98 manifest file, <a 99 href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>, 100 although not everything in the manifest file can trigger filtering. The 101 table below lists the manifest elements that you can use to trigger Android 102 Market filtering, and explains how the filtering works.</p> 103 104 <p class="table-caption"><strong>Table 1.</strong> Manifest elements that 105 trigger filtering on Market.</p> 106 <table> 107 <tr> 108 <th>Manifest Element</th> 109 <th>Filter Name</th> 110 <th>How It Works</th> 111 </tr> 112 <tr> 113 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> 114 <!-- ##api level 4## --></td> 115 <td valign="top">Screen Size</td> 116 <td valign="top"> 117 118 <p>An application indicates the screen sizes that it is capable of supporting by 119 setting attributes of the <code><supports-screens></code> element. When 120 the application is published, Market uses those attributes to determine whether 121 to show the application to users, based on the screen sizes of their 122 devices. </p> 123 124 <p>As a general rule, Market assumes that the platform on the device can adapt 125 smaller layouts to larger screens, but cannot adapt larger layouts to smaller 126 screens. Thus, if an application declares support for "normal" screen size only, 127 Market makes the application available to both normal- and large-screen devices, 128 but filters the application so that it is not available to small-screen 129 devices.</p> 130 131 <p>If an application does not declare attributes for 132 <code><supports-screens></code>, Market uses the default values for those 133 attributes, which vary by API Level. Specifically: </p> 134 135 <ul> 136 <li><p>In API level 3, the <code><supports-screens></code> element itself 137 is undefined and no attributes are available. In this case, Market assumes that 138 the application is designed for normal-size screens and shows the application to 139 devices that have normal or large screens. </p> 140 141 <p>This behavior is especially significant for applications that set their 142 <code><a 143 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">android: 144 minSdkVersion</a></code> to 3 or lower, since Market will filter them from 145 small-screen devices by default. Such applications can enable support for 146 small-screen devices by adding a <code>android:targetSdkVersion="4"</code> 147 attribute to the <code><uses-sdk></code> element in their manifest 148 files. For more information, see <a 149 href="{@docRoot}guide/practices/screens_support.html#strategies">Strategies for 150 Legacy Applications</a>.</p></li> 151 152 <li>In API Level 4, the defaults for all of the attributes is 153 <code>"true"</code>. If an application does not declare a 154 <code><supports-screens></code> element, Market assumes that the 155 application is designed for all screen sizes and does not filter it from any 156 devices. If the application does not declare one of the attributes, Market uses 157 the default value of <code>"true"</code> and does not filter the app for devices 158 of corresponding screen size.</li> 159 </ul> 160 161 <p><strong>Example 1</strong><br /> 162 The manifest declares <code><uses-sdk android:minSdkVersion="3"></code> 163 and does not does not include a <code><supports-screens></code> element. 164 <strong>Result</strong>: Android Market will not show the app to a user of a 165 small-screen device, but will show it to users of normal and large-screen 166 devices, users, unless other filters apply. </p> 167 <p><strong>Example 2<br /> 168 </strong>The manifest declares <code><uses-sdk android:minSdkVersion="3" 169 android:targetSdkVersion="4"></code> and does not include a 170 <code><supports-screens></code> element. 171 <strong>Result</strong>: Android Market will show the app to users on all 172 devices, unless other filters apply. </p> 173 <p><strong>Example 3<br /> 174 </strong>The manifest declares <code><uses-sdk android:minSdkVersion="4"></code> 175 and does not include a <code><supports-screens></code> element. 176 <strong>Result</strong>: Android Market will show the app to all users, 177 unless other filters apply. </p> 178 <p>For more information on how to declare support for screen sizes in your 179 application, see <code><a 180 href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> 181 and <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 182 Screens</a>.</p> 183 </td> 184 </tr> 185 <tr> 186 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> 187 <!-- ##api level 3## --></td> 188 <td valign="top">Device 189 Configuration: <br /> 190 keyboard, navigation, touch screen</td> 191 <td valign="top"><p>An application can 192 request certain hardware features, and Android Market will show the app only on devices that have the required hardware.</p> 193 <p><strong>Example 1<br /> 194 </strong>The manifest includes <code><uses-configuration android:reqFiveWayNav="true" /></code>, and a user is searching for apps on a device that does not have a five-way navigational control. <strong>Result</strong>: Android Market will not show the app to the user. </p> 195 <p><strong>Example 2<br /> 196 </strong>The manifest does not include a <code><uses-configuration></code> element. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply.</p> 197 <p>For more details, see <a 198 href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code></a>.</p></td> 199 </tr> 200 <tr> 201 <td rowspan="2" valign="top" style="white-space:nowrap;"><code><a 202 href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> 203 </code> 204 <!-- ##api level 4## --></td> 205 <td valign="top">Device Features<br /> 206 (<code>name</code>)</td> 207 <td valign="top"><p>An application can require certain device features to be 208 present on the device. This functionality was introduced in Android 2.0 (API 209 Level 5).</p> 210 <p><strong>Example 1<br /> 211 </strong>The manifest includes <code><uses-feature 212 android:name="android.hardware.sensor.light" /></code>, and a user 213 is searching for apps on a device that does not have a light sensor. 214 <strong>Result</strong>: Android Market will not show the app to the user. </p> 215 <p><strong>Example 2<br /> 216 </strong>The manifest does not include a <code><uses-feature></code> 217 element. <strong>Result</strong>: Android Market will show the app to all users, 218 unless other filters apply.</p> 219 <p>For complete information, see <code><a 220 href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> 221 </code>.</p> 222 <p><em>Filtering based on implied features:</em> In some cases, Android 223 Market interprets permissions requested through 224 <code><uses-permission></code> elements as feature requirements equivalent 225 to those declared in <code><uses-feature></code> elements. See <a 226 href="#uses-permission-filtering"><code><uses-permission></code></a>, 227 below.</p> 228 </td> 229 </tr> 230 <tr> 231 <td valign="top">OpenGL-ES 232 Version<br /> 233 (<code>openGlEsVersion</code>)</td> 234 <td valign="top"><p>An application can require that the device support a specific 235 OpenGL-ES version using the <code><uses-feature 236 android:openGlEsVersion="int"></code> attribute.</p> 237 <p><strong>Example 1<br /> 238 </strong>An app 239 requests multiple OpenGL-ES versions by specifying <code>openGlEsVersion</code> multiple times in the 240 manifest. <strong>Result</strong>: Market assumes that the app requires the highest of the indicated versions.</p> 241 <p><strong>Example 2<br /> 242 </strong>An app 243 requests OpenGL-ES version 1.1, and a user is searching for apps on a device that supports OpenGL-ES version 2.0. <strong>Result</strong>: Android Market will show the app to the user, unless other filters apply. If a 244 device reports that it supports OpenGL-ES version <em>X</em>, Market assumes that it 245 also supports any version earlier than <em>X</em>. 246 </p> 247 <p><strong>Example 3<br /> 248 </strong>A user is searching for apps on a device that does not 249 report an OpenGL-ES version (for example, a device running Android 1.5 or earlier). <strong>Result</strong>: Android Market assumes that the device 250 supports only OpenGL-ES 1.0. Market will only show the user apps that do not specify <code>openGlEsVersion</code>, or apps that do not specify an OpenGL-ES version higher than 1.0. </p> 251 <p><strong>Example 4<br /> 252 </strong>The manifest does not specify <code>openGlEsVersion</code>. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply. </p> 253 <p>For more details, see <a 254 href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a>.</p></td> 255 </tr> 256 <tr> 257 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></td> 258 <td valign="top">Software Libraries</td> 259 <td valign="top"><p>An application can require specific 260 shared libraries to be present on the device. </p> 261 <p><strong>Example 1<br /> 262 </strong>An app requires the <code>com.google.android.maps</code> library, and a user is searching for apps on a device that does not have the <code>com.google.android.maps</code> library. <strong>Result</strong>: Android Market will not show the app to the user. </p> 263 <p><strong>Example 2</strong><br /> 264 The manifest does not include a <code><uses-library></code> element. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply.</p> 265 <p>For more details, see <a 266 href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a>.</p></td> 267 </tr> 268 <tr id="uses-permission-filtering"> 269 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></td> 270 <td valign="top"> </td> 271 <td valign="top">Strictly, Android Market does not filter based on 272 <code><uses-permission></code> elements. However, it does read the 273 elements to determine whether the application has hardware feature requirements 274 that may not have been properly declared in <code><uses-feature></code> 275 elements. For example, if an application requests the <code>CAMERA</code> 276 permission but does not declare a <code><uses-feature></code> element for 277 <code>android.hardware.camera</code>, Android Market considers that the 278 application requires a camera and should not be shown to users whose devices do 279 not offer a camera.</p> 280 <p>In general, if an application requests hardware-related permissions, 281 Android Market assumes that the application requires the underlying hardware 282 features, even though there might be no corresponding to 283 <code><uses-feature></code> declarations. Android Market then sets up 284 filtering based on the features implied by the <code><uses-feature></code> 285 declarations.</p> 286 <p>For a list of permissions that imply hardware features, see 287 the documentation for the <a 288 href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features"><code><uses-feature></code></a> 289 element.</p> 290 </td> 291 </tr> 292 <tr> 293 <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> 294 <td valign="top">Minimum Framework Version (<code>minSdkVersion</code>)</td> 295 <td valign="top"><p>An application can require a minimum API level. </p> 296 <p><strong>Example 1</strong><br /> 297 The manifest includes <code><uses-sdk 298 android:minSdkVersion="3"></code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Android Market will not show the app to the user. </p> 299 <p><strong>Example 2</strong><br /> 300 The manifest does not include <code>minSdkVersion</code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Android Market assumes that <code>minSdkVersion</code> is "1" and that the app is compatible with all versions of Android. Market shows the app to the user and allows the user to download the app. The app crashes at runtime. </p> 301 <p>Because you want to avoid this second scenario, we recommend that you always declare a <code>minSdkVersion</code>. For details, see <a 302 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min"><code>android:minSdkVersion</code></a>.</p></td> 303 </tr> 304 <tr> 305 <td valign="top">Maximum Framework Version (<code>maxSdkVersion</code>)</td> 306 <td valign="top"><p><em>Deprecated.</em> Android 307 2.1 and later do not check or enforce the <code>maxSdkVersion</code> attribute, and 308 the SDK will not compile if <code>maxSdkVersion</code> is set in an app's manifest. For devices already 309 compiled with <code>maxSdkVersion</code>, Market will respect it and use it for 310 filtering.</p> 311 <p> Declaring <code>maxSdkVersion</code> is <em>not</em> recommended. For details, see <a 312 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:maxSdkVersion</code></a>.</p></td> 313 </tr> 314 </table> 315 316 <h2 id="other-filters">Other Filters</h2> 317 <p>Android Market uses other application characteristics to determine whether to show or hide an application for a particular user on a given device, as described in the table below. </p> 318 319 <p class="table-caption"><strong>Table 2.</strong> Application and publishing characteristics that affect filtering on Market.</p> 320 <table> <tr> 321 <th>Filter Name</th> <th>How It Works</th> </tr> 322 323 <tr> 324 <td valign="top">Publishing Status</td> <td valign="top"><p>Only published applications will appear in 325 searches and browsing within Android Market.</p> <p>Even if an app is unpublished, it can 326 be installed if users can see it in their Downloads area among their purchased, 327 installed, or recently uninstalled apps.</p> <p>If an application has been 328 suspended, users will not be able to reinstall or update it, even if it appears in their Downloads.</p> </td></tr> 329 <tr> 330 <td valign="top">Priced 331 Status</td> <td valign="top"><p>Not all users can see paid apps. To show paid apps, a device 332 must have a SIM card and be running Android 1.1 or later, and it must be in a 333 country (as determined by SIM carrier) in which paid apps are available.</p></td> 334 </tr> <tr> 335 <td valign="top">Country / Carrier Targeting</td> <td valign="top"> <p>When you upload your app to 336 the Android Market, you can select specific countries to target. The app will only 337 be visible to the countries (carriers) that you select, as follows:</p> 338 <ul><li><p>A device's country is determined based on the carrier, if a carrier is 339 available. If no carrier can be determined, the Market application tries to 340 determine the country based on IP.</p></li> <li><p>Carrier is determined based on 341 the device's SIM (for GSM devices), not the current roaming carrier.</p></li></ul> 342 </td> </tr> <tr> 343 <td valign="top">Native Platform</td> <td valign="top"><p>An application that includes native 344 libraries that target a specific platform (ARM EABI v7, for example) will only be 345 visible on devices that support that platform. For details about the NDK and using 346 native libraries, see <a href="{@docRoot}sdk/ndk/index.html#overview">What is the 347 Android NDK?</a></p> </tr> <tr> 348 <td valign="top">Forward-Locked Applications</td> <td valign="top"><p>To 349 forward lock an application, set copy protection to "On" when you upload the 350 application to Market. Market will not show copy-protected applications on 351 developer devices or unreleased devices.</p></td> </tr> </table> 352 353 354
