Branding Agentry Clients for Android

Prerequisites

The following items must be addressed prior to performing this procedure:

Review the information provided related to this procedure and the Agentry Client branding SDK for Android clients; especially the information found in the sections “Android Client Branding Image Specifications” and “Command Line Arguments for aapt Explained.”
It is recommended that the icons to be used as replacement for those provided by default already exist and ready for inclusion in the packaging specified in this procedure.
The default package name for the Agentry Client is set to com.syclo.agentry.client.android. This package name is changed during this process to a package name you will enter. This name should be determined ahead of time.
The following determinations should be made prior to beginning:
- Whether or not push functionality is to be implemented and, if so, whether or not it is desired to use Google Cloud Messaging to support notifications for missed pushes. If this is to be a part of the implementation, follow the instructions provided at the following URL to register your application to obtain both a Product ID and a Simple API Key this should be performed before performing the branding procedure.
```
http://developer.android.com/google/gcm/gs.html
```
- Whether or not localization/translation is a part of the implementation.

Task

This procedure describes the steps necessary to change the default SAP and Agentry branding of the Agentry Client for Android devices. To perform this procedure you must have downloaded the ZIP archive Agentry_6.1.x.x_Client-Android_Branding.zip containing the branding resources from the SAP Service Marketplace.

The steps in this procedure include environment setup, file and resource modification, and other similar tasks. The result of this procedure is an Agentry Client for Android (.apk file) with all branded components replaced with the desired name and icons which can then be installed to Android devices.

As options to this process, the client application may be registered with Google Cloud Message to support missed push notifications on the device, and also translated default display strings.

Install the Java SDK (“JDK”) version 1.6, latest patch release. Note the installation location’s full path. DO NOT install version 1.7 of this SDK, as it is not supported by the Android SDK.
Create an Environment Variable for Windows named JAVA_HOME and set the path to the installation folder of the JDK from the previous step.
Download and install API level 15 of the Android SDK. To download the SDK, click click here; or enter the following URL in a web browser: http://developer.android.com/sdk/index.html. Note the installation location’s full path. Alternately, if this SDK is already installed, but is not the latest version, update it to the latest version of the Android SDK.
Within the Windows Environment Variables the installation location of the Android SDK must be set in two different variables:
1. Edit the existing Path variable by adding the full path of the Android SDK installation location.
2. Create a new Environment Variable named ANDROID_SDK_ROOT and set its value to the installation location of the Android SDK
Install the Ant build utility. For instructions on installing this utility, click here; or, enter the following URL into your web browser: http://dita-ot.sourceforge.net/doc/ot-userguide13/xhtml/installing/windows_installingant.html
Install the Cygwin tool, which provides Linux commands to the Windows environment. This tool is needed to use the Android Branding SDK in Windows. It can be downloaded and installed by clicking here; or by entering the following URL into your web browser: http://www.cygwin.com. During the installation process, verify the packages bash, ls, grep, awk, and sed are included. Typically these are selected by default in the installer.
Create a folder named C:\ag-android-branding, or similar, and extract the contents of the Agentry_6.1.x.x_Client-Android_Branding.zip archive (where x.x represents the latest service pack or patch release) provided with the SAP Mobile SDK to this location.
CONDITIONAL: If it is desired to use Google Cloud Messaging (GCM) for missed push notifications, and if you have obtained both a Product ID and Simple API Key from GCM: If you are not using this service for missed push notifications, or if push functionality is not part of your implementation, skip to the next step in the procedure.
1. Open the file found at C:\ag-android-branding\assets\AgentryClient.properties in a text editor. Here, set the value of the setting gcm_product_id to your GCM Product ID. Save and close the file when complete.
2. Either now or at some point during the remaining implementation tasks for your environment, the API Key must be configured within the Agentry Server, in the Configuration section of properties accessible in the SAP Control Center, in the setting gcmServerAuthenticationKey.
If you do not have a GCM Product ID and Simple API Key, see the URL provided in the prerequisites to this procedure.
CONDITIONAL: By default the Agentry Client’s screen orientation will rotate with orientation of the device, as is standard behavior. If it is a requirement for your implementation to lock the screen orientation, open the file found at C:\ag-android-branding\assets\AgentryClient.properties. Within this file add one or more of the following settings and values, based on your implementation requirements. If the standard screen orientation behavior is required, skip to the next step in this procedure.
- screen_orientation_phone=LANDSCAPE | REVERSE_LANDSCAPE | PORTRAIT | REVERSE_PORTRAIT
- screen_orientation_tablet=LANDSCAPE | REVERSE_LANDSCAPE | PORTRAIT | REVERSE_PORTRAIT
For these options, screen_oreientation_phone specifies the setting for Android phones and screen_orientation_tablet specifies the setting for Android tablets. The available settings are:
- LANDSCAPE - Lock the orientation in landscape
- REVERSE_LANDSCAPE - Lock the orientation in reverse landscape.
- PORTRAIT - Lock the orientation in portrait.
- REVERSE_PORTRAIT - Lock the orientation in reverse portrait.
Replace the images branding found in the following folders and leave others as is:

Refer to the information provided in the section “Android Client Branding Image Specifications” for details on the properties of the images found in these locations.
- C:\ag-android-branding\bin\res\drawable-hdpi
- C:\ag-android-branding\bin\res\drawable-ldpi
- C:\ag-android-branding\bin\res\drawable-mdpi
To modify the strings displayed in the client at run time to match your branding requirements, open the XML file located at C:\ag-android-branding\res\values\strings.xml. Search for and replace the text value Agentry with the desired name for the mobile client. Save and close the file when finished.
To modify the application full and short names, open the XML file located at C:\ag-android-branding\res\values\manifest_strings.xml. Here modify the contents of the two elements, which contain the text “Agentry Client” and “Agentry” for the application name and application short name, to match your branding requirements. Save and close the file when complete.
CONDITIONAL: For localization or translation requirements, manifest_strings.xml files found in each of the language-specific folders of the languages to be supported must be edited. The folders at res\value-xx, where xx is the language code for the desired language, contains the file to be modified. Additionally, the strings.xml file must be modified to If supporting only English, these additional files need not be modified. Skip to the next step in this procedure.
Within the Cygwin tool, change directories to the location where the Agentry Android Branding SDK was extracted, e.g., C:\ag-android-branding. All commands run from this point on in this procedure must be run from this location.
Execute the following command to begin packaging the Agentry Client for Android, substituting the <tokens> below with the values required for your environment (See section “Command Line Arguments for aapt Explained” for details):
```
$ANDROID_SDK_ROOT/platform-tools/aapt package --no-crunch -f --auto-add-overlay
```
```
	--version-code <version_code>
```
```
	--version-name <version_name>
```
```
	--rename-manifest-package <pkg_name> 
```
```
-M AndroidManifest.xml 
```
```
-S bin/res 
```
```
-S res <res_includes> 
```
```
-A assets 
```
```
-I $ANDROID_SDK_ROOT/platforms/<target>/android.jar 
```
```
-F bin/AgentryAndroidClient.ap_ --generate-dependencies
```
The above is a single command line string. It is displayed on multiple lines here for clearer presentation. It should be entered on a single line when actually executed in your environment.
Next run the package.xml Ant script using the following command:
```
$ANT_HOME/bin/ant -f package.xml
```
Copy and rename the unsigned Agentry Client for Android form the bin directory to the current base directory of the branding SDK with the following command:
```
cp bin/AgentryAndroidClient-release-unsigned.apk ./AgentryAndroidClient.apk
```
Create a keystore and password using the keytool Java utility by running the following command. Replace the <myAlias> token with a value unique value, which should be noted as it will be needed in the next step of this procedure:
```
$JAVA_HOME/bin/keytool -genkey -keystore gen.keystore 
```
```
-alias <myAlias> keyalg RSA -keysize 2048 -validity 10000
```
The above is a single command line string. It is displayed on multiple lines here for clearer presentation. It should be entered on a single line when actually executed in your environment.

After running the above command you will be prompted for passwords for the keystore and key, as well as other information. Note the values you enter as they will be used in the next step.
Now sign the Agentry Client .apk file using the Java tool jarsigner by entering the following command. The <myAlias>, <store_password>, and <key_pasword> tokens should be replaced with the values entered in the previous step:
```
$JAVA_HOME/bin/jarsigner -keystore gen.keystore 
```
```
-storepass <store_password> 
```
```
-keypass <key_password> 
```
```
AgentryAndroidClient.apk 
```
```
<myAlias>
```
The above is a single command line string. It is displayed on multiple lines here for clearer presentation. It should be entered on a single line when actually executed in your environment.
Align the Agentry Client .apk file using the following command. Note that the output of this command is the branded, signed, and aligned Agentry Client .apk file, named according to the <client_file> token in the following command, which can be installed to the Android client devices in your implementation environment.
```
$ANDROID_SDK_ROOT/tools/zipalign AgentryAndroidClient.apk <client_file>.apk
```

With the completion of this task you should now have an .apk file that is the Agentry Client for Android branded for your needs. This file can be installed to and run on an Android device.

Next

The newly branded client should be installed to an Android device (or devices) for testing. The device or devices should be representative of the devices to be used in the runtime environment of your implementation.