Wrapping Android mobile apps

This article describes how Citrix Endpoint Management administrators wrap third-party enterprise apps and how developers wrap ISV apps. To wrap Android mobile apps, use the MDX Toolkit, which includes a macOS graphical interface tool and a Java command-line tool. The command-line tool has customization options, can be referenced from scripts that automate the app wrapping process, and lets you preset some MDX policies.

The file type for a wrapped app is .mdx. You upload the .mdx file to the Endpoint Management console where you then configure specific app details and policy settings that the Endpoint Management Store enforces. When users sign on, the app appears in the app store. Users can then subscribe, download, and install the app on their device.

The following figure provides an overview of the app wrapping steps, from installation of the MDX Toolkit through testing mobile productivity apps. Related topics are listed under the diagram.

For details on number one, see:

• System requirements
• Other requirements for wrapping Android mobile apps
• Endpoint Management compatibility
• Installing the MDX Toolkit

For details on number two, see:

• ISV Android app wrapping with the command line
• Enterprise Android app wrapping with the command line
• Command Options
• Presetting MDX policies for Android apps
• Identifying Android app wrapping errors
• Collecting app logs from the command line
• Add an MDX app

Important:

Make sure that your user devices are updated with a version of Secure Hub that is compatible with the version of MDX Toolkit used to wrap apps. Otherwise, users receive an error message about the incompatibility. For details, see Endpoint Management compatibility.

ISV app wrapping with the graphical interface

The following steps describe the general process for wrapping an ISV app that you will deploy from the Google Play Store.

1. Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed.

2. Start the MDX Toolkit from your iOS Applications folder, select For Independent Software Vendors (ISVs), and then click Next.

   

3. In the Deploy from App Store screen, select your app and click Next.

4. In the User Settings screen, if you already have the app store URL, enter it. If you don’t have the URL, enter a placeholder such as https://play.google.com/store/apps/details?id=com.citrix. You can update the URL later.

   For Premium apps, select MDX apps. For General apps, select App Store apps.

   

5. In the Verify App Details screen, update the details as needed.

6. Browse to your keystore and click Create.

   

7. Save your app.

   

   When the GUI tool finishes wrapping an app, the app file name includes _andr.

Enterprise Android app wrapping with the command line

You can use enterprise app wrapping to wrap custom (in-house) apps and some third-party apps. You should acquire third-party apps directly from the app vendor. For enterprise app wrapping, begin with an Android application (.apk). Before you use the toolkit to wrap apps, back up the original version of those apps so you can return to them if needed.

The following example shows a basic app wrapping command using default settings. The app is signed with the provided keystore. A keystore is a file that contains certificates used to sign your Android app. If the keystore contains multiple private keys, you can specify the key alias. You create a keystore one time. Then, you can use the keystore to sign the apps that you wrap. If you do not use the same keystore to wrap the new version of an app you previously deployed, upgrades of that app will not work. Users will need to manually remove the old version before they can install the new one.

Modify the bold information for your specific system. The trailing backslash signifies that the command continues to the next line. Please remove these symbols before running the command.

Note:

Because the /Applications/ directory is restricted, you may need to run the following command in super user mode. To do this, add sudo in front of the command. You will be prompted for your computer password when running from this restricted directory.

java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \
wrap \
-in ~/Desktop/SampleApps/Sample.apk \
-out ~/Desktop/SampleApps/Sample.mdx \
-keystore ~/Desktop/MyCompany.keystore \
-storepass MyKeystorePassword \
-keyalias MyCompanyKeyAlias \
-keypass MyKeyAliasPassword
<!--NeedCopy-->

The following are examples of options you may add to the preceding command, after modifying the information in bold:

• -appName “Wrapped Sample app”
• -appDesc “This is my newly wrapped Android application.”

In addition, if the release keystore is not available during development, use the following command to create a retail build of a mobile app that is signed with your key:

java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \
wrap \
-in ~/Desktop/SampleApps/Sample.apk \
-out ~/Desktop/SampleApps/Sample.mdx \
-keystore ~/Desktop/MyCompany.keystore \
-storepass MyKeystorePassword \
-keyalias MyCompanyKeyAlias \
-keypass MyKeyAliasPassword \
-createCert
<!--NeedCopy-->

For details about the options, see Command Options. For inline documentation, use the -help option.

ISV Android app wrapping with the command line

Before you use the toolkit to wrap apps, be sure to back up the original version of those apps so you can return to them if needed. To generate wrapped ISV applications for Android, start with the following basic wrapping command.

java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \
wrap \
-in ~/Desktop/SampleApps/Sample.apk \
-out ~/Desktop/SampleApps/Sample.mdx \
-keystore ~/Desktop/MyCompany.keystore \
-storepass MyKeystorePassword \
-keyalias MyCompanyKeyAlias \
-keypass MyKeyAliasPassword \
-createCert
<!--NeedCopy-->

To wrap an app as an ISV app, you must set the -apptype parameter as follows:

• Premium: To wrap an app as a Premium app, in which some Citrix policies are enforced even for unmanaged users, add the following option: -apptype Premium
• General: To wrap an app as a General app, which contains no Citrix policy enforcement for an unmanaged user, add the following option: -apptype General

If you need to upload the wrapped .apk file to the Google Play Store or web server and the URL is known when wrapping, add the -storeURL option. Make sure to also set the apptype parameter.

-storeURL "https://play.google.com/store/apps/details?id=com.zenprise"

If you do not know the URL at the time of wrapping, you can modify the .mdx file later with the following command:

java -jar /Applications/Citrix/MDXToolkit/ManagedAppUtility.jar \
setinfo \
-in ~/Desktop/SampleApps/Sample.mdx \
-out ~/Desktop/SampleApps/wrapped/Sample.mdx \
-storeURL \
“https://play.google.com/store/apps/details?id=com.zenprise”
<!--NeedCopy-->

If you customized the policy file, be sure to point to your modified file:

-policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml For details about the options, see Command Options. For inline documentation, use the -help option.

Command Options

wrap command

• Help: Displays Help for this command.
• In: Required. Path and file name of the app you are wrapping.
• Out: Optional. Path and file name for the resulting .mdx file. If this option is omitted, the file has the same path and file name as the input file and has an .mdx extension.
• AppType: Optional. Defaults to MDXOnly. To generate ISV apps, use either General or Premium.
• KeyStore: Path to the keystore file. Required if signing the .apk file.
• StorePass: Password for the keystore. Required if signing the .apk file.
• KeyAlias: Name of the specific key in the keystore. Required if signing the .apk file.
• KeyPass: Password for the specific key. Required if signing the .apk file.
• SigAlg: Optional. Algorithm to use when signing.
• AppName: Optional. Application name, obtained from the app if possible.
• AppDesc: Optional. Application description, obtained from the app if possible.
• MinPlatform: Optional. Minimum supported SDK level. Defaults to blank.
• MaxPlatform: Optional. Maximum supported SDK level. Defaults to blank.
• ExcludedDevices: Optional. List of device types on which the app is not allowed to run. Defaults to blank.

• PolicyXML: Optional. Replacement XML policy definition file and path. Defaults to the built-in policy definitions. Example:

  -policyxml/Applications/Citrix/MDXToolkit/data/policy_metadata.xml

  For details, see Presetting MDX Policies for Android Apps, next.

• StoreURL: For ISV apps, the URL of the app in the Google App Store. Defaults to blank.

sign command

• Help: Displays Help for this command.
• In: Required. Path and file name of the app you are wrapping.
• Out: Optional. Path and file name for the resulting .mdx file. If this option is omitted, the file has the same path and file name as the input file and has an .mdx extension.
• KeyStore: Required. Path to the keystore file.
• StorePass: Required. Password for the keystore.
• KeyAlias: Required. Name of the specific key in the keystore.
• KeyPass: Required. Password for the specific key.
• SigAlg: Optional. Algorithm to use when signing.

setinfo command

• Help: Displays Help for this command.
• In: Required. Path and file name of the app to be modified.
• Out: For setinfo, the output path or file name must differ from the original.
• AppType: Optional. Defaults to MDXOnly. To generate ISV apps, use either General or Premium.
• KeyStore: Path to the keystore file. Required if signing the .apk file.
• StorePass: Password for the keystore. Required if signing the .apk file.
• KeyAlias: Name of the specific key in the keystore. Required if signing the .apk file.
• KeyPass: Password for the specific key. Required if signing the .apk file.
• SigAlg: Optional. Algorithm to use when signing.
• AppName: Optional. Application name, obtained from the app if possible.
• AppDes: Optional. Application description, obtained from the app if possible.
• MinPlatform: Optional. Minimum supported SDK level. Defaults to blank.
• MaxPlatform: Optional. Maximum supported SDK level. Defaults to blank
• ExcludedDevices: Optional. List of device types on which the app is not allowed to run. Defaults to blank.
• StoreURL: For ISV apps, the URL of the app in the Google App Store. Defaults to blank.

• PolicyXML: Optional. Replacement XML policy definition file and path. Defaults to the built-in policy definitions. Example:

  -policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml

  For details, see Presetting MDX Policies for Android Apps, next.

Presetting MDX policies for Android apps

For apps that you wrap with the MDX Toolkit command-line tool, you can preset some MDX policies. You can also configure policies in the Citrix Endpoint Management console when you add the apps.

1. Update policy values in the policy XML file.

   The MDX Toolkit installer creates this policy file: Applications/Citrix/MDXToolkit/data/policy_metadata.xml

   Note

   Be aware that the policies files for Android and iOS differ. To preset policies for both of those platforms, you must update their respective policy XML files.

2. When you wrap the app with the command line, include

   -policyxml /Applications/Citrix/MDXToolkit/data/policy_metadata.xml

Identifying Android app wrapping errors

If you encounter an error when wrapping an Android app, you can use the MDX Toolkit logs to identify the error. You must have administrator rights to view the MDX Toolkit logs.

When you run the MDX Toolkit, the tool saves a log file to the following location: Applications/CitrixMDXToolkit/Logs/Citrix.log. By default, the tool saves warnings and errors in the log.

Collecting app logs from the command line

1. Install the Android Debug Bridge from the Android Developer web site. For details, see Android Debug Bridge.
2. Enter the following command to clear existing logs: “adb logcat -c”
3. Reproduce the issue.
4. Enter the following command to capture the logs in a file: adb logcat -d > Name_of_Log_File.txt