Customizing Your Android Application (Magic xpa 3.x)

To see a video demonstration about customizing and deploying your Android application, click here.

To compile the code, you need to install the JDK and SDK as defined in the Android prerequisites section.

You can customize the application and compile it automatically using Magic xpa’s Rich Client Deployment Builder or you can do it manually as described below. Since version: 2.3

The source code for the Android application is located at: %EngineDir%\RIAModules\Android\Source.

You can change the characteristics of the application in the settings.properties file as follows:

• sdk.dir – The directory in which the Android SDK is installed. When you use a backslash (\), you need to double it: \\.

• target – The Android version that the compilation is done for. Note that the version should be installed on your PC. You can see the installed versions using the Android SDK manager or by browsing to the android-sdk\platforms folder. Refer to the Compatibility Guide for the minimum value that you can use. Note that this value is only for compilation. The application will run on older Android versions (as defined in the Compatibility Guide).Note that the value set in this property is case sensitive.

• client.title – The application title as visible to the user.

• client.version.code – An integer value that represents the version of the application code, relative to other versions.

• client.version.name – A string value that represents the release version of the application code, as it should be shown to users.

• package.name – The identifier of the project. The package name must be in lower case and unique across all packages installed on the Android system. If you use upper case letters, the build script will convert them to lower case. The package name cannot include numbers and some reserved words such as ‘new’.

• key.store, key.alias, key.store.password, key.alias.password – The properties of the keystore.

• output.dir – The folder that will contain the built installers.

• build.dir – A temporary folder location used during the build process. This folder is removed after a successful build. It can be an absolute or relative path.

You can change the following files as well:

• Icon – Replace the icons’ files in the res\drawable-XXX folders. The names of the image files need to remain the same.

o You need to provide icon files in all of the following sizes: 36x36, 48x48 and 72x72 pixels.

• Startup screen logo – Replace the logo.png files located in the res\drawable-XXX folders. The names of the image files need to remain the same.

• You need to provide logo files in different sizes corresponding to the device’s size.
  

• Execution properties – Open the execution.properties file and change the execution values.

o You need to define either the execution properties’ values or a URL referring to a file containing the execution properties’ values as defined above.

o Leaving the URL property empty means that a dialog box will be opened and the end user will need to write the URL.

This is useful when having a generic application where different customers can log in to different servers.

After specifying the URL in the dialog box, you can change the URL value in the Android device’s built-in Accounts screen. Note that the account detail screen also shows syncing capabilities. These capabilities are not supported and will not affect the application.

Resources, such as images, can be packaged as part of the APK / IPA. Refer to: Packaging Resource Files.

After performing the desired changes, you need to compile the application and sign it.

Follow these steps to compile and sign your custom application:

1. Create a keystore file.

To sign your APK file, you first need to create a keystore with your own keys and certificates. (This only needs to be done once.)

A test keystore is provided in the installation, so for testing purposes you can skip this stage and use the test keystore. For deployment it is recommended to create your own keystore.

To create a keystore, we will use the keytool application installed with the Java SDK.

Run the following command and follow the instructions and finalize the creation of your keystore: keytool -genkeypair -keystore my.keystore -alias mykey -validity 8000

2. Create a signed APK file.

The compilation of the Android project is done using the Gradle tool.

• Navigate to the application source folder: %EngineDir%\RIAModules\Android\Source.

• Run the following file: build.cmd.

The build process creates an APK file named myapp.apk inside the project’s %EngineDir%\RIAModules\Android\Source\Output directory.

Note:

• You must have internet access (at least on the first build) in order to download all of the Gradle components.

• If a proxy needs to be used, define it in the gradle.properties file as defined at: https://docs.gradle.org/current/userguide/build_environment.html#sec:accessing_the_web_via_a_proxy.

• You need to install the Android Support Repository, Google Play Services and Google Repository components from the Extras folder in the Android SDK Manager.

• To troubleshoot the build process, you can run the build.cmd file. In the output folder that you chose (in the Rich Client Deployment Builder's Deployment files folder property) there's a folder called Android\source and you can run the build process manually from this folder by opening a command prompt and running the build.cmd file. You can then see any errors that occurred when trying to build the Android client.

• When you have an application name in a non-English language:

• 1. The package name must still be in English.

  2. The encoding in the build.xml file should be changed according to your language. For example, for a Chinese application name, use "gb2312".

  3. After the build, there will still be a failure copying the file from the build folder to the new name (with Chinese characters). Therefore, you need to manually copy the file or change the build.xml so that it copies the file into a generic English name file.

That’s it; you can now take the Dev-release.apk file and install your application on your mobile device as detailed above.

For more information, you can refer to: http://developer.android.com/guide/publishing/preparing.html.

Defining the Application Permissions

By default, the Android application requires permissions for different actions, such as sending a text message and making phone calls.

These permissions are defined by default since these capabilities are provided by the built-in Magic xpa functionality.

You can, however, disable them by opening the AndroidManifest.xml file (located at RIAModules\Android\Source\app\src\main) using a text editor and adding tools:node="remove" to the not-required permission.

For example, to remove the SEND_SMS permission, change the line to:

<uses-permission android:name="android.permission.SEND_SMS" tools:node="remove" />

Note:

• Commenting or removing the permission line from the manifest file will not remove the permission, since this permission is also defined in the Magic xpa core library.

• You can check which permissions are required in your APK by running the following DOS command: aapt d permissions "MyApp.apk". The aapt.exe is a utility available in the android-sdk\build-tools\xxx\ folder.