Customizing Your Android Application (Magic xpa 2.x)

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

To compile the code, you need to install the JDK and SDK as defined in the Android emulator 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.

• 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. The minimum value you can use is android-15. Note that although the minimum version is android-15 (meaning Android 4.0.3 ), the application will also run on Android 2.3.3 since the minimum SDK version is defined as android-10.

• 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.

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.

• 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 as follows:

o On Android – 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.

o On iOS – In the iOS device’s built-in Settings screen.

Note that if you compile the client using Xcode and not by running the build.sh command, then in order to see the application in the Settings screen, you need to do the following from Xcode:

From the File menu, select Add Files to “MagicApp”. In the opened dialog box, select the Settings.Bundle folder and click Add.

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 Ant tool. The Ant tool is located in the %EngineDir%\RIAModules\Utils\apache-ant-1.8.3 folder.

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

• Run the following file: build.cmd.

The build process creates an APK file named Dev-release.apk inside the project’s bin directory.

Note:

• You can edit the build.cmd file in order to troubleshoot the build process. For example, to see the full actions, remove the -q from the command in the build.cmd file and to save the log to a file, add -l build.log to the command in the build.cmd file.

• 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.