Tech
APK Expansions And Google Play
When submitting your game to the the Google Play store, you will see that it currently limits the upload size of an individual application to 100MB. However there are larger games out there that you can download and they get around this limitation by using APK Expansions.
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. Now, when the user installs your game and then runs it for the first time, they will be prompted to download the package either over WifFi or from their mobile carrier, and once downloaded it will be installed on the device to create the full game.
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 will find in the Global Game Settings Licencing Tab. You will also have to click the Enable Google Licencing checkbox and add your public key too.
There are a few conditions attached to this option, which we list below:
- The checkbox only takes effect when you use Create Application, and not on testing
- Android YYC is not currently supported
- You must have “Enable Google Licensing” checked, and a valid Public Key (available from your Google Play Dashboard)
- You must use a correct package name (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 50MB 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 compiling your game, 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 as a main expansion file (you will see that there is also a “patch” expansion file option, but this can be ignored).
This feature does have it's limits, however:
- 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 files when it first opens, 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 "draft" application, and this will make your expansion files available for download. The actual procedure is as follows:
- Upload your *.apk and corresponding expansion *.zip using the Google Play Developer Console.
- Fill in the necessary game details (you can come back and finalize these details before publishing your game).
- Click the Save button. Do not click Publish. This saves the game as a "draft", such that your game is not published for Google Play users, but the expansion files are available for you to test the download process.
- Install the game on your test device using ADB.
- Launch the game.
- 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 and you should be able to play as normal. That doesn't mean to say that from now on everything is perfect, as there are also a few things to note about the content downloaded in this way:
- 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 neglect to 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.
And that's it! The 50MB limit that the Google Play store imposes is no longer an issue for those of you making larger games.