# Expansion Files

## Intermediate Level Tutorial

## What you will learn

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.

## What are expansion files?

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 -

- Graphics totalling 20 mb
- Sound files around 15 mb
- Videos coming in at 200 mb

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.

## Creating an 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.

- main.1.uk.co.mycompany.mygame.obb

## Downloading an expansion file

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

## Loading media from an expansion file

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.

## Testing expansion files

Expansion files can be tested locally or through the Google Play Beta Testing. To test your expansion files locally -

- On your Android device navigate to the Android/OBB folder
- Create a folder with the same name as the package e.g. uk.co.mycompany.mygame
- Place your OBB file within this folder
- Install your main APK
- When your application runs GetExpansionFileState will return 3 as the expansion file is in place
- Now you can check if your files are being correctly loaded from the expansion file

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.

## Conclusion

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.