Chapter 5. Xamarin

5.1. Download

5.2. Introduction

This is a standard Xamarin App which allows you to create Native iOS, Android and Windows Phone apps in C#.

The SDK itself is an open source project that is hosted here. Feel free to fork it and make contribution to this project.

Before using this SDK, make sure you have Xamarin developer tools installed. You can download them from here.

To develop Windows Phone app, you need to have Windows Phone Developer tools installed. You can download it from here.

We recommend you install Xamarin For Visual Studio as well.

5.3. NuGet

NuGet is a dependency management tool for the Microsoft development platform including .NET and is used to share and distribute C# code. It serves as the primary tool for distributing the RHMAP .NET Client SDK.

5.3.1. Install the NuGet CLI using the Installer

To install NuGet on Windows-based Systems, download and run the NuGet Commandline installer.

5.3.2. Install NuGet Using Chocolatey

If you are using Chocolatey, you can install NuGet by executing the following command on the Windows command line: 

choco install nuget.commandline

5.4. New App

Download the sample app to get started with a new Xamarin App which has the RHMAP SDK already included.

The app contains 4 sub-projects. It is setup to use Portable Class Libraries to share code across all the apps. More details about this approach can be found here.

  • App.Core - A PCL project. The code in this project is shared by other apps. Most of the app’s business logic should be defined here.
  • App.WP - A Windows Phone app project depends on the App.Core project. Normally it should contain UI code and WP-specific code.
  • App.Android - An Android app project depends on the App.Core project. Normally it should contain UI code and Android-specific code.
  • App.iOS - An iOS app project depends on the App.Core project. Normally it should contain UI code and iOS-specific code.

image

5.5. Existing App

You can install the SDK to your project either automatically (using NuGet) or manually.

5.5.2. Manually

Download the SDK and unzip it. Adding the .dll assembly files from the folder that is corresponding to your project’s build target as references.

image

image

If you are developing a Portable Class Library project, only reference the FHSDK.dll file.

The SDK depends on Json.Net and Microsoft HTTP Client Libraries. You need to install the assemblies of those libraries as well if they are not available in your project.

5.5.3. Set up Configuration

For each platform-specific application, you need to create the corresponding configuration files. The content of each file should be the same as described in each platform’s native SDK doc.

5.5.4. iOS

fhconfig.plist in the root of the application. Set build action to BundleResource.

image

fhconfig.plist file contents: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>host</key>
  <string>__APP_STUDIO_HOST__</string>
  <key>appid</key>
  <string>__ID_OF_APP_IN_PROJECT__</string>
  <key>projectid</key>
  <string>__PROJECT_ID__</string>
  <key>appkey</key>
  <string>__APP_API_KEY_OF_APP_IN_PROJECT__</string>
  <key>connectiontag</key>
  <string>__CONNECTION_TAG_TO_USE_FOR_CLOUD__</string>
</dict>
</plist>

5.5.5. Android

fhconfig.properties in the Assets directory of the application. Set build action to AndroidAsset.

image

fhconfig.properties file contents: 

host = __APP_STUDIO_HOST__
projectid = __PROJECT_ID__
connectiontag = __CONNECTION_TAG_TO_USE_FOR_CLOUD__
appid = __ID_OF_APP_IN_PROJECT__
appkey = __APP_API_KEY_OF_APP_IN_PROJECT__

5.5.6. Windows Phone 8

fhconfig.json in the root of the application. Set build action to Content.

xamarin sdk install7

fhconfig.json file contents: 

{
  "appid": "__ID_OF_APP_IN_PROJECT__",
  "appkey": "__APP_API_KEY_OF_APP_IN_PROJECT__",
  "connectiontag": "__CONNECTION_TAG_TO_USE_FOR_CLOUD__",
  "host": "__APP_STUDIO_HOST__",
  "projectid": "__PROJECT_ID__"
}

More information on connections can be found here.

5.5.7. Initialise

To use the RHMAP .NET SDK, you will need to initialise the SDK like this in the platform-specific project (not the PCL project) when app finish starting. 

try
{
  bool inited = await FHClient.Init();
  if(inited) {
    //Initialisation is successful
  }
}
catch(FHException e)
{
  //Initialisation failed, handle exception
}

FHClient is available in the following namespaces:

  • FHSDK.Phone — For WP8
  • FHSDK.Droid — For Android
  • FHSDK.Touch — For iOS

Depending on your app’s build target, only one of these name spaces should be available to your app.

The main reason for having the same FHClient class defined in different name spaces is to ensure that the platform-specific assembly file is loaded correctly.

Note

The Init method is the only one that is called using FHClient class, and is the only one that needs to be called from a platform-specific project (for example, Can not be called from a PCL project).

All the other SDK methods are called using FH class which is defined in the FHSDK.dll assembly. This assembly can be references by other PCL projects. This way if your cross-platform solution contains a PCL project, you can reference this assembly file and call SDK functions from there.

5.6. Use your own choice of HttpClient

By default, the .NET SDK will use the Microsoft HTTP Client Libraries to perform all the http requests. However, if you are developing iOS and Android apps using Xamarin, the ModernHttpClient is a better choice. If you want to use that, all you have to do is to install the ModernHttpClient component in your app, then use it like this: 

//the following should be called BEFORE FHClient.Init is called
//use ModernHttpClient on Android
FHHttpClientFactory.Get = (() => new HttpClient(new OkHttpNetworkHandler()));

If you don’t like either of these, you can use whatever HTTP (or REST) client you like. All you need is the cloud host of the app, which you can get using the following method: 

string cloudHost = FH.GetCloudHost();

However, the downside of the approach is that your app won’t be able to use the analytics service provided by the platform as some meta data is missing in the requests. To re-enable that, all you have to do is to add the meta data returned by the following method as a set of headers to each HTTP request: 

IDictionary<string, string> metaData = FH.GetDefaultParamsAsHeaders();
HttpRequestMessage requestMessage = new HttpRequestMessage(...);
//then loop through the metaData and add each entry as a http header to your request, using the key as the header name and value as the header value
foreach(var item in metaData){
  requestMessage.Headers.Add(item.Key, item.Value);
}
...

5.7. Use SDK

See API Docs for full details on the APIs available within the SDK.