Create an Android Launcher
When running Tabris on Android you have two options to get started. The simplest way is to install the tabris.apk from the Tabris SDK directly onto your device. If you want to have more control over the title, launcher icon, etc., you can use the second approach and build the Tabris client yourself. This guide will help you to get started with your own Tabris build on Android.
Install the Android SDK
In order to create a customized version of the Tabris Android client, we need to install the Android SDK. The Android SDK contains the SDK Manager from which we will install the following components:
- Tools/Android SDK Tools (
- Tools/Android SDK Platform-tools (
- Tools/Android SDK Build-tools (
- Extras/Android Support Repository (
- Extras/Google Repository (
at least 6.5.87)
Build the Tabris Android Client
Inside the Tabris SDK we find the folder
tabris-sdk/android. It contains the the following directory structure:
.repository tabris-android-launcher tabris-android-xxx.apk
To build our own Tabris launcher we will make use of the content in the
tabris-android-launcher folder. Inside
tabris-android-launcher invoke the command
The command will download all required dependencies and build our Tabris Android app. The build output can be found in the folder
tabris-android-launcher/build/apk/. Congratulations! You have build your own Tabris client.
Customize the Tabris Android Client
Several features of the Tabris Android client can be customized:
In the file
tabris-android-launcher/build.gradle update the line
buildConfigField "String", "DEFAULT_URL", "\"http://tabris.eclipsesource.com/2.x/\""
with your own server url. Make sure to keep the quotation and escape characters.
In the file
tabris-android-launcher/src/main/res/values/strings.xml change the
Update the files
tabris-android-launcher/src/main/res/drawables-<xxx>/ic_launcher.png to your app icon. Make sure to use the correct sizes for your icons. If you only have one size delete to the other files.
The Tabris Android client comes with three different base themes: “light”, “light with dark action bar” and “dark”. To choose your default theme update the file
tabris-android-launcher/src/main/AndroidManifest.xml. Set the
manifest/application/@theme attribute to
Sign the Tabris Android App
To submit an Android app into an app store like Google Play, the app has to be signed with a release key. To create a private key we use the
keytool application contained in the Java JDK:
$ keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000
For more detailed information please see http://developer.android.com/tools/publishing/app-signing.html#cert.
We can now pass the signing details to our Tabris Android client build. Create a file
tabris-android-launcher/sign.properties with the following details:
storeFile=<absolute/path/to/keystore.file> storePassword=<storePassword> keyAlias=<keyAlias> keyPassword=<keyPassword>
When building on Windows make sure to use double backslashes for path seperators. Eg.:
To build a signed Android apk we simply run
gradlew build again. The signed apk file has the postfix
-release.apk in the folder
Configure Behavior of the Tabris Client
The Tabris Android client is represented by the
TabrisActivity. When creating a custom launcher for the Tabris Android client, all connection parameters are passed to the
TabrisActivity via the
Intent extra parameters.
You can configure those parameters from the
build.gradle file of the launcher project. See the
LauncherActivity class in the launcher project of the Tabris SDK for more details.
The following configuration parameters are available:
|endPoint||String||The remote Tabris server URL to connect to.|
|theme||int||The base theme to use for the Tabris client. The following themes are currently available:
|networkProgressIndicatorType||String||How to visualize an ongoing network request. Possible values are:
|networkProgressIndicatorShowDelay||int||Specifies the amount of time (in ms) until the network progress indicator is shown.|
|networkProgressIndicatorHideDelay||int||Specifies the amount of time (in ms) until the network progress indicator dialog is hidden after is has been shown.|
|networkConnectionTimeout||int||Specifies the amount of time (in ms) until a connection to the remote server has to be established.|
|networkReadTimeout||int||Specifies the amount of time (in ms) until the response from the server has to be received.|
|networkNumberOfRetries||int||Specifies the number of retry attempts after a request has failed.|
|requiredServerId||String||Specifies the server id to be matched. If the server id and this id do not match the client won't connect. Having no id on either side runnes the client normally.|
|gcmSenderId||String||The Google Cloud Messaging id associated with your app.|
|strictSSL||boolean||Wheter to validate the SSL certificate when connecting to a server with an unsigned certificate. True by default.|
To simplify the usage of these parameters, the TabrisActivity class provides predefined constants. The following example show how to launch the TabrisActivity with custom parameters:
Intent intent = new Intent( this, TabrisActivity.class ); intent.putExtra( TabrisActivity.EXTRA_END_POINT, "http://server.com/app" ); intent.putExtra( TabrisActivity.EXTRA_THEME, 1 ); intent.putExtra( TabrisActivity.EXTRA_NETWORK_PROGRESS_INDICATOR_STYLE, "topBar" ); intent.putExtra( TabrisActivity.EXTRA_NETWORK_PROGRESS_INDICATOR_SHOW_DELAY, 1500 ); intent.putExtra( TabrisActivity.EXTRA_NETWORK_PROGRESS_INDICATOR_HIDE_DELAY, 1500 ); intent.putExtra( TabrisActivity.EXTRA_NETWORK_CONNECTION_TIMEOUT, 10000 ); intent.putExtra( TabrisActivity.EXTRA_NETWORK_READ_TIMEOUT, 10000 ); intent.putExtra( TabrisActivity.EXTRA_NETWORK_NUMBER_OF_RETRIES, 3 ); intent.putExtra( TabrisActivity.EXTRA_REQUIRED_SERVER_ID, "someServerId" ); intent.putExtra( TabrisActivity.EXTRA_STRICT_SSL, false ); intent.putExtra( TabrisActivity.GCM_SENDER_ID, "gcmSenderIdOfYourApp" ); ... startActivityForResult( intent, 0 );