Support for AAB packages and new deploy options for Android

The newly released versions 4.7.0 and 5.5.0 introduce the long awaited support for Android App Bundle, or simply AAB, which is now required for Play Store distribution.

Deploying for Android will simply create both AAB and APK files inside the Android install folders, but there are new options to configure the signing process and a few caveats regarding these changes.

Support for MANAGE_EXTERNAL_STORAGE and the Play Store

Applications distributed through the Play Store can no longer access files in shared storage by default, with exceptions handled by the Play Store according to their policy for acceptable use. More information can be found here: https://support.google.com/googleplay/android-developer/answer/10467955?hl=en

Scoped storage summary. Source: Google

To comply with this restriction, this permission is not included in TotalCross applications by default, both for AAB and APK distributions. The option /force_android_storage_access can be used with the deploy to force the inclusion of the MANAGE_EXTERNAL_STORAGE permission and add the proper permission request in runtime.

Source: xda-developers

Applications distributed through APK files are free to use this permission as they see fit. This is a Play Store restriction and may or may not be applied to other third-parties managed stores.

Android signing configuration

With the new option /android_signing_config users may now provide the path to a properties file with configuration for the signing process.

By default, the deploy will always load the configuration provided by the file etc/security/android_keystore.properties, which is the following:

# AAB Signing configuration
aab_signing_enabled=true
aab_keystore_path=etc/security/tc_aab_key.keystore
aab_keystore_digestalg=SHA-256
aab_keystore_sigalg=SHA256withRSA
aab_keystore_storetype=JKS
aab_keystore_storepass=****
aab_keystore_keypass=****
aab_keystore_alias=tcandroidkey
# APK Signing configuration
apk_signing_enabled=true
apk_keystore_path=etc/security/tcandroidkey.keystore
apk_keystore_storepass=****
apk_keystore_keypass=****
apk_keystore_alias=tcandroidkey

You may copy this file to use as a starting point to create your own. Remember that you may omit some of these keys to keep using the default values.

• aab_signing_enabled — Change to false to disable signing the AAB file.
• aab_keystore_path — Path to a keystore file to use for signing the AAB file. Prefer using absolute paths, but paths relative to the SDK home folder is also accepted.
• aab_keystore_digestalg — Digest algorithm used with the keystore, SHA-256 is the default value. Refer to your own jarsigner version for other supported options.
• aab_keystore_sigalg — Signature algorithm used with the keystore, SHA256withRSA is the default value. Refer to your own jarsigner version for other supported options.
• aab_keystore_storetype — Format of the provided keystore. The default keystore included uses the JKS format to keep compatibility with Java 8, but when creating your own keystore, it is recommended that you use the format PKCS12, which is the default starting Java 11.
• aab_keystore_storepass & aab_keystore_keypass — Passwords for the keystore.
• aab_keystore_alias — Keystore alias. The default value is tcandroidkey.
• apk_signing_enabled — Change to false to disable signing the APK file.
• apk_keystore_path — Path to a keystore file to use for signing the APK file. Prefer using absolute paths, but paths relative to the SDK home folder is also accepted.
• apk_keystore_storepass & apk_keystore_keypass — Passwords for the keystore.
• apk_keystore_alias — Keystore alias. The default value is tcandroidkey.

Recommendations and caveats

For maximum security, creating your own keystores using the PKCS12 format and proper passwords is recommended. However, this may lead to problems when updating existing applications and require the removal of the previous version from the device first, causing local files to be removed as well.

For full APK compatibility, the default keystore must be used, but you should make the necessary changes on your application to allow a safe removal in the future.

AAB signing may also be disabled if you wish to let the Play Store handle the signing for you.

The generation of the AAB file requires the execution of the protoc executable, included in etc/tools/android, which may require setting up permissions. For the Mac OS, the following command is required:

xattr -d com.apple.quarantine /<path to TotalCross home>/etc/tools/android/protoc/protoc-3.20.1-osx-x86_64/bin/protoc