Native app properties are divided into two categories: those that are common to all platforms, and those that are platform-specific. These properties range from the logo image your app displays to the types of screens and SDKs the app supports, and how certificates are handled.
From Quantum Visualizer V8 SP4, you can also enable certain Android features by manually adding the corresponding properties to the androidbuild.properties file.
To set Native app properties, follow these steps:
Note: For iOS applications, if the Name of the app has non-English characters, you must add the unicodeAppNameFlag: true
key in the infoplist_configuration.json
file.
icon.png
while building the application on the iPhone platform.Click the Android sub-tab, and set the following properties:
domain.company.application
.Note: The name you specify for Android Package must contain at least two segments.
A segment is a valid Java package name. The following are a few examples of valid Android Package names:
com.konylabs.<ApplicationName>
com.kony.<ApplicationName>
com.konysolutions.<ApplicationName>
com.kony.<ApplicationName>_Android
.Note: The application must be built with a minimum version matching the device SDK version. For example, a device with 5.0 version of SDK cannot run an application built on 4.0.
Note: The Target SDK Version must be greater than or equal to the Minimum SDK Version.
.so
files (armeabi-v7a and x86) are packed and the application leaves out 64-bit .so
files (arm64-v8a and x86_64). If you do not select the Support 32-bit devices option, 64-bit libraries /.so
files (arm64-v8a and x86_64) are packed by default.Note: From Quantum Visualizer V9 onwards, 64-bit APK’s are generated, by default.
Note: From August 1st 2019 onwards, all apps published on Google Play must support 64-bit architectures.
To support both 64-bit and 32-bit architectures in Google Play store, you must make sure that you perform the following actions:
64-bit version code = 32-bit version code + 1000
.AAR
files) contain the respective .so
files in all supported architectures: lib/armeabi-v7a, lib/arm64-v8a, and lib/x86 lib/x86_64 for 32-bit and 64-bit architectures, respectively.Note: To enable your application to be built with both 32-bit and 64-bit native libraries, refer to Support for 32-bit and 64-bit Architectures in a Single APK.
Large Screens - If this option is enabled, the application supports larger screen form-factors. A large screen is defined as a screen that is significantly larger than a normal handset screen, and might require some special care on the application's part to make good use of it. The application may rely on resizing by the system to fill the screen.
If this option is unchecked, it enables screen compatibility mode.
Note: This works only if the Minimum SDK is 2.3 or above.
Note: FIPS does not provide the mechanism to build the x86_64 architecture for Android. From V8 SP4 onwards, for the x86_64 architecture, Quantum Visualizer automatically bundles libraries that are non-compliant to FIPS for the following items:
SQLCipher
OpenSSL
Note: FIPS does not provide the mechanism to build the x86_64 architecture for Android. From V8 SP4 onwards, for the x86_64 architecture, Quantum Visualizer automatically bundles libraries that are non-compliant to FIPS for the following items:
SQLCipher
OpenSSL
<workspace>/<app>/resources/mobile/native/android/assets/certs
. For tablet, <workspace>/<app>/resources/tablet/native/androidtab/assets/certs
Note: If an assets folder does not exist, create an assets folder under respective locations as indicated above.
Create certs directory under the assets folder and add all the certificates into this folder.
Important: Allow Bundled option will not work in Android 2.3.x OS versions due to certificate chaining issue (causes certificate exception). This is a known Android native issue. For more information, see Issue 25152 on the Android Open Source Project Issue Tracker. Among other topics, Issue 25152 documents that to make the bundled option work in Android 2.3.x devices, the root CA needs to be omitted from the server end.
<workspace>/<app>/resources/mobile/native/android
.mobile > native > android
instead of drawable-port or drawable-land folder.Important: GCM (Google Cloud Messaging) is supported only for Android SDK Versions 2.3 and above.
Permissions tab: Set the permissions to true or false based on the application requirements. Set the appropriate permissions for Android Manifest file. For more information, see The Android Manifest File.
Important: Add the WRITE_EXTERNAL_STORAGE
setting if you need to save images in an external storage like SD Card.
For more information on the tags you can add, see http://developer.android.com/guide/topics/manifest/manifest-intro.html.
You can specify build.gradle entries as a prefix or suffix entries:
Use the gradle.properties entry to configure project-wide Gradle settings, such as the Gradle daemon's maximum heap size or proxy settings. For more information, see The Build Environment.
Use the settings.gradle entry to specify external modules (Gradle-based third-party Android libraries) to include when building your application. For more information, see Configure Your Build.
com.kony.<appname>
.Allow Self Signed Certificate: By default it is false, if true, it allows self signed certificate for development.
Note: Self Signed Certificate option is only applicable if you use Network APIs in your application.
Note: This feature is available from Quantum Visualizer V8 SP4 FP19 onwards, and is available in both Kony Visualizer Classic and Quantum Visualizer.
From V8 SP4 onwards, you can enable or disable certain Android features by adding the corresponding properties to the androidbuild.properties
file. You must first create the androidbuild.properties
file in your Quantum Visualizer project workspace (workspaceLocation\\project) as shown in the image.
Note: If the same property is passed from Quantum Visualizer in future plugins, the Quantum Visualizer property takes precedence.
You can enable the following Android features by adding these properties in the androidbuild.properties file:
You can enable the Public Key Pinning feature by specifying the following property in the androidbuild.properties file as shown.
This feature is enabled only if the networktrustconfig
property is set as Allow Pinned
in the androidbuild.properties file.
networktrustconfig = Allow Pinned
The APK Tamper Protection feature helps you to verify if an APK has been tampered with (modified from its original version). If a tamper is detected, the application safely exits during the bootup process. This is an optional feature that is supported only in Release and Protected modes. APK Tamper Protection is available from V8 SP4 onwards. From V8 SP4 Fixpack 20 onwards, support for Google Play App Signing has been added. Google Play App Signing is a mandatory signup for Android App Bundle support.
This feature is enabled only if the addAPKTamperProtection
property is set as true
in the androidbuild.properties file.
addAPKTamperProtection = true
For this feature to work, you must provide either of the information as follows:
developerSigningKeyHash:2otpMeAC68KCm7Q+F48tzTFtzmU=
The developerSigningKeyHash key helps you to utilize the APK Tamper Protection feature in the following scenarios:
<WorkSpace>\temp\<AppID>\build\luaandroid\extres
.PrintApkSignatureHash.jar
file.java -jar PrintApkSignatureHash.jar --fingerprint "<Hash-Algorithm>: <certificate fingerprint in Hexadecimal>"
Hash-Algorithm
can either be SHA-1
or SHA-256
.java - jar PrintApkSignatureHash.jar--fingerprint“ SHA256: EB: 71: 4E: 90: 3D: 2A: 7E: 14: 4B: D1: 73: 47: 3A: EA: 3D: 06: C5: F2: 69: B5: DC: BB: 28: 44: A0: 8D: AC: 17: E7: F2: 7F: 8F”
developerSigningKeyHash : xxxxxxxxxxxxxxxxxx
androidbuild.properties
file.uploadSigningKeyHash
property in the androidbuild.properties file as an alternative to specifying KeyStore entries. To manually sign the application by using your own keystore file, follow these steps:
<WorkSpace>\temp\<AppID>\build\luaandroid\extres
.PrintApkSignatureHash.jar
file.java -jar PrintApkSignatureHash.jar keyStorePath keyStorePassword keyAlias
-- algorithm
input parameter.java -jar PrintApkSignatureHash.jar –-storepath keyStorePath –-storepass keyStorePassword –-alias keyAlias --algorithm hash-logo
Here, the items are as follows:
SHA-1
or SHA-256
.Note: If the hash is generated with SHA-256 algorithm, the hash will not work for apps built in Quantum Visualizer V8 SP4 Fixpack 19 or earlier. However, if the hash is generated with SHA-1 or SHA-256 algorithm, the hash will work for apps built in Quantum Visualizer V8 SP4 Fixpack 20 or later.
developerSigningKeyHash : xxxxxxxxxxxxxxxxxx
Note: If you are generating the hash of the upload signing key to support Google Play App Signing, use uploadSigningKeyHash
as the key instead of developerSigningKeyHash
.
androidbuild.properties
file.From V9 onwards, when you enable the support64bit
property in the androidbuild.properties
file and select the Support 32-bit Devices check box from Project Settings > Native > Android, the Quantum Visualizer Android build generates a Fat
application. This Fat
application supports all architectures: armeabi-v7a, x86, arm64-v8a, and x86_64.
support64bit = true
Note: Quantum Visualizer recommends that you use a Fat
binary for testing purposes only, and Kony does not recommend you to upload a Fat
binary to Google Play. Use either the Split APK feature or the Android App Bundle feature to reduce the size of the binary that is downloaded to customers' devices.
Bundling all architectures into a single fat APK increases the APK size of the app that is delivered to customers. This APK Splitting feature, which has been introduced from V8 SP4 Fixpack 12 GA onwards, helps you to decrease the APK size that is downloaded based on the target platform architecture. For more information on the splitting of APKs, click here.
You must enable the splitapks
property as true
in the androidbuild.properties file. This action generates the architecture-specific individual .apk files and universal .apk file that supports all the architectures. This approach reduces the size of the .apk file.
splitapks = true
Note: Based on the specified value of the support64bit property in the androidbuild.properties file as well as on the selection of the Support x86 Devices and Support 32-bit Devices check boxes in the Quantum Visualizer Project Settings, the Quantum Visualizer Android build generates a set of APKs, each with a single supported architecture.
<appid>-<architecture>-<buildtype>.apk
<appid>-universal-<buildtype>.apk
The APKs are generated under the following paths:
Note: For architecture-specific .apk files, the version code of the individual .apk file must be unique. This is because since both 32-bit and 64-bit APKs are supported in 64-bit devices, there will be a conflict while choosing the APK file. Specifying a higher version code for the 64-bit APK file results in a greater precedence, and thus the 64-bit APK file would be chosen for a 64-bit device. This process helps to leverage the higher performance of a 64-bit APK in a 64-bit device.
The Quantum Visualizer Android build.gradle
file automatically handles the use cases related to APK versioning in the following manner:
build.gradle
file assigns architecture codes in the following order of priority:Note: If you want to split APKs based on density along with architecture, customize the build by adding the appropriate build.gradle
entries in the Gradle Entries tab > build.gradle entries to Suffix section.
Google Play’s Dynamic Delivery feature uses your Android App Bundle to build and serve APKs that are optimized for each device configuration. This results in a smaller app download for customers by removing unused code and resources needed for other devices. The support for Android App Bundle generation has been added from V8 SP4 Fixpack 12 GA onwards. For more information about Android App Bundle, refer Google's Android App here.
To enable the Generate Android App Bundle feature, you must set the generateAppBundle
property as true
in the androidbuild.properties file. The Quantum Visualizer Android build then generates the binary in App Bundle (aab) format. The AAB file is a Google Play upload format file, and is not an installable file.
Note: Quantum Visualizer and CI builds in Quantum Visualizer do not provide support for the generation of binaries in the Android App Bundle (aab) format. You must configure Quantum Visualizer to support the generation of 32-bit and 64-bit architectures in a single APK for generating the Android App Bundle.
generateAppBundle = true
The AAB file is generated in the following paths after the build:
Note: The Quantum Visualizer Android build generates an AAB file with all the selected architectures. The selected architectures are based on the specified value of the support64bit property in the androidbuild.properties file as well as on the selection of the Support x86 Devices and Support 32-bit Devices check boxes from the Quantum Visualizer Project Settings.
To test how Google Play uses the AAB file to generate APKs and how those APKs behave when deployed to a device, follow these steps:
Note: Android provides a tool, named bundletool, to extract APKs from the AAB file and test them. For more information on the usage of bundletool, click here.
java -jar bundletool.jar build-apks --bundle=<app-id>.aab --output=<app-id>.apks --overwrite
java -jar bundletool.jar install-apks --apks=<app-id>.apks --device-id=serial-id
Note: If you want to estimate the download size of the APKs from Google Play, generate the device-specific set of APKs by following the procedure specified here.
As part of the V8 SP4 Fixpack 12 GA release, the Dynamic Delivery feature (on-demand delivery of modules when an app developer requests) is not supported for Quantum Visualizer framework libraries. You can, however, implement the Dynamic Delivery feature for third-party libraries by using FFI code.
To sign the App Bundle file and ensure that the file is ready to be uploaded to Google Play, follow these steps
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore <keystorefile>
<app bundle file> alias_name
Note: apksigner is not supported to sign the App Bundle.
Google Play services include services such as Maps, Push Notification, Geofencing, Metrics, Places, etc. These services access is authorized using an API key. The API key is associated with a developer key for authentication, quota, and billing purposes.
When the Upload Signing Key is different from the Google App Signing Key and if you have registered only the upload key against the API key, Google Play services may fail when the user installs the APK from the Google Play store.
To overcome this, you must register Google App signing key as well with the same API key in the Google Play console. The same applies to external services such as OAuth, Facebook, Twitter APIs, etc. You must register the Google App Signing Key against those services.
The locationListenerType property specifies the location permissions. The permissions can be coarse or fine and are either in the background or foreground. Based on the listener type, an appropriate entry is added to the AndroidManifest.xml file.
Sample Usage
locationListenerType = always
If the developer does not set the value for the property, the default value is foreground.
Possible Values
Note: locationListenerType is respected if the Use Google play Location services checkbox is selected in Project Settings >Native > Android
To bundle the manually customized version of your Cordova-generated Android project, you must set the cordovabuildmode
property as incremental
in the androidbuild.properties file. This feature is available from Quantum Visualizer V8 SP4 Fixpack 47.
cordovabuildmode = incremental
For more information about how to manually customize the Cordova-generated Android project, click here.
In an app that contains a flow wherein an external activity (such as a payment flow) is launched through app interaction, issues may occur when the app is moved to the background and launched again.
If a user moves the app to the background by pressing the Home button after the external activity flow is launched, and launches the app again (through the app launcher), the external activity flow is destroyed when the app moves to the foreground. However, if the user launches the application from the Recent Apps tray instead of through the App Launcher, the state of the external activity is retained. To mitigate this Native Android issue, you must use the HeadlessLauncher activity. Support for the HeadlessLauncherActivity has been added from Quantum Visualizer V9 Service Pack 1.
To enable HeadlessLauncherActivity, add the following entry in the androidbuild.properties file.
useHeadlessLauncherActivity = true
/*adds headless launcher activity as root activity of the app*/
Note: This solution is purely based on current Android Native behavior observed for singleTask
mode launcher activity and is not an Android-documented approach. This approach may not work in the future if the Android Framework implementation for Launch Modes is modified.
You can customize the HeadlessLauncherActivity to add additional functionality. To create and use a custom HeadlessLauncherActivity, follow these steps:
useCustomHeadlessLauncherActivity = true
entry in the androidbuild.properties file. .jar
or .aar
file that contains the custom implementation and extends the KonyHeadlessLauncherActivity class. For example, CustomHeadlessLauncherActivity extends com.konylabs.android.KonyHeadlessLauncherActivity
.Place the file in the following location:
<WorkSpace>/<app>/resources/customlibs/lib/android
<WorkSpace>/<app>/resources/customlibs/lib/tabrcandroid
<activity android:theme="@style/Theme.AppCompat.NoActionBar
android:name="com.example.CustomHeadlessLauncherActivity" >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
In case of a .aar
file, add the activity tag as part of the AndroidManifest.xml in the .aar file.
In case of a .jar
file, add the custom activity tag in the Project Settings → Native → Android Mobile/Tablet → Tags → Child tag entries under <application> tag.
Note: To avoid any flickering during launch, ensure that the android:theme is the same as the theme of the auto-generated activity that extends KonyMain.
Details of the auto-generated activity and its theme are available in the AndroidManifest.xml with the same class name as the Application ID.
You can customize the auto-generated Main activity to add additional functionality. To create and use a custom MainActivity that extends the KonyMain activity, follow these steps:
Note: These steps can be followed independent of the usage of the useCustomHeadlessLauncherActivity
and the useHeadlessLauncherActivity
properties.
.jar
or .aar
file that contains the custom Activity class implementation and extends the KonyMain class. For example, CustomMainActivity extends com.konylabs.android.KonyMain
. Place the file in the following location:
<WorkSpace>/<app>/resources/customlibs/lib/android
<WorkSpace>/<app>/resources/customlibs/lib/tabrcandroid
Override the required Activity Class methods and invoke necessary superclass methods from the overridden methods so that the functionality does not break.
For example:
CustomMainActivity extends com.konylabs.android.KonyMain{
public void onCreate(Bundle savedInstanceState) {
super.onCreate(Bundle savedInstanceState);
//Your custom functionality
}
}
android:name = <CustomMainActivity>
. .aar
file, add the activity tag as part of the AndroidManifest.xml in the .aar file. .jar
file, add the custom activity tag in the Project Settings → Native → Android Mobile/Tablet → Tags → Main Launcher <activity> Tag attributes.Note: The <CustomMainActivity> must be the fully qualified path of the custom activity or the path relative to the package name of the current application.
Android 11 introduces restrictions on how apps query and interact with other apps installed on a device. When you try to invoke a specific app or query the list of installed apps on the device, the returned list is filtered . Apps must use the <queries>
element to define other packages that interact with the app. For more information, Refer Package Visibility.
If an app runs on Android 11 (Target SDK level 30, or later) devices, you must include one of the following entries in the Android Manifest file of the app:
<queries>
child tag. Within the <queries>
tag, you can specify packages by name, by intent signature, or by provider authority.<uses-permission android:name=“android.permission.QUERY_ALL_PACKAGES”/>
. Based on the Package Visibility behavior updates, when you build an Android 11 (Target SDK level 30, or later) app in Protected Mode, by default, the <uses-permission android:name=“android.permission.QUERY_ALL_PACKAGES”/>
permission is added in the Android Manifest file for Protected Mode Builds to work seamlessly. If you do not want this permission to be automatically added, you must add the donotAddQueryAllPackages = true
entry in the androidbuild.properties file of the project source directory.
The Android Framework relies on Security Providers to provide secure network communications. However, you might find intermittent vulnerabilities in the default security provider. To protect against such vulnerabilities, Google Play Services provides a way to automatically update the security provider to enhance device protection.
By using the kony.gms.installSecurityProvider or kony.gms.installSecurityProviderAsync APIs, you can ensure that the device has the latest updates that protect against security exploits. These APIs install a new security provider in the application process, GmsCore_OpenSSL, that is set as the default security provider for the app. The security provider must be installed every time you restart an application process.
To support the Security Crypto Provider Patching, you must add/modify the following entries in the androidbuild.properties file:
To add the GMS (Google Mobile Services or Google Play Services) Library Dependencies, you must add the supportGooglePlayBaseLib = true
entry in the androidbuild.properties file of the project. When you add this entry, the com.google.android.gms:play-services-base
library dependency is added in the build.gradle file of the app.
Note: If other APIs such as Map APIs are included in the project, you may not need to add this entry in the androidbuild.properties file.
To support security provider patching during the application boot-up process, you must add the patchSecurityProvider
key in the androidbuild.properties file of the project. The value of the patchSecurityProvider key must be set to sync
for synchrounous and async
for asynchrounous patching.
Note: In case of synchronous patching, the time taken for patching adds to the time taken for boot-up.
Security provider patching takes about 280 ms in low-end devices and 100 ms in high-end devices for the first time after the application is installed. Due to ART-JIT optimizations, subsequent launches of the application (after the process is killed) may be faster than the first boot-up after the install. If a security provider is available for an app, subsequent launches will not add to the overhead time for an app as the launches will be quick (less than 10ms even on low-end devices).
Note: Security Provider Patching during the app boot-up process only works if the device has the latest version of the crypto provider (that is offered by the Google Play Services library). If the Google Play Services is not up-to-date, security provider patching is skipped in silent mode.
During network communication (while using the kony.net APIs), only a subset of the TLS protocols and ciphers (that are supported by the device) are enabled for an SSL handshake. To have greater control over the enabled protocols and ciphers used in a network, developers can modify the following configurations in the androidbuild.properties file of the project:
Set the value of this property to true to enable all the TLS protocols and ciphers (that are supported by the device) during the SSL handshake, after the provider update is successful. When you set the value of this property to true, you can enable the latest TLS protocols and ciphers on older devices as well. When you set the value of this property to false, only the default TLS protocols and ciphers (that are supported by the device) are enabled for the SSL handshake.
The value of this property is set as true, by default.
Set the value of this property to true to enable all the TLS protocols and ciphers (that are supported by the device) during the SSL handshake, irrespective of a provider update. When you set the value of this property to false, only the default TLS protocols and ciphers (that are supported by the device) are enabled for the SSL handshake.
The value of this property is set as false, by default.
Note: In normal circumstances, you must not set the value of this property to true, as deprecated protocols and ciphers may also be enabled on the device.
Copyright © 2020 Temenos. All rights reserved. |