When submitting your game to the the Google Play store, you will see that it currently limits the upload size of an individual application following these simple rules:
- 100MB - APKs that target Android 2.3 and higher (API level 9-10 and 14+)
- 50MB - APKs that target Android 2.2 and lower (API level 8 or lower)
However there are larger games out there that you can download and they use APK Expansions to get around this maximum file size limit.
IMPORTANT! This feature is for APK files only, and will not function - nor is it required - for AAB files.
An APK Expansion splits your final game into two parts, the *.apk and the expansion *.zip, with all the game assets placed in the separate expansion file in order to reduce the overall size of the initial *.apk package. On the Store, the total application size of APK + ZIP will be shown, but when the user installs the game, first the APK is installed and then the ZIP installed separately. In this way you can have larger games on the Store (with a maximum size of 2GB for an expansion ZIP).
Before going any further, you should note that this feature requires a Google Licensing Public Key to work, and so you will need to have prepared a store listing for your game to get this.
Using Expansions
This functionality is only available to you on the Android target platform, and can be activated by clicking the checkbox for it that you can find in the Android Game Options Packaging Section.
Clicking the checkbox will prompt you to download and install the YoYo Games APK Expansion extension. Select "Yes" when prompted, then add the extension to your account from the Marketplace page that opens and click the "Download" button - this will then open your Library window where you can search for the asset and install it:
Once installed, you will then have to do the same for the Licensing options, and click the Enable Google Licensing checkbox then follow the same procedure as before to install the extension. Finally, you should add your public key into the Google Licensing Public Key area of the options. You can get the Public Key from the Services and APIs section of the Developer Dashboard for your game listing:
The following is worth noting before you decide to go ahead and use this feature:
- The checkbox only takes effect when you use Create Application, and not on testing
- You must have “Enable Google Licensing” checked, a valid Public Key, and the Licensing extension installed
- You must use the correct package name as defined in the store listing for the game (for example, the default “com.yoyogames.runner” as the Package Name will not work)
It is also worth noting that this option will create an expansion file regardless of the final size of your .apk. However there is no point using this functionality if your final .apk is less than the 50/100MB limit or if you are not planning on uploading it to Google Play, since this feature is exclusively for use on that store.
Uploading The Game
Once Create Application has completed (using either the VM or YYC option), you will find that as well as the usual “<ProjectName>-<Config>.x.y.z.apk” file, there will be an additional “<ProjectName>-<Config>.x.y.z-assets.zip” output to the chosen folder for your game. Now, when you upload the .apk file to the Google Play store from your developer dashboard, you must also upload this assets.zip file along with the .apk file.
It is worth noting the following important conditions for using this feature:
- Your expansion file has a maximum size of 2GB.
- When updating an expansion file manually, you must delete the previous file.
- Whenever you upload a new apk with a different version number, you must also upload the matching assets.zip as the expansion file. You cannot update only the apk and assume the assets will work, as they will not since the version codes won't match.
- You cannot update your game by changing the expansion files alone you must upload a new *.apk too.
- In order to download your expansion files from Google Play, the user must have acquired your application from Google Play. Google Play will not provide the URLs for your expansion files if the application was installed by other means.
Testing Your Game Expansion
Because your application must manually download the expansion, it is very important that you test the feature to be sure that your game can successfully query for the URLs, download the files, save them to the device, and then access them.
To test your game and its expansion, you must first upload it to your Google Play developers dashboard as a an "Alpha" build, and this will make your expansion files available for download to those people added to your tester list.
When you run the installed *.apk and Google Play is ready with the expansion file, download will commence and you will see a progress bar along with related information.
NOTE: It can take several hours before the expansion file will be available from Google Play. If you run the *.apk on the device during this time, the download will fail, because Google Play will report that there is no file available.
Once the download is complete, the game will launch, but it is worth noting the following before testing:
- If you re-install the *.apk via Create Application, the expansion file is removed and will be re-downloaded (the option to install the *.apk on create can be found in the Android Preferences)
- If you install an *.apk with a different version number, but don’t upload the matching expansion file, the download will fail, due to mismatched version codes.
Once the download is complete, if you close and re-start the game, it will start immediately, with no further downloads since the expansion file is already on the device.