Home | History | Annotate | Download | only in practices
      1 page.title=Device Compatibility
      2 excludeFromSuggestions=true
      3 @jd:body
      4 
      5 <div id="qv-wrapper">
      6 <div id="qv">
      7 <h2>In this document</h2>
      8 <ol>
      9   <li><a href="#defined">What Does "Compatibility" Mean?</a></li>
     10   <li><a href="#how">Controlling Your App's Availability to Devices</a>
     11     <ol>
     12       <li><a href="#Features">Device features</a></li>
     13       <li><a href="#Versions">Platform version</a></li>
     14       <li><a href="#Screens">Screen configuration</a></li>
     15     </ol>
     16   </li>
     17   <li><a href="#filtering">Controlling Your App's Availability for Business Reasons</a></li>
     18 </ol>
     19 
     20 <h2>See also</h2>
     21  <ol>
     22 <li><a
     23 href="{@docRoot}google/play/filters.html">Filtering on Google Play</a></li>
     24 <li><a
     25 href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></li>
     26 <li><a href="http://source.android.com/compatibility/index.html" class="external-link">
     27 Android Compatibility</a></li>
     28 </ol>
     29 
     30 
     31 </div> </div>
     32 
     33 <p>Android is designed to run on many different types of devices, from phones
     34 to tablets and televisions. As a developer,
     35 the range of devices provides a huge potential audience for your app. In order for your app
     36 to be successful on all these devices, it should tolerate some feature variability
     37 and provide a flexible user interface that adapts to different screen
     38 configurations.</p>
     39 
     40 <p>To facilitate your effort toward that goal, Android provides a dynamic app framework in which
     41 you can provide configuration-specific <a href="{@docRoot}guide/topics/resources/overview.html"
     42 >app resources</a> in static files (such as different XML layouts
     43 for different screen sizes). Android then loads the appropriate resources based on
     44 the current device configuration. So with some forethought to your app design and some additional
     45 app resources, you can publish a single application package (APK) that provides an optimized user
     46 experience on a variety of devices.
     47 
     48 <p>If necessary, however, you can specify your app's feature requirements and control
     49 which types of devices can install your app from Google Play Store. This page explains how you can
     50 control which devices have access to your apps, and how to prepare your apps to make sure they
     51 reach the right audience. For more information about how you can make your app adapt
     52 to different devices, read <a href="{@docRoot}training/basics/supporting-devices/index.html"
     53 >Supporting Different Devices</a>.</p>
     54 
     55 
     56 
     57 <h2 id="defined">What Does "Compatibility" Mean?</h2>
     58 
     59 <p>As you read more about Android development, you'll probably encounter the term "compatibility"
     60 in various situations. There are two types of compatibility: <em>device compatibility</em>
     61 and <em>app compatibility</em>.
     62 
     63 <p>Because Android is an open source project, any hardware manufacturer can build a device
     64 that runs the Android operating system. Yet, a <b>device is "Android compatible"</b> only if
     65 it can correctly run apps written for the
     66 <em>Android execution environment</em>. The exact details of the Android execution
     67 environment are defined by the <a href="http://source.android.com/compatibility/overview.html"
     68 class="external-link">Android compatibility program</a> and each device must pass the Compatibility
     69 Test Suite (CTS) in order to be considered compatible.</p>
     70 
     71 <p>As an app developer, you don't need to worry about whether a device is Android compatible, because
     72 only devices that are Android compatible include Google Play Store. So you can rest assured that
     73 users who install your app from Google Play Store are using an Android compatible device.</p>
     74 
     75 
     76 <p>However, you do need to consider whether your <b>app is compatible</b> with each potential
     77 device configuration. Because Android runs on a wide range of device configurations, some features
     78 are not available on all devices. For example, some devices may not include a
     79 compass sensor. If your app's core functionality requires the use
     80 of a compass sensor, then your app is compatible only with devices that
     81 include a compass sensor.</p>
     82 
     83 <h2 id="how">Controlling Your App's Availability to Devices</h2>
     84 
     85 <p>Android supports a variety of features your app can leverage through platform APIs. Some
     86 features are hardware-based (such as a compass sensor), some are software-based (such as app
     87 widgets), and some are dependent on the platform version. Not every device supports every feature,
     88 so you may need to control your app's availability to devices based on your app's required
     89 features.</p>
     90 
     91 <p>To achieve the largest user-base possible for your app, you should strive to support as many
     92 device configurations as possible using a single APK. In most situations, you can do so by
     93 disabling optional features at runtime and <a
     94 href="{@docRoot}guide/topics/resources/providing-resources.html">providing app resources</a>
     95 with alternatives for different configurations (such as different layouts for different
     96 screen sizes).
     97 If necessary, however, you can restrict your app's availability to devices through Google Play
     98 Store based on the following device characteristics:</p>
     99 
    100 <ul>
    101   <li><a href="#Features">Device features</a>
    102   <li><a href="#Version">Platform version</a>
    103   <li><a href="#Screens">Screen configuration</a>
    104 </ul>
    105 
    106 <h3 id="Features">Device features</h3>
    107 
    108 <p>In order for you to manage your apps availability based on device features,
    109 Android defines <em>feature IDs</em> for any hardware or software feature
    110 that may not be available on all devices. For instance, the
    111 feature ID for the compass sensor is {@link
    112 android.content.pm.PackageManager#FEATURE_SENSOR_COMPASS} and the feature ID for app widgets
    113 is {@link android.content.pm.PackageManager#FEATURE_APP_WIDGETS}.</p>
    114 
    115 <p>If necessary, you can prevent users from installing your app when their devices don't provide a
    116 given feature by declaring it with a <a href=
    117 "{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a>
    118 element in your app's <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest
    119 file</a>.</p>
    120 
    121 <p>For example, if your app does not make sense on a device that lacks a compass sensor,
    122 you can declare the compass sensor as required with the following manifest tag:</p>
    123 
    124 <pre>
    125 &lt;manifest ... &gt;
    126     &lt;uses-feature android:name="android.hardware.sensor.compass"
    127                   android:required="true" /&gt;
    128     ...
    129 &lt;/manifest&gt;
    130 </pre>
    131 
    132 <p>Google Play Store compares the features your app requires to the features available on
    133 each user's device to determine whether your app is compatible with each device.
    134 If the device does not provide all the features your app requires, the user cannot install
    135 your app.</p>
    136 
    137 <p>However, if your app's primary functionality does not <em>require</em>
    138 a device feature, you should set the <a href=
    139 "{@docRoot}guide/topics/manifest/uses-feature-element.html#required">{@code required}</a>
    140 attribute to {@code "false"} and check
    141 for the device feature at runtime. If the app feature is not available on the current device,
    142 gracefully degrade the corresponding app feature. For example, you can query whether
    143 a feature is available by calling
    144 {@link android.content.pm.PackageManager#hasSystemFeature hasSystemFeature()} like this:</p>
    145 
    146 <pre>
    147 PackageManager pm = getPackageManager();
    148 if (!pm.hasSystemFeature(PackageManager.FEATURE_SENSOR_COMPASS)) {
    149     // This device does not have a compass, turn off the compass feature
    150     disableCompassFeature();
    151 }
    152 </pre>
    153 
    154 <p>For information about all the filters you can
    155 use to control the availability of your app to users through Google Play Store, see the
    156 <a href="{@docRoot}google/play/filters.html">Filters on Google Play</a>
    157 document.</p>
    158 
    159 <p class="note"><strong>Note:</strong> Some <a href=
    160 "{@docRoot}guide/topics/security/permissions.html">system permissions</a> implicitly require the
    161 availability of a device feature. For example, if your app requests permission to access to {@link
    162 android.Manifest.permission#BLUETOOTH}, this implicitly requires the {@link
    163 android.content.pm.PackageManager#FEATURE_BLUETOOTH} device feature. You can disable filtering based
    164 on this feature and make your app available to devices without Bluetooth by setting the <a href=
    165 "{@docRoot}guide/topics/manifest/uses-feature-element.html#required">{@code required}</a> attribute
    166 to {@code "false"} in the <a href=
    167 "{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> tag.
    168 For more information about implicitly required device features, read <a href=
    169 "{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions">Permissions that Imply
    170 Feature Requirements</a>.</p>
    171 
    172 <h3 id="Versions">Platform version</h3>
    173 
    174 <p>Different devices may run different versions of the Android platform,
    175 such as Android 4.0 or Android 4.4. Each successive platform version often adds new APIs not
    176 available in the previous version. To indicate which set of APIs are available, each
    177 platform version specifies an <a
    178 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level</a>. For instance,
    179 Android 1.0 is API level 1 and Android 4.4 is API level 19.</p>
    180 
    181 <p>The API level allows you to declare the minimum version with which your app is
    182 compatible, using the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
    183 <uses-sdk>}</a> manifest tag and its
    184 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>
    185 attribute.</p>
    186 
    187 <p>For example, the <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar
    188 Provider</a> APIs were added in Android 4.0 (API level 14). If your app cannot function without
    189 these APIs, you should declare API level 14 as your app's minimum supported
    190 version like this:</p>
    191 
    192 <pre>
    193 &lt;manifest ... &gt;
    194     &lt;uses-sdk android:minSdkVersion="14" android:targetSdkVersion="19" /&gt;
    195     ...
    196 &lt;/manifest&gt;
    197 </pre>
    198 
    199 <p>The <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
    200 minSdkVersion}</a> attribute declares the minimum version with which your app is compatible
    201 and the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
    202 targetSdkVersion}</a> attribute declares the highest version on which you've optimized
    203 your app.</p>
    204 
    205 <p>Each successive version of Android provides compatibility for apps that were built using
    206 the APIs from previous platform versions, so your app should always be compatible with future
    207 versions of Android while using the documented Android APIs.</p>
    208 
    209 <p class="note"><strong>Note:</strong>
    210 The <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
    211 targetSdkVersion}</a> attribute does not prevent your app from being installed on platform
    212 versions that are higher than the specified value,
    213 but it is important because it indicates to the system whether your
    214 app should inherit behavior changes in newer versions. If you don't update the
    215 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
    216 targetSdkVersion}</a> to the latest version, the system assumes that your
    217 app requires some backward-compatibility behaviors when running on the latest version.
    218 For example, among the <a href="{@docRoot}about/versions/android-4.4.html#Behaviors"
    219 >behavior changes in Android 4.4</a>, alarms created with the {@link android.app.AlarmManager} APIs
    220 are now inexact by default so the system can batch app alarms and preserve system power,
    221 but the system will retain the previous API behavior for your app if your target API level
    222 is lower than "19".</p>
    223 
    224 <p>However, if your app uses APIs added in a more recent
    225 platform version, but does not require them for its primary functionality,
    226 you should check the API level at runtime and gracefully degrade
    227 the corresponding features when the API level is too low. In this case,
    228 set the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
    229 minSdkVersion}</a> to the lowest value possible for your app's primary functionality,
    230 then compare the current system's version, {@link android.os.Build.VERSION#SDK_INT}, to one the
    231 codename constants in {@link android.os.Build.VERSION_CODES} that corresponds to the
    232 API level you want to check. For example:</p>
    233 
    234 <pre>
    235 if (Build.VERSION.SDK_INT &lt; Build.VERSION_CODES.HONEYCOMB) {
    236     // Running on something older than API level 11, so disable
    237     // the drag/drop features that use {@link android.content.ClipboardManager} APIs
    238     disableDragAndDrop();
    239 }
    240 </pre>
    241 
    242 <h3 id="Screens">Screen configuration</h3>
    243 
    244 <p>Android runs on devices of various sizes, from phones to tablets and TVs.
    245 In order to categorize devices by their screen type, Android defines two characteristics for
    246 each device: screen size (the physical size of the screen) and screen density (the physical
    247 density of the pixels on the screen, known as <acronym title="dots per inch">DPI</acronym>).
    248 To simplify the different configurations, Android generalizes these variants into groups that make
    249 them easier to target:</p>
    250 
    251 <ul>
    252   <li>Four generalized sizes: small, normal, large, and xlarge.</li>
    253   <li>And several generalized densities: mdpi (medium), hdpi (hdpi), xhdpi (extra high),
    254   xxhdpi (extra-extra high), and others.</li>
    255 </ul>
    256 
    257 <p>By default, your app is compatible with all screen sizes and densities,
    258 because the system makes the appropriate adjustments to your UI layout and image
    259 resources as necessary for each screen. However, you should optimize the user experience for each
    260 screen configuration by adding specialized layouts for different screen sizes and
    261 optimized bitmap images for common screen densities.</p>
    262 
    263 <p>For information about how to create alternative resources for different screens
    264 and how to restrict your app to certain screen sizes when necessary, read <a
    265 href="{@docRoot}training/basics/supporting-devices/screens.html">Supporting Different Screens</a>.
    266 </p>
    267 
    268 <h2 id="filtering">Controlling Your App's Availability for Business Reasons</h2>
    269 
    270 <p>In addition to restricting your app's availability based on device characteristics,
    271 its possible you may need to restrict your apps availability for
    272 business or legal reasons. For instance, an app that displays train schedules
    273 for the London Underground is unlikely to be useful to users outside the United
    274 Kingdom. For this type of situation, Google Play Store provides
    275 filtering options in the developer console that allow you to control your apps
    276 availability for non-technical reasons such as the user's locale or wireless carrier.</p>
    277 
    278 <p>Filtering for technical compatibility (such as required hardware components)
    279 is always based on information contained within your APK file. But
    280 filtering for non-technical reasons (such as geographic locale) is always
    281 handled in the Google Play developer console.</p>
    282 
    283 <div class="next-docs">
    284 <div class="col-6">
    285   <h2 class="norule">Continue reading about:</h2>
    286   <dl>
    287     <dt><a
    288 href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></dt>
    289     <dd>Information about how Android apps are structured to separate app resources from the
    290    app code, including how you can provide alternative resources for specific device
    291    configurations.
    292     </dd>
    293     <dt><a href="{@docRoot}google/play/filters.html">Filters on Google Play</a></dt>
    294     <dd>Information about the different ways that Google Play Store can prevent your app
    295    from being installed on different devices.</dd>
    296   </dl>
    297 </div>
    298 <div class="col-6">
    299   <h2 class="norule">You might also be interested in:</h2>
    300   <dl>
    301     <dt><a href="{@docRoot}guide/topics/security/permissions.html"
    302         >System Permissions</a></dt>
    303     <dd>How Android restricts app access to certain APIs with a permission system that requires
    304   the user's consent for your app to use those APIs.</dd>
    305   </dl>
    306 </div>
    307 </div>
    308