Prepare a Qt app for Play Store Publishing

This blog post will guide you through the entire process of preparing your Qt for Android app with CMake for publishing on the Play Store. By the end, you’ll be ready to distribute your Qt app to millions of Android users, buckle up! 

App Configuration with CMake

Qt 6 offers excellent CMake support and that includes Android. Android apps depend on many aspects of the app being set in the AndroidManifest.xml or under Gradle build configuration files. You can always manage those files under you Qt project if you wish, however, Qt offers many APIs that allows managing that directly from within your CMake project configuration:

Set Target Properties

Define essential Android properties like the package, app names, app icon, versioning information:

set_target_properties(${appname} PROPERTIES
    QT_ANDROID_PACKAGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/android"
    QT_ANDROID_PACKAGE_NAME "io.qt.calqlatr"
    QT_ANDROID_APP_NAME "Calqlatr"
    QT_ANDROID_APP_ICON "@drawable/ic_launcher"
    QT_ANDROID_TARGET_SDK_VERSION 35
    QT_ANDROID_MIN_SDK_VERSION 28
    QT_ANDROID_VERSION_NAME "1.0"
    QT_ANDROID_VERSION_CODE 10
)

For QT_ANDROID_TARGET_SDK_VERSION, make sure to use the current version required by the Google Play Store.

Regarding QT_ANDROID_APP_ICON, expects the icon files/drawables to exist under the directory:

/<QT_ANDROID_PACKAGE_SOURCE_DIR>/res/drawable-<dpi>

To generate such icons files, you can use Qt Creator's Android Icon Generator or Android Studio's Icon Creator. Alternatively, you can use one of the many online Android icon generator tools over the internet.

Manage Packaged Plugins

Going a step further, you can customize what plugins to package in your app's bundle. Due to the way the Qt Android deployment tool works, it doesn't necessarily know at build time what plugins your app would need, so it might end up packing plugins that are not needed at runtime, to go around this, you can explicitly manage what plugins to include or exclude. This can be done using qt_import_plugins() function:

qt_import_plugins(${appname}
    INCLUDE_BY_TYPE imageformats Qt::QSvgPlugin Qt::QJpegPlugin
    EXCLUDE_BY_TYPE iconengines networkinformation tls platforminputcontexts qmltooling
)

The first line INCLUDE_BY_TYPE ensures that only QSvg and QJpeg plugins of imageformats type are included, and the second line with EXCLUDE_BY_TYPE ensures to not add the other plugin types that we don't really need for our app. Keep in mind that qt_import_plugins() only attempts to include plugins from a target's list of dependencies that this target links against.

Use Release Build Type

Published apps to the Play Store are always expected to be a release build type, so it's import you get this step set right from the start to avoid potentially re-doing some of the work again if you decided to switch build types later on.

Or do this from the command line with:

qt-cmake -DCMAKE_BUILD_TYPE=Release ...

By default, Android release apps are not debuggable, so if you explicitly manage that make sure to set the app debuggable state to false in AndroidManifest.xml or Gradle Configuration. It's also advised to disable various logs as they won't be that useful on production devices, as recommended by Android.

Enable Multi-ABI Builds

To support multiple device architectures, configure your build to generate Android multi-ABI APKs and/or Bundles (AAB). If you have a Qt for Android version installed from the official installer, this can be as simple as configuring your app with the CMake variable:

qt-cmake -DQT_ANDROID_BUILD_ALL_ABIS:BOOL=ON ...

This can easily be set from the project settings in Qt Creator as well.

For more in depth explanation on handling Qt for Android multi-ABI builds, see Alexey Edelev's blog post Android Multi-ABI builds for user projects are back.

Prepare Signing Keys

Google Play Store requires every app release to be signed. At the time of writing this blog post, the Google recommends using a Google Play managed signing key. Using this way you'd have two signing keys, one is generated when creating your app on the Play Store Console, and is afterwards managed by Google. The second key, is the one you have locally and is called an upload key, which would be used to sign app bundles when uploading them to the Google Play Console to ensure the authenticity of the bundle. For more information, see Use Play App Signing.

The bottom line, we need to generate an upload key. Both Qt Creator and Android Studio have UI tools to help you create such a key.

Using Qt Creator

To handle this using Qt Creator, see Signing Android Packages. Once the key is generated, make sure to tick the Project Settings > Build Android APK > Application Signature > Sign package checkbox.

Using Command Line

To generate a signing key store using only a command line prompt, use the following:

keytool -genkey -keyalg RSA -keystore upload-key.keystore \
    -alias play_apps \
    -storepass <password> -keypass <key-password> \
    -dname "CN=<name>, OU=<unit>, O=<organisation>, L=<city>, ST=<state>, C=<country>"

Once that's ready, enable signing for your project by configuring your project with the following arguments:

qt-cmake -DQT_ANDROID_SIGN_APK:BOOL=ON -DQT_ANDROID_SIGN_AAB:BOOL=ON ...

Then, set the following environments variables that specify the key's details:

export QT_ANDROID_KEYSTORE_PATH=upload-key.keystore
export QT_ANDROID_KEYSTORE_ALIAS=play_apps
export QT_ANDROID_KEYSTORE_STORE_PASS=<password>
export QT_ANDROID_KEYSTORE_KEY_PASS=<key-password>

Enable AAB Bundles

The Play Store nowadays accepts mainly Android App Bundles (AAB) rather than APKs because they offer more compatibility and are more practical for releasing purposes. AAB package resources and libraries for different device architectures, screen sizes and densities. The Store later creates installable APKs for individual devices depending on their requirements. For more information, see Android App Bundle frequently asked questions.

Now, let's tell Qt to generate such AAB bundles...

Using Qt Creator

To handle this using Qt Creator, see Signing Android Packages. Once the key is generated, make sure to tick the Project Settings > Build Android APK > Advanced Actions > Build Android App Bundle checkbox. Additionally to have Qt Creator open the release directory after it's been built, tick "Open package location after build" checkbox.

Using Command Line

To generate an AAB for your app, simply run:

cd build
cmake --build . --target aab

If you have multiple apps under your project, the previous command will generate an AAB for each app/executable target in your project, so to generate an AAB only for a given target, you can run:

cd build
cmake --build . --target appname_make_aab

This would result in an AAB under the path:

/<project-build-path>/android-build-appname/build/outputs/bundle/release/android-build-appname-release.aab

After this, your builds are expected to generate signed release packages that are acceptable by the Play Store.

Play Store Console

Before moving to publish your app, it goes without saying that you should test your app with various devices, and scenarios to make sure your app is ready for the public. Now, is also a good time to have your artwork ready, things like screenshots, demonstrative designs and promotional videos.

Google makes it possible to manage published app through the Google Play Console, that means the first thing you need is to have an account ready, to do that follow the steps provided under How to get started with Play Console.

Now, the final step is publishing, for a comprehensive guide on the various requirements and steps for making your app available on the store, it's highly advisable to follow the official Play Console guide Create and set up your app. It will take you step by step on how to prepare your app, create testing tracks, upload your app bundles, get it reviewed and finally release your app to the Play Store.

For more useful information about the store to get the best results out of it, it's also advisable to check the Google Play Console webinars.

You might as well find the guide Publish your app from Google very useful, as it also gives overall tips and considerations to consider when releasing an Android app.

And that’s the end of this blog post! Hoping this guide has helped you navigate the publishing process and you're well on your way to releasing your Qt powered Android app to the Google Play Store.

Happy publishing! 🚀