1 page.title=Creating Multiple APKs with 2+ Dimensions
2 parent.title=Creating and Maintaining Multiple APKs
6 previous.title=Creating Multiple APKs for Different GL Textures
7 previous.link=texture.html
12 .blueCell { background-color: #9fc5e8;}
13 .greenCell { background-color: #b6d7a8;}
14 .redCell { background-color: #ea9999;}
15 .purpleCell { background-color: #b4a7d6;}
16 .blackCell { background-color: #000000;}
22 <!-- table of contents -->
23 <h2>This lesson teaches you to</h2>
25 <li><a href="#Confirm">Confirm You Need Multiple APKs</a></li>
26 <li><a href="#ChartReqs">Chart Your Requirements</a></li>
27 <li><a href="#CreateLibrary">Put All Common Code and Resources in a Library Project.</a></li>
28 <li><a href="#CreateAPKs">Create New APK Projects</a></li>
29 <li><a href="#AdjustManifests">Adjust the Manifests</a></li>
30 <li><a href="#PreLaunch">Go Over Pre-launch Checklist</a></li>
33 <!-- other docs (NOT javadocs) -->
34 <h2>You should also read</h2>
36 <li><a href="http://developer.android.com/guide/market/publishing/multiple-apks.html">Multiple APK
43 <p>When developing your Android application to take advantage of multiple APKs on Android Market,
44 it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches
45 further into the development process. This lesson shows you how to create multiple APKs of your
46 app, each covering a different class of screen size. You will also gain some tools necessary to
47 make maintaining a multiple APK codebase as painless as possible.</p>
50 <h2 id="Confirm">Confirm You Need Multiple APKs</h2>
52 <p>When trying to create an application that works across the huge range of available Android
53 devices, naturally you want your application look its best on each individual device. You want to
54 take advantage of the space of large screens but still work on small ones, to use new Android API
55 features or visual textures available on cutting edge devices but not abandon older ones. It may
56 seem at the outset as though multiple APK support is the best solution, but this often isn’t the
57 case. The <a href="{@docRoot}guide/market/publishing/multiple-apks.html#ApiLevelOptions">Using
58 Single APK Instead</a> section of the multiple APK guide includes some useful information on how to
59 accomplish all of this with a single APK, including use of our <a
60 href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">support library</a>,
61 and links to resources throughout the Android Developer guide.</p>
63 <p>If you can manage it, confining your application to a single APK has several advantages,
67 <li>Publishing and Testing are easier</li>
68 <li>There’s only one codebase to maintain</li>
69 <li>Your application can adapt to device configuration changes</li>
70 <li>App restore across devices just works</li>
71 <li>You don’t have to worry about market preference, behavior from "upgrades" from one APK to the
72 next, or which APK goes with which class of devices</li>
75 <p>The rest of this lesson assumes that you’ve researched the topic, studiously absorbed the
76 material in the resources linked, and determined that multiple APKs are the right path for your
80 <h2 id="ChartReqs">Chart Your Requirements</h2>
82 <p>Start off by creating a simple chart to quickly determine how many APKs you need, and what screen
83 size(s) each APK covers. Fortunately, it’s easy to chart out your requirements quickly, easily, and
84 have an easy reference for later. Let’s say you want to split your APKs across two dimensions, API
85 and screen size. Create a table with a row and column for each possible pair of values, and color
86 in some "blobs", each color representing one APK.</p>
88 <table cellpadding="10" cellspacing="0" border="1">
105 <td class="blueCell"></td>
106 <td class="blueCell"></td>
107 <td class="blueCell"></td>
108 <td class="blueCell"></td>
109 <td class="blueCell"></td>
110 <td class="blueCell"></td>
111 <td class="blueCell"></td>
112 <td class="blueCell"></td>
113 <td class="purpleCell"></td>
114 <td class="purpleCell"></td>
115 <td class="purpleCell"></td>
119 <td class="blueCell"></td>
120 <td class="blueCell"></td>
121 <td class="blueCell"></td>
122 <td class="blueCell"></td>
123 <td class="blueCell"></td>
124 <td class="blueCell"></td>
125 <td class="blueCell"></td>
126 <td class="blueCell"></td>
127 <td class="purpleCell"></td>
128 <td class="purpleCell"></td>
129 <td class="purpleCell"></td>
133 <td class="greenCell"></td>
134 <td class="greenCell"></td>
135 <td class="greenCell"></td>
136 <td class="greenCell"></td>
137 <td class="greenCell"></td>
138 <td class="greenCell"></td>
139 <td class="greenCell"></td>
140 <td class="greenCell"></td>
141 <td class="purpleCell"></td>
142 <td class="purpleCell"></td>
143 <td class="purpleCell"></td>
147 <td class="redCell"></td>
148 <td class="redCell"></td>
149 <td class="redCell"></td>
150 <td class="redCell"></td>
151 <td class="redCell"></td>
152 <td class="redCell"></td>
153 <td class="redCell"></td>
154 <td class="redCell"></td>
155 <td class="purpleCell"></td>
156 <td class="purpleCell"></td>
157 <td class="purpleCell"></td>
163 Above is an example with four APKs. Blue is for all small/normal screen devices, Green is for large
164 screen devices, and Red is for xlarge screen devices, all with an API range of 3-10. Purple is a
165 special case, as it’s for all screen sizes, but only for API 11 and up. More importantly, just by
166 glancing at this chart, you immediately know which APK covers any given API/screen-size combo. To
167 boot, you also have swanky codenames for each one, since "Have we tested red on the ?" is a lot
168 easier to ask your cubie than "Have we tested the 3-to-10 xlarge APK against the Xoom?" Print this
169 chart out and hand it to every person working on your codebase. Life just got a lot easier.</p>
171 <h2 id="CreateLibrary">Put All Common Code and Resources in a Library Project.</h2>
173 <p>Whether you’re modifying an existing Android application or starting one from scratch, this is
174 the first thing that you should do to the codebase, and by the far the most important. Everything
175 that goes into the library project only needs to be updated once (think language-localized strings,
176 color themes, bugs fixed in shared code), which improves your development time and reduces the
177 likelihood of mistakes that could have been easily avoided.</p>
179 <p class="note"><strong>Note:</strong> While the implementation details of how to create and
180 include library projects are beyond the scope of this lesson, you can get up to speed quickly on
181 their creation at the following links:</p>
184 href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject">Setting up
185 a library project (Eclipse)</a></li>
187 href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject">Setting up
188 a library project (Command line)</a></li>
191 <p>If you’re converting an existing application to use multiple APK support,
192 scour your codebase for every localized string file, list of values, theme
193 colors, menu icons and layout that isn’t going to change across APKs, and put
194 it all in the library project. Code that isn’t going to change much should
195 also go in the library project. You’ll likely find yourself extending these
196 classes to add a method or two from APK to APK.</p>
198 <p>If, on the other hand, you’re creating the application from scratch, try as
199 much as possible to write code in the library project <em>first</em>, then only move it down to an
200 individual APK if necessary. This is much easier to manage in the long run than adding it to one,
201 then another, then another, then months later trying to figure out whether this blob can be moved up
202 to the library section without screwing anything up.</p>
204 <h2 id="CreateAPKs">Create New APK Projects</h2>
205 <p>There should be a separate Android project for each APK you’re going to release. For easy
206 organization, place the library project and all related APK projects under the same parent folder.
207 Also remember that each APK needs to have the same package name, although they don’t necessarily
208 need to share the package name with the library. If you were to have 3 APKs following the scheme
209 described earlier, your root directory might look like this:</p>
211 <pre class="no-pretty-print classic">
212 alexlucas:~/code/multi-apks-root$ ls
220 <p>Once the projects are created, add the library project as a reference to each APK project. If
221 possible, define your starting Activity in the library project, and extend that Activity in your APK
222 project. Having a starting activity defined in the library project gives you a chance to put all
223 your application initialization in one place, so that each individual APK doesn’t have to
224 re-implement "universal" tasks like initializing Analytics, running licensing checks, and any other
225 initialization procedures that don’t change much from APK to APK.</p>
228 <h2 id="AdjustManifests">Adjust the Manifests</h2>
229 <p>When a user downloads an application which uses multiple APKs through Android Market, the correct
230 APK to use is chosen using two simple rules:
233 <li>The manifest has to show that particular APK is eligible</li>
234 <li>Of the eligible APKs, highest version number wins.</li>
237 <p>By way of example, let’s take the set of multiple APKs described earlier, and assume that each
238 APK has been set to support all screen sizes larger than its "target" screen size. Let’s look at
239 the sample chart from earlier:</p>
241 <table cellpadding="10" cellspacing="0" border="1">
258 <td class="blueCell"></td>
259 <td class="blueCell"></td>
260 <td class="blueCell"></td>
261 <td class="blueCell"></td>
262 <td class="blueCell"></td>
263 <td class="blueCell"></td>
264 <td class="blueCell"></td>
265 <td class="blueCell"></td>
266 <td class="purpleCell"></td>
267 <td class="purpleCell"></td>
268 <td class="purpleCell"></td>
272 <td class="blueCell"></td>
273 <td class="blueCell"></td>
274 <td class="blueCell"></td>
275 <td class="blueCell"></td>
276 <td class="blueCell"></td>
277 <td class="blueCell"></td>
278 <td class="blueCell"></td>
279 <td class="blueCell"></td>
280 <td class="purpleCell"></td>
281 <td class="purpleCell"></td>
282 <td class="purpleCell"></td>
286 <td class="greenCell"></td>
287 <td class="greenCell"></td>
288 <td class="greenCell"></td>
289 <td class="greenCell"></td>
290 <td class="greenCell"></td>
291 <td class="greenCell"></td>
292 <td class="greenCell"></td>
293 <td class="greenCell"></td>
294 <td class="purpleCell"></td>
295 <td class="purpleCell"></td>
296 <td class="purpleCell"></td>
300 <td class="redCell"></td>
301 <td class="redCell"></td>
302 <td class="redCell"></td>
303 <td class="redCell"></td>
304 <td class="redCell"></td>
305 <td class="redCell"></td>
306 <td class="redCell"></td>
307 <td class="redCell"></td>
308 <td class="purpleCell"></td>
309 <td class="purpleCell"></td>
310 <td class="purpleCell"></td>
314 <p>Since it’s okay for coverage to overlap, we can describe the area covered by each APK like
317 <li>Blue covers all screens, minSDK 3.</li>
318 <li>Green covers Large screens and higher, minSDK 3.</li>
319 <li>Red covers XLarge screens (generally tablets), minSDK of 9.</li>
320 <li>Purple covers all screens, minSDK of 11.</li>
322 <p>Note that there’s a <em>lot</em> of overlap in those rules. For instance, an
323 XLarge device with API 11 can conceivably run any one of the 4 APKs specified.
324 However, by using the "highest version number wins" rule, we can set an order of
325 preference as follows:</p>
327 Purple ≥ Red ≥ Green ≥ Blue
329 Why allow all the overlap? Let’s pretend that the Purple APK has some requirement on it that the
330 other two don’t. The <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters page</a>
331 of the Android Developer guide has a whole list of possible culprits. For the sake of example,
332 let’s assume that Purple requires a front-facing camera. In fact, the entire point of Purple is to
333 use entertaining things with the front-facing camera! But, it turns out, not all API 11+ devices
334 even HAVE front-facing cameras! The horror!</p>
336 <p>Fortunately, if a user is browsing Market from one such device, Android Market will look at the
337 manifest, see that Purple lists the front-facing camera as a requirement, and quietly ignore it,
338 having determined that Purple and that device are not a match made in digital heaven. It will then
339 see that Red is not only compatible with xlarge devices, but also doesn’t care whether or not
340 there’s a front-facing camera! The app can still be downloaded from Android Market by the user,
341 because despite the whole front-camera mishap, there was still an APK that supported that particular
344 <p> In order to keep all your APKs on separate "tracks", it’s important to have a good version code
345 scheme. The recommended one can be found on the <a
346 href="{@docRoot}guide/market/publishing/multiple-apks.html#VersionCodes">Version Codes</a> area of
347 our developer guide. It’s worth reading the whole section, but the basic gist is for this set of
348 APKs, we’d use two digits to represent the minSDK, two to represent the min/max screen size, and 3
349 to represent the build number. That way, when the device upgraded to a new version of Android,
350 (say, from 10 to 11), any APKs that are now eligible and preferred over the currently installed one
351 would be seen by the device as an "upgrade". The version number scheme, when applied to the example
352 set of APKs, might look like:</p>
354 <p>Blue: 0304001, 0304002, 0304003...<br />
355 Green: 0334001, 0334002, 0334003<br />
356 Red: 0344001, 0344002, 0344003...<br />
357 Purple: 1104001, 1104002, 1104003...<br />
360 <p> Putting this all together, your Android Manifests would likely look something like the
364 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
365 android:versionCode="0304001" android:versionName="1.0" package="com.example.foo">
366 <uses-sdk android:minSdkVersion="3" />
367 <supports-screens android:smallScreens="true"
368 android:normalScreens="true"
369 android:largeScreens="true"
370 android:xlargeScreens="true" />
376 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
377 android:versionCode="0334001" android:versionName="1.0" package="com.example.foo">
378 <uses-sdk android:minSdkVersion="3" />
379 <supports-screens android:smallScreens="false"
380 android:normalScreens="false"
381 android:largeScreens="true"
382 android:xlargeScreens="true" />
388 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
389 android:versionCode="0344001" android:versionName="1.0" package="com.example.foo">
390 <uses-sdk android:minSdkVersion="3" />
391 <supports-screens android:smallScreens="false"
392 android:normalScreens="false"
393 android:largeScreens="false"
394 android:xlargeScreens="true" />
400 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
401 android:versionCode="1104001" android:versionName="1.0" package="com.example.foo">
402 <uses-sdk android:minSdkVersion="11" />
403 <supports-screens android:smallScreens="true"
404 android:normalScreens="true"
405 android:largeScreens="true"
406 android:xlargeScreens="true" />
411 Note that technically, multiple APK’s will work with either the supports-screens tag, or the
412 compatible-screens tag. Supports-screens is generally preferred, and it’s generally a really bad
413 idea to use both- It makes things needlessly complicated, and increases the opportunity for errors.
414 Also note that instead of taking advantage of the default values (small and normal are always true
415 by default), the manifests explicitly set the value for each screen size. This can save you
416 headaches down the line - By way of example, a manifest with a target SDK of < 9 will have xlarge
417 automatically set to false, since that size didn’t exist yet. So be explicit!
420 <h2 id="PreLaunch">Go Over Pre-launch Checklist</h2>
421 <p> Before uploading to Android Market, double-check the following items. Remember that these are
422 specifically relevant to multiple APKs, and in no way represent a complete checklist for all
423 applications being uploaded to Android Market.</p>
425 <li>All APKs must have the same package name.</li>
426 <li>All APKs must be signed with the same certificate.</li>
427 <li>If the APKs overlap in platform version, the one with the higher minSdkVersion must have a
428 higher version code.</li>
429 <li>Every screen size you want your APK to support, set to true in the manifest. Every screen size
430 you want it to avoid, set to false.</li>
431 <li>Double check your manifest filters for conflicting information (an APK that only supports
432 cupcake on XLARGE screens isn’t going to be seen by anybody)</li>
433 <li>Each APK's manifest must be unique across at least one of supported screen, OpenGL texture, or
434 platform version.</li>
435 <li>Try to test each APK on at least one device. Barring that, you have one of the most
436 customizable device emulators in the business sitting on your development machine. Go nuts!</li>
439 <p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t
440 any surprises that could hide your application in Market. This is actually quite simple using the
441 "aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and
442 packaging your Android applications, and is also a very handy tool for inspecting them. </p>
444 <pre class="no-pretty-print classic">
445 >aapt dump badging
446 package: name='com.example.hello' versionCode='1' versionName='1.0'
448 uses-permission:'android.permission.SEND_SMS'
449 application-label:'Hello'
450 application-icon-120:'res/drawable-ldpi/icon.png'
451 application-icon-160:'res/drawable-mdpi/icon.png'
452 application-icon-240:'res/drawable-hdpi/icon.png'
453 application: label='Hello' icon='res/drawable-mdpi/icon.png'
454 launchable-activity: name='com.example.hello.HelloActivity' label='Hello' icon=''
455 uses-feature:'android.hardware.telephony'
456 uses-feature:'android.hardware.touchscreen'
458 supports-screens: 'xlarge'
459 supports-any-density: 'true'
461 densities: '120' '160' '240'
464 <p>When you examine aapt output, be sure to check that you don’t have conflicting values for
465 supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values
466 that were added as a result of permissions you set in the manifest. In the example above, the APK
467 will be invisible to most, if not all devices.</p>
468 <p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Market will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware.
470 <p>Fortunately this is easily fixed by adding the following to your manifest:<p>
472 <uses-feature android:name="android.hardware.telephony" android:required="false" />
475 <p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p>