Customizing Your Android Application (Magic xpa 4.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.
-
httpLibrary - The http library identifier. The valid values are: native and okhttp.
The value native is deprecated. Since version: 3.3e
You can change the following files as well:
o You need to provide icon files in all of the following sizes: 36x36, 48x48 and 72x72 pixels.
o You need to provide logo files in different sizes corresponding to the device’s size.
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.
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:
-
-
The package name must still be in English.
-
The encoding in the build.xml file should be changed according to your language. For example, for a Chinese application name, use "gb2312".
-
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.
The custom-defined variables remain specific to the Android client you created.
The okhttp library is an easy to use open source library introduced for http communication of Android client. It supports stability during common network connection problems.
When the entry httpLibrary=okhttp is present, Android client uses okhttp library for all http communication.
Since version: 3.3c
Sending the Custom Header and Custom URL Parameter from Android Client
Follow the given steps to add a custom header and URL parameter for each HTTP request from Android client:
|
Import android.app.NotificationManager;
import android.content.Context;
import android.os.Bundle;
import android.accounts.Account;
import android.accounts.AccountManager;
public class MainActivity extends SplashScreenActivity {
static String intentArgs;
@Override
public int getExecutionPropertiesResource() {
return R.raw.execution;
}
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
/* Uncomment following lines to be able to add custom header and custom url parameter to the request */
// CoreApplication.getInstance().addCustomHeaderToRequest("customheader1", "customvalue1"); // Adding custom header and value to the request
// CoreApplication.getInstance().addCustomURLParameter("customparamname1", "customparamvalue1"); // Adding custom URL params
|
Note: The custom-defined variables remain specific to the Android client you created.
Implementing Authenticator with OKHTTP
The following steps explain the process of supporting OKHTTP authenticator for basic authentication set on IIS:
-
Open IIS.
-
Set basic authentication for the scripts alias.
-
Add a file which contains an Authenticator for OKHTTP in the wrapper project.
-
Open MainApplication.java and assign an object of this authenticator to CoreApplication.getInstance().g_okHttpAuthenticator in the constructor of MainApplication.java.
-
Before creating APK, open settings.properties and change the httpLibrary=okhttp. This enables Magic client to use OKHTTP library in runtime.
-
Create the APK as usual.
A sample Authenticator called MgAuthenticator example is as shown below:
|
package com.magicsoftware.magicdev;
import okhttp3.Authenticator;
import okhttp3.Credentials;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.Route;
public class MgAuthenticator implements Authenticator
{
@Override
public Request authenticate(Route route, Response response)
{
String credential = Credentials.basic("testusername",
"testpassword");
return response.request().newBuilder().header("Authorization", credential).build();
}
}
|
The corresponding MainApplication.java file looks like as given:
|
package com.magicsoftware.magicdev;
import java.util.Locale;
import com.google.firebase.iid.FirebaseInstanceId;
import com.magicsoftware.core.CoreApplication;
public class MainApplication extends CoreApplication {
public MainApplication()
{
super();
// set the authenticator for okhttp
**CoreApplication.getInstance().g_okHttpAuthenticator = new MgAuthenticator();**
}
}
|
Since version: 3.3d
