1 page.title=Distributing to Specific Screens 2 parent.title=Supporting Multiple Screens 3 parent.link=screens_support.html 4 5 @jd:body 6 7 <div id="qv-wrapper"> 8 <div id="qv"> 9 10 <h2>Quickview</h2> 11 <ul> 12 <li>If necessary, you can control distribution of your application based on the device 13 screen configuration</li> 14 </ul> 15 16 <h2>In this document</h2> 17 <ol> 18 <li><a href="#FilteringHansetApps">Declaring an App is Only for Handsets</a></li> 19 <li><a href="#FilteringTabletApps">Declaring an App is Only for Tablets</a></li> 20 <li><a href="#MultiApks">Publishing Multiple APKs for Different Screens</a></li> 21 </ol> 22 23 <h2>See also</h2> 24 <ol> 25 <li><a 26 href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> 27 <li><a 28 href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0</a></li> 29 </ol> 30 31 </div> 32 </div> 33 34 35 36 <p>Although we recommend that you design your application to function properly on multiple 37 configurations of screen size and density, you can instead choose to limit the distribution of your 38 application to certain types of screens, such as only tablets and other large devices or only 39 handsets and similar-sized devices. To do so, you can enable filtering by external services such as 40 Android Market by adding elements to your manifest file that specify the screen configurations your 41 application supports.</p> 42 43 <p>However, before you decide to restrict your application to certain screen configurations, you 44 should understand the techniques for <a 45 href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and implement 46 them to the best of your ability. By supporting multiple screens, your application can be made 47 available to the greatest number of users with different devices, using a single APK.</p> 48 49 50 51 <h2 id="FilteringHandsetApps">Declaring an App is Only for Handsets</h2> 52 53 <p>Because the system generally scales applications to fit larger screens well, you shouldn't 54 need to filter your application from larger screens. As long as you follow the <a 55 href="{@docRoot}guide/practices/screens_support.html#screen-independence">Best Practices for Screen 56 Independence</a>, your application should work well on larger screens such as tablets. However, you 57 might discover that your application can't scale up well or perhaps you've decided to publish two 58 versions of your application for different screen configurations. In such a case, you can use the <a 59 href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 60 <compatible-screens>}</a> element to manage the distribution of your application based on 61 combinations of screen size and density. External services such as Android Market use this 62 information to apply filtering to your application, so that only devices that have a screen 63 configuration with which you declare compatibility can download your application.</p> 64 65 <p>The <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 66 <compatible-screens>}</a> element must contain one or more {@code <screen>} elements. Each 67 {@code <screen>} element specifies a screen configuration with which your application is 68 compatible, using both the {@code android:screenSize} and {@code android:screenDensity} attributes. 69 Each {@code <screen>} element <strong>must include both attributes</strong> to specify an 70 individual screen configuration—if either attribute is missing, then the element is invalid 71 (external services such as Android Market will ignore it).</p> 72 73 <p>For example, if your application is compatible with only small and normal size screens, 74 regardless of screen density, you must specify eight different {@code <screen>} elements, 75 because each screen size has four density configurations. You must declare each one of 76 these; any combination of size and density that you do <em>not</em> specify is considered a screen 77 configuration with which your application is <em>not</em> compatible. Here's what the manifest 78 entry looks like if your application is compatible with only small and normal screen sizes:</p> 79 80 <pre> 81 <manifest ... > 82 <compatible-screens> 83 <!-- all small size screens --> 84 <screen android:screenSize="small" android:screenDensity="ldpi" /> 85 <screen android:screenSize="small" android:screenDensity="mdpi" /> 86 <screen android:screenSize="small" android:screenDensity="hdpi" /> 87 <screen android:screenSize="small" android:screenDensity="xhdpi" /> 88 <!-- all normal size screens --> 89 <screen android:screenSize="normal" android:screenDensity="ldpi" /> 90 <screen android:screenSize="normal" android:screenDensity="mdpi" /> 91 <screen android:screenSize="normal" android:screenDensity="hdpi" /> 92 <screen android:screenSize="normal" android:screenDensity="xhdpi" /> 93 </compatible-screens> 94 ... 95 <application ... > 96 ... 97 <application> 98 </manifest> 99 </pre> 100 101 <p class="note"><strong>Note:</strong> Although you can also use the <a 102 href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 103 <compatible-screens>}</a> element for the reverse scenario (when your application is not 104 compatible with smaller screens), it's easier if you instead use the <a 105 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 106 <supports-screens>}</a> as discussed in the next section, because it doesn't require you 107 to specify each screen density your application supports.</p> 108 109 110 111 112 <h2 id="FilteringTabletApps">Declaring an App is Only for Tablets</h2> 113 114 <p>If you don't want your app to be used on handsets (perhaps your app truly makes sense only on a 115 large screen) or you need time to optimize it for smaller screens, you can prevent small-screen 116 devices from downloading your app by using the <a 117 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 118 <supports-screens>}</a> manifest element.</p> 119 120 <p>For example, if you want your application to be available only to tablet devices, you can declare 121 the element in your manifest like this:</p> 122 123 <pre> 124 <manifest ... > 125 <supports-screens android:smallScreens="false" 126 android:normalScreens="false" 127 android:largeScreens="true" 128 android:xlargeScreens="true" 129 android:requiresSmallestWidthDp="600" /> 130 ... 131 <application ... > 132 ... 133 </application> 134 </manifest> 135 </pre> 136 137 <p>This describes your app's screen-size support in two different ways:</p> 138 139 <ul> 140 <li>It declares that the app does <em>not</em> support the screen sizes "small" and 141 "normal", which are traditionally not tablets.</li> 142 <li>It declares that the app requires a screen size with a minimum usable area that is at least 143 600dp wide.</li> 144 </ul> 145 146 <p>The first technique is for devices that are running Android 3.1 or older, because those devices 147 declare their size based on generalized screen sizes. The <a 148 href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code 149 requiresSmallestWidthDp}</a> attribute is for devices running Android 3.2 and newer, which includes 150 the capability for apps to specify size requirements based on a minimum number of 151 density-independent pixels available. In this example, the app declares a minimum width requirement 152 of 600dp, which generally implies a 7"-or-greater screen. </p> 153 154 <p>Your size choice might be different, of course, based on how well your design works on different 155 screen sizes; for example, if your design works well only on screens that are 9" or larger, you 156 might require a minimum width of 720dp.</p> 157 158 <p>The catch is that you must compile your application against Android 3.2 or higher in order to use 159 the <code>requiresSmallestWidthDp</code> attribute. Older versions don't understand this attribute 160 and will raise a compile-time error. The safest thing to do is develop your app against the platform 161 that matches the API level you've set for <a 162 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">minSdkVersion</a 163 >. When you're making final preparations to build your release candidate, change the build target to 164 Android 3.2 and add the <code>requiresSmallestWidthDp</code> attribute. Android versions older than 165 3.2 simply ignore that XML attribute, so there's no risk of a runtime failure.</p> 166 167 <p>For more information about why the "smallest width" screen size is 168 important for supporting different screen sizes, read <a 169 href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html">New 170 Tools for Managing Screen Sizes</a>.</p> 171 172 <p class="caution"><strong>Caution:</strong> If you use the <a 173 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 174 <supports-screens>}</a> element for the reverse scenario (when your application is not compatible 175 with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then 176 external services such as Android Market <strong>do not</strong> apply filtering. Your application 177 will still be available to larger screens, but when it runs, it will not resize to fit the screen. 178 Instead, the system will emulate a handset screen size (about 320dp x 480dp; see <a 179 href="{@docRoot}guide/practices/screen-compat-mode.html">Screen Compatibility Mode</a> for more 180 information). If you want 181 to prevent your application from being downloaded on larger screens, use <a 182 href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 183 <compatible-screens>}</a>, as discussed in the previous section about <a 184 href="#FilteringHandsetApps">Declaring an App is Only for Handsets</a>.</p> 185 186 <p>Remember, you should strive to make your application available to as many devices as possible by 187 applying all necessary techniques for <a 188 href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a>. You should 189 use <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 190 <compatible-screens>}</a> or <a 191 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 192 <supports-screens>}</a> only when you cannot provide compatibility on all screen configurations 193 or you have decided to provide different versions of your application for different sets of screen 194 configurations.</p> 195 196 197 198 <h2 id="MultiApks">Publishing Multiple APKs for Different Screens</h2> 199 200 <p>Although we recommend that you publish one APK for your application, Android Market allows 201 you to publish multiple APKs for the same 202 application when each APK supports a different set of screen configurations (as declared in 203 the manifest file). For example, if you want to publish both a handset version and a tablet 204 version of your application, but you're unable to make the same APK work for both screen sizes, 205 you can actually publish two APKs for the same application listing. Depending on each device's 206 screen configuration, Android Market will deliver it the APK that you've declared to support that 207 device's screen.</p> 208 209 <p>Beware, however, that publishing multiple APKs for the same application is 210 considered an advanced feature and <strong>most applications should publish only one 211 APK that can support a wide range of device configurations</strong>. Supporting multiple screen 212 sizes, especially, is within reason using a single APK, as long as you follow the guide to 213 <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> 214 215 <p>If you need more information about how to publish multiple APKs on Android Market, read <a 216 href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> 217
