Setting up the sample Xamarin.Android (Native) app with MAM SDK

Introduction

The Citrix Xamarin MAM SDK libraries are useful for developing Xamarin.Android (Native) and Xamarin.Forms apps with the Citrix Endpoint Management Mobile Application Management SDK (MAM SDK). The Citrix Xamarin MAM SDK libraries are designed to allow per-app VPN connections without requiring mobile device management (MDM). These libraries enable the creation of a Web SSO network tunnel for a Xamarin app. With the Citrix Xamarin MAM SDK libraries, apps are no longer required to be wrapped with the MDX Toolkit.

Currently, the Citrix Xamarin MAM SDK libraries for Android support tunneling for the following Xamarin components:

• Xamarin.Android WebView
• Xamarin.Forms WebView
• Xamarin HttpClient

Pre-requisites

Before you proceed, ensure that you have met the following pre-requisites:

• Access to a Citrix developer account(Optional).
• Experience with Xamarin.Android (Native) mobile app development on the Visual Studio IDE.
• Access to a Citrix Endpoint Management console to deploy MDX and APK files.
• Access to an Android Enterprise account to upload .aab or .apk files to the Managed Google Play Store.
• Access to test micro VPN tunneling with your app through Citrix Gateway.
• Recommended reading:
  • Generate a key and KeyStore to sign your apps.
  • Setting up the Citrix Xamarin MAM SDK libraries.

Software requirements

Overview

Perform the following steps to build, deploy, and test your MAM SDK integrated Xamarin.Android app:

• Download the Citrix Xamarin MAM SDK libraries and the Xamarin.Android sample app.
• Integrate the Citrix Xamarin MAM SDK libraries with the sample app.
• Build the sample app.
• Generate the MDX file from the APK.
• Distribute the sample app.
• Test the sample app.

Note: There are two ways to download the Citrix Xamarin MAM SDK libraries and the Xamarin.Android sample app:

1. From the Citrix GitHub repository - Click here to go to section 1 for the steps.

2. From citrix.com/downloads - Click here to go to section 2 for the steps.

   Note: A Citrix developer account is required to download the zip file.

Perform the following steps to download the Citrix Xamarin MAM SDK libraries from GitHub

1.1 - Clone the Citrix MAM SDK repository.

git clone https://github.com/citrix/citrix-mam-sdks.git
<!--NeedCopy-->

1.2 - Clone the Citrix Xamarin sample app repository.

git clone https://github.com/citrix/citrix-mam-sdk-sample-browser-app-xamarin.git

# Rename the sample app

mv citrix-mam-sdk-sample-browser-app-xamarin/AndroidApp citrix-mam-sdk-sample-browser-app-xamarin/MvpnTestAndroidApp
<!--NeedCopy-->

1.3 - After you have performed the preceding steps, go to section 3 - Integrate the plug-in with the sample app.

2. Perform the following steps to download the Citrix Xamarin MAM SDK zip file from the Citrix website’s downloads page

2.1 - Download the Citrix Xamarin MAM SDK zip file.

Note: A Citrix developer account is required to download the zip file.

2.2 - Unzip the file - MAM_SDK_for_Android_Xamarin_23.1.0.3.zip.

unzip MAM_SDK_for_Android_Xamarin_23.1.0.3.zip -d MAM_SDK_for_Android_Xamarin_23.1.0.3
<!--NeedCopy-->

The unzipped folder will have the following directory structure:

2.3 - Unzip the sample app - MvpnTestAndroidApp.zip.

cd MAM_SDK_for_Android_Xamarin_23.1.0.3
unzip SampleCode/MvpnTestAndroidApp.zip -d SampleCode/MvpnTestAndroidApp
<!--NeedCopy-->

The unzipped folder will have the following directory structure:

3. Integrate the plugin with the sample app

3.1 - Ensure that you have created a KeyStore and have a key within it.

Make a note of the key alias, KeyStore password and, key password. You need these details for signing apps and generating the MDX file. The following link has more details on generating a key and KeyStore: Generate a key and KeyStore to sign your apps using Visual Studio.

3.2 - Open the .csproj file in Visual Studio.

The .csproj file is located at <path to sample app>/MvpnTestAndroidApp.csproj and can be opened in Visual Studio as shown in the following image:

3.3 - Add the Citrix.Xamarin.Android.MAMSDK NuGet source to your project.

The latest version of the NuGet libraries can be found in the following locations:

• If using the cloned MAM SDK repository: <path>/citrix-mam-sdks/xamarin/Citrix.Xamarin.Android.MAMSDK/<latest version>
• If using the unzipped MAM SDK: <path to Xamarin MAM SDK location>/NugetPackage/Android

nuget sources Add -Name Xamarin.MAMSDK.Android -Source <Enter Xamarin MAM SDK Location Here>/NugetPackage/Android
<!--NeedCopy-->

3.4 - Update the Citrix.Xamarin.Andorid.MAMSDK package to its latest version.

1. Expand the MvpnTestAndroidApp project and expand the Packages folder.
2. Right-click Citrix.Xamarin.Android.MAMSDK and click Update.
3. Accept any licenses that might be required.

If you see that the packages have not loaded correctly, right-click the Packages folder and click Restore.(Example:21.7.0.11.)

3.5 - The Xamarin MAM SDK should now be at the latest available version. Example: 21.6.0.4 -> 21.7.0.11.

3.6 - Change the DeX compiler to d8 for your Xamarin project.

Add the element <AndroidDexTool>d8</AndroidDexTool> under the PropertyGroup nodes in your .csproj file.

Note: For the sample app provided by Citrix, the following snippet is already included in the file: MvpnTestAndroidApp.csproj.

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
…
<AndroidDexTool>d8</AndroidDexTool>
…
</PropertyGroup>

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
…
<AndroidDexTool>d8</AndroidDexTool>
…
</PropertyGroup>
<!--NeedCopy-->

3.7 - Change the minSdkVersion and targetSdkVersion in your Androidmanifest.xml file.

<uses-sdk android:minSdkVersion="24" android:targetSdkVersion="31" />
<!--NeedCopy-->

3.8 - Change the package name in your Androidmanifest.xml file to a valid, unique name.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.example.xamarin.mytestapp">
<!--NeedCopy-->

3.9 - Add your KeyStore details to sign your Android package.

This can either be done using the IDE or by editing the .csproj file.

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
…
    <AndroidKeyStore>True</AndroidKeyStore>
    <AndroidSigningKeyStore>/Users/****/Downloads/mycompany.keystore</AndroidSigningKeyStore>
    <AndroidSigningStorePass>*****</AndroidSigningStorePass>
    <AndroidSigningKeyAlias>*****</AndroidSigningKeyAlias>
    <AndroidSigningKeyPass>****</AndroidSigningKeyPass>
…
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
…
    <AndroidKeyStore>True</AndroidKeyStore>
    <AndroidSigningKeyStore>/Users/****/Downloads/mycompany.keystore</AndroidSigningKeyStore>
    <AndroidSigningStorePass>*****</AndroidSigningStorePass>
    <AndroidSigningKeyAlias>*****</AndroidSigningKeyAlias>
    <AndroidSigningKeyPass>****</AndroidSigningKeyPass>
…
</PropertyGroup>
<!--NeedCopy-->

3.10 - Ensure the Release build includes no debugging information.

1. Right-click the MvpnTestAndroidApp project and click Options.
2. Expand Build and click Compiler.
3. Set the Configuration to Release.
4. Set Debug Information to None.

4. Build the sample app

4.1 - Select the build type as Release to generate the release version of the APK.

4.2 - Right-click the MvpnTestAndroidApp project and click Rebuild MvpnTestAndroidApp.

Wait for the build to complete successfully.

4.3 - Right-click the MvpnTestAndroidApp project and click Archive for Publishing.

4.4 - Right-click the MvpnTestAndroidApp archive and select Sign and Distribute.

4.5 - Select Ad-Hoc and click Next.

4.6 - Choose your signing option and click Next.

4.7 - Click Publish.

4.8 - Save the APK at your desired location. A window with the message Publishing Succeeded appears.

5. Manually generate the MDX file from the APK file

5.1 - Generate the MDX file corresponding to the sample app’s APK file using the command-line tool managed-app-utility.jar.

You must manually generate the MDX file from the APK you saved earlier. You can refer how to manually generate a MDX file in the following page: Generate and update an MDX file.

Note: It is imperative to use the same KeyStore that you signed your APK with, when generating the MDX file.

Use the following command to generate the MDX file:

java -jar <mamSdkLib path>/managed-app-utility.jar \
wrap \
-in <path to apk>/<apk name>.apk \
-out <path to save mdx file>/<mdx name>.mdx \
-appType sdkapp \
-keystore <keyStorePath> \
-storepass <keystorePassword> \
-keyalias <keyAlias> \
-keypass <keyPassword> \
-storeUrl "https://play.google.com/store/apps/details?id=<sample.app.package.name>"
<!--NeedCopy-->

6. Distribute the sample app

6.1 - Choose your platform and distribute the sample app.

MAM SDK is supported for the Android Enterprise platform. To distribute your app, see the following page: Distribute your app.

7. Test the sample app

7.1 - Test the sample app depending on the build type.

Depending on the build type, you can test your app by visiting the following pages:

1. Test the release build of the sample app.
2. Test the debug build of the sample app.

7.2 - Verify the behavior of the sample app.

1. Verify that clicking Start Tunnel is successful.
2. Verify that clicking WebView loads the URL entered.
3. Verify that clicking HttpClient loads the URL entered.