Xamarin

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

Posted on .

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

For most applications maximum app sizes means 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).

Xamarin.Forms - How to find people.db3

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 database file called “people.db3” which I decided to move out of the APK and add as expansion file.

The steps

1. Update application manifest with new version informations
2. Use Android APK Expansion Downloader library from NuGet
3. Add necessary permissions for expansion files
4. Delete old database reference from 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

Xamarin.Forms - Alternative adding by NuGet Manager

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 reference from Android Assets folder to file “people.db3”. After this our APK size will be reduced, so we can prepare file that will be uploaded to Google Play as 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” mean [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 path to 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 other 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:

Xamarin.Forms - Adding code in console

Firstly our method get path to database file and check if 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 file may not be downloaded, so we should implement downloading service if we decide to support them.

Last thing that we must change is method to begin processing of expansion files. In 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 good file name, and preparing data before we will use it 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 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 app and let your app process extra files.

The best tips for using Xamarin, Mobile and Web technologies directly to your inbox