Android Development

uProxy can now be built for Android using the Cordova Chrome Apps (CCA) tool, a.k.a. Chrome Apps for Mobile Toolchain.

Build

The fast way

Use our Android Docker image:

./tools/build_env/build_env.sh -v android npm run grunt build_android

Note: Subsequent builds can be sped up with grunt build_android_lite. Use this if you've only changed HTML and TypeScript.

The long way

OSX

• You need Xcode 6.4 (7 will not work!).
• Things are easy for Homebrew users: brew install android-sdk android-ndk
• If you don't have Homebrew, you will need to:
  • install the Android SDK
  • set the ANDROID_HOME environment variable to Android SDK's path, e.g. export ANDROID_HOME=/usr/local/opt/android-sdk (you may want to persist this in your .bashrc)
  • install the Android NDK

Linux

• Install the Android SDK.
  • Since the command-line tools are largely unmaintained, the easiest way to get them is as part of Android Studio. Download the installer and start Android Studio; on first run, it will prompt you to install the SDK.
• Install the Android NDK.
  • Add ndk-build to your PATH.

Lastly, we need to install version 23 of the API (at the time of writing, only the latest, i.e. 24, is included at install time). Open Android SDK Manager:

$ANDROID_HOME/tools/android update sdk

Ensure that "SDK Platform" is installed for Android 6.0 (API 23).

Now, you can build the app with grunt build_android.

Troubleshooting

1. Confirm that your cca package is ready by running node_modules/.bin/cca checkenv from your git clone root directory.
2. Confirm that ndk-build is in your PATH with which ndk-build.

Install

The built output should be in build/src/android/platforms/android/build/outputs/apk/.

For reals

You'll need the adb tool. On OSX, it's included with the Android SDK; on Linux, try apt-get install android-tools-adb.

• On your phone, enable USB debugging.
• Connect your phone to your computer, accepting the connection if necessary.
• On your computer, upload the app to the phone using a command like adb install -r build/src/android/platforms/android/build/outputs/apk/android-armv7-debug.apk.

Troubleshooting

You may see an error if uProxy is already installed. If so, try first removing it by via Settings -> Apps -> uProxy.

Emulation

• Create a virtual device using the Android Virtual Device Manager with an API of 23 (Marshmallow) or higher. Choosing the same architecture as your host system for the CPU/ABI (e.g. x86_64) will result in faster emulation, but obfuscation will fail silently, and in one recent case uProxy wouldn't even start, so you may have to choose ARM and suffer with 10x slower emulation.
• Launch the emulator and check adb devices at the command line to make sure an emulator is running.
• Install the app from the command line with e.g. adb install -r build/src/android/platforms/android/build/outputs/apk/android-armv7-debug.apk. You should see success if the app is installed.
• You may then launch the app from the emulator. If after the uProxy splash screen is shown, you get "Application Error: The connection to the server was unsuccessful. (file:///android_asset/www/plugins/cordova-plugin-chrome-apps-bootstrap/chromeapp.html)", just try opening uProxy again. Apparently there is a race condition that sometimes causes this error.

Debugging

You can remotely debug the uProxy instance running on your Android device using the Chrome Developer Tools on your desktop Chrome. Just go to chrome://inspect in Chrome, and click the "inspect" link corresponding to the uProxy app on your connected Android device:

Creating a Play Store release build

Android app release builds must be signed. To create a release build:

1. Get the appropriate play_store_keys.p12 and android-release-keys.properties files, and symlink them into a keys directory in the git repo root.

• The uProxy team's release keys are stored in a secure location, not in the public git repository. Symlinking ensures that you do not accidentally copy the keys into insecure storage.

1. Run grunt release_android
2. From the build/dev/uproxy/android/platforms/android/build/outputs/apk/ directory, upload android-release.apk, android-x86-release.apk, and android-armv7-release.apk to the Play Store using the multiple APK upload procedure.

• This allows us to have a smaller build (~10 MB) for modern Android, and a larger build (~33 MB) for older Android versions that need Crosswalk because the system webview is too old to run uProxy.