/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page android-publishing-to-googleplay.html
\title Publishing to Google Play
\brief Provides instructions to prepare your application for publishing.
\ingroup androidplatform
\previouspage android-3rdparty-libs.html
\nextpage Supporting Google Emoji Font Policy

\l{Qt for Android} provides a complete solution to develop, build, and package
your applications for Android. Most of these tasks, especially packaging and
deployment are handled by Qt Creator providing rich developer experience.

Every time you run the application using Qt Creator, an Android Application
Package (APK) is created and deployed onto the target of your choice
(device or emulator). With a few minor changes to packaging settings, you can
publish your application on Google Play.

\section1 Building the App

The following instructions guide you to create an \c{.apk} or \c{.aab}
that can go live on Google Play

    \list 1
        \li Open your project with Qt Creator 4.11 or later choosing a \c{Release Build}.

        \li Select \uicontrol Projects > \uicontrol Build > \uicontrol {Build Android APK}
        > \uicontrol {Create Templates} to create the Android package template files
        such as \c{AndroidManifest.xml} which is the main file of concern here.

        \li Check for the following settings in \c{AndroidManifest.xml}:
        \list
            \li Set \uicontrol{Minimum required SDK} to API 23 or later.

            \li Set \uicontrol{Application name} and \uicontrol{Application icon}.

            \li Check the \uicontrol{Permissions} list has all the required permissions.

            \li Check the \uicontrol{Features} list has the software or hardware
                features that your application depends on, such as GPS or NFC.
        \endlist
        See \l{Notes on Android project settings} for more information.

        \li Set up a \l{Android: Android keystore system}{keystore} to sign your
        \c{.apk} file. You can create a new keystore if you do not have one. For more
        information, see \l{Qt Creator: Specifying Settings for Packages}
        {Specifying Settings for Packages in Qt Creator}.

        \li Locate the generated package:

        \list
        \li For APK packages, locate the \c{.apk} package at:

            \badcode
            <$BUILD_DIR>/android-build/build/outputs/apk/release/android-build-release.apk
            \endcode

            \note In Qt Creator, select \uicontrol{Projects} > \uicontrol{Build}
                > \uicontrol{Build Steps} > \uicontrol{Build Android APK} >
                \uicontrol{Open package location after build} to build the
                application's \c{.apk} and open the directory containing the
                package.

        \li For AAB packages, select \uicontrol{Projects} > \uicontrol{Build}
            > \uicontrol{Build Steps} > \uicontrol{Build Android APK} >
            \uicontrol{Build .aab (Android App Bundle)} for Qt Creator to generate
            the \c{.aab} file, then locate the package at:

            \badcode
            <$BUILD_DIR>/android-build/build/outputs/bundle/release/android-build-release.aab
            \endcode

        \endlist
    \endlist

\section1 Uploading the App to Google Play Store

    Log into the \l{Google Play Developer Console} and upload the \c{.aab} files,
    along with a description and screen captures resembling the usage of your application.

    For Qt versions that support building a multi-abi bundle (i.e. Qt 5.14 and 5.15),
    uploading one \c {.aab} with all the supported architectures is enough.
    However, for Qt versions that don't have the multi-abi build support,
    publishing your app requires additional steps.

    \section2 Publishing Single-ABI bundles

        To publish your app that is built using a single ABI kit, you need
        to make sure that each ABI uses a different internal version code.
        The version code is an internal non-public identifier for your app's
        release. Build each one of the architectures you want to support
        and set a different version code for each ABI. This can be done
        as follows, for CMake:

        \badcode
        set_property(TARGET scroll_example APPEND PROPERTY QT_ANDROID_VERSION_CODE <unique_version>)
        \endcode

        Or as follows for qmake:

        \badcode
        ANDROID_VERSION_CODE = <unique_version>
        \endcode

        The app developer can use a specific scheme for the version code, for example,
        the code could have chunks for the platform, the ABI, and the actual
        version. Then, a sample scheme would be \c {<Platform><ABI><AppVersion>}:

        \list
        \li Platform:
            \list
                \li 1 for Arm
                \li 2 for Intel
            \endlist
        \li Architecture:
            \list
                \li 32 for 32 bit
                \li 64 for 64 bit
            \endlist
        \endlist

        The resulting version code for a release 1.0 for arm64-v8a ABI,
        would be \c {16410}.

        For more information, see Google's documentation on
        \l{https://developer.android.com/studio/publish/versioning#appversioning}{app versioning}.

        The following screenshot shows an example for an app targeting 4 ABIs,
        while each package uses a unique version code, which is different from
        the version name that is the public version string.

        \image android-single-abis.png

    For more information on packaging, see \l{Deploying an Application on Android}.

\section1 Notes on Android project settings

    Settings for \uicontrol {Minimum required SDK} and
    \uicontrol {Target SDK} versions are set in the Gradle build configuration and
    are controlled by the following variables:
    For qmake:
    \list
        \li \l ANDROID_TARGET_SDK_VERSION
        \li \l ANDROID_MIN_SDK_VERSION
    \endlist

    For CMake:
    \list
        \li \l QT_ANDROID_TARGET_SDK_VERSION
        \li \l QT_ANDROID_MIN_SDK_VERSION
    \endlist

    See \l {CMake Property Reference} for CMake projects, and
    \l {qmake Variable Reference} for Android-specific settings in qmake projects.

    \note As before with Qt 5.15, you can specify these settings in
    \c {AndroidManifest.xml}. Be aware that \c build.gradle will override these if
    set there. See \l{Android: App Versioning} for more information on setting
    these in \c build.gradle.

    \note By default, Qt adds the permissions and the features based on the module
    dependencies of your application. If you do not want these default permissions
    and features, either deselect the checkboxes
    \uicontrol{Include default permissions for Qt modules} and
    \uicontrol{Include default features for Qt modules}, or remove the following
    part from the \c{AndroidManifest.xml} file:

    \badcode
    <!-- The following comment will be replaced upon deployment with default permissions based on the dependencies of the application.
         Remove the comment if you do not require these default permissions. -->
    <!-- %%INSERT_PERMISSIONS -->

    <!-- The following comment will be replaced upon deployment with default features based on the dependencies of the application.
         Remove the comment if you do not require these default features. -->
    <!-- %%INSERT_FEATURES -->
    \endcode

    For information on the manifest, see \l{Android: App Manifest} and
    \l{Qt Creator: Editing Manifest Files}.
*/
