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 (latest version)
  • Tools/Android SDK Platform-tools (latest version)
  • Tools/Android SDK Build-tools (21.1.2)
  • Extras/Android Support Repository (latest version)
  • Extras/Google Repository (at least 6.5.87)

Install Eclipse and Android SDK

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

./gradlew build

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:

Default URL

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.

App title

In the file tabris-android-launcher/src/main/res/values/strings.xml change the app_name value.

App icon

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.

Default theme

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

  • @style/Theme.Holo.Light.Tabris
  • @style/Theme.Holo.Light.Tabris.DarkActionBar
  • @style/Theme.Holo.Tabris

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.: c:\\path\\to\\keystore.file

To build a signed Android apk we simply run gradlew build again. The signed apk file has the postfix -release.apk in the folder build/outputs/apk/.

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:

Parameter

Type

Description

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:
  • 0 - default theme as configured in AndroidManifest.xml
  • 1 - Android holo light
  • 2 - Android holo light with dark ActionBar
  • 3 - Android holo
networkProgressIndicatorType String How to visualize an ongoing network request. Possible values are:
  • topBar (default) - A bar sliding in from the top
  • fullscreen - An overlay covering the entire ui which also blocks touch input
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 );