Building CHT Android Flavors

Building CHT Android Flavors

This tutorial will take you through building a CHT Android Application off the existing wrapper.

The cht-android application is a thin wrapper to load the CHT Core Framework web application in a webview.

You will be adding a new android flavor based off the cht-android.

Brief Overview of Key Concepts

A native Android container for Community Health Toolkit (CHT), it allows the application to be hardcoded to a specific CHT deployment and have a partner specific logo and display name.

To proceed you need to have ready, the following:

  • Title of the application
  • Logo 512x512, typically a version of the partner logo e.g. square design icons
  • URL is needed in the product flavor

Required Resources

You should have a functioning Android SDK installed. You will also need an image asset studio to create the icon resources required. The Android image asset studio is easily available.

Additionally, the following command tools are required:

  • Java 11
  • keytool
  • apksigner
  • openssl
  • base16

Implementation Steps

You need to prepare your resources (icons and application ID) then add the new application to the src folder and gradle.

1. Adding the new brand/application

  • Clone the cht-android repo
  • Add productFlavors { <new_brand> { ... } } in build.gradle
  • Add icons, strings etc. in src/<new_brand>. The src/new_brand/res/values/strings.xml file is mandatory
  • To enable automated deployments, add the new_brand to .github/workflows/publish.yml

2. Building the APK and AAB files

  • Execute: make org=new_brand keygen to generate the keystore
  • Execute: make org=new_brand keyrm-all to clean all the files generated to repeat keystore generation (optional)
  • Execute: make org=new_brand keydec to decrypt contents of the keystore (optional)
  • Execute: make org=new_brand keyprint to see the certificate content, like the org name, the certificate fingerprints, etc.
  • Execute: make org=new_brand flavor=New_brandWebview assemble to build the Webview versions of the .apk files
  • Execute: make keyprint-apk to verify the files were signed with the right signature
  • Execute: make org=new_brand flavor=New_brandWebview bundle to build the .aab files
  • Execute: make keyprint-aab to verify the files were signed with the right signature

3. Testing

  • Plug in your phone. Ensure that it is detected within adb devices
  • Execute: make using the SDK command line. (This will also push the app onto your phone.)
  • Execute: make test to run unit tests (static checks are also executed).
  • Uninstall previous versions of the app, otherwise an InstallException: INSTALL_FAILED_VERSION_DOWNGRADE can cause tests to fail. Android needs to have English as the default language.
  • Execute: make test-ui or make test-ui-gamma

4. Releasing

Alpha for release testing

  • Ensure tests have passed and merge to master
  • Create a git tag starting with v and ending with the alpha version, e.g. v1.2.3-alpha.1 and push the tag to GitHub.
  • The release-ready APKs are available for side-loading from GitHub Releases, along with the AABs required by Google Play Store.

Releasing in the Play Store

5. Updating the Play Store App

  • Rebuild the signed updated AAB or APK file to a new version
  • Follow the steps in 4. above

medic-android set up on Android Studio

CHT Core Framework

Technical overview and architecture of CHT Core used to build digital health applications