Instrumenting an Android Application

This article shows how to manually implement Webtrends data collection methods.

Use the following steps to call Webtrends data collection methods directly, in addition to, or instead of, using automatic tracking. For examples, see "Instrumentation Examples for Android," below.

1. In each .java file where you will call a method, include the statements:

import com.webtrends.mobile.analytics;

2. Call event methods of your choice inside application events such as onCreate or onClick:

   WTDataCollector.getInstance().onScreenView(eventPath, eventDesc, eventType, customData, contentGroup);

   The values you specify for eventPath, eventDesc, eventType, customData, and contentGroup provide data that can be accessed in Webtrends reporting. Note that the minimal suggested data for these event methods is an eventPath such as /MyApplication/Settings/Save_Credentials_Screen, an eventDesc such as Restaurant Details Screen and aneventType such as view or click. Some methods require additional data such as a product SKU or a conversion event name.

3. If you want to pass custom data specific to your application, or if you want to pass additional Webtrends-specific data, use the customParams argument. The customParams argument is a Map object with string-type key/value pairs that you create and populate before calling an event method. All event methods have the option to pass data using the customParams argument. For example, you could use the following code to pass information about an advertising click:

   import java.util.*;
   Map <String, String> customData = new HashMap<String, String>();
   customData.put("custom", "data");
   customData.put("WT.ad", "advertisement");
   WTDataCollector.getInstance().onScreenView(eventPath, eventDesc, eventType, customData, contentGroup);
   
   

4. The library validates the format of values passed as event method arguments. If a value is malformed, an IllegalWebtrendsParameterValueException is generated. To handle the exception, you must enclose your event method calls in a try statement as shown here:

   Map <String, String> customData = new HashMap<String, String>();
   customData.put("custom", "data");
   customData.put("WT.ad", "advertisement");
   try {
       WTDataCollector.getInstance().onScreenView(eventPath, eventDesc, eventType, customData, contentGroup);
   } catch (IllegalWebtrendsParameterValueException e) {
       // Handle and/or log the error
   }
   

Instrumentation Examples for Android

Examples of instrumentation for an Android application:

Calling from OnCreate

public void onCreate(Bundle savedInstanceState) {
    WTDataCollector.getInstance().onActivityStart(this.getClass().getSimpleName(), null);
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
}

Calling from OnPause

 private void onPause() {
         WTDataCollector.getInstance().onActivityPause(this.getClass().getSimpleName(), null);
             super.onPause();
 }