Deploying Applications to Android Devices

On Android, applications are distributed in specially structured types of ZIP packages called Application Packages (APK) or Android App Bundles (AAB). APK files can be downloaded to and executed on a device, whereas AAB is intended to be interpreted by the Google Play store and is used to generate APK files.

Qt for Android has binaries for armv7a, arm64-v8a, x86, and x86-64. To support several different ABIs in your application, build an AAB that contains binaries for each of the ABIs. The Google Play store uses the AAB to generate optimized APK packages for the devices issuing the download request and automatically signs them with your publisher key.

Qt Creator supports the following methods of deployment for Android applications:

  • As a stand-alone, distributable application package (APK).
  • Since Qt 5.14.0, as an app bundle (AAB), intended for distribution in the Google Play store.

Note: Since Qt Creator 4.12, Ministro is not supported.

To specify settings for application packages, select Projects > Build Android APK > Details.

For more information about options that you have for running applications, see Specifying Run Settings for Android Devices.

Packaging Applications

Because bundling applications as APK packages is not trivial, Qt 5 provides a deployment tool called androiddeployqt. When you deploy an application using a Qt for Android Kit, Qt Creator uses the androiddeployqt tool to create the necessary files and to bundle them into an APK:

  • Java files, which serve as the entry point into your application and that automatically load Qt and execute the native code in your application.
  • AndroidManifest.xml, which provides meta-information about your application.
  • Other XML files, which specify the dependencies of your application.
  • Resource files.
  • Libraries and QML files, which can be included in the project depending on the deployment method that you select.
  • Gradle wrappers that are needed to download and use Gradle.
  • Gradle script that is needed by Java IDEs, such as Android Studio. It allows the user to extend the Java part without copying our Java sources. It also allows the IDEs to provide code completion, syntax highlighting, and so on.

The Gradle wrappers and scripts are bundled only if you use Gradle to build the application packages. For more information, see Connecting Android Devices.

To view the packages that the androiddeployqt tool created, select the Open package location after build check box.

The packages are deployed on the connected Android devices. To switch the device used as a default device for the selected kit, select Projects > Run > Deploy to Android Device > Reset Default Devices. The setting applies until you restart Qt Creator. For more information, see Selecting Android Devices.

For more information about the androiddeployqt tool, see Deploying an Application on Android.

Specifying Settings for Packages

You can specify settings for the androiddeployqt tool in Qt Creator and in the project .pro file. To specify settings in Qt Creator, select Projects > Build > Build Android APK > Details.

"Deploy configurations"

The anddroiddeployqt tool uses the information in the project .pro file to create APKs. For more information about the qmake variables that you can set in the .pro file to tailor the APK, see Deploying an Application on Android.

You can view information about what the anddroiddeployqt tool is doing in the Compile Output pane. To view additional information, select the Verbose output check box.

Selecting API Level

In the Android build SDK field, you can select the API level to use for building the application. Usually, you should select the newest API level available.

Note: For Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1, Android build SDK 28 should be used. For recent versions than the latter, build SDK 29, or the most recent should be used.

This field does not specify the minimum supported API level nor the target API level, which you can specify in the Android manifest. See Editing Manifest Files. For more information about Android API levels, see What is API Level?.

Building AABs

For testing the application locally, use the APK format, because the package can be uploaded directly to the device and run. For distribution to the Google Play store, create an AAB by selecting the Build .aab (Android App Bundle) check box.

When building with CMake, you can view the selected ABIs in the Initial CMake parameters field in the CMake section. You can set additional ABIs as values of the ANDROID_ABI key:

"CMake settings for building AABs"

When building with qmake, you can select the ABIs in the ABIs field in the Build Steps:

"qmake settings for building AABs"

Signing Android Packages

To publish your application, you must sign it by using a public-private key pair that consists of a certificate and a corresponding private key and is identified by an alias. The key pair is used to verify that the future versions of your application are actually created by you.

Warning: Keep the key pair in a safe place and take back up copies, because you cannot update the application if you lose the key pair.

You can use Qt Creator to generate a keystore and a self-signed certificate. The generated certificate has the structure of an X.509 v3 digital certificate. It contains information about the version, serial number, and validity period of the certificate, the ID of the algorithm that is used to encrypt the data, the organization that issued the certificate, and the subject (owner) of the certificate. In case of a self-signed certificate, the issuer and owner of the certificate are the same. In addition, the certificate contains information about the algorithm that is used to sign the certificate, as well as the signature of the certificate.

The keystore is protected by a password. In addition, you can protect each alias with its individual password.

When you sign an Android application, you must select a keystore that contains certificates and a certificate alias from the keystore. The public key (certificate) for the alias is embedded into the APK during signing.

To create a keystore and a self-signed certificate:

  1. In the Keystore field, select Create to create a new keystore that contains one key pair in the Create a Keystore and a Certificate dialog:

  2. In the Keystore group, enter a password to protect the keystore.
  3. In the Certificate group, specify the key size and validity period of the certificate. You can specify a separate password to protect the key pair or use the keystore password.
  4. In the Certificate Distinguished Names group, enter information about yourself and your company or organization that identifies the issuer and the owner of the key pair.
  5. Select Save.
  6. In the Keystore File Name dialog, enter a name for the keystore and select a location for it.
  7. In the Keystore dialog, enter the keystore password to create the key pair in the keystore.

To sign an Android package by using a key pair, set the Sign package group settings described in Specifying Settings for Packages:

  1. In the Keystore field, select Choose to select an existing keystore.
  2. In the Certificate alias field, select an alias from the list of key pairs that the keystore contains.
  3. Select the Sign package check box to use the alias to sign the Android package.

Adding External Libraries

Qt Creator automatically detects which Qt libraries the application uses and adds them as dependencies. If the application needs external libraries, specify them in Projects > Build > Build Android APK > Additional Libraries field. The libraries are copied into your application's library folder and loaded on startup.

To add OpenSSL libraries, select Include prebuilt OpenSSL libraries in the Additional Libraries group. This will add the OpenSSL include project defined in device settings in Android OpenSSL group. This can be used for QMake and CMake projects.

Otherwise, you can manually add the paths to the required and libraries to the Additional Libraries field.

Editing Manifest Files

You can use the qmake variables to specify all the settings you need for the androiddeployqt tool and you do not need an Android manifest file unless you need to specify Android specific settings like the application's icon. Also, the manifest file is needed if you want to publish the package in the Play Store. If you use qmake as the build system, you can create an Android manifest file and edit it in Qt Creator. Select Projects > Build > Build Android APK > Create Templates to create the file and to open it in the Android Manifest Editor.

"Android Manifest Editor"

  1. In the Package name field, enter a package name for the application. The application is launched by an automatically generated Java launcher that is packaged with the application into an Android package (.apk). For more information, see Android Application Fundamentals.
  2. You can specify an internal version number for the package in the Version code field. It is used to determine whether one version of the application is more recent than another. In the Version name field, specify the version number that is shown to users.
  3. In the Minimum required SDK field, select the minimum API level required to run the application. The minimum supported API level for Qt Creator is android-9. However, Qt versions might have different minimum API levels, and therefore Qt Creator does not allow you to select an API level that the Qt version specified for the kit does not support.
  4. In the Target SDK field, select the targeted API level of the application. This affects the activation of some compatibility features in the OS. The value used by the androiddeployqt tool by default is 14, which means that the overflow button in the system navigation bar will not be enabled by default.
  5. In the Application group, set the application's name. You can also give an activity a name and select the activity to run.
  6. In the Style extraction field, set the method that Qt uses to extract style information:
    • Select Default or Full when using Qt Widgets or Qt Quick Controls 1 in your project.

      Note: This method uses some Android non-SDK interfaces, that are being restricted by Google starting from Android 9.0 (API 28).

    • Select Minimal when using Qt Quick Controls 2 but no Qt Widgets or Qt Quick Controls 1. This is faster than using the default or full options.
    • Select None when using neither Qt Widgets nor Qt Quick Controls 1 or 2.
  7. In Application icon, select an icon. Click the Master icon button to select an icon with the highest resolution, then, it will resize and set the three icon fields for low, medium, and high DPI icons as needed.
  8. In Splash screen, select images to display as splash screens depending on the device orientation. You can set different images to be shown on low, medium, and high DPI displays. By default, the splash screen is hidden automatically when an activity is drawn. To keep it visible until QtAndroid::hideSplashScreen() is called, select the Sticky splash screen check box.
  9. In Android services, you can add and remove services. You must enter at least a service class name for a new service. If you select Run in external process, you also need to enter a process name. If you select Run in external library, you need to enter a library name. Service arguments are mandatory for a service that is not run in an external library. For more information about writing service code and structure of services, see Android Services.
  10. In the Permissions field, you can specify the permissions that your application needs. Starting from Android 6.0 (API 23), permissions have to be requested at runtime (see QtAndroid::requestPermissionsSync() or QtAndroid::requestPermissions()). For lower Android API levels, users are asked to grant the permissions when they install the application. Android OS then grants the application access to the appropriate data and features.
  11. Select the Include default permissions for Qt modules and Include default features for Qt modules check boxes to add the permissions needed by Qt libraries. This can be android.permission.WRITE_EXTERNAL_STORAGE for Qt Core or android.permission.ACCESS_COARSE_LOCATION for Qt Location.
  12. To add a permission, select it from the list, and then click Add.

On the top header, select the XML Source tab to edit the file in XML format.

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.