—Rate this article—
 

Add monitoring to your Android application

Deprecated

Mobile Analytics is now App Monitoring and content about Mobile Analytics is deprecated. For documentation related to these features, please see App Monitoring content, such as:

 

For information on migrating to App Monitoring, see Migrating from Mobile Analytics to App Monitoring.

Here's how to integrate Mobile Analytics monitoring and configuration functionality into your Android application. 

Step 1: Sign in to Apigee Mobile Analytics

Sign in or create a new account if you do not already have one.

Step 2: Add a new app

Click Add New App and give your app a name. Click Save. Mobile Analytics will generate unique identification keys for your application. The keys are: App Id, Consumer Key, and Secret Key . You'll need to use them when you initialize the SDK

Step 3: Download the Android SDK

Download and unzip the Mobile Analytics Android SDK. The client code is distributed as a binary library. 

Step 4: Add JAR files to the classpath

Add the instaops-android-<version_number>.jar file to your class path.

For Android 4.0 (or later) projects: Copy the jar file into the libs folder in your project.

For Android 3.0 (or earlier) projects: Perform the following steps in Eclipse for the instaops-android-<version_number>.jar file:

  • Select your application's project.
  • Select File > Properties.
  • Select Java Build Path
  • Click the Add External JARs button in the Java Build Path page.
  • Browse to the instaops-android-<version_number>.jar file, and click the Open button

If you use the Ant tool to build your application, copy the instaops-android-<version_number>.jar file to the libs folder in your application.

Step 5: Order the JAR files to the top of the classpath

Order the instaops-android-<version_number>.jar  at the top of the class path.

For Android 4.0 (or later) projects: You can skip this step because Android will automatically order the JAR files properly.

For Android 3.0 (or earlier) projects: Perform the following steps in Eclipse:

  • Select your application's project.
  • Select File > Properties.
  • Select Java Build Path
  • Select the “Order and Export” tab
  • IMPORTANT: Select checkboxes for  instaops-android-<version_number>.jar, and click the “Top” button

Step 6: Import and Initialize Mobile Analytics

Import the MA class from the downloaded Android client by adding the following code to your main activity. Your main activity is identified in your applications's AndroidManifest.xml file.

import com.instaops.android.MA;

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  boolean crashReportingEnabled = true;
  MA.initialize("<app_id>", "<consumer_key>","<secret_key>",this,crashReportingEnabled);
  ...
}

Replace <app_id>, <consumer_key>, <secret_key> with the app ID access key, and secret key for your application. You can find these values in the Mobile Analytics Portal by navigating to Configure > App Description.

If you would like to disable our crash reporting functionality (if you're using another framework for this), just pass false for the corresponding argument of the initialize method.

Note: You need to import and initialize Mobile Analytics and any Android service that your application uses. An Android service is an application component that can perform long-running operations in the background and does not provide a user interface.

Step 7: Add permissions

Add the following Internet permissions to your application's AndroidManifest.xml file (unless they have already been added). Note that with the exception of INTERNET, enabling all other permissions is optional.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE"/> 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />  
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Step 8: Integrate log monitoring into your app

To enable remote logging, replace android.util.Log with com.instaops.android.Log. Apigee's logger preserves the Android Logging API, so you should not need to modify any of your existing code.  For example:

Change your package imports from:

import android.util.Log;

To:

import com.instaops.android.Log;

Examples of logging statements:

Log.i("MY_TAG", "this is an informational message");
Log.e("MY_TAG", "this is an error-level message");

Step 9: Build and Test your app

Congratulations. Run your app and you should be able to see new session data appear in 2-3 minutes.

(Optional) Integrate network monitoring into your app

To enable network monitoring, replace references to the Android HTTP Client with the Mobile Analytics HTTP Client. For example:

Change:

HttpClient client = new DefaultHttpClient()

To:

HttpClient client = MANet.getHttpClient();

Alternatively, you can wrap an existing HTTP client. This approach is useful if you have a custom HTTP client, or if you need to initialize an HTTP client in a special way. You can wrap an HTTP client like this:

HttpClient wrappedHTTPClient = MANet.wrap(originalClient);

If you're using HttpURLConnection, change:

java.net.URL url = new java.net.URL(uri);

To:

com.instaops.android.URLWrapper url = MANet.urlForUri(uri);

Our URLWrapper class provides the same interface as java.net.URL, so you can use it as though it were a normal URL object (e.g., call openConnection on it).

If you're using a WebView, simply set our custom class for the client:

webView.setWebViewClient(new com.instaops.android.InstaOpsWebViewClient(this));

This call would be made in your onActivityCreated method (Fragment) or your onCreate method (Activity).

(Optional) Enable application-specific configuration

To enable an application-specific configuration for a parameter, add the following code. This allows Mobile Analytics to retrieve the parameter:

String value = MAConfig.getValue("<category>", "<key>");

Replace <category> and <key> with the category and key value for the parameter.

(Optional) Refresh configuration parameters while app is running

If you'd like to refresh (re-read) your configuration parameters after your application has already been initialized and is running, you may request the refresh as follows:

if (MA.refreshConfiguration(null)) {
    Log.i("MY_TAG","configuration refresh requested");
} else {
    Log.i("MY_TAG","unable to refresh configuration");
}

This method call (refreshConfiguration) is asynchronous.  If you'd like to know when the re-read of the configuration has completed, pass a non-null value for the method argument.  The argument is an interface (com.instaops.android.ConfigurationReloadedListener) whose interface is:

public interface ConfigurationReloadedListener {
    public void configurationReloaded();
}

Please note that if you specify a non-null value for the listener interface, the callback method (configurationReloaded) will be called on a background (non-UI) thread.

(Optional) Get the Apigee Device ID

To send application specific configurations to particular devices, you many need a way to display the Apigee Device ID to your beta testers. (We suggest displaying this ID in a help activity or a About activity). For example, to set the device ID in a text field, use the following code:

TextView device_id = (TextView) findViewById(R.id.about_fifth_line);
  try {
    device_id.setText(MA.getApigeeDeviceId());
  } catch (Exception e) {
  }

 

Troubleshooting

Q: Everything compiles, but my app is crashing. What's going on?

A: It's likely that your app's JAR files are not ordered properly. Make sure you follow Step 5 again.

Q: I'm getting duplicate classes exceptions when running my app. What's going on?

A: It's likely that your app depends on a library that is already included in our Android SDK. You will need to remove those libraries manually from the Android SDK. This is tricky, so feel free to contact Apigee Support, and we'll guide you through this process.

Q: I don't use HTTP Client for my network connections. What do I do?

A: We will support other popular networking packages over time (such as, java.net.URL). Let us know in the forum what you want, and we'll let you know when we will be supporting that network library. We will also be open sourcing the client soon, so you can write your own wrapper for your favorite network library.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)