1 page.title=Creating Multiple APKs for Different GL Textures 2 parent.title=Maintaining Multiple APKs 3 parent.link=index.html 4 5 trainingnavtop=true 6 previous.title=Creating Multiple APKs for Different Screen Sizes 7 previous.link=screensize.html 8 next.title=Creating Multiple APKs with 2+ Dimensions 9 next.link=multiple.html 10 11 @jd:body 12 13 <style type="text/css"> 14 .blueCell { background-color: #9fc5e8;} 15 .greenCell { background-color: #b6d7a8;} 16 .redCell { background-color: #ea9999;} 17 </style> 18 19 <div id="tb-wrapper"> 20 <div id="tb"> 21 22 <!-- table of contents --> 23 <h2>This lesson teaches you to</h2> 24 <ol> 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> 31 </ol> 32 33 <!-- other docs (NOT javadocs) --> 34 <h2>You should also read</h2> 35 <ul> 36 <li><a href="http://developer.android.com/google/play/publishing/multiple-apks.html">Multiple APK 37 Support</a></li> 38 </ul> 39 40 </div> 41 </div> 42 43 <p>When developing your Android application to take advantage of multiple APKs on Google Play, its important to adopt some good practices from the get-go, and prevent unnecessary headaches further into the development process. This lesson shows you how to create multiple APKs of your app, each supporting a different subset of OpenGL texture formats. You will also gain some tools necessary to make maintaining a multiple APK codebase as painless as possible.</p> 44 45 46 <h2 id="Confirm">Confirm You Need Multiple APKs</h2> 47 48 <p>When trying to create an application that works across all available Android-powered 49 devices, naturally you want your application look its best on each individual device, regardless of 50 the fact they dont all support the same set of GL textures. It may seem at the outset as though 51 multiple APK support is the best solution, but this often isnt the case. The <a 52 href="{@docRoot}google/play/publishing/multiple-apks.html#ApiLevelOptions">Using Single APK 53 Instead</a> section of the multiple APK developer guide includes some useful information on how to 54 accomplish this with a single APK, including how to <a 55 href="{@docRoot}google/play/publishing/multiple-apks.html#TextureOptions">detect supported texture 56 formats at runtime</a>. Depending on your situation, it might be easier to bundle all formats with 57 your application, and simply pick which one to use at runtime.</p> 58 59 <p>If you can manage it, confining your application to a single APK has several advantages, 60 including:</p> 61 <ul> 62 <li>Publishing and Testing are easier</li> 63 <li>Theres only one codebase to maintain</li> 64 <li>Your application can adapt to device configuration changes</li> 65 <li>App restore across devices just works</li> 66 <li>You dont have to worry about market preference, behavior from "upgrades" from one APK to the 67 next, or which APK goes with which class of devices</li> 68 </ul> 69 70 <p>The rest of this lesson assumes that youve researched the topic, studiously absorbed the 71 material in the resources linked, and determined that multiple APKs are the right path for your 72 application.</p> 73 74 75 <h2 id="ChartReqs">Chart Your Requirements</h2> 76 77 <p>The Android Developer Guide provides a handy reference of some of common supported textures on 78 the <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">supports-gl-texture 79 page</a>. This page also contains some hints as to which phones (or families of phones) support 80 particular texture formats. Note that its generally a good idea for one of your APKs to support 81 ETC1, as that texture format is supported by all Android-powered devices that support the OpenGL ES 82 2.0 spec.</p> 83 84 <p>Since most Android-powered devices support more than one texture format, you need to establish an 85 order of preference. Create a chart including all the formats that your application is going to 86 support. The left-most cell is going to be the lowest priority (It will probably be ETC1, a really 87 solid default in terms of performance and compatibility). Then color in the chart such that each 88 cell represents an APK.</p> 89 <table cellpadding="10" cellspacing="0" border="1"> 90 <tbody> 91 <tr> 92 <td class="blueCell">ETC1</td> 93 <td class="redCell">ATI</td> 94 <td class="greenCell">PowerVR</td> 95 </tr> 96 </tbody> 97 </table> 98 99 <p> 100 Coloring in the chart does more than just make this guide less monochromatic - It also has a way of 101 making intra-team communication easier- You can now simply refer to each APK as "blue", "green", or 102 "red", instead of "The one that supports ETC1 texture formats", etc.</p> 103 104 <h2 id="CreateLibrary">Put All Common Code and Resources in a Library Project</h2> 105 <p>Whether youre modifying an existing Android application or starting one from scratch, this is 106 the first thing that you should do to the codebase, and by the far the most important. Everything 107 that goes into the library project only needs to be updated once (think language-localized strings, 108 color themes, bugs fixed in shared code), which improves your development time and reduces the 109 likelihood of mistakes that could have been easily avoided.</p> 110 111 <p class="note"><strong>Note:</strong> While the implementation details of how to create and 112 include library projects are beyond the scope of this lesson, you can get up to speed 113 by reading <a 114 href="{@docRoot}studio/projects/android-library.html">Create an Android Library</a>.</p> 115 116 <p>If youre converting an existing application to use multiple APK support, 117 scour your codebase for every localized string file, list of values, theme 118 colors, menu icons and layout that isnt going to change across APKs, and put 119 it all in the library project. Code that isnt going to change much should 120 also go in the library project. Youll likely find yourself extending these 121 classes to add a method or two from APK to APK.</p> 122 123 <p>If, on the other hand, youre creating the application from scratch, try as 124 much as possible to write code in the library project <em>first</em>, then only move it down to an 125 individual APK if necessary. This is much easier to manage in the long run than adding it to one, 126 then another, then another, then months later trying to figure out whether this blob can be moved up 127 to the library section without screwing anything up.</p> 128 129 <h2 id="CreateAPKs">Create New APK Projects</h2> 130 <p>There should be a separate Android project for each APK youre going to release. For easy 131 organization, place the library project and all related APK projects under the same parent folder. 132 Also remember that each APK needs to have the same package name, although they dont necessarily 133 need to share the package name with the library. If you were to have 3 APKs following the scheme 134 described earlier, your root directory might look like this:</p> 135 136 <pre class="no-pretty-print classic"> 137 alexlucas:~/code/multi-apks-root$ ls 138 foo-blue 139 foo-green 140 foo-lib 141 foo-red 142 </pre> 143 144 145 <p>Once the projects are created, add the library project as a reference to each APK project. If 146 possible, define your starting Activity in the library project, and extend that Activity in your APK 147 project. Having a starting activity defined in the library project gives you a chance to put all 148 your application initialization in one place, so that each individual APK doesnt have to 149 re-implement "universal" tasks like initializing Analytics, running licensing checks, and any other 150 initialization procedures that dont change much from APK to APK.</p> 151 152 153 <h2 id="AdjustManifests">Adjust the Manifests</h2> 154 <p>When a user downloads an application which uses multiple APKs through Google Play, the correct 155 APK to use is chosen using some simple rules:</p> 156 157 <ul> 158 <li>The manifest has to show that particular APK is eligible</li> 159 <li>Of the eligible APKs, highest version number wins</li> 160 <li>If <em>any</em> of the texture formats listed in your APK are supported by the device on market, 161 that device is considered eligible</li> 162 </ul> 163 164 <p>With regards to GL Textures, that last rule is important. It means that you should, for 165 instance, be <em>very</em> careful about using different GL formats in the same application. If you 166 were to use PowerVR 99% of the time, but use ETC1 for, say, your splash screen... Then your manifest 167 would necessarily indicate support for both formats. A device that <em>only</em> supported ETC1 168 would be deemed compatible, your app would download, and the user would see some thrilling crash 169 messages. The common case is going to be that if youre using multiple APKs specifically to target 170 different devices based on GL texture support, its going to be one texture format per APK.</p> 171 172 <p>This actually makes texture support a little bit different than the other two multiple APK 173 dimensions, API level and screen size. Any given device only has one API level, and one screen 174 size, and its up to the APK to support a range of them. With textures, the APK will generally 175 support one texture, and the device will support many. There will often be overlap in terms of one 176 device supporting many APKs, but the solution is the same: Version codes.</p> 177 178 <p>By way of example, take a few devices, and see how many of the APKs defined earlier fit each 179 device.</p> 180 <table cellpadding="10" cellspacing="0" border="1"> 181 <tbody> 182 <tr> 183 <td>FooPhone</td> 184 <td>Nexus S</td> 185 <td>Evo</td> 186 </tr> 187 <tr> 188 <td class="blueCell">ETC1</td> 189 <td class="blueCell">ETC1</td> 190 <td class="blueCell">ETC1</td> 191 </tr> 192 <tr> 193 <td></td> 194 <td class="greenCell">PowerVR</td> 195 <td class="redCell">ATI TC</td> 196 </tr> 197 </tbody> 198 </table> 199 <p> Assuming that PowerVR and ATI formats are both preferred over ETC1 when available, than 200 according to the "highest version number wins" rule, if we set the versionCode attribute in each APK 201 such that red ≥ green ≥ blue, then both Red and Green will always be chosen over Blue on 202 devices which support them, and should a device ever come along which supports both Red and Green, 203 red will be chosen. 204 </p> 205 206 <p> In order to keep all your APKs on separate "tracks," its important to have a good version code 207 scheme. The recommended one can be found on the Version Codes area of our developer guide. Since 208 the example set of APKs is only dealing with one of 3 possible dimensions, it would be sufficient to 209 separate each APK by 1000 and increment from there. This might look like:</p> 210 211 <p>Blue: 1001, 1002, 1003, 1004...<br /> 212 Green: 2001, 2002, 2003, 2004...<br /> 213 Red:3001, 3002, 3003, 3004...</p> 214 215 <p> Putting this all together, your Android Manifests would likely look something like the 216 following:</p> 217 <p>Blue:</p> 218 <pre> 219 <manifest xmlns:android="http://schemas.android.com/apk/res/android" 220 android:versionCode="1001" android:versionName="1.0" package="com.example.foo"> 221 <supports-gl-texture android:name="GL_OES_compressed_ETC1_RGB8_texture" /> 222 ... 223 </pre> 224 225 <p>Green:</p> 226 <pre> 227 <manifest xmlns:android="http://schemas.android.com/apk/res/android" 228 android:versionCode="2001" android:versionName="1.0" package="com.example.foo"> 229 <supports-gl-texture android:name="GL_AMD_compressed_ATC_texture" /> 230 ... 231 </pre> 232 233 <p>Red:</p> 234 <pre> 235 <manifest xmlns:android="http://schemas.android.com/apk/res/android" 236 android:versionCode="3001" android:versionName="1.0" package="com.example.foo"> 237 <supports-gl-texture android:name="GL_IMG_texture_compression_pvrtc" /> 238 ... 239 </pre> 240 241 <h2 id="PreLaunch">Go Over Pre-launch Checklist</h2> 242 <p>Before uploading to Google Play, double-check the following items. Remember that these are 243 specifically relevant to multiple APKs, and in no way represent a complete checklist for all 244 applications being uploaded to Google Play.</p> 245 246 <ul> 247 <li>All APKs must have the same package name</li> 248 <li>All APKs must be signed with the same certificate</li> 249 <li>Double check your manifest filters for conflicting information (an APK that only supports 250 cupcake on XLARGE screens isnt going to be seen by anybody)</li> 251 <li>Each APK's manifest must be unique across at least one of supported screen, OpenGL texture, or 252 platform version</li> 253 <li>Try to test each APK on at least one device. Barring that, you have one of the most 254 customizable device emulators in the business sitting on your development machine. Go nuts!</li> 255 </ul> 256 257 <p>Its also worth inspecting the compiled APK before pushing to market, to make sure there arent 258 any surprises that could hide your application on Google Play. This is actually quite simple using the 259 "aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and 260 packaging your Android applications, and is also a very handy tool for inspecting them. </p> 261 262 <pre class="no-pretty-print classic"> 263 >aapt dump badging 264 package: name='com.example.hello' versionCode='1' versionName='1.0' 265 sdkVersion:'11' 266 uses-permission:'android.permission.SEND_SMS' 267 application-label:'Hello' 268 application-icon-120:'res/drawable-ldpi/icon.png' 269 application-icon-160:'res/drawable-mdpi/icon.png' 270 application-icon-240:'res/drawable-hdpi/icon.png' 271 application: label='Hello' icon='res/drawable-mdpi/icon.png' 272 launchable-activity: name='com.example.hello.HelloActivity' label='Hello' icon='' 273 uses-feature:'android.hardware.telephony' 274 uses-feature:'android.hardware.touchscreen' 275 main 276 supports-screens: 'xlarge' 277 supports-any-density: 'true' 278 locales: '--_--' 279 densities: '120' '160' '240' 280 </pre> 281 282 <p>When you examine aapt output, be sure to check that you dont have conflicting values for 283 supports-screens and compatible-screens, and that you dont have unintended "uses-feature" values 284 that were added as a result of permissions you set in the manifest. In the example above, the APK 285 will be invisible to most, if not all devices.</p> 286 <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, Google Play 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. 287 </p> 288 <p>Fortunately this is easily fixed by adding the following to your manifest:</p> 289 <pre> 290 <uses-feature android:name="android.hardware.telephony" android:required="false" /> 291 </pre> 292 <p>The <code>android.hardware.touchscreen</code> requirement is also implicitly added. If you want your APK to be visible on TVs which are non-touchscreen devices you should add the following to your manifest:</p> 293 <pre> 294 <uses-feature android:name="android.hardware.touchscreen" android:required="false" /> 295 </pre> 296 297 <p>Once youve completed the pre-launch checklist, upload your APKs to Google Play. It may take a bit for the application to show up when browsing Google Play, 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, youre done!</p> 298