Setting up the sample Cordova app with MAM SDK

A sample Cordova app is provided with the Citrix micro VPN plug-in for Cordova(cordova-plugin-android-mvpn). In this article, we describe how to set up, build, distribute, and test the sample app. Currently, the Citrix micro VPN plug-in for Cordova supports tunneling for the following components and plug-ins in the Android Platform:

• Cordova WebView - This is the main WebView of the Cordova app.
• InAppBrowser - This uses the plugin, cordova-plugin-inappbrowser. It is used to view webpages without leaving the app.
• Fetch - This component is used for fetching data using the micro VPN tunnel.

Pre-requisites

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

• A Citrix developer account(Optional).
• Experience in developing Android mobile apps using Cordova.
• Access to a Citrix Endpoint Management environment to upload the .mdx and .apk files to distribute the app.
• Access to an Android Enterprise account to upload the .aab or .apk files to the Managed Google Play portal(Optional).

• Access to test micro VPN tunneling with your app through Citrix Gateway.

• Recommended reading:
  • Generate a key and KeyStore to sign your apps.
  • Create your first Cordova app.
  • Using the Citrix micro VPN plug-in for Cordova.

Software requirements

Overview

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

• Download the Citrix micro VPN plug-in for Cordova and the sample app.
• Integrate the plug-in with the sample app.
• Build the sample app.
• Distribute the sample app.
• Test the sample app.

a Download the Citrix micro VPN plug-in for Cordova and the sample app.

There are two ways to download the sample app and the Citrix micro VPN plug-in for Cordova:

1. From Citrix’s GitHub Repository - Start from step 1 in the following steps.
   • Citrix micro VPN plug-in for Cordova.
   • Citrix Cordova sample app.

2. From citrix.com/downloads - Start from step 2 in the following steps.

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

1. Download the plug-in 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 Cordova sample app.

git clone https://github.com/citrix/citrix-mam-sdk-sample-browser-app-android-cordova.git cordova-mvpnsampleapp
<!--NeedCopy-->

1.3 - Copy the Citrix micro VPN plug-in for Cordova to the sample app’s root folder.

cp -r citrix-mam-sdks/cordova/android/cordova-plugin-android-mvpn/21.7.0 cordova-mvpnsampleapp/cordova-plugin-android-mvpn
<!--NeedCopy-->

1.4 - Change the working directory to the sample app’s root folder.

cd cordova-mvpnsampleapp
<!--NeedCopy-->

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

2. Download the zip file from the Citrix website’s downloads page

2.1 - Download the Citrix micro VPN plug-in for Cordova.

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

2.2 - Unzip the file MAM_SDK_for_Android_Cordova_21.7.0.zip.

unzip MAM_SDK_for_Android_Cordova_21.7.0.zip
<!--NeedCopy-->

The unzipped folder has the following directory structure:

2.3 - Unzip the plug-in file - cordova-plugin-mvpn.zip.

cd Cordova_mVPN_Plugin
unzip Plugin/cordova-plugin-mvpn.zip -d Plugin/cordova-plugin-mvpn
<!--NeedCopy-->

The unzipped folder has the following directory structure:

2.4 - Unzip the sample app - cordova-mvpnsampleapp.zip.

cd SampleApp
unzip cordova-mvpnsampleapp.zip -d cordova-mvpnsampleapp
cd cordova-mvpnsampleapp
<!--NeedCopy-->

The unzipped folder has the following directory structure:

2.5 - Copy the plug-in folder to the sample app.

cp -r ../../Plugin/cordova-plugin-android-mvpn ./
<!--NeedCopy-->

3. Integrate the plug-in 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 Android Studio.

3.2 - Create a build.json file in your Cordova sample app’s root folder with the following content:

The root folder for this sample app is **/Cordova_mVPN_Plugin/SampleApp/cordova-mvpnsampleapp**.

{
    "android": {
        "debug": {
            "keystore": "<path>/yourdebug.keystore",
            "storePassword": "yourstorepassword",
            "alias": "youralias",
            "password": "yourpassword"
        },
        "release": {
            "keystore": "<path>/yourrelease.keystore",
            "storePassword": "yourstorepassword",
            "alias": "youralias",
            "password": "yourpassword"
        }
    }
}
<!--NeedCopy-->

3.3 - Modify the app’s package name.

3.3.1. Navigate to cordova-mvpnsampleapp folder.

3.3.2. Open the package.json file.

3.3.3. Modify the app’s package name.

Note: The package name has to be globally unique. E.g. com.citrix.cordova.testapp.<some_unqiue_value>.

{
    "name": "com.citrix.cordova.testapp.<some_unique_value>",
    "displayName": "CordovaTestApp",
    "version": "21.6.0",
    …
}
<!--NeedCopy-->

3.4 - Modify the widget ID to have the same name as the package name.

3.4.1. Navigate to cordova-mvpnsampleapp folder.

3.4.2. Open the config.xml file.

3.4.3. Modify the widget ID to have the same name as the package name.

<widget id="com.citrix.cordova.testapp.<some_unique_value>" version="20.11.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>CordovaTestApp</name>
    …
</widget>
<!--NeedCopy-->

3.5 - Add the Android platform to your project by running the following command using the Cordova CLI:

Note: If you are using the sample app from GitHub, you would first need to downgrade the plug-in version within the package.json file from "@citrix/cordova-plugin-android-mvpn": "^21.7.0", to "@citrix/cordova-plugin-android-mvpn": "^21.6.1",.

Run the following command from the sample app’s root folder:

cordova platform add android
<!--NeedCopy-->

3.6 - Install cordova-plugin-android-mvpn plug-in using the Cordova CLI by running the following command:

Run the following command from the sample app’s root folder:

cordova plugin add cordova-plugin-android-mvpn/
<!--NeedCopy-->

Note: Alternatively, you can install the cordova-plugin-android-mvpn plug-in using Plugman by running the following command, if you want to install it only for a specific platform such as Android:

plugman install --platform android --project platforms/android  --plugin cordova-plugin-android-mvpn/ --plugins_dir plugins
<!--NeedCopy-->

3.7 - Using the Cordova micro VPN plug-in.

The sample app already uses the features of the MAM SDK through the Citrix micro VPN plug-in for Cordova.

If you are building your own project, it is now ready to use the features of the Citrix micro VPN plug-in for Cordova. To make the necessary code changes to your Cordova app to use micro VPN tunneling, see Using the Citrix micro VPN plug-in for Cordova.

3.8 - Update the test URLs within the file located at cordova-mvpnsampleapp/www/index.html.

<ul>
    <li><button id="loadCitrix">https://www.citrix.com</button></li>
    <li><button id="loadFacebook">https://facebook.com</button></li>
    <li><button id="loadHttpTestWeb">http://internal.mycompanyurl.com</button></li>
    <li><button id="loadHttpsTestWeb">https://internal.mycompanyurl.com</button></li>
</ul>
<!--NeedCopy-->

3.9 - Update the URL within <h2> under <div id="testBase"> in the file located at cordova-mvpnsampleapp/www/index.html.

The string here is the URL of the website which is displayed in an iframe. Ensure that the website you choose can be embedded within an iframe.

To check if a website supports iframes, ensure that the HTTP response header X-Frame-Options does not have the values SAMEORIGIN or DENY. If the header does not exist or has a different value, the website can be loaded in an iframe. You can check this using developer tools of your browser.

<h2>Cordova Web View test (https://wikipedia.org):</h2>
<!--NeedCopy-->

3.10 - Update the URL value for iframe.src within the file located at cordova-mvpnsampleapp/www/js/index.js.

This value should be the same as the URL from step 3.9.

iframe.src = 'https://wikipedia.org';
<!--NeedCopy-->

4. Build the sample app

4.1 - Execute the Ccordova build command in your Cordova app project.

cordova clean android

# For the debug build
cordova build android

# For the release build
cordova build --release android
<!--NeedCopy-->

The cordova build step calls a hook to generate a .mdx file that must be uploaded to the Citrix Endpoint Management console. When the build completes successfully, the following message appears:

Successfully generated mdx
===== DONE CREATING MDX FOR ANDROID =====
<!--NeedCopy-->

4.2 - Verify that the .mdx and .apk files are created.

Note: Verify that the location of the .mdx and .apk files are present in the output of the previous command, cordova build android.

Input: /Users/user/Cordova_mVPN_Plugin/SampleApp/cordova-mvpnsampleapp/platforms/android/app/build/outputs/apk/debug/app-debug.apk
Output: /Users/user/Cordova_mVPN_Plugin/SampleApp/cordova-mvpnsampleapp/mdx/android-debug.mdx
<!--NeedCopy-->

5. Distribute the sample app

5.1 - Choose your platform and distribute the sample app.

MAM SDK is supported for Android Enterprise. See Distribute apps for steps to distribute the sample app.

6. Test the sample app

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

There are two ways in which you can test the sample app.

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

6.2 - Verify the behavior of the sample app.

1. Ignore the message Waiting for MVPN SDK existence.
2. Clicking the different links under In App Browser Test opens the respective URLs.
3. The message Fetch confirmed appears in green under Fetch test.
4. Verify that the iframe loads Wikipedia.

The following image shows a working sample Cordova app: