Building for Android

Types of Build

In Monaca, Android app has two types of build: debug version and release version. The differences between these types of build are as follows:

Types of Build Description Installation
Debug Build An unsigned package which cannot be distributed in the market
Release Build A signed package with the developer’s code sign which can be distributed in the market
  • Sideloading
  • Google Play Store and other eligible markets
Sideloading typically refers to media file transfer to a mobile device via USB, Bluetooth, WiFi or by writing to a memory card for insertion into the mobile device. When referring to Android apps, "sideloading" typically means installing an application package in APK format onto an Android device without going through the market.

Step 1: Configure Android App

  1. From the Monaca Cloud IDE menu, go to Configure → App Settings for Android .
  2. Fill in the necessary information of your app:

    • General settings:

      Application Name A name representing your app publicly such as in the Market
      Package Name A unique name which will be used when uploading to the Android Market. It is recommended to use reverse-domain style (for example, io.monaca.app_name) for App ID. Only alphanumeric characters, periods (at least one period must be used) and underscore are allowed. Each segment should be separated by a period and started with an alphabetic character.
      Use Different Package Name for Debug Build If enable, the package name of the release-built and debug-built apps are different. In other words, the package name of debug-built app will have .debug extension, and the one for project debugger will have .debugger extension. However, this option is disable by default because it made some plugins impossible to be debugged due to the fact that they are tied to exact package names (eg. in-app purchase).
      Version The version number of your app. A version number consist of only number seperated by dots (for example, 1.0.0).
      Version Code An internal version number of your app, relative to other versions. The value must be integer, so that the applications can programmatically evaluate it for an upgrade.
      Fullscreen This option is only available with the Cordova 3.5 and later. If enable, your app will be run in a fullscreen mode which hide the status bar.
    • Misc: various settings regarding your Android app such as:

      Allowed URL * Specify URL(s) which can be accessed from your app. If set to *, you can access all domains from your app.
      Keep Running Enable Enable this if you want Cordova to keep running in the background.
      Disallow Overscroll Enable Enable this if you want to disable the glow when a user scrolls beyond the edge of the webview.
      WebView Engine Stock WebView Set to High Performance (Crosswalk) for a more powerful and larger app size. It’s required Android 4.0 and up. For Cordova 5.2 and and higher, Stock WebView will be applied as default.
      Screen Orientation Default You can also set the device’s screen orientation when running your app as Landscape or Portrait.

    After finishing the configurations, click Save.

    Currently, when you update either iOS's App ID or Android's Package Name, both of them will change. In other words, they are configured to be the same. However, it is possible to make them different. Please refer to How to make iOS’s App ID and Android’s Package Name differently .
  3. Set of adaptive icons

    If you are using a monaca project with cordova 9.0 or later, you can set an adaptive icon for android 8.0 or later.

    To set an adaptive icon, upload an image file under the res folder and add a background attribute and a foreground attribute to the icon tag of config.xml. If the previous src attribute is set, the value of the src attribute is not used.

    If the os version does not support adaptive icons, the image set in the foreground attribute will be displayed. If the previous src attribute is set, the value of the src attribute takes precedence.

    The following is an example of placing an image under /res/android/icon/.

    <platform name="android">
        <icon density="ldpi" background="/res/android/icon/ldpi-background.png" foreground="/res/android/icon/ldpi-foreground.png"/>
        <icon density="mdpi" background="/res/android/icon/mdpi-background.png" foreground="/res/android/icon/mdpi-foreground.png"/>
        <icon density="hdpi" background="/res/android/icon/hdpi-background.png" foreground="/res/android/icon/hdpi-foreground.png"/>
        <icon density="xhdpi" background="/res/android/icon/xhdpi-background.png" foreground="/res/android/icon/xhdpi-foreground.png"/>
        <icon density="xxhdpi" background="/res/android/icon/xxhdpi-background.png" foreground="/res/android/icon/xxhdpi-foreground.png"/>
        <icon density="xxxhdpi" background="/res/android/icon/xxxhdpi-background.png" foreground="/res/android/icon/xxxhdpi-foreground.png"/>

    The following is an example of setting the src attribute.

    <platform name="android">
        <icon src="/res/android/icon/ldpi.png" density="ldpi" background="/res/android/icon/ldpi-background.png" foreground="/res/android/icon/ldpi-foreground.png"/>
        <icon src="/res/android/icon/mdpi.png" density="mdpi" background="/res/android/icon/mdpi-background.png" foreground="/res/android/icon/mdpi-foreground.png"/>
        <icon src="/res/android/icon/hdpi.png" density="hdpi" background="/res/android/icon/hdpi-background.png" foreground="/res/android/icon/hdpi-foreground.png"/>
        <icon src="/res/android/icon/xhdpi.png" density="xhdpi" background="/res/android/icon/xhdpi-background.png" foreground="/res/android/icon/xhdpi-foreground.png"/>
        <icon src="/res/android/icon/xxhdpi.png" density="xxhdpi" background="/res/android/icon/xxhdpi-background.png" foreground="/res/android/icon/xxhdpi-foreground.png"/>
        <icon src="/res/android/icon/xxxhdpi.png" density="xxxhdpi" background="/res/android/icon/xxxhdpi-background.png" foreground="/res/android/icon/xxxhdpi-foreground.png"/>

Step 2: Configure Android Keystore

A keystore is a binary file that contains a set of private keys. A private key represents the entity to be identified with the app, such as a person or a company. A keystore is encrypted with a password and it cannot be restored if the password is lost. When a keystore is lost or it overwrites another keystore, it is impossible to use the same key to re-sign the signed package.

A keystore is required for the building of a release version for your Android app. In Monaca, you can either create a new keystore or import an existing one. In order to create a new keystore, please do as follows:

  1. From the Monaca Cloud IDE menu, go to Configure → Android KeyStore Settings .

  2. Then, Manage KeyStore and Alias page will appear.

  3. Click on Clear and Generate New button. Then, the following screen will appear:

  4. Fill in the necessary information as shown in the above screen such as:

    • Alias: a name representing a private key that you will use later when signing your app. Multiple aliases can be stored within one keystore.
    • Password: a password for the private key (alias).
    • Password of the keystore: a password for the keystore. You will need this password when importing this keystore.
  5. Then, click on Generate Keystore and Alias button to Generate the keystore.

When a keystore is lost, it is impossible to use the same key to re-sign the signed package. Therefore, always back up and keep the keystore which is used to sign application(s). Use the Export button to download your keystore.

Step 3: Start Building

  1. From the Monaca Cloud IDE menu, go to BuildBuild App for Android.
  2. Select appropriate type of build you want and click Start Build.

  3. If you choose Release Build, you will also need to select an alias to sign your package before start building.

  4. It may take several minutes for the build to complete. Please wait. Once the build is completed, your built app is ready to be installed/downloaded. See below screenshot as an example:

See Also: