Android Developer Tutorial

This tutorial describes the process of embedding the Apphance client library within any Android application. 

Download the Apphance jar

Embedding Apphance

Embedding Apphance consists of the following steps:
  1. Add Apphance JAR to build path of your Android project
  2. Modify the AndroidManifest.xml file (see below)
  3. Invoke Apphance.startNewSession() method from your application's code

1. Adding Apphance to build path

Let's assume that you have put it into libs/ sub directory of your project tree. You can then include it in your Java build in one of the following ways:
  1. Edit your .classpath file directly and adding the following <classpathentry> tag inside the <classpath> element:

    <classpathentry kind="lib" path="libs/apphance.jar"/>

  2. Via Eclipse's Project Properties (Alt+Enter or using context menu). There, in the Java Build Path section you can find the Libraries tab. Click on Add JAR button there and find apphance.jar in directories' tree.
Please note that due to the way ADT finds and includes libraries in the APK file, your library folder must be named libs. Breaking this convention might cause NoClassDefFoundErro errors.
 
Your project should have Apphance JAR in Referenced Libraries and in .classpath, as shown in examples below.


<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path="src"/>
<classpathentry kind="src" path="gen"/>
<classpathentry kind="con" path="com.android.ide.eclipse.adt.ANDROID_FRAMEWORK"/>
<classpathentry kind="lib" path="libs/apphance.jar"/>
<classpathentry kind="output" path="bin"/>
</classpath>

2. Modifying the manifest file

Apphance requires some modifications to the AndroidManifest.xml file of your application. This is necessary to display the Apphance-specific activities (e.g. the problem report activity) and to collect device condition information.

Declaring activities

In order for Apphance to display its activities, the following markup must be added withing the <application> tag in your manifest file:

<activity android:name="com.apphance.android.ui.LoginActivity" android:configChanges="orientation"
android:launchMode="singleInstance" />

<activity android:name="com.apphance.android.ui.ProblemActivity" android:configChanges="orientation" android:launchMode="singleInstance" />

Adding required permissions  (see http://developer.android.com/guide/topics/security/security.html)

Apphance needs the INTERNET and READ_PHONE_STATE permissions. The latter is needed for obtaining the device ID (such as IMEI) which is used by the server to identify each device uniquely.

Thus the required permissions are as follows:

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

Additional permissions

In order to access and monitor device conditions, additional permissions are required. If you want to be provided with additional debugging information - besides your own application's logs then the following permissions can be added:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

The above permissions allow Apphance to obtain detailed information about connectivity services present on the device, including network interfaces supported, type of network connection used (Wi-Fi or 3G), Wi-Fi information such as singal strength, and more.

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<uses-permission android:name="android.permission.BLUETOOTH" />
  • ACCESS_COARSE_LOCATION - allows Apphance to report location information based on coarse providers such as mobile network cell ID.
  • ACCESS_FINE_LOCATION - allows Apphance to report location information based on precise providers such as GPS.
  • BLUETOOTH - allows Apphance to report information about Bluetooth interface, including its state (on/off) and pair/unpair events.

3. Starting an Apphance session

Your application is identified by the Application Key (available in Application > Settings) section in web panel. This key must be provided to Apphance.startNewSession() method invoked in onCreate event of your main activity:

package com.apphance.example;

import com.apphance.android.Apphance;
import android.app.Activity;
import android.os.Bundle;

public class HelloApphanceProject extends Activity {

    public static final String APP_KEY = "a1b2c3d4e5f6g7h8i9j10k11l12m13n14";

    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {

        super.onCreate(savedInstanceState);
        Apphance.startNewSession(this, APP_KEY [, APPHANCE_MODE]);
        setContentView(R.layout.main);
    }
}

  • Context - Context object. It can be either the activity (this) or an application context obtained via getApplicationContext().
  • APP_KEY  -  String containing the application key - available in the Apphance panel (after registering your app in Apphance you will receive it). Alternatively, rather then putting the Apphance Application key directly into your code, you can pass an identifier of string resource containing the key Apphance.startNewSession(this, R.string.apphance_app_key);
  • APPHANCE_MODE - (OptionalDefines the logging mode for Apphance, for now following ones are supported:
    • Apphance.Mode.QA QA mode in which testers can manually report problems while testing the application. Using this mode will make the Apphance Client Library present a log in form upon startup.  
    • Apphance.Mode.Silent - Silent mode switches Apphance to silently work in the background. User log in form is not presented, additionaly this mode does not allow for manual problem reporting.

Logging to Apphance

Apphance comes with it's own logger com.apphance.android.Log. This class is designed to mimic the standard android.util.Log and has the same interface, including Log.v, Log.d, Log.i, Log.w and Log.e methods.

The easiest way to have all your logs go through Apphance is to replace the import statement:

import android.util.Log;

with

import com.apphance.android.Log;

Note that while your logs will be sent to Apphance, they will be still outputed to Android logcat.

An alternative is to use the Apphance.log method along with constants defined in Apphance class (corresponding to the level of log message). This would ensure that logs are sent only to Apphance and are not outputed to standard Android logcat.

Troubleshooting

If you encounter problems while using Apphance along with ProGuard, you should configure the latter to always keep Apphance classes in generated .apk files. To do that, add the following to your proguard.cfg configuration file:

-keep class com.apphance.android.**
Č
ċ
Piotr Duda,
Mar 8, 2012, 6:51 AM
ċ
apphanceandroid1.6.jar
(453k)
Piotr Duda,
Jun 13, 2012, 5:38 AM
Comments