Expansion files are used on the Play Store when targeting Android devices. This guide provides an explanation of what expansion files are and how they can be used.
The Play Store for Google has a maximum file size limit of 100 mb for your application. If your application exceeds this limit then you will need to split your application into two parts - the main application, which must be 100 mb or under and an expansion file that has no size limit.
As an example consider a program that has been created to play a collection of videos. The media for the program is as follows -
If you were to generate an APK for this program it would come in at over 235 mb. This APK could not be uploaded to the Play Store, therefore it would require the use of an expansion file. In this example you would remove the video files from the main project, resulting in the APK begin around 35 mb, and then create an expansion file for the videos, which would be 200 mb. Taking these actions means you ensure your main application APK is well under the 100 mb limit, so you'll have no problems uploading it to the Play Store alongside your expansion file.
An expansion file is essentially a ZIP file that has been created without using any form of compression. To create an expansion file you can use software such was WinZip or WinRar, then select the files you want to add into the expansion file and create a ZIP file from them, ensuring you turn off compression. When the ZIP file has been generated simply rename its extension from .zip to .obb.
Once created the expansion file will need to be named correctly. It must have a version number in it and also the package name for the application e.g.
An application downloaded from the Play Store may have its expansion file automatically downloaded, although in some cases this may not happen. Your program will need to take into account these options and cater for them accordingly. The typical logic for dealing with an expansion file will be something like this -
Call SetExpansionFileKey at the start of your program. This is a command that takes in a parameter defining the public key to use for the expansion file. The public key can be found in the Google Play Developer Console and is different for each app. Click on the app and then click on the Services and APIs section, it is the long string that starts MIIB
Call SetExpansionFileVersion passing in the version number for the expansion file.
Make a call to GetExpansionFileState to check the status of the expansion file. This command will return -1 if some kind of error has occurred. A value of 0 will be returned if the expansion file is not used on this platform e.g. on iOS. It will return 1 if the app requires an expansion file that has not been downloaded. A value of 2 will be returned if the expansion file is currently being downloaded. Finally a value of 3 is returned if the expansion file has been downloaded and is available for use.
In the event that GetExpansionFileState returns 1 then it is your responsibility to download the expansion file. To initiate the download of an expansion file call DownloadExpansionFile. After this command has been called you should continually check the return value of GetExpansionFileState. It will return a value of 2 while the expansion file is being downloaded. If this is the case you should let the user know that the file is being downloaded. The progress of the download can be monitored by calling GetExpansionFileProgress, which returns a value between 0 and 100 indicating the current download progress. When GetExpansionFileState returns 3 you can break out of this process and continue your normal logic for the application.
The following code shows how this process might work -
SetExpansionFileKey("MIIB...") // base 64 encoded public key from your Google Play app settings
SetExpansionFileVersion(version)
if ( GetExpansionFileState() = 1 )
DownloadExpansionFile()
if ( GetExpansionFileState() = 2 )
fontimage=LoadImage("/Arial.png")
downloadtxt = CreateText("Downloading Additional Files")
progresstxt = CreateText("0%")
othertxt = CreateText("The download will continue in the background if you close the app")
SetTextAlignment(downloadtxt,1)
SetTextAlignment(progresstxt,1)
SetTextAlignment(othertxt,1)
SetTextPosition(downloadtxt,50,30)
SetTextPosition(progresstxt,50,40)
SetTextPosition(othertxt,50,50)
SetTextFontImage(downloadtxt,fontimage)
SetTextFontImage(progresstxt,fontimage)
SetTextFontImage(othertxt,fontimage)
while ( GetExpansionFileState() = 2 )
progress# = GetExpansionFileProgress()
SetTextString(progresstxt,Str(progress#,2)+"%")
Sync()
endwhile
DeleteText(downloadtxt)
DeleteText(progresstxt)
DeleteText(othertxt)
DeleteImage( fontImage )
endif
endif
Media contained within an expansion file can still be loaded using the regular commands e.g. LoadImage and LoadVideo. There is one important difference to be aware of - you must precede the filename with "expansion:" and not uses paths.
Take the example of a file called video.mp4 that is placed in a video folder. If no expansion file was being used it would be loaded like this -
LoadVideo ( "video\video.mp4" )
When loading media from an expansion file the load call would need to be changed to this -
LoadVideo ( "expansion:video.mp4" )
The same principle applies when dealing with loading media using other commands.
Expansion files can be tested locally or through the Google Play Beta Testing. To test your expansion files locally -
To test through the Play Store upload your APK to the Beta Testing section using the advanced mode. At this point you will be able to upload your main APK and the expansion file.
Expansion files are vital when targeting the Play Store if your application file size exceeds 100 mb. Bear in mind that on other platforms this restriction does not exist, so your application will need to be coded to handle the different scenarios.
App Game Kit © The Game Creators Ltd. All Rights Reserved. Report an issue