Downloading Expansion Files in Xamarin.Android

Google Play currently requires that our APK file be no more than 50MB. For most apps, this is plenty of space for all the app’s code and assets. However, some apps need more space for high-fidelity graphics, media files, or other large assets. Google Play allows us to attach two large expansion files that supplement our APK.

Google Play hosts the expansion files for our app and serves them to the device at no cost to us. The expansion files are saved to the device’s shared storage location (the SD card or USB-mountable partition, also known as the “external” storage) where our app can access them. On most devices, Google Play downloads the expansion file(s) at the same time it downloads the APK, so our app has everything it needs when the user opens it for the first time. In some cases, however, our app must download the files from Google Play when our app starts.

We can obtain the library from NuGet or we can compile the code directly from GitHub.

The Expansion Files

Expansion files are treated as opaque binary blobs (obb) and each may be up to 2GB in size. Android does not perform any special processing on these files after they are downloaded – the files can be in any format that is appropriate for the app. Conceptually, each expansion file plays a different role:

  • The main expansion file is the primary expansion file for additional resources
  • The patch expansion file is optional and intended for small updates to the main expansion file

When Google Play downloads our expansion files to a device, it saves them to the system’s shared storage location. To ensure proper behavior, we must not delete, move, or rename the expansion files. In the event that our app must perform the download from Google Play itself, we must save the files to the exact same location. Any updates to the expansion files overwrite the existing files.

The specific location for our expansion files is:
[shared-storage]/Android/obb/[package-name]/

  • [shared-storage] is the path to the shared storage space, available from Environment.ExternalStorageDirectory
  • [package-name] is our app’s Java-style package name, available from PackageName

Each expansion file we upload will be renamed to match the pattern:
[main|patch].[expansion-version].[package-name].obb

  • [main|patch] specifies whether the file is the main or patch expansion file. There can be only one main file and one patch file for each APK
  • [expansion-version] is an integer that matches the version code of the APK with which the expansion is first associated
    “First” is emphasized because although the Developer Console allows we to reuse an uploaded expansion file with a new APK, the expansion file’s name does not change – it retains the version applied to it when we first uploaded the file*
  • [package-name] the Java-style app package name

For example, suppose our APK version is 23 and our package name is com.example.app. If we upload a main expansion file, the file is renamed to main.23.com.example.app.obb.

Getting Things Ready

We will need to obtain the base64-encoded RSA public key. More information on this in the Getting Things Ready section of this post.

Implementing the Downloader

Once we have installed the library and have our key, we need to ensure that the app has the appropriate permissions to access Play, the licensing service, the Internet, the network state and the external storage:

    [assembly: UsesPermission(Manifest.Permission.Internet)]
    [assembly: UsesPermission(Manifest.Permission.WriteExternalStorage)]
    // required to poll the state of the network connection
    // and respond to changes
    [assembly: UsesPermission(Manifest.Permission.AccessNetworkState)]
    // required to keep CPU alive while downloading files
    [assembly: UsesPermission(Manifest.Permission.WakeLock)]
    [assembly: UsesPermission(Manifest.Permission.AccessWifiState)]
    [assembly: UsesPermission("com.android.vending.CHECK_LICENSE")]

Once we have permission, we can then create a DownloaderService service that will manage the downloads of the expansion files. In addition to the download management, the service will create an alarm to resume downloads and build and update a notification that displays download progress. We can create the service by simply overriding three properties:

    [Service]
    public class SampleDownloaderService : DownloaderService
    {
        // the API key used to access Play
        protected override string PublicKey
        {
            get { return "Base64 API Public Key"; }
        }

        // the salt used to encrypt the cached server response
        protected override byte[] Salt
        {
            get { return new byte[] { ... }; }
        }

        // the name of the broadcast reciever that will resume 
        // the downloads if the service is stopped
        protected override string AlarmReceiverClassName
        {
            get { return "namespace.ClassName"; }
        }
    }

Finally, we will need to implement a BroadcastReciever that will be used to resume any downloads if the service is stopped:

    [BroadcastReceiver(Exported = false)]
    public class SampleAlarmReceiver : BroadcastReceiver
    {
        public override void OnReceive(Context context, Intent intent)
        {
            // start the service if necessary
            DownloaderService.StartDownloadServiceIfRequired(
                context, intent, typeof(SampleDownloaderService));
        }
    }

Starting the Check

Once we have the download service and the broadcast receiver, we can then start the downloading. Before we start any downloads, we should make sure that we have not already downloaded all the files:

    // get a list of all the downloaded expansion files
    var downloads = DownloadsDatabase.GetDownloads();
    if (!downloads.Any())
    {
        // start the download as nothing is here
    }
    foreach (var file in downloads)
    {
        if (!Helpers.DoesFileExist(this, file.FileName, file.TotalBytes, false))
        {
            // start the download as this file is incomplete
            break;
        }
    }

If the expansion files are not there or not complete, we need to start the download from the OnCreate method. In order to start the service, we need to provide an Intent that will be used to launch the app when the user taps the notification:

    // build the intent that launches this activity.
    Intent launchIntent = this.Intent;
    var intent = new Intent(this, typeof(SuperSimpleActivity));
    intent.SetFlags(ActivityFlags.NewTask | ActivityFlags.ClearTop);
    intent.SetAction(launchIntent.Action);
    if (launchIntent.Categories != null)
    {
        foreach (string category in launchIntent.Categories)
        {
            intent.AddCategory(category);
        }
    }

    // build PendingIntent used to open this activity when user 
    // taps the notification.
    PendingIntent pendingIntent = PendingIntent.GetActivity(
        this, 0, intent, PendingIntentFlags.UpdateCurrent);

Now that we have the Intent, we can start the service. Starting the service will return a result that indicates whether the service was started:

    // request to start the download
    var startResult = DownloaderService.StartDownloadServiceIfRequired(
        this, pendingIntent, typeof(SampleDownloaderService));

If the service was started, we obtain an IDownloaderServiceConnection to the service which will be used to communicate with the service from the activity:

    // the DownloaderService has started downloading the files
    if (startResult != DownloadServiceRequirement.NoDownloadRequired)
    {
        // create the connection to the service so that we can show progress.
        // when creating the marshaller, we pass in the IDownloaderClient
        // that will be used to handle the updates from the service
        connection = ClientMarshaller.CreateStub(
          this, typeof(SampleDownloaderService));
    }
    else
    {
        // all files have finished downloading already
    }

Once we have started the downloader and created a connection, we need to connect and disconnect in line with the activity’s lifecycle. In the OnResume method of the activity, we connect to the service:

    if (connection != null)
    {
        connection.Connect(this);
    }

And, in the OnStop method, we disconnect from the service:

    if (connection != null)
    {
        connection.Disconnect(this);
    }

Receiving Download Progress Updates

As the download progresses, we will receive updates such as the number of bytes downloaded, the download speed and various network states. We can use all of this to display information on the user interface. This is all in addition to the notification that is automatically created and managed by the service.

In order to receive updates, we need to get hold of an IDownloaderService from the IDownloaderServiceConnection. To do this, we have to implement the IDownloaderClient somewhere, such as on the activity:

    public class SuperSimpleActivity : Activity, IDownloaderClient
    {
        public void OnServiceConnected(Messenger m)
        {
            // create the proxy that is used to communicate with the service
            service = ServiceMarshaller.CreateProxy(m);
            // let the service know about us and request an update
            service.OnClientUpdated(connection.GetMessenger());
        }
        public void OnDownloadProgress(DownloadProgressInfo progress)
        {
            // handle download progress updates
        }
        public void OnDownloadStateChanged(DownloaderState newState)
        {
            // handle download states, such as completion or pause
        }
    }

Managing the Service

Once we have the service started and the download going, we may want to be able to pause the download. We can request the download be paused using the IDownloaderService:

    service.RequestPauseDownload();

Similarly, we can resume a download:

    service.RequestContinueDownload();

We may also want to change various properties, such as whether to download over mobile or not when the download is paused due to Wi-Fi being unavailable. To do this we use the SetDownloadFlags method on the IDownloaderService:

    public void OnDownloadStateChanged(DownloaderState newState)
    {
        if (newState == DownloaderState.PausedNeedCellularPermission ||
            newState == DownloaderState.PausedWifiDisabledNeedCellularPermission)
        {
            // let the service know that it can download over mobile
            service.SetDownloadFlags(ServiceFlags.FlagsDownloadOverCellular);
            // resume the download
            service.RequestContinueDownload();
        }
    }

Reading the Expansion Files

Because the expansion files are saved to a specific location, namely [shared-storage]/Android/obb/[package-name]/, we could read the files using any file means available.

If we must unpack the contents of our expansion files, do not delete the .obb expansion files afterwards and do not save the unpacked data in the same directory. We should save our unpacked files in the directory specified by GetExternalFilesDir(). However, if possible, it’s best if we use an expansion file format that allows we to read directly from the file instead of requiring we to unpack the data. The reason for this is that the expansion files will now exist twice on the device.

Using a ContentProvider

One way in which we can read the expansion files is to make use of a content provider that can read them. In the library, there is a special content provider, the ApezProvider, that can read uncompressed zip files. If all the expansion resources are bundled in an uncompressed, storage zip archive, this provider allows access to the individual resources without having to first extract them.

Using this provider is simple and easy to implement:

    [ContentProvider(new[] { ContentProviderAuthority }, Exported = false)]
    [MetaData(ApezProvider.MetaData.MainVersion, Value = "14")]
    [MetaData(ApezProvider.MetaData.PatchVersion, Value = "14")]
    public class ZipFileContentProvider : ApezProvider
    {
        public const string ContentProviderAuthority = "expansiondownloader.sample.ZipFileContentProvider";

        protected override string Authority
        {
            get { return ContentProviderAuthority; }
        }
    }

The [MetaData] attributes let the provider know what version of the expansion files to load. For example, if we have uploaded the app with a version number of 5 and new expansion files, the version we place in the attributes will be 5. When we update the app, we may choose to use the same expansion files. So, our new app version will be 6, but because we selected the old expansion files, they are still version 5. Thus, the provider will still use the version numbers of 5 in the attributes.

If we want to access a file in this provider, we can use a Uri to the resource in the provider:

    var uri = Uri.Parse(string.Format(
        "content://{0}/relative/path/to/movie.mp4",
        ZipFileContentProvider.ContentProviderAuthority));
    videoView.SetVideoURI(uri);

It is important to note that the provider uses file descriptors and cannot support reading compressed expansion files.

Using the Zip Archive

Another way to access the files is to access them directly by filename. We can use the ApkExpansionSupport type to obtain the files stored in each expansion file:

    var files = ApkExpansionSupport.GetApkExpansionZipFile(context, 14, 14);
    var entry = files.GetEntry("relative/path/to/file.extension");
    using (var zip = new ZipFile(entry.ZipFileName))
    using (var stream = zip.ReadFile(entry))
    {
        // process the stream of the contained file
    }

Files accessed this way can be stored in a compressed format as a decompression stream is provided. This stream can be processed using typical .NET means, such as providing this stream to a deserializer or some other reader.

The ApkExpansionSupport.GetApkExpansionZipFile method returns a combined collection of all the items in either of the expansion files. We can then query this for a specific item using the GetEntry method on the collection. We pass a relative path to the item in expansion file. Once the entry is returned, we can then create a ZipFile using the path of the entry’s containing expansion file. And, after we have the zip file, we read the stream of the item inside using the ReadFile method.

Testing the Downloader

Testing the download manager is very similar to testing the licensing. More information on this in the Testing the Licensing section of this post. The downloader performs the license check internally, and in the response, it receives the expansion files URIs from Play. It then uses these to initiate the download.

In order to be able to download the expansion files, we have to have uploaded them when updating the app. The first upload does not allow the expansion files to be added, but we can just re-upload the same package twice. On the second time, we can upload the expansion files with the actual app package, remembering to increase the version number beforehand.

We can start testing our app by checking its ability to read the expansion files. We can do this by placing and naming the files just as the downloader would. Because the downloader always places the files at the [shared-storage]/Android/obb/[package-name]/ location, with the name [main|patch].[expansion-version].[package-name].obb, we just have to place our files there. By skipping the downloading, we don’t have to upload the app first.

Once we are sure that the app can access and use the expansion files, we can upload the files with the app to Play and publish to any channel to test the download. Any channel can be used, including Alpha and Beta.

Important Things to Remember

Testing the expansion files, from downloading to reading, requires that we have the various bits in place:

  1. The app version on the device must be the same as the app that is on the store
  2. Make sure that the app is indeed published, and not in draft
  3. Ensure that the Expansion files have been associated with the app
  4. Make sure that the response in “Settings” is set to “RESPOND_NORMALLY” as this is the only response that returns the expansion files
  5. Make sure the app has all the required permissions, there are 6 at least

Play Licensing in Xamarin.Android

Google Play offers a licensing service that lets us enforce licensing policies for applications that us publish on Google Play. With Google Play Licensing, our application can query Google Play at runtime to obtain the licensing status for the current user, then allow or disallow further use as appropriate.

The Google Play Licensing service is primarily intended for paid applications that wish to verify that the current user did in fact pay for the application on Google Play. However, any app (including free apps) may use the licensing service to initiate the download of an APK expansion file.

Getting Things Ready

In order to add licensing to our app, all we will need is the licensing verification library. We can get this from NuGet.org or the Component Store (coming soon), or, we can build the source using the GitHub repository.

After adding the library, we need to get hold of our API key for this app:

  1. Browse to the Google Play Developer Console
  2. Select “All Applications” from the sidebar
  3. Select the app we want to implement licensing for
    • If we are going to create a new app, select “Add new application”
    • Enter a name for the app
    • Select “Prepare store listing”
    • Enter the required details for publishing
  4. Select “Services & APIs” from the left menu
  5. Scroll to the “Licensing & In-app billing” section
  6. Under the “Your license key for this application” heading, copy the base64-encoded RSA public key
  7. Paste it into a string constant in the app code:
    const string ApiKey = "XXX";

All Applications in Play
Public Key

Adding the License Handlers

Once we have installed the library and have our key, we need to ensure that the app has the appropriate permissions to access Play and the licensing service:

    [assembly: UsesPermission("com.android.vending.CHECK_LICENSE")] 

Once we have permission, We can then implement the ILicenseCheckerCallback interface. This can be implemented on the activity, but does not have to:

    public class MainActivity : Activity, ILicenseCheckerCallback
    {
      public void Allow(PolicyServerResponse response)
      {
        // Play has determined that the app is owned,
        // either purchased or free
      }
      public void DontAllow(PolicyServerResponse response)
      {
        // Play has determined that the app should not be available to the user,
        // either because they haven't paid for it or it is not a valid app

        // However, there may have been a problem when Play tried to connect,
        // so if this is the case, allow the user to try again
        if (response == PolicyServerResponse.Retry)
        {
          // try the check again
        }
      }
      public void ApplicationError(CallbackErrorCode errorCode)
      {
        // There was an error accessing the license
      }
    }

Starting the Check

Once we have implemented the interface, all we need to do now is start the check. There are two basic methods provided in order do this, one with caching and one without.

Using StrictPolicy

To make things easier to start off with, I will first demonstrate the one without caching, the StrictPolicy:

    // create the policy we want to use
    var policy = new StrictPolicy();
    // instantiate a checker, passing a Context, an IPolicy and the Public Key
    var checker = new LicenseChecker(this, policy, "Base64 Public Key");
    // start the actual check, passing the callback
    checker.CheckAccess(this);

As soon as the check has completed, either with an error or successfully, one of the methods on the callback will be called, either Allow, DontAllow or ApplicationError.

Allow will receive a Licensed response
DontAllow will receive a NotLicensed response
ApplicationError will have the reason for the error, such as NotMarketManaged, InvalidPublicKey or some other reason.

Using ServerManagedPolicy

Although checking with Play each time the app launches is not a problem, doing so requires additional time and resources before the app can start. Usually, we can use the one with caching, the ServerManagedPolicy policy. This is very much the same as the StrictPolicy, but with an additional step to provide an IObfuscator to store the response:

    // create a device-unique identifier to prevent other devices from decrypting the responses
    string deviceId = Settings.Secure.GetString(ContentResolver, Settings.Secure.AndroidId);
    // create a app-unique identifer to prevent other apps from decrypting the responses
    var appId = this.PackageName;
    // create a random salt to be used by the AES encryption process
    byte[] salt = new byte[] { 46, 65, 30, 128, 103, 57, 74, 64, 51, 88, 95, 45, 77, 117, 36, 113, 11, 32, 64, 89 };

    // create the obfuscator that will read and write the saved responses, 
    // passing the salt, the package name and the device identifier
    var obfuscator = new AesObfuscator(salt, appId, deviceId);
    // create the policy, passing a Context and the obfuscator
    var policy = new ServerManagedPolicy(this, obfuscator);
    // create the checker
    var checker = new LicenseChecker(this, policy, Base64PublicKey);
    // start the actual check, passing the callback
    checker.CheckAccess(this); 

As soon as the checker has returned and we know that we can start the application, we should destroy the cecker in order to free up resources and close connections:

    // free resources and close connections
    checker.OnDestroy();

Testing the Licensing

The last thing that is needed is testing. To do this, we have to be sure that we have uploaded and published the app to Play. Publishing to any of the channels, including Alpha and Beta, will work.
In order for the Alpha or Beta channels to be used on devices other than the publisher’s device, those people have to be added to the Alph or Beta testers group.
If we want to test different responses that our app may receive from Play, we can select the desired response from the settings:

  1. Select “Settings” from the sidebar
  2. Select “Account details” from the left menu
  3. Scroll dow to the “License Testing” section
  4. Select the desired response from the drop down titled “License Test Response”
    • For other testers, make sure we enter their Google account email address in the text area above titled “Gmail accounts with testing access”

Custom License Responses

Important Things to Remember

Testing licensing is easy to do, provided we have all the required bits in place. Here are some common things that we may have to check:

The Play Store

  1. The app version on the device must be the same as the app that is on the store
  2. Provide enough time for the app to appear on the store, this can be determined by a little exclamation sign next to the app title when viewing the app details
  3. Make sure that the app is indeed published, and not in draft

For Other Testers

  1. Ensure that the testers have been added to the Alpha or Beta testers group
  2. If we are testing custom responses, make sure that their emails are added to the “Gmail accounts with testing access” text area in “Settings”

For The App

  1. Make sure we have the Android permission
    com.android.vending.CHECK_LICENSE
  2. Ensure that the app has the same version code/number and package name as that which is on the store

Returning with the iOS Keyboard

Almost all mobile apps have some sort of text entry. One of the main ways to do this is to simply add a text box. Adding a text box is both simple and easy to do, but we can take this a little further and improve the user experience.

Hiding the Keyboard

When the keyboard is shown by tapping a text box, the natural thing to do in order to hide it would be to tap outside the text box. However, this is not the case by default. But, this is easy to add by overriding the TouchesBegan method of the ViewController:

    public override void TouchesBegan (NSSet touches, UIEvent evt)
    {
        // hide the keyboard from all views
        View.EndEditing (true);

        base.TouchesBegan (touches, evt);
    }

Enabling/Disabling the Return Key

There is a very simple way to let the user know that some text is required: disable the return key if no text is provided. This can be done in both the code and in the designer. In the code we set the EnablesReturnKeyAutomatically property:

    textField.EnablesReturnKeyAutomatically = true;

There is a checkbox in the designer labeled “Auto-enable Return Key”.

It is important to note that this does not apply if the keyboard type is NumberPad as there is no return key for this keyboard type.

Changing the Keyboard Type

Another way to provide a basic restriction of the UI is to select a keyboard type. By selecting an appropriate keyboard type, the user can know what is expected to be entered as well as make the available characters easier to reach. If we only want numbers, we use the NumberPad as this removes the other keys. If we are providing an entry for an email address, we use the EmailAddress type which makes the @ and the . key more available:

    textField.KeyboardType = UIKeyboardType.NumberPad;

There is a dropdown in the designer labeled “Keyboard” which provides all the available options.

Keyboard Types on iOS

Changing the Return Key Type

Another nice user experience is to change the text for the “return” key, which provides additional hints as to what is going to happen with the input. There are several options that are available, such as Done, Search or Next:

    textField.ReturnKeyType = UIReturnKeyType.Done;

There is a dropdown in the designer labeled “Return Key” which provides all the available options.

Adding an Action to the Return Key

When the user presses the return key on the keyboard, we would expect something to happen, especially if it is a single line textbox. But, on iOS nothing happens, so we attach a delegate that can hide the keyboard and maybe do some more work. This is easy to add by assiging a delegate to the ShouldReturn property of the UITextFied:

    textField.ShouldReturn = delegate {
        // hide the keyboard
        textField.ResignFirstResponder ();

        // the "return" logic here

        return true;
    };

Adding “Return” to the Number Pad

As the NumberPad keyboard type does not have a return key, there is no default way to hide the keyboard, we have to manually add a handler to hide the keyboard when another view is tapped. Another way we can do this is to add a “Cancel” or a “Done” button accessory to the keyboard:

    // create the toolbar
    UIToolbar numberToolbar = new UIToolbar ();
    numberToolbar.BarStyle = UIBarStyle.Default;
    numberToolbar.Translucent = true;
    // set the items
    numberToolbar.Items = new [] { 
        // the cancel button
        new UIBarButtonItem (UIBarButtonSystemItem.Cancel, delegate {
            // hide the keyboard
            idEntryTextField.ResignFirstResponder ();
        }),
        // the space to separate the buttons
        new UIBarButtonItem (UIBarButtonSystemItem.FlexibleSpace, null),
        // the "continue" button
        new UIBarButtonItem ("Login"), UIBarButtonItemStyle.Done, delegate {
            // hide the keyboard
            idEntryTextField.ResignFirstResponder ();

            // the "return" logic here
        })
    };
    // fill the screen width
    numberToolbar.SizeToFit ();

    // set the accessory
    textField.InputAccessoryView = numberToolbar;

Xamarin Insights for Older Androids

Recently, Xamarin announced a real-time crash reporting and analytics solution for mobile apps, Xamarin Insights.

This is an awesome tool with many great features. They support all the major platforms, iOS Android Windows Phone, Windows RT and traditional desktop applications. Support for Xamarin.Mac is coming soon.

Some of the major features:

  • Report details about the device statistics such as operating system and screen resolution
  • Gather and report any uncaught native or managed exceptions
  • Report any caught exception, along with any additional data
  • Track both past and active sessions
  • Track any event that occurs in your application, including the time it takes to execute
  • Cross-platform across almost all devices, including support for PCL libraries

Old Androids

Recently they added support for Android versions below API level 14 (Android Version 4.0 – Ice Cream Sandwich). To use Xamarin Insights in an Android app below API level 14, such as API Level 8 (Android Version 2.3 – Gingerbread), there are a few things that need to happen:

  1. Set your ‘Compile using Android version’ or ‘Target framework’ value to be API level 14 or higher, such as API level 19
  2. Set the ‘Minimum Android to target’ or ‘Minimum Android version’ to be the value you are wanting to support, such as API level 8.

This will result in your app building against the higher API level, but can run on earlier devices.

However, even after all this, there is still a limitation, namely the inability to record sessions. This may not be a deal breaker for you, but for some, this is. The reason for this is that Xamarin Insights is using the IActivityLifecycleCallbacks interface. This is a relatively new addition to the Android API and is very useful in that it allows you to hook into the Activity lifecycle without having to use the Activity itself. As this interface is not available for the older versions, they simple can’t record the Activity sessions.

The Code

I am here to give you that solution that you always wanted: Manually starting and stopping sessions from within the activity. To do this I have created a simple class InsightsCompat:

    public static class InsightsCompat
    {
        public static void Initialize(string apiKey)
        {
            Insights.Initialize(apiKey, Application.Context);
        }

        public static void StartSession()
        {
            EmitBackgroundChange(false);
        }

        public static void StopSession()
        {
            EmitBackgroundChange(true);
        }

        private static void EmitBackgroundChange(bool backgroundState)
        {
            try
            {
                var status = backgroundState ? "Background" : "Resumed";
                var table = new Dictionary<string, string> {{"Status", status}};
                Insights.Track("X-App-State", table);
            }
            catch (Exception ex)
            {
                Insights.Report(ex);
            }
        }
    }

The Usage

This simple class can do all the work that is needed, plus there is an additional method, Initialize, that allows you to start up Xamarin Insights without having to find the context:

    // from anywhere in your code
    InsightsCompat.Initialize("your API key");

To start and stop sessions, you can override the OnResume and OnPause methods:

    protected override void OnPause()
    {
        InsightsCompat.StopSession();
        base.OnPause();
    }

    protected override void OnResume()
    {
        base.OnResume();        
        InsightsCompat.StartSession();
    }

We only have to override these two methods as android will always call these methods, no matter where the Activity came from or where it is going.

There’s More

Even though Xamarin Insights has many features, it is still in preview and there can still be many more features. If you have any feature requests or ideas, be sure to drop a message on the Xamarin Insights User Voice.

There is a small docs page for Xamarin Insights here. So head over to the dashboard and get started creating and supporting awesome cross-platform apps now.

Flurry Analytics Portable

We all know about Flurry Analytics, and we know how we can use this with Xamarin in iOS and Android, as well as on Windows Phone.

Well, now there is a portable version that allows the analytics to be implemented in portable class libraries! The portable API abstracts away all the platform differences, but keeps all the power of the Flurry!

This can be found on NuGet and on GitHub.

Features

The features of the portable API are the same as the native API’s, as the portable is more of an abstraction than anything else. So along with all the native features, there are a few nice new once that make the API easier to use.

This is the primary advantage of this library, it allows the analytics to be implemented in portable projects. This is especially useful if you are using a cross-platform framework, such as MvvmCross. There is a sample that you can check out that makes use of all the features.

Starting Sessions

Although the library is portable, each platform needs to start the analytics session natively/differently:

For iOS, it is very simple call StartSession from the AppDelegate:

    AnalyticsApi.StartSession("[API KEY]");

For Android, there are two ways to do this. Either by overriding the OnStart and OnStop methods from each Activity:

    // in OnStart
    AnalyticsApi.StartSession(this, "[API KEY]");

    // in OnStop
    Analytics.EndSession(this);

Or, by using the IActivityLifecycleCallbacks for the Application. This way allows you to start and end the session without having to implement the logic in each Activity. However it is only available from API Level 14 / Android 4.0 / Ice Cream Sandwich.

For Windows Phone, starting the session is done by attaching the StartSession method call to the Launching and Activated events:

    PhoneApplicationService.Current.Launching += (sender, args) => AnalyticsApi.StartSession();
    PhoneApplicationService.Current.Activated += (sender, args) => AnalyticsApi.StartSession();

For each of the platforms, there is also a way to pass the key in to the API, but only start the session later:

    // somewhere in the code
    AnalyticsApi.ApiKey = "[API KEY]";

    // and then a little later
    AnalyticsApi.StartSession();

There is also a boolean property, IsSupported, that will return true if the platform supports Flurry Analytics:

    if (!Analytics.IsSupported)
        Debug.WriteLine("PLatform does not support Flurry, nothing will be tracked.");

Setting Up Analytics

There are a few methods that hide the platform differences. Some examples of this are in the setting of user details, such as SetAppVersion, SetUserId, SetLocation, SetAge and SetGender.

Not only that, there are a few methods that specify how Flurry should communicate, such as SetSessionContinueTimeout and EnableSecureTransport.

Usually these methods should be called before starting the session.

Logging Events & Errors

Along with tracking basic analytics, events and errors can be tracked. There are a few methods that support this: LogPageView, LogEvent, LogTimedEvent, EndTimedEvent and LogError.

Logging timed events has been made much easier by implementing a new pattern for doing this. By calling LogTimedEvent in a using block, you can end the event in case of any exceptions as well as removing an extra call:

    using (AnalyticsApi.LogTimedEvent("EventId"))
    { 
        // perform a long running task
    } 

Before, you would have to ensure that you called EndTimedEvent to avoid any problems:

    try
    {
        AnalyticsApi.LogTimedEvent("EventId");
        // perform the long running task
    }
    finally
    {
        AnalyticsApi.LogTimedEvent("EventId");
    }

Parameters can also be passed with the events using a simple Dictionary:

    var parameters = new Dictionary<string, string> 
    {
        {"ParameterKey", "ParameterValue"}
        {"AnotherParameterKey", "AnotherParameterValue"}
    };
    AnalyticsApi.LogEvent("EventId", parameters);

MVVMCross Startup Crashes

Have you every used MvvmCross in your app, only for it to crash on startup when launching without the debugger? Well it happened for me quite a few times, and its because I was having a brain fart…

After launching the app many times and trying to somehow gain knowledge magically due to repeating the same thing over and over, I decided to add some “logging”:

    // Code to execute if a navigation fails
    private void RootFrame_NavigationFailed(object sender, NavigationFailedEventArgs e)
    {
        MessageBox.Show(e.Exception.ToString()); // <- LOGGING!
        if (System.Diagnostics.Debugger.IsAttached)
        {
            // A navigation has failed; break into the debugger
            System.Diagnostics.Debugger.Break();
        }
    }

    // Code to execute on Unhandled Exceptions
    private void Application_UnhandledException(object sender, ApplicationUnhandledExceptionEventArgs e)
    {
        MessageBox.Show(e.ExceptionObject.ToString()); // <- LOGGING!
        if (System.Diagnostics.Debugger.IsAttached)
        {
            // An unhandled exception has occurred; break into the debugger
            System.Diagnostics.Debugger.Break();
        }
    }

This returns a nice little error message:

System.NullReferenceException: Object reference not set to an instance of an object.
  at Cirrious.CrossCore.Mvx.Resolve[TService]()
  at MvvmCrossSample.WindowsPhone.App.<RootFrameOnNavigating>b__0()

So what does that mean? Well, over there I am trying to resolve the IMvxAppStart type:

RootFrame.Dispatcher.BeginInvoke(() => { 
    Mvx.Resolve<IMvxAppStart>().Start();
});

So for some reason, my Setup object wasn’t getting initialized… This is what I had:

    // Show graphics profiling information while debugging.
    if (System.Diagnostics.Debugger.IsAttached)
    {
        // ...

        Setup setup = new Setup(RootFrame);
        setup.Initialize();
    }

Hmm… Maybe the app should start up for the users without debuggers as well? All I needed to do was to move the startup object out of the scope of the if block:

    // Show graphics profiling information while debugging.
    if (System.Diagnostics.Debugger.IsAttached)
    {
        // ...
    }

    Setup setup = new Setup(RootFrame);
    setup.Initialize();

After that, the app worked fine.

In short, don’t just copy-and-paste when using templates, at least read the snippet you are pasting.

Running Mac OS X in Windows 8

Have you ever wanted or needed to run OS X on your Windows PC? I certainly did. As I am a developer of multiple platforms, Android, iOS and Windows, I would like to use one device to develop for all platforms, and of course using Visual Studio.

In order to install Mac OS X in VMWare on a PC, there are a few things that are needed:

  1. the OS X operating system (from an existing Mac)
  2. a Windows machine
  3. UniBeast
  4. VMWare Workstation
  5. Hackintosh VMWare Template for OS X

Now to get started, we have to get the OS X from the physical Mac. The first thing that we are going to do is prepare a bootable USB drive that we will use to install the OS on the VM.
In order to do this, there are a few steps (in order to do anything, we need to make sure that we have downloaded OS Mavericks from the App Store):

  1. Insert a USB Drive of at least 8GB
  2. Use Disk Utility:
    1. Choose USB Drive
    2. Choose Partition (Partition Layout: 1 partition)
    3. Under options choose Master Boot Record
    4. Choose Format (Mac OS Extended (Journaled))
    5. Click Apply
  3. Use UniBeast
    1. Download UniBeast
    2. Run Unibeast
    3. Choose USB Drive
    4. Select Mavericks 10.9
    5. Continue – This takes a while (not less than a minute)

Once we have done this, we should have a bootable USB drive containing Mavericks. Now we need to prepare our Windows machine. As there can only be one instance of hypervisor running, we may have to disable Hyper-V. If you don’t have Hyper-V installed, you can skip this step.

In order to disable Hyper-V, we are going to create a boot profile that will start up our PC without Hyper-V.
The first thing we need to do is to create a copy of our current boot profile. From the command line, execute this command:

    bcdedit /copy {current} /d "Disable Hyper-V"

This command creates a copy of our current profile {current} and creates a new profile with the name Disable Hyper-V. This name could be anything we like. This command will return a GUID that we are going to use in the next step to disable Hyper-V:

    bcdedit /set {INSERT-GUID-HERE} hypervisorlaunchtype off

This command disables Hyper-V for the profile with the GUID {INSERT-GUID-HERE} from the previous command.

If we restart our computer now, we should be presented with two options: “Windows 8.1” and “Disable Hyper-V”. Everytime we wish to use VMWare, we need to start with the “Disable Hyper-V” profile. This profile is exactly the same as the “normal” profile, just without Hyper-V, so you can use this profile for typical development as well.

The next thing to do is install VMWare:

  1. Install VMWare Workstation 10
    (the free VMWare Player will work as well to playback VMs)
  2. Install Hackintosh Template for OS X
  3. Create a Virtual Machine with Workstation 10 Compatibility hardware
  4. Install Operating System Later
  5. Choose OSX 10.9
  6. Add desired Hardware with at least 40 GB disk space allocated to the Virtual Hard Disk.
  7. Run NAT preferably
  8. Insert USB Boot Drive Created on Mac into PC
  9. Boot Virtual Machine
  10. Under VM > Removable Disks > Connect the USB Drive
    (this will remove it from visibility to Windows Host)
  11. Reset the VM
  12. OS X should install

That’s it! You should now have Mac OS X running on your PC!

Binding Flurry Analytics with Xamarin.Android

This week, I needed to use Flurry Analytics in my Xamarin.iOS and my Xamarin.Android apps, but there was no .NET SDK for these platforms. Flurry did provide a SDK for each platform, but it was the native libraries, which cannot be used directly in .NET. Given this, I decided to bind those native libraries using Xamarin.iOS and Xamarin.Android.

I have split this project up into four parts:

  1. Introduction and Pre-requisites
  2. Xamarin.iOS binding
  3. Xamarin.Android binding
  4. Flurry.Analytics in the wild

After binding the iOS SDK for Flurry Analytics, we are going to move onto the Android release. This task needs only one thing from the downloaded SDK:

  • [Android-sdk-path]/Android 4.1.0/FlurryAnalytics/FlurryAnalytics-4.1.0.jar

Of course, the version numbers may change for later releases. The java archive file (.jar) is going to be used to generate the .NET interfaces and enums, and then be embedded in the resulting assembly.

Just before we do the real binding, we should just create our C# solution for the Xamarin.Android binding. Just create a new project/solution and select the Android “Bindings Library” template. For my project name I used Flurry.Analytics.Android, but you could use anything.

The default project has a few files and directories in it, we will have a look at each one in depth as we go through the binding steps:

  • /Additions/ (this allows you to add arbitrary C# to the generated classes
    before they are compiled)
  • /Properties/AssemblyInfo.cs (the usual assembly information attributes)
  • /Jars/ (this directory is for Android .jars)
  • /Transforms/EnumFields.xml (this allows you to map Java int constants to C# enums)
  • /Transforms/EnumMethods.xml (this allows changes to method parameters and return types from Java int constants to C# enums)
  • /Transforms/Metadata.xml (this allows changes to be made to the final API)

Creating the Initial Binding

This step will involve just adding the jar to the project, and letting the compiler do it’s thing, but we will almost always have to go in and tweak a few things in the Metadata.xml.

So, first things first, add the jar file to the project and compile. The build will probably fail with error messages containing single character methods and types. This is because the actual jar file has been obfuscated. However this can easily be fixed.

The way the generation works is that there is a two step process, there is a tool that generates a bunch of xml files from the jar file. These xml files are then used to generate C# code. The Metadata.xml sits in between the two steps and can be used to transform the generated xml before the C# generation.

Tweaking the Generated Binding (Manifest.xml)

As we can see that the build fails on obfuscated types, we can remove these. The removal is safe as we are only preventing the .NET binding from being created, not actually removing the underlying Java members. And, as these items have been obfuscated, we can safely assume that we aren’t supposed to be accessing them anyway.

But, instead of removing each member or type that appears, we can use a great tool that will decompile the jar file and show us exactly what types are internal and what types we should be binding. I use JD-GUI, which is a free Java decompiler. They also have a nice online version, JD-Online. What we can do is to just upload the jar file here and see what’s inside:

  • com.flurry.android.impl.analytics.*
  • com.flurry.android.*
  • com.flurry.sdk.*

As we can see, the impl and sdk branches contain internal and obfuscated types, so we can remove those:

<remove-node path="/api/package[starts-with(@name, 'com.flurry.sdk')]" />
<remove-node path="/api/package[starts-with(@name, 'com.flurry.android.impl')]" />

After this, the build should now succeed and we will have an assembly that we can use. However, there are still some types that we can remove to clean the API a bit: InstallReceiver and Constants. InstallReciever is not used by the consumer, so this is safe to remove, but Constants is still used. If we remove this, then the consumer will not have access to the values on the type. We can see that Constants just contains the values representing male, female and unknown.

To remove the InstallReciever, we can add this line to Metadata.xml:

<remove-node path="/api/package[@name='com.flurry.android']/class[@name='InstallReceiver']" />

For the Constants type, we will do something different.

Managing the Enumerations (Additions & EnumFields.xml)

As we clean up the API, we want to remove the Constants type and replace it with an enum. One way to do this is to use the EnumFields.xml:

<mapping clr-enum-type="Flurry.Analytics.Gender" jni-interface="com/flurry/android/Constants">
    <field clr-name="Male" jni-name="MALE" value="1" />
    <field clr-name="Female" jni-name="FEMALE" value="0" />
    <field clr-name="Unknown" jni-name="UNKNOWN" value="-1" />
</mapping>

This will generate a nice enum for us, but this does leave an unused interface IConstants. As this is a very small library, we can do this mapping slightly differently. First we remove the entire Constants type in the Metadata.xml:

<remove-node path="/api/package[@name='com.flurry.android']/interface[@name='Constants']" />

Then, we can create the enum in the /Additions/ directory. To do this, add a new file (for example called FlurryAgent.cs) under this directory and add the enum:

public enum Gender
{
    Male = 1,
    Female = 0,
    Unknown = -1
}

Now there is one last thing to do before the API definition is complete. There is a SetGender method on the type FlurryAgent, which takes the type sbyte. It is not intuitive to use the Gender enum here, so we can fix this in a two step process. First we will create an overload in the FlurryAgent.cs file that accepts a Gender enum member as an argument:

public partial class FlurryAgent
{
    public static void SetGender(Gender gender)
    {
        FlurryAgent.SetGender ((sbyte)gender);
    }
}

And, what we can do is also hide the original member as the new overload is good enough:

<attr path="/api/package[@name='com.flurry.android']/class[@name='FlurryAgent']/method[@name='setGender']" name="visibility">internal</attr>

And with this, our binding is complete, although we can do a few nice changes to the namespace and parameter names.

Changing Parameter Names

Now that we have the binding complete, we can see that it is using the namespace Com.Flurry.Android, which is no .NET-like at all. We can change this to something better:

<attr path="/api/package[@name='com.flurry.android']" name="managedName">Flurry.Analytics</attr>

This maps the com.flurry.android package name to the neat Flurry.Analytics namespace. One last thing is to fix the parameter names. Sometimes you can use the JavaDocs, but in this case, I couldn’t get it to work. Doing it manually is not hard, but it is boring and time consuming, but here are a few.

This is the usual mapping:

<attr path="/api/package[@name='com.flurry.android']/class[@name='FlurryAgent']/method[@name='onStartSession']/parameter[@name='p0']" name="name">context</attr>
<attr path="/api/package[@name='com.flurry.android']/class[@name='FlurryAgent']/method[@name='onStartSession']/parameter[@name='p1']" name="name">apiKey</attr>
<attr path="/api/package[@name='com.flurry.android']/class[@name='FlurryAgent']/method[@name='onEndSession']/parameter[@name='p0']" name="name">context</attr>

If there are complicated parameter types (note the &lt;):

<attr path="/api/package[@name='com.flurry.android']/class[@name='FlurryAgent']/method[@name='logEvent']/parameter[@name='p1' and @type='java.util.Map<java.lang.String, java.lang.String>']" name="name">parameters</attr>

If there are overloads with different parameter types:

<attr path="/api/package[@name='com.flurry.android']/class[@name='FlurryAgent']/method[@name='onError']/parameter[@name='p2' and @type='java.lang.Throwable']" name="name">exception</attr>
<attr path="/api/package[@name='com.flurry.android']/class[@name='FlurryAgent']/method[@name='onError']/parameter[@name='p2' and @type='java.lang.String']" name="name">errorClass</attr>

After doing this for all the members, the binding is now complete.

Finishing Up

So far we have defined our API, added any additional logic or types, added the native library and added parameter names. This is all that is needed, so our library should build fine now and we should be able to use it in an Xamarin.Android app:

// the methods
FlurryAgent.StartSession(this, "PQSZJRK4B5BW8Q7YQQXF");

// the properties that we changed back into methods
string version = FlurryAgent.ReleaseVersion;

// the extra method that we added
FlurryAgent.SetGender (Gender.Male);

Flurry.Analytics for Xamarin

The Flurry Analytics Agent allows you to track the usage and behavior of your Android, iOS or Windows Phone application on users’ phones for viewing in the Flurry Analytics system. It is designed to be as easy as possible with a basic setup complete in few minutes.

Features

There are many features available in the Flurry Analytics API, such as:

  • Session tracking
  • Event logging, with optional parameters
  • Page View tracking
  • Demographics tracking, such as age, gender and user id
  • Location tracking
  • App version tracking
  • And much more…

Getting Started

The setup for all the platforms is very easy with only a few steps:

Android

  1. Add the INTERNET permission to AndroidManifest.xml.
  2. Add FlurryAgent.OnStartSession(this, "YOUR_API_KEY"); to the OnStart method of the Activity or Service.
  3. Add FlurryAgent.OnEndSession(this); to the OnStop method of the Activity or Service.

iOS

  1. Add FlurryAgent.StartSession("YOUR_API_KEY"); to the FinishedLaunching method of the Application Delegate

Windows Phone

  1. Add ID_CAP_NETWORKING and ID_CAP_IDENTITY_DEVICE capabilities to WMAppManifest.xml.
  2. Add FlurryWP8SDK.Api.StartSession("YOUR_API_KEY"); to Launching and Activated events of the Application.

And that’s it, your mobile app will start sending activity usage statistics to the Flurry servers!

Advanced

Flurry Analytics SDK supported versions:

  • SDK for iOS supports Xcode tools 4.5 and above
  • SDK for Android supports Android API level 10 (Gingerbread) and above
  • SDK for Windows Phone supports Windows Phone 8 and above

Downloading

The Flurry.Analytics API is available on NuGet.org (Flurry.Analytics) and on GitHub (mattleibow/Flurry.Analytics).

It is released under the same license as the native libraries.

The Making Of

You can read up on how the binding was created in my blog:

  1. Introduction and Pre-requisites
  2. Xamarin.iOS binding
  3. Xamarin.Android binding
  4. Flurry.Analytics in the wild

Bing Maps iOS SDK

The Bing Maps iOS SDK is a control for embedding maps directly into native iOS apps. With a rich, gesture-based UI, the SDK provides support for adding pushpins and other overlays to the maps. The SDK also allows your device location to be displayed and provides the ability to retrieve contextual information for a given map location.

This project provides a managed binding of the native library for Xamarin.iOS.

Sadly, after getting all this nice stuff going, I found the actual native library to be very buggy and often caused the app to crash. For example, if the push pins were animated, tapping them caused the app to crash. As a result, I won’t be pushing this to the stores.

Getting Started

Before you can use the map control, you will need a Bing Maps Key from the Bing Maps Portal. The process is described in the MSDN documentation, Getting a Bing Maps Key, and is very simple with only four steps.

A map key is not required for the maps to appear, but will display a popup reminder every time a map view is displayed.

Using the Map View

Once you have obtained a key, the next step is to add the map view to your app. You can obtain the control from the 3.

Once you have added the assembly to your app, you then need to add your Bing Maps Key to the Info.plist file in your project. This is a string key-value item with the key, BingMapsKey, with the value being the key you obtained from the portal.

Now, all that is left to do is to add the map view to your view. This can be done in the code or in the designers (storyboards or interface files).

If we are going to use the designers, then you can just add a UIView to your app, and then change the Class to be BMMapView. When the app is launched, a map should appear. If the code is used, then this snippet is all that is needed:

    // create the map view
    BMMapView mapView = new BMMapView (UIScreen.MainScreen.Bounds);
    // add to some View
    View.AddSubview (mapView);
    // show the user's location on the map (optional)
    mapView.ShowsUserLocation = true;