Five steps to using expansion files for Android in Xamarin.Forms

Have you ever worried that resources or assets in your Xamarin project may exceed the maximum size limit for a single application?

For most applications, maximum app sizes mean plenty of space for application code and assets. From the other hand in some cases, you might want to use high-fidelity graphics, media files, or other large assets. They can easily exceed 100MB APK size limit on Google Play. Using expansion files allows you to attach two large files that can increase the limit for your resources by 2GB per file (so in 4 GB in total).

I prepare some sample-based on existing project called DbPublish that I find out on Xamarin University classes to demonstrate how to use expansion files in Xamarin.Forms application. Application is written by Rob Gibbens (Xamarin Instructor) and source code is available on his public repository. In this app, we got a database file called “people.db3” which I decided to move out of the APK and add as an expansion file.

The steps

1. Update application manifest with new version information
2. Use Android APK Expansion Downloader library from NuGet
3. Add necessary permissions for expansion files
4. Delete old database reference from the project and prepare OBB file (file threaten as expansion file by Google Play)
5. Modify existing application methods

Step 1

In the first step, we will update our application manifest. Our changes include setting:
– versionCode from 1 to 2;
– versionName from 1.0 to 2.0;

So now on our AndroidManifest.xml we will have:

android:versionCode="2"
android_versionName="2.0"

The important thing to remember is code version, because it will be used in next steps.

Step 2

Next step is linking .NET implementation of Google’s Android APK Expansion Downloader. If you prefer to use Package Manager Console type:

PM> Install-Package DotNetDevAddict.Android.ExpansionDownloader

Of course you can do it by adding reference with Nuget Manager.

Step 3

In AssemblyInfo.cs file you should have some common permissions:

[assembly: UsesPermission(Android.Manifest.Permission.Internet)]
[assembly: UsesPermission(Android.Manifest.Permission.WriteExternalStorage)]

However some of required permissions are missing, so you need to add them:

[assembly: UsesPermission(Android.Manifest.Permission.AccessNetworkState)]

[assembly: UsesPermission(Android.Manifest.Permission.WakeLock)]

[assembly: UsesPermission(Android.Manifest.Permission.AccessWifiState)]

[assembly: UsesPermission(LicenseChecker.Manifest.Permission.CheckLicense)]

Without them our application won’t be able to use download service.

Step 4

In this step, we need to do delete the reference from the Android Assets folder to file “people.db3”. After this our APK size will be reduced, so we can prepare a file that will be uploaded to Google Play as an expansion file. We need to compress “people.db3” to OBB file and call it:

main.2.com.xamarin.People.Droid.obb

Easiest way to prepare that file is to use command line and compress with zip command:

zip -n .db3 main.2.com.xamarin.People.Droid.obb people.db3

Alternatively, you can use any other solution to zip your files without compression. Remember that file name must be set correct – in our case, “main.2.com.xamarin.People.Droid.obb” means [main|patch]…obb,

where:
main or patch – we decided that this is our main patch file
– version code from manifest
– package name from manifest
obb – if you will compress file with other filename extension just change it to obb

Step 5

Last but not least step is about modifying existing application methods to start using expansion files. Now our app launch main activity, get a path to the database file that exists in-app assets and copy it to local app storage. After update there won’t be any file in assets, so we need to modify some part of code and get that missing file from another directory.

In FileAccessHelper we will create new method called ProcessExpansionDatabase:

internal static bool ProcessExpansionDatabase()
  {
    var localFilePath = GetLocalFilePath();

    // Check if database file exists, so there is no point in processing data
    if(File.Exists(localFilePath))
      return true;

    var expansionFiles = ApkExpansionSupport.GetApkExpansionZipFile(Application.Context, Application.Context.PackageManager.GetPackageInfo(Application.Context.PackageName, 0).VersionCode, 0);

   // Check if there is expansion file available
   var expansionFileEntry = expansionFiles.GetEntry(dbFileName);
   if (expansionFileEntry == null)
     return false;

   CopyZipDatabase(expansionFiles.GetEntry(dbFileName), dbFileName, localFilePath);
   return true;
}

The process of adding the code looks like this:

Firstly our method gets a path to a database file and checks if the database exists. If not we are checking if expansion file is available. In most cases, expansion files are downloaded with APK from Google Play. However on some older devices, those files may not be downloaded, so we should implement downloading service if we decide to support them.

The last thing that we must change is method to begin processing of expansion files. In the Main Activity onCreate method we will add some logic:

if (FileAccessHelper.ProcessExpansionDatabase())
      LoadApplication(new People.App(FileAccessHelper.GetLocalFilePath(), new SQLitePlatformAndroid()));
   else
      Log.WriteLine(LogPriority.Warn, "Expansion Files", "Expansion process failed...");

After this changes when our app launch and go to main activity it will process expansion files, extract database and move on.

So as you can see it’s not so hard to start using expansion files on Android. There are some rules that you should remember like setting a good file name, and preparing data before we will use it the first time. On the end, I would like to share with you one extra thing – how to check if our expansion files are working without uploading app on Google Play.

Install the app on your physical device and copy expansion file in your Android Device\External SD\Android\obb\ folder. If it does not exist – just create it. Then launch the app and let your app process extra files.