Setting up the Citrix micro VPN plug-in for Cordova
Download the Citrix micro VPN plug-in for Cordova
You can download the sample app and the Citrix micro VPN plug-in for Cordova using the following options:
- From Citrix’s GitHub repository - Start from step 1 in the following steps.
-
From Citrix’s downloads page - Start from step 2 in the following steps.
Note: A Citrix developer account is required to download the zip file from the downloads page.
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 - Copy the Citrix micro VPN plug-in for Cordova to your app’s root folder.
cp -r citrix-mam-sdks/cordova/android/cordova-plugin-android-mvpn/23.1.0 <path-to-your-app>/cordova-plugin-android-mvpn
<!--NeedCopy-->
1.3 - Modify the working directory to your app’s root folder.
cd <path-to-your-app>
<!--NeedCopy-->
1.4 - 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 zip file.
Note: A Citrix developer account is required to download the zip file.
2.2 - Unzip the file.
unzip MAM_SDK_for_Android_Cordova_23.1.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 - Copy the plug-in folder to your app’s root folder.
cp -r Plugin/cordova-plugin-android-mvpn <path to your app root folder>
cd <path to your app root folder>
<!--NeedCopy-->
3. Integrate the plug-in with your app
3.1 - Add a build.json file in your Cordova project’s root folder. This file must have the KeyStore signing details as shown in the following snippet:
{
"android": {
"debug": {
"keystore": "mdx/yourdebug.keystore",
"storePassword": "yourstorepassword",
"alias": "youralias",
"password": "yourpassword"
},
"release": {
"keystore": "mdx/yourrelease.keystore",
"storePassword": "yourstorepassword",
"alias": "youralias",
"password": "yourpassword"
}
}
}
<!--NeedCopy-->
3.2 - Add the mdxJarPath key to build.json if you are providing a location for a previously downloaded managed-app-utility.jar file.
When you build your app, the managed-app-utility.jar file will be automatically downloaded from the Citrix GitHub repository. However, if you have downloaded the Citrix micro VPN plug-in for Cordova zip file, you can find the managed-app-utility.jar file in the Tools folder. Add the mdxJarPath key to build.json with the location to the managed-app-utility.jar file to avoid downloading the file again during the build process.
Alternatively, you can use the switch --mdxJarPath when building the project using the Cordova CLI to provide the location of the managed-app-utility.jar file if you prefer not to use build.json.
{
"android": {
"debug": {
"keystore": "mdx/yourdebug.keystore",
"storePassword": "yourstorepassword",
"alias": "youralias",
"password": "yourpassword"
},
"release": {
"keystore": "mdx/yourrelease.keystore",
"storePassword": "yourstorepassword",
"alias": "youralias",
"password": "yourpassword"
}
},
"mdxJarPath": <full-path-to-managed-app-utility.jar>
}
<!--NeedCopy-->
3.3 - Add the Android platform to your project by running the following command using the Cordova CLI:
Run the following command from your app’s root folder:
cordova platform add android
<!--NeedCopy-->
3.4 - Install the cordova-plugin-android-mvpn plug-in using the following Cordova CLI command:
Run the following command from your 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.5 - Your project is ready to use the Citrix micro VPN plug-in for Cordova. To make necessary code changes to your Cordova app to use micro VPN tunneling, see Using the Citrix micro VPN plug-in for Cordova.
4. Build your app
4.1 - Execute the Cordova 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
# Commonly used build switches
cordova build android --release -- --keystore=<path-to-keystore> --storePassword=<keystore-password> --alias=<key-alias> --password=<key-password> --packageType=apk --mdxJarPath=<path-to-managed-app-utility.jar>
<!--NeedCopy-->
The Cordova build step calls a hook to generate a .mdx file that must be uploaded to the Citrix Endpoint Management console. Once the build completes successfully, the following message appears:
Successfully generated mdx
===== DONE CREATING MDX FOR ANDROID =====
4.2 - When the build completes successfully, an MDX file and an APK file are generated. Verify their existence.
5. Distribute and test your app
5.1 - Upload the MDX file to the Citrix Endpoint Management console.
This allows the app to be managed through Citrix Endpoint Management. For more details about distributing and testing your app, see:
If you are using the split tunnel mode REVERSE, then you can define Reverse Split Tunnel Exclusion List under MDX Policies. You can also override the default log settings under MDX Policies.
5.2 - Install the latest version of Secure Hub from the Google Play Store.
5.3 - Launch Secure Hub and enroll to the Citrix Endpoint Management environment.
5.4 - Install the SDK app. (E.g: cordova-mvpnsampleapp) from the Secure Hub Store or from the Intune Company Portal.
This step opens Google Play Store to install the app. If the app is not yet published on the Play Store, sideload the APK file using the adb tool.
adb install app-debug.apk