1page.title=Filters on Google Play 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7<h2>Quickview</h2> 8<ul> 9<li>Google Play applies filters to control which Android devices can download 10your application from the store.</li> 11<li>Filtering ensures that your apps are available only to users whose devices meet your app's compatibility requirements. 12<li>Filtering is determined by the configuration requirements that you declare in you app's 13manifest file, as well as other factors.</li> 14</ul> 15 16<h2>In this document</h2> 17 18<ol> 19 <li><a href="#how-filters-work">How Filters Work on Google Play</a></li> 20 <li><a href="#manifest-filters">Filtering based on Manifest Elements</a> 21 </li> 22 <li><a href="#other-filters">Other Filters</a></li> 23 <li><a href="#MultiApks">Publishing Multiple APKs with Different Filters</a></li> 24</ol> 25 26<h2>See also</h2> 27 <ol> 28<li><a 29href="{@docRoot}guide/practices/compatibility.html">Android Compatibility</a></li> 30<li><code><a 31href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture></a></code></li> 32<li><code><a 33href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> 34<li><code><a 35href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code></li> 36<li><code><a 37href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code></li> 38<li><code><a 39href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></li> 40<li><code><a 41href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></li> 42<li><code><a 43href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></code></a></li> 44</ol> 45 46</div> 47</div> 48 49<p>When a user searches or browses for apps to download on Google Play, the 50results are filtered based on which applications are compatible with the device. 51For example, if an app requires a camera, Google Play would not show the app to devices 52that do not have a camera. This <em>filtering</em> helps developers manage the 53distribution of their apps and helps ensure the best possible experience for 54users.</p> 55 56<p>Filtering in Google Play is based on several types of app metadata and 57configuration settings, including manifest declarations, required 58libraries,architecture dependencies, and distribution controls set in the Google 59Play Developer Console, such as geographic targeting, pricing, and more.</p> 60 61<p>Google Play filtering is based in part on manifest declarations and other 62aspects of the Android framework, but actual filtering behaviors are distinct 63from the framework and are not bound to specific API levels. This document 64specifies the current filtering rules used by Google Play.</p> 65 66 67<h2 id="how-filters-work">How Filters Work on Google Play</h2> 68 69<p>Google Play uses the filter restrictions described below to determine 70whether to show your application to a user who is browsing or searching for 71applications from the Google Play app.</p> 72 73<p>When determining whether to display your app, Google Play checks the device's 74hardware and software requirement, as well as it's carrier, location, and other 75characteristics. It then compares those against the restrictions and 76dependencies expressed by the application's manifest file and publishing 77details. </p> 78 79<p>If the application is compatible with the device according to the filter 80rules, Google Play displays the application to the user. Otherwise, Google Play 81hides your application from search results and category browsing, even if a user 82specifically requests the app by clicking a deep link that points directly to 83the app's ID within Google Play.</p> 84 85<p>You can use any combination of the available filters for your app. For example, you can set a 86<code>minSdkVersion</code> requirement of <code>"4"</code> and set <code>smallScreens="false"</code> 87in the app, then when uploading the app to Google Play you could target European countries (carriers) 88only. Google Play's filters will thus prevent the application from being available on any device 89that does not match all three of these requirements. </p> 90 91<p>All filtering restrictions are associated with an application's version and can 92change between versions. For example, if a user has installed your application and you publish an 93update that makes the app invisible to the user, the user will not see that an update is 94available.</p> 95 96<h4>Filtering on the Google Play web site</h4> 97 98<p>When users browse the <a href="http://play.google.com/apps">Google Play web 99site</a>, they can see all published applications. The Google Play web site 100compares the application requirements to each of the user's registered devices 101for compatibility, though, and only allows them to install the application if 102it's compatible with their device.</p> 103 104<h2 id="manifest-filters">Filtering based on the App Manifest</h2> 105 106<p>Most filters are triggered by elements within an application's 107manifest file, <a 108href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> 109(although not everything in the manifest file can trigger filtering). 110Table 1 lists the manifest elements that you should use to trigger 111filtering, and explains how the filtering for each element works.</p> 112 113<p id="table1" class="table-caption"><strong>Table 1.</strong> Manifest elements that 114trigger filtering on Google Play.</p> 115<table> 116 <tr> 117 <th>Manifest Element</th> 118 <th>Filter Name</th> 119 <th>How It Works</th> 120 </tr> 121 <tr> 122 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> 123 <!-- ##api level 4## --></td> 124 <td valign="top">Screen Size</td> 125 <td valign="top"> 126 127<p>An application indicates the screen sizes that it is capable of supporting by 128setting attributes of the <code><supports-screens></code> element. When 129the application is published, Google Play uses those attributes to determine whether 130to show the application to users, based on the screen sizes of their 131devices. </p> 132 133<p>As a general rule, Google Play assumes that the platform on the device can adapt 134smaller layouts to larger screens, but cannot adapt larger layouts to smaller 135screens. Thus, if an application declares support for "normal" screen size only, 136Google Play makes the application available to both normal- and large-screen devices, 137but filters the application so that it is not available to small-screen 138devices.</p> 139 140<p>If an application does not declare attributes for 141<code><supports-screens></code>, Google Play uses the default values for those 142attributes, which vary by API Level. Specifically: </p> 143 144<ul> 145<li><p>For applications that set either the <code><a 146href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">android: 147minSdkVersion</a></code> or <code><a 148href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">android: 149targetSdkVersion</a></code> to 3 or lower, the <code><supports-screens></code> element itself 150is undefined and no attributes are available. In this case, Google Play assumes that 151the application is designed for normal-size screens and shows the application to 152devices that have normal or larger screens. </p> 153 154<li>When the either the <code><a 155href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">android: 156minSdkVersion</a></code> or <code><a 157href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">android: 158targetSdkVersion</a></code> is set to 4 or higher, the default for all attributes is 159<code>"true"</code>. In this way, the application is considered to support all screen sizes by 160default.</li> 161</ul> 162 163 <p><strong>Example 1</strong><br /> 164 The manifest declares <code><uses-sdk android:minSdkVersion="3"></code> 165 and does not include a <code><supports-screens></code> element. 166 <strong>Result</strong>: Google Play will not show the app to a user of a 167 small-screen device, but will show it to users of normal and large-screen 168 devices, unless other filters apply. </p> 169 <p><strong>Example 2<br /> 170 </strong>The manifest declares <code><uses-sdk android:minSdkVersion="3" 171 android:targetSdkVersion="4"></code> and does not include a 172 <code><supports-screens></code> element. 173 <strong>Result</strong>: Google Play will show the app to users on all 174 devices, unless other filters apply. </p> 175 <p><strong>Example 3<br /> 176 </strong>The manifest declares <code><uses-sdk android:minSdkVersion="4"></code> 177 and does not include a <code><supports-screens></code> element. 178 <strong>Result</strong>: Google Play will show the app to all users, 179 unless other filters apply. </p> 180 <p>For more information on how to declare support for screen sizes in your 181 application, see <code><a 182 href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> 183 and <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 184 Screens</a>.</p> 185</td> 186 </tr> 187 188 <tr> 189 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> 190 <!-- ##api level 3## --></td> 191 <td valign="top">Device 192 Configuration: <br /> 193 keyboard, navigation, touch screen</td> 194 <td valign="top"><p>An application can 195 request certain hardware features, and Google Play will show the app only on devices that have the required hardware.</p> 196 <p><strong>Example 1<br /> 197 </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> 198 <p><strong>Example 2<br /> 199 </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> 200<p>For more details, see <a 201href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code></a>.</p></td> 202 </tr> 203 204 <tr> 205 <td rowspan="2" valign="top" style="white-space:nowrap;"><code><a 206href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> 207</code> 208 <!-- ##api level 4## --></td> 209 <td valign="top">Device Features<br /> 210 (<code>name</code>)</td> 211 <td valign="top"><p>An application can require certain device features to be 212present on the device. This functionality was introduced in Android 2.0 (API 213Level 5).</p> 214 <p><strong>Example 1<br /> 215 </strong>The manifest includes <code><uses-feature 216android:name="android.hardware.sensor.light" /></code>, and a user 217is searching for apps on a device that does not have a light sensor. 218<strong>Result</strong>: Google Play will not show the app to the user. </p> 219 <p><strong>Example 2<br /> 220 </strong>The manifest does not include a <code><uses-feature></code> 221element. <strong>Result</strong>: Google Play will show the app to all users, 222unless other filters apply.</p> 223 <p>For complete information, see <code><a 224href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> 225</code>.</p> 226 <p><em>Filtering based on implied features:</em> In some cases, Google 227Play interprets permissions requested through 228<code><uses-permission></code> elements as feature requirements equivalent 229to those declared in <code><uses-feature></code> elements. See <a 230href="#uses-permission-filtering"><code><uses-permission></code></a>, 231below.</p> 232</td> 233 </tr> 234 235 <tr> 236 <td valign="top">OpenGL-ES 237 Version<br /> 238(<code>openGlEsVersion</code>)</td> 239 <td valign="top"><p>An application can require that the device support a specific 240 OpenGL-ES version using the <code><uses-feature 241 android:openGlEsVersion="int"></code> attribute.</p> 242 <p><strong>Example 1<br /> 243 </strong>An app 244 requests multiple OpenGL-ES versions by specifying <code>openGlEsVersion</code> multiple times in the 245 manifest. <strong>Result</strong>: Google Play assumes that the app requires the highest of the indicated versions.</p> 246<p><strong>Example 2<br /> 247</strong>An app 248 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 249 device reports that it supports OpenGL-ES version <em>X</em>, Google Play assumes that it 250 also supports any version earlier than <em>X</em>. 251</p> 252<p><strong>Example 3<br /> 253</strong>A user is searching for apps on a device that does not 254 report an OpenGL-ES version (for example, a device running Android 1.5 or earlier). <strong>Result</strong>: Google Play assumes that the device 255 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> 256 <p><strong>Example 4<br /> 257 </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> 258<p>For more details, see <a 259href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a>.</p></td> 260 </tr> 261 262 <tr> 263 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></td> 264 <td valign="top">Software Libraries</td> 265 <td valign="top"><p>An application can require specific 266 shared libraries to be present on the device. </p> 267 <p><strong>Example 1<br /> 268 </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> 269 <p><strong>Example 2</strong><br /> 270 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> 271<p>For more details, see <a 272href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a>.</p></td> 273 </tr> 274 <tr id="uses-permission-filtering"> 275 <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></td> 276 <td valign="top"> </td> 277 <td valign="top">Strictly, Google Play does not filter based on 278<code><uses-permission></code> elements. However, it does read the 279elements to determine whether the application has hardware feature requirements 280that may not have been properly declared in <code><uses-feature></code> 281elements. For example, if an application requests the <code>CAMERA</code> 282permission but does not declare a <code><uses-feature></code> element for 283<code>android.hardware.camera</code>, Google Play considers that the 284application requires a camera and should not be shown to users whose devices do 285not offer a camera.</p> 286 <p>In general, if an application requests hardware-related permissions, 287Google Play assumes that the application requires the underlying hardware 288features, even though there might be no corresponding to 289<code><uses-feature></code> declarations. Google Play then sets up 290filtering based on the features implied by the <code><uses-feature></code> 291declarations.</p> 292 <p>For a list of permissions that imply hardware features, see 293the documentation for the <a 294href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features"><code><uses-feature></code></a> 295element.</p> 296</td> 297 </tr> 298 299 <tr> 300 <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> 301 <td valign="top">Minimum Framework Version (<code>minSdkVersion</code>)</td> 302 <td valign="top"><p>An application can require a minimum API level. </p> 303 <p><strong>Example 1</strong><br /> 304 The manifest includes <code><uses-sdk 305 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> 306 <p><strong>Example 2</strong><br /> 307 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> 308 <p>Because you want to avoid this second scenario, we recommend that you always declare a <code>minSdkVersion</code>. For details, see <a 309href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min"><code>android:minSdkVersion</code></a>.</p></td> 310 </tr> 311 <tr> 312 <td valign="top">Maximum Framework Version (<code>maxSdkVersion</code>)</td> 313 <td valign="top"><p><em>Deprecated.</em> Android 314 2.1 and later do not check or enforce the <code>maxSdkVersion</code> attribute, and 315 the SDK will not compile if <code>maxSdkVersion</code> is set in an app's manifest. For devices already 316 compiled with <code>maxSdkVersion</code>, Google Play will respect it and use it for 317 filtering.</p> 318<p> Declaring <code>maxSdkVersion</code> is <em>not</em> recommended. For details, see <a 319href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:maxSdkVersion</code></a>.</p></td> 320 </tr> 321</table> 322 323 324 325<h3 id="advanced-filters">Advanced manifest filters</h3> 326 327<p>In addition to the manifest elements in <a href="#table1">table 1</a>, Google Play can also 328filter applications based on the advanced manifest elements in table 2.</p> 329 330<p>These manifest elements and the filtering they trigger are for exceptional use-cases 331only. These are designed for certain types of high-performance games and similar applications that 332require strict controls on application distribution. <strong>Most applications should never use 333these filters</strong>.</p> 334 335<p id="table2" class="table-caption"><strong>Table 2.</strong> Advanced manifest elements for 336Google Play filtering.</p> 337<table> 338 <tr><th>Manifest Element</th><th>Summary</th></tr> 339 <tr> 340 <td><nobr><a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 341<compatible-screens>}</a></nobr></td> 342 <td> 343 <p>Google Play filters the application if the device screen size and density does not match 344any of the screen configurations (declared by a {@code <screen>} element) in the {@code 345<compatible-screens>} element.</p> 346 <p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use 347this manifest element</strong>. Using this element can dramatically 348reduce the potential user base for your application, by excluding all combinations of screen size 349and density that you have not listed. You should instead use the <a 350href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 351<supports-screens>}</a> manifest element (described above in <a href="#table1">table 3521</a>) to enable screen compatibility mode for screen configurations you have not accounted for 353with alternative resources.</p> 354 </td> 355 </tr> 356 <tr> 357 <td><nobr><a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code 358<supports-gl-texture>}</a></nobr></td> 359 <td> 360 <p>Google Play filters the application unless one or more of the GL texture compression 361formats supported by the application are also supported by the device. </p> 362 </td> 363 </tr> 364</table> 365 366 367 368<h2 id="other-filters">Other Filters</h2> 369 370<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> 371 372<p id="table3" class="table-caption"><strong>Table 3.</strong> Application and publishing 373characteristics that affect filtering on Google Play.</p> 374<table> <tr> 375 <th>Filter Name</th> <th>How It Works</th> </tr> 376 377 <tr> 378 <td valign="top">Publishing Status</td> <td valign="top"><p>Only published applications will appear in 379 searches and browsing within Google Play.</p> <p>Even if an app is unpublished, it can 380 be installed if users can see it in their Downloads area among their purchased, 381 installed, or recently uninstalled apps.</p> <p>If an application has been 382 suspended, users will not be able to reinstall or update it, even if it appears in their Downloads.</p> </td></tr> 383 <tr> 384 <td valign="top">Priced 385 Status</td> <td valign="top"><p>Not all users can see paid apps. To show paid apps, a device 386must have a SIM card and be running Android 1.1 or later, and it must be in a 387country (as determined by SIM carrier) in which paid apps are available.</p></td> 388</tr> <tr> 389 <td valign="top">Country Targeting</td> <td valign="top"> <p>When you upload your app to 390 Google Play, you can select the countries in which to distribute your app 391 under <strong>Pricing and Distribution</strong>. The app will then 392 be available to users in only the countries you select.</p> 393</td> </tr> <tr> 394 <td valign="top" style="white-space:nowrap;">CPU Architecture (ABI)</td> 395 <td valign="top"><p>An application that includes native 396 libraries that target a specific CPU architecture (ARM EABI v7 or x86, for example) are 397 visible only on devices that support that architecture. For details about the NDK and using 398 native libraries, see <a href="{@docRoot}tools/sdk/ndk/index.html#overview">What is the 399 Android NDK?</a></p> </tr> <tr> 400 <td valign="top">Copy-Protected Applications</td> <td valign="top"><p class="caution">Google 401 Play no longer supports the Copy Protection feature in the Developer Console and no longer 402 filters apps based on it. To secure your app, please use <a href="{@docRoot}google/play/licensing/index.html"> 403 Application Licensing</a> instead. See <a href="{@docRoot}google/play/licensing/overview.html#CopyProtection"> 404 Replacement for Copy Protection</a> for more information.</p></td> </tr> </table> 405 406<h2 id="MultiApks">Publishing Multiple APKs with Different Filters</h2> 407 408<p>Some specific Google Play filters allow you to publish multiple APKs for the same 409application in order to provide a different APK to different device configurations. For example, if 410you're creating a video game that uses high-fidelity graphic assets, you might want to create 411two APKs that each support different texture compression formats. This way, you can reduce the 412size of the APK file by including only the textures that are required for each device 413configuration. Depending on each device's support for your texture compression formats, Google 414Play will deliver it the APK that you've declared to support that device.</p> 415 416<p>Currently, Google Play allows you to publish multiple APKs for the same application only 417when each APK provides different filters based on the following configurations:</p> 418<ul> 419 <li>OpenGL texture compression formats 420 <p>By using the <a 421href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code 422<supports-gl-texture>}</a> element.</p> 423 </li> 424 <li>Screen size (and, optionally, screen density) 425 <p>By using the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 426<supports-screens>}</a> or <a 427href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 428<compatible-screens>}</a> element.</p> 429 </li> 430 <li>API level 431 <p>By using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code 432<uses-sdk>}</a> element.</p> 433 </li> 434 <li>CPU Architecture (ABI) 435 <p>By including native libraries built with the <a href="{@docRoot}tools/sdk/ndk/index.html">Android 436 NDK</a> that target a specific CPU architecture (ARM EABI v7 or x86, for example).</p> 437 </li> 438</ul> 439 440<p>All other filters still work the same as usual, but these four are the only filters that can 441distinguish one APK from another within the same application listing on Google Play. For example, 442you <em>cannot</em> publish multiple APKs for the same application if the APKs differ only based on 443whether the device has a camera.</p> 444 445<p class="caution"><strong>Caution:</strong> Publishing multiple APKs for the same application is 446considered an advanced feature and <strong>most application should publish only one 447APK that supports a wide range of device configurations</strong>. Publishing multiple APKs 448requires that you follow specific rules within your filters and that you pay extra attention to the 449version codes for each APK to ensure proper update paths for each configuration.</p> 450 451<p>If you need more information about how to publish multiple APKs on Google Play, read <a 452href="{@docRoot}google/play/publishing/multiple-apks.html">Multiple APK Support</a>.</p> 453