zec
/
secant-android-wallet
mirror of https://github.com/zcash/secant-android-wallet.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
secant-android-wallet/docs/Sideloading.md

8.3 KiB
Raw Permalink Blame History

Sideloading

This documentation describes how to sideload a Debug or Universal release APK created by the project Continuous Integration. It also provides details on how to install an Android emulator on a desktop machine for non-Android users.

  1. Obtain binary
    1. Look under the GitHub Actions tab. Every pull request and merge to the Main branch will trigger a workflow that generates builds of the app. The workflows are called Pull Request and Deploy.
    2. Click on a successful workflow
    3. Scroll down the workflow results page to find an attached build output called Binaries
    4. Download the Binaries file
    5. Look for either the Universal or Debug APK in the flavor that you'd like to install. It should be under app/build/outputs/
  2. Install binary
    1. If using a physical device, run the terminal command adb install -r $PATH_TO_APK (see more about ADB commands). Alternatively, if you have the Android Studio installed, you can drag-and-drop the selected APK file to the physical device screen shared in the Running devices panel. Then, open the installed app from the device launcher.
    2. If using a virtual device, you can drag-and-drop the APK file onto the virtual device screen as well. See the next section on how to install an Android emulator on a desktop machine.

Install emulator

Besides third-party, often paid solutions, there are two ways to run an Android emulator on a desktop. Note that the following instructions describe the installation process on a Unix-based machine, but after a slight adjustment, it can also be used for a Windows-based machine.

  1. Install Android Studio using the instructions in the first steps of Setup documentation. The Android studio installation requires about 8 GB RAM or more and 8 GB of available disk space (IDE + Android SDK + Android Emulator).
  2. The second option is to install the Android SDK tools only, which requires less disk space and is used within the machine's terminal. Remember that this approach requires some manual steps, and you might need to adjust the following commands based on the specific versions and configurations you choose.
    • Tip: On Unix-based OS, SdkManager and the other tools are invoked with ./sdkmanager. On Windows, SdkManager is invoked with sdkmanager. Throughout the documentation, the macOS and Linux syntax is used by default.
    1. Download and install Java if you haven't done so yet
      • Install JVM 17 or greater on your system. Our setup has been tested with Java 17. Although a variety of JVM distributions are available and should work, we have settled on recommending [Adoptium/Temurin] (https://adoptium.net) because this is the default distribution used by Gradle toolchains. Be sure that the JAVA_HOME environment variable points to the correct Java version using the command: 
        export JAVA_HOME="$(/usr/libexec/java_home)"
    2. Download Android cmdline-tools
      • If you haven't already, download the Android cmdline-tools from the official website, section Command Line Tools.
      • Extract the downloaded archive to a location of your choice.
      • In the unzipped cmdline-tools directory, create a subdirectory called latest.
      • Move the original cmdline-tools directory contents, including the lib directory, bin directory, NOTICE.txt file, and source.properties file, into the newly created latest directory.
      • Move the updated cmdline-tools directory into a new directory, such as android_sdk. This new directory is your Android SDK directory now.
      • Open the Terminal cmdline app and navigate to the new android_sdk directory. You can now use the command-line tools from this location.
    3. Install Android platform-tools using the new sdkmanager with accepting all the necessary licence agreements 
      ./cmdline-tools/latest/bin/sdkmanager "platform-tools"
    4. Install Android SDK Packages using the new sdkmanager
      • Run the following command to install the necessary SDK packages. Replace <version> with the desired Android version (e.g., 34), <image-type> with the system image type (e.g., google_apis), and <abi> with the desired ABI (e.g., arm64-v8a).
      ./cmdline-tools/latest/bin/sdkmanager "platforms;android-<version>" "system-images;android-<version>;<image-type>;<abi>"
      • Example of such a command:
      ./cmdline-tools/latest/bin/sdkmanager "platforms;android-34" "system-images;android-34;google_apis;arm64-v8a"
    5. Create an AVD (Android Virtual Device)
      • Run the following command to create an AVD. Replace <avd-name> with the desired name for your AVD (e.g., pixel7_api34), <image-type>, <verison> and <abi> with the previously selected. Then, also replace <sd-card-size> with the desired size for the SD card (e.g., 1024M), and <device> with the desired device (e.g., pixel 7).
      ./cmdline-tools/latest/bin/avdmanager create avd -n <avd-name> -k "system-images;android-<version>;<image-type>;<abi>" -c <sd-card-size> -d <device> --abi <abi> --force
      • Example of such a command:
      ./cmdline-tools/latest/bin/avdmanager create avd -n pixel7_api34 -k "system-images;android-34;google_apis;arm64-v8a" -c 1024M -d pixel_7 --abi "arm64-v8a" --force
    6. Run the Emulator
      • Start the emulator with the following command. Replace <avd-name> with the name you gave to your AVD:
      ./emulator/emulator -avd <avd-name>
      • Example of such a command:
      ./emulator/emulator -avd pixel7_api34
      • Now, you should have the Android emulator running on your machine without installing the Android Studio, and you can finish the app installation from the previous section.

Build variants notes

  • Apps can be distributed in two different formats: Application Package (APK) and Android App Bundle (AAB). AAB is uploaded to Google Play, and allows the store to deliver device-specific slices (e.g. CPU architecture, screen size, etc.) for smaller downloads. APK is the format for sideloading. APK files are the original format from Android 1.0, and can be generated directly from a Gradle build. AAB files are a newer format, and APK files can also be derived from AAB. A "universal" APK is one that was derived from an AAB without any slicing. We use "universal" APKs for testing of release builds, as they are processed through bundletool (which has introduced bugs in the past) and therefore somewhat closer to what would be delivered to end user devices.
  • Android apps must be digitally signed. The signing key is critical to app sandbox security (preventing other apps from reading our app's data). We have multiple signing configurations:
    • If you build from source, your computer will generate a random debug signing key. This key will be consistent for multiple builds, allowing you to keep re-deploying changes of the app. But if you connect your physical Android device to a different computer, the debug key will be different and therefore the app will need to be uninstalled/reinstalled to update it.
    • Debug builds on the CI server always have a new randomly generated signing key for each build. This means each time you sideload a CI generated debug build, uninstall/reinstall will be necessary.
    • Release builds from a Pull Request workflow always have a new randomly generated signing key for each build.
      This means each time you sideload a CI generated debug build, uninstall/reinstall will be necessary.
    • Release builds from a Deploy workflow always are signed with the "upload" keystore. The upload keystore is consistent and is the signing key for uploading to Google Play. Google Play will then re-sign the app with the signing keystore when delivering the app to end users. Therefore, moving between a release build downloaded from Google Play versus one sideloaded from a Deploy workflow will require uninstall/reinstall.