IBM Tealeaf CX Mobile Android Logging Framework Version 9 Release 0.1 December 4, IBM Tealeaf CX Mobile Android Logging Framework Guide

(1)

IBM Tealeaf CX Mobile Android Logging Framework

Version 9 Release 0.1

December 4, 2104

IBM Tealeaf CX Mobile Android Logging

Framework Guide

(2)

Note

Before using this information and the product it supports, read the information in âNoticesâ on page 155.

This edition applies to version 9, release 0, modification 1 of IBM Tealeaf CX Mobile Android Logging Framework and to all subsequent releases and modifications until otherwise indicated in new editions.

(3)

Chapter 2. Configuration file . . . 87

Log level settings . . . 87

Kill switch settings . . . 87

Local cache file settings . . . 88

Post settings . . . 88

Masking settings . . . 89

Filter message type setting . . . 90

Cookie settings . . . 90

Session timeout setting . . . 90

Screen shot settings. . . 90

Internal settings: do not change. . . 91

Chapter 3. Sample applications . . . . 93

Chapter 4. Guidelines . . . 95

Chapter 5. Reference

. . . 97

UICActivity class . . . 97 UICApplication class . . . 99 Tealeaf class . . . 100 TLDefaultHttpClient class . . . 110 TLHttpRequestInterceptor class . . . 111 TLHttpResponseInterceptor class . . . 112 UICWebView class. . . 113 UICWebChromeClient Class . . . 115 UICWebViewClient Class . . . 116

Chapter 6. Sample Code . . . 119

How to instrument TextView based controls . . . 119

How to instrument ExpandableListView based controls . . . 119

How to instrument SlidingDrawer based controls 120 How to mask controls . . . 120

Server-Side KillSwitch sampling function . . . . 120

Sampling Function for ASPX . . . 121

Sampling Function for JSP . . . 121

Sampling Function for PHP . . . 123

JSON message type schemas and examples . . . 124

Message header properties . . . 125

Message header properties schema . . . 125

Message header properties schema . . . 126

Client state (Type 1) messages . . . 127

ScreenView (Type 2) messages . . . 129

Connections (Type 3) messages . . . 131

Control (Type 4) messages . . . 132

Custom Event (Type 5) messages . . . 135

Exception (Type 6) messages . . . 136

Performance (Type 7) messages . . . 137

Web Storage (Type 8) messages . . . 138

Overstat Hover Event (Type 9) messages . . . 138

Layout (Type 10) messages . . . 139

Gesture (Type 11) messages. . . 141

DOM Capture (Type 12) messages . . . 146

Examples . . . 149

Chapter 7. Troubleshooting . . . 151

Debugging Tips . . . 151

Inclusion of raw request and response headers 151 Managing client-side issues. . . 151

Exceptions or crashes. . . 151

Power failures . . . 151

Kill switch . . . 152

Network issues . . . 152

(4)

Chapter 8. IBM Tealeaf documentation

and help

. . . 153

Notices . . . 155

Trademarks . . . 157

(5)

IBM Tealeaf CX Mobile Android Logging Framework Guide

The IBM Tealeaf CX Mobile Android Logging Framework for mobile native applications requires the IBM Tealeaf CX Mobile license for Mobile App. For more information, contact your IBM Tealeaf representative. Licensees must implement in their apps code that is provided by IBM Tealeaf. For more

information on downloading IBM Tealeaf, see IBMÂ®Passport AdvantageÂ®Online. TheIBM Tealeaf CX Mobile Android Logging Framework Guideprovides guidance on how to enable the capture of mobile application data directly from the application that is installed on the visitor's Android-enabled device.

Note: Whenever possible, use the latest version of the IBM Tealeaf CX Mobile Android Logging Framework software.

(6)

(7)

Chapter 1. Tealeaf installation and implementation in an

Android application

You add the TealeafÂ®SDK to your application so that the CX Mobile Android Logging Framework can capture user interface and application events. There are two ways to install the Tealeaf SDK in your Android application.

Supported Frameworks

The installation and implementation instructions in this guide apply to the step-based version of JSON messaging from this client framework.

The step-based version of JSON messaging from this client framework was introduced in Release 8.5.

For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of submitting data from the client frameworks, which resulted in submitted data being split into individual hits in the Windows pipeline.

In a future release, the hit-splitting method of processing data that is submitted from client frameworks is likely to be deprecated.

The installation and implementation instructions for the legacy version are similar but require additional configuration in the Windows pipeline.

Eclipse Tealeaf plug-in for Android development

The Eclipse Tealeaf plug-in installs the Tealeaf SDK into your Eclipse workspace and includes basic configuration. You download the plug-in and install the plug-in with the Eclipse Install new softwareoption. The plug-in installs custom widgets in your Eclipse workspace. These widgets can be used in any application in that workspace.

If you do not have a custom Application class in your application, the plug-in creates and extends one for you. If you create a custom Application class after you install the plug-in, you:

1. Create and extend your custom Application class

2. ModifyAndroidManifest.xmlfile to use your custom Application class

You manually configure properties, including application-specific URLs, and Android Activity class extension.

Tealeaf SDK for Android development

You manually install and configure the Tealeaf SDK. You download the Tealeaf package and you:

1. Move files to the proper locations in your application

2. Configure properties, including application-specific URLs

(8)

Client Framework versions supported in this documentation

The installation and implementation instructions in this guide apply to the step-based version of JSON messaging from this client framework.

The step-based version of JSON messaging from this client framework was introduced in Release 8.5.

For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of submitting data from the client frameworks, which resulted in submitted data being split into individual hits in the Windows pipeline.

Note: In a future release, the hit-splitting method of processing data that is submitted from client frameworks is likely to be deprecated.

The installation and implementation instructions for the legacy version are similar but require additional configuration in the Windows pipeline. For more

information about the earlier versions, including implementation steps, use the links that follow.

Install the Tealeaf SDK for Android development in your application

You add the Tealeaf SDK to your application so that the CX Mobile Android Logging Framework can capture user interface and application events. You manually install and configure the Tealeaf SDK in each application .

Tealeaf SDK for Android development

You manually install and configure the Tealeaf SDK. You download the Tealeaf installation package and you:

1. Move files to the proper locations in your application

2. Configure properties, including application-specific URLs

3. Extend Application and Activity classes

Tealeaf package contents

A single file contains the CX Mobile Android Logging Framework and its software components.

IBM Tealeaf CX Mobile Android Logging Framework is delivered in the IBM Tealeaf CX Mobile Android Logging Framework 8.8 - iOS Logging Framework for Windows within the IBM Passport Advantage Online.

The package contains the following software components.

v _KillSwitch_{. Code to implement the kill switch traffic manager for different}

server technologies. â ASPX:

- killswitch.aspx: Page with logic.

- web.config: Configuration file that is used by the page. â JSP:

- killswitch.jsp: Page with logic.

- config.properties: Configuration file that is used by the page. â PHP

(9)

- killswitch.php: Page with logic.

- config.ini: Configuration file that is used by the page.

v _{PipelineAgents}_{- JSON parser for Android logging framework} v _UICAndroid_:

â uicandroid.jar: Android library JAR file that contains the CX Mobile Android Logging Framework.

â TLFConfigurableItems.properties: Configuration file.

v _SampleCode_{: Contains the following versions of a sample Android application.}

â UICSP_Clean: An Android application without IBM Tealeaf CX Mobile Android Logging Framework integrated.

â UICSP_ManualLog: An Android application with IBM Tealeaf CX Mobile Android Logging Framework integrated

â UICSP_ManualLog_ServerSessionID: An Android application with IBM Tealeaf CX Mobile Android Logging Framework integrated by using a session ID provided from a web application.

See "Sample Code" in theIBM Tealeaf CX Mobile Android Logging Framework Guide.

v _{AndroidEclipsePlugin}_{- An Eclipse Plug-in to assist with Tealeaf Integration.}

â tealeaf.plugin.android.site-1.0.0-SNAPSHOT.zip The Plug-in archive to be added to your Eclipse IDE.

â tealeafandroidsdk.jar- Android Library JAR file that contains pre-instrumented Tealeaf widgets.

Tealeaf sample application

You deploy the sample application that is provided by IBM Tealeaf to test the capabilities and measure the effects of the CX Mobile Android Logging Framework.

Instead of integrating the CX Mobile Android Logging Framework with your application in development, you deploy the sample application and complete any necessary configuration steps on the remainder of this page to begin to capture mobile app data into your instance of IBM Tealeaf.

See Chapter 3, âSample applications,â on page 93.

Android development environment requirements

To develop Android applications with the Android SDK, follow these system and software requirements.

Minimum requirements

Develop Android applications with a minimum API Level 8, which is Android 2.2 (Froyo).

Consult the Google Android Dev Center for the latest Android technical documentation and tools.

IBM Tealeaf client frameworks do not support forwarding of application data to third-party systems. Application data must be forwarded to the server that hosts the native application.

(10)

Supported operating systems

Tealeaf supports these versions of the Windows, Mac, and Linux operating systems:

v _{Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit)} v _{Mac OS X 10.5.8 or later (x86 only)}

v _{Linux (tested on Ubuntu Linux, Lucid Lynx)}

â GNU C Library (glibc) 2.7 or later is required. â On Ubuntu Linux, version 8.04 or later is required.

â 64-bit distributions must be able to run 32-bit applications. For information about how to add support for 32-bit applications, see the Ubuntu Linux installation notes.

Eclipse platforms

Tealeaf supports these Eclipse platforms:

v _{Froyo 2.2} v _{Galileo 3.5} v _{Helios 3.6} v _{Indigo 3.7} v _{Juno 4.2} v _{Kepler 4.3} v

Tealeaf uses the Eclipse JDT plug-in (included in most Eclipse IDE packages). For information on the Eclipse versions supported by the Android Development Tools, check the Eclipse web sitehttp://www.eclipse.org/.

Eclipse packages

Several types of Eclipse packages are available for each platform. For developing Android applications, install one of these packages.

v _{Eclipse IDE for Java}â¢_Developers

â Java version 1.6.

â Java version 1.7 can be used in compatibility mode.

v _{Eclipse Classic}

v _{Eclipse IDE for Java EE Developers}

â JDK 5 or JDK 6 (JRE alone is not sufficient). â Android Development Tools plug-in

â Not compatible with GNU Compiler for Java (gcj)

Tealeaf impact on Android device resources

In benchmark tests, the CX Mobile Android Logging Framework has the following effects on resources of the visitor's device.

v _{2-3% more memory consumption} v _{Minimal effect on battery life}

(11)

Android project changes

After you acquire IBM Tealeaf CX Mobile Android Logging Framework, complete the following steps to install the CX Mobile Android Logging Framework libraries into an Android application project.

Your Eclipse project must include the frameworks that follow. Testing of the CX Mobile Android Logging Framework involved Android 2.2 to 4.3.3.

Installation of

UICAndroid.jar

Using Eclipse to install theuicandroid.jar:

Follow these instructions to use the Eclipse integrated development environment to install the uicandroid.jarin an Android application.

1. In Eclipse, open the Android application to be instrumented.

2. Placeuicandroid.jarinto thelib folder.

3. Right-clickuicandroid.jarand selectBuild Path.

4. ClickAdd on Build Path.

Installation of theuicandroid.jarin another environment:

In integrated development environments other than Eclipse, you add the UICAndroid.jarinto the build path of the application you want to instrument.

Installation of

TLFConfigurableItems.properties

To install the TLFConfigurableItems.propertiesfile, place it in theassetsfolder of the Android application.

Auto-instrumentation not supported

Android enables the use of a one handler at a time for any object. As a result, the CX Mobile Android Logging Framework cannot auto-instrument objects.

You must apply instrumentation as part of your application development.

Configure Tealeaf properties

You configure several items for your app in Tealeaf, including how screen layouts are logged, Target page location, kill switch location, and whether gestures will be logged.

TLFConfigurableItems.properties

Everything that you configure is in theTLFConfigurableItems.propertiesfile. This file is in the Install Package in the <what is the name of the install package for Tealeaf+Plugin?>file.

Configurable properties

There are many properties that you can configure in Tealeaf. At the minimum, you must configure:

v _{Whether to display logcat messages.} v _{The Target page URL.}

v _{Enable/disable the kill switch URL} v _{The kill switch URL.}

(12)

v _{How screen layouts are logged.} v _{The logging level.}

For information to the other properties that you can configure, go to <link to reference topic that I don't have access to right now>.

Whether to display logcat messages

<need a description of what this really is>. Whether you see logcat messages is set with the DisplayLoggingproperty.

Set Target URL

All events that are captured are sent in JSON format to a Target page. The Target page acknowledges the receipt of the JSON message and forwards the client-side events to Tealeaf. The person that sets up Tealeaf on the server creates the Target page. The Target page is set with the PostMessageUrlproperty.

Enable and set kill switch

The Kill Switch is used to control logging. When the kill switch is enabled, it must have a URL to check before the framework initializes. When the page is reachable, the framework initializes. If the page is not reachable, because of network

problems or because you disabled it on your server, the framework does not initialize. The kill switch URL is set by the person who sets up Tealeaf on the server. The kill switch is enabled with theKillSwitchEnabledproperty. The kill switch URL is set with theKillSwitchUrl property.

How screen layouts are logged

Tealeaf can log screen images as base64 or as MD5 checksum with png or jpg images. SetGetImageDataOnScreenLayouttoYESto capture base 64 data. Set GetImageDataOnScreenLayouttoNOto log MD5 checksum and png or jpg images. This option creates smaller payloads in production and is the recommended setting.

Set logging level

You set the logging level based on where your project is in the development cycle. You can set the level high for development and testing and then lower the logging level for production. The logging level is set with the LoggingLevelproperty.

Auto-instrumentation

Android enables the use of one handler at a time for any object. As a result, auto-instrumentation is not supported in Tealeaf. You must apply instrumentation as part of your application development.

Configuring Tealeaf properties for your application

You configure Tealeaf to use specific URLS for logging events and to control message flow, set how screen layouts are logged, modify logging levels. All of the configuration in this task involves modifying settings in the

TLFConfigurableItems.propertiesfile in the Assets folder of your Eclipse project.

(13)

2. Set theDisplayLoggingtoFalse.

3. Set thePostMessageUrlto the URL of the target page for your app.

4. Set theKillSwitchEnabledtoTrue.

5. Set theKillSwitchUrlto the URL for the kill switch for your app.

6. Set theGetImageDataOnScreenLayouttoFalse.

7. Set theLoggingLevelto an appropriate level for development, testing, or production.

8. Save and exit theTLFConfigurableItems.propertiesfile.

Extended Android classes

You extend Android classes to provide logging for components in your application. You can extend the classes with the IBM Tealeaf extended classes or you can extend the classes manually. If you install the Tealeaf SDK, you must extend the Application and Activity classes. When you install the Eclipse Tealeaf plug-in, you must extend only the Activity class. How you extend the classes depends on whether you have custom Application or Activity classes.

Application class

You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Tealeaf listens to these events:

v _{onLowMemory - disable the library when you get a LowMemory warning} v _{onCreate - initialize the library when the application starts}

v _{onTerminate - clean up the library when the application is terminated}

How you extend the Application class depends on whether you have a custom activity class for your application. If you:

v _{Do not have a custom Application class for your application, use the IBM}

Tealeaf class UIApplication. You do this only if you are not using the Eclipse Tealeaf plug-in. The plug-in automatically extends the Application class with the Tealeaf UICApplication class.

v _{Have a custom Activity class for your application, modify your custom}

Application class to point to the Tealeaf UICApplication class.

Application class and the Eclipse Tealeaf plug-in

After you install the Eclipse Tealeaf plug-in, if you decide to use a custom Application class in your application, you need to change the Application class automatically added by the plug-in:

1. Create the custom Application class.

2. ModifyAndroidManifest.xmlfile for the application and change the application class name to the name of Application class you created.

Activity class

You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Tealeaf listens to these events:

v _{onPause - what happens when the application goes to the background} v _{onResume - what happens when the application goes to the foreground} v _{onDestroy - what happens when the activity is no longer in memory and gets}

(14)

How you extend the Activity class depends on whether you have a custom activity class for your application. If you:

v _{Do not have a custom Activity class for your application, use the Tealeaf}

UIActivity class.

v _{Have a custom Activity class for your application, modify your custom Activity}

class to point to the Tealeaf UICActivity class.

Extending the Application class with the Tealeaf UICApplication

class

If you do not have a custom Application class, you can use the IBM Tealeaf UICApplication class to extend the Application class. The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onLowMemory to disable library if you get a warning,onTerminate to clean up library, and onCreateto initialize the library.

1. Open the existing Java file that extends from application class. If this file does not exist, you must create it and have it listen to the complete lifecycle of an Android application to control library and log information needed. You must also change the file to extend fromcom.tl.uic.app.UICApplicationinstead of android.app.Application.

2. Add these imports:

a. importcom.tl.uic.Tealeaf;

b. importcom.tl.uic.app.UICApplication;

3. InonCreate()method, addTealeaf.enable()that initializes capture of user actions in the application.

4. AdjustAndroidManifest.xmlto indicate application class. For example, if your application class is namedMyApplication, you can add

android:name=".MyApplication"in<application>node.

5. Add the following permissions inAndroidManifest.xml. <uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.SET_DEBUG_APP" /> This example shows the lines that you add to the AdroidManifest.xmlfile: import com.tl.uic.Tealeaf;

import com.tl.uic.app.UICApplication;

public class MyApplication extends UICApplication { @Override

public void onCreate() { super.onCreate(); Tealeaf.enable(); }

}

Extending the Activity class with the Tealeaf UICActivity class

The activity file manages the lifecycle of a page in a native Android application similar to what a page does in a web application. IBM Tealeaf listens to the

following eventsonPause, which happen when application goes to the background, onResume, which happens when application goes to foreground, andonDestroy when activity is no longer in memory and gets garbage collected.

On each activity files that you want to log, extend it using UICActivity. Using UICActivity extends the base Activity from the Android framework.UICActivity

(15)

adds some functionality that is required by the IBM Tealeaf Logging Framework library to enable and disable asynchronous tasks, and to perform screen captures of the device after creation.

To avoid capturing potentially private data, the CX Mobile Android Logging Framework takes screen captures as soon as the image was rendered on the device. As a result, no user-defined fields are populated in any captured screen image. Android does not support capture of pop-up windows.

For hybrid applications, screen captures might be missing or out of order due to timing issues.

The method in this task enables automatic capture of screen captures from the client application. If you do not enable this item through UICActivity, you can manually capture screen captures through the Logging Framework. See "Reference" in theIBM Tealeaf CX Mobile Android Logging Framework Guide.

The value for the black background color can be replaced by any color constant to set the color of the background of your screen captures.

1. Open the existing Java file that extends fromandroid.app.Activityclass, and change it to extend fromcom.tl.uic.app.UICActivityinstead of

android.app.Activity.

2. Add these imports:

a. Importcom.tl.uic.Tealeaf;

b. Importcom.tl.uic.app.UICApplication;

3. In the onCreate()method, add:

a. Add this.setTakeSnapshotAfterCreate(true); //To enable automatic screen shots.

b. Add setLogicalPageName("LoginPage") //Recommended to identify page.

c. Add setImageBackground(-16777216) //To set to black background of screenshotbecause the screen capture background is transparent. This example shows the lines that you add to the file that extends the Activity class:

import com.tl.uic.app.UICActivity;

public class LoginActivity extends UICActivity { @Override

public void onCreate(Bundle savedInstanceState) {

this.setTakeSnapshotAfterCreate(true); //To enable automatic screen shots setLogicalPageName("LoginPage") //Recommended to identify page setImageBackground(-16777216) //To set to back background of screenshot

super.onCreate(savedInstanceState);

Extending your custom Application class to point to the Tealeaf

UICApplication class

If you have a custom Application class in your application, point your custom class to the Tealeaf UICApplication class. The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to

onLowMemory to disable library if you get a warning,onTerminateto clean up library, andonCreateto initialize the library. .

(16)

1. Open the existing Java file that extends from theandroid.app.Application class. If this file does not exist, you must create it and have it listen to the complete lifecycle of an Android application to control library and log information needed.

2. Add this import:

import com.tl.uic.Tealeaf;

3. InonCreate():

a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the IBM Tealeaf library with a reference to application instrumented.

b. AddTealeaf.enable();that initializes capture of user actions in the application.

4. InonLowMemory():

a. AddTealeaf.onLowMemory();before superso it can adjust the library due to low memory.

5. InonTerminate():

a. AddTealeaf.disable();before superso it can disable the library.

6. AdjustAndroidManifest.xmlto indicate application class. For example, if your application class is namedMyApplication, you can add

android:name=".MyApplication"in <application> node.

7. Add these permissions toAndroidManifest.xml.

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

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

This example shows the lines you add to the file that extends the Application class: import android.app.Application;

public class MyApplication extends Application { @Override

public void onCreate() { super.onCreate();

Tealeaf tealeaf = new Tealeaf(this); Tealeaf.enable();

}

@Override

public void onLowMemory() { Tealeaf.onLowMemory(); super.onLowMemory(); }

@Override

public void onTerminate() { Tealeaf.disable(); super.onTerminate(); }

}

Extending your custom Activity class to point to the Tealeaf

UICActivity class

If you have a custom Activity class, extend it to point to the Tealeaf UICActivity class. The activity file manages the lifecycle of a page in a native Android

application similar to what a page does in a web application. IBM Tealeaf listens to the following events onPause, which happen when application goes to the

(17)

background, onResume, which happens when application goes to foreground, and onDestroy when activity is no longer in memory and gets garbage collected. Each activity needs a logical page name that helps indicate what activity is being displayed. If no logical page name is given, IBM Tealeaf recommends using class name that gives some indication what activity is being displayed.

1. Open the existing Java file that extends fromandroid.app.Activityclass, and change it to extend fromcom.tl.uic.app.UICActivityinstead of

android.app.Activity.

2. Add this import:

a. Importcom.tl.uic.Tealeaf;

3. Add the logical page name to the class: private String logicalPageName;

public final String getLogicalPageName() { if ((this.logicalPageName == null) || (this.logicalPageName.equals(""))) { this.logicalPageName = this.getClass().getName().substring(this.getClass() .getName().lastIndexOf(".") + 1); } return this.logicalPageName; }

4. In the onPause()method, add:

a. Add Tealeaf.onPause(this, getLogicalPageName());

5. In the onResume()method, add:

a. Add Tealeaf.onResume(this, getLogicalPageName());

6. In the onDestroy()method, add:

a. Add Tealeaf.onDestroy(this, getLogicalPageName());

This example shows the lines that you add to the file that extends your custom Activity class:

public class BaseActivity extends Activity { private String logicalPageName;

/**

* Logical page name of the Activity. *

* @return Logical page name of the Activity. */

public final String getLogicalPageName() { if ((this.logicalPageName == null) || (this.logicalPageName.equals(""))) { this.logicalPageName = this.getClass().getName().substring(this.getClass(). getName().lastIndexOf(".") + 1); } return this.logicalPageName; } /**

* Logical page name of the Activity. *

* @param logicalPageName

* Logical page name of the Activity.

*/

public final void setLogicalPageName(final String logicalPageName) { this.logicalPageName = logicalPageName;

(18)

}

protected void onPause() {

Tealeaf.onPause(this, getLogicalPageName()); super.onPause();

}

protected void onResume() {

Tealeaf.onResume(this, getLogicalPageName()); super.onResume();

}

protected void onDestroy() {

Tealeaf.onDestroy(this, getLogicalPageName()); super.onDestroy();

} }

Implement Tealeaf

After you install Tealeaf, you complete several tasks to implement Tealeaf functions in your application. These tasks involve modifying your application to capture controls, events, and screen views.

Implementation tasks

KT Comment - This is the overview topic that lists and describes all of the rest of the implementation tasks that the user has to do for the Android. All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf plug-in for Tealeaf to work. Just completing the installation is not enough. All of these tasks are manual. This table lists and describes the tasks that you perform to implement Tealeaf in your application:

Task Description

Log Screen Layout for Android Mobile App Replay

Configure logging screen layout to use JSON data not screen captures. Includes

configuring logical pages names, alert dialogs, and keyboard events. Tealeaf SDK ONLY

Integration for Apache Cordova, PhoneGap, and IBM WorklightÂ®

applications using Android classes without IBM Tealeaf classes

Integrate Cordova, PhoneGap, and IBM Worklight applications in your application. Includes extending the Application class for onCreate, onLowMemory, onTerminate methods and onPause, on'Resume, and onDestroy methods for Cordova. .

Implementing screenViews Implementing screenViews as segments for pages in which the state or context can be switched without rerendering the page. Target page configuration Set up the target page that acknowledges

that events are captured.

KT question - This task is part of initial configuration installation. Why is it repeated here in the docs?

Data privacy Specify the fields that are blocked or masked during capture.

Configuring sessionization for Android applications on the client

(19)

Task Description

Network traffic that is used in application contains requests only

KT comment - this section in the doc just says that Tealeaf does this, it doesn't include any information on what the user has to do, if anything.

Configure requests in Android application Configure Tealeaf to put session IDS in cookies.

KT comment - again, this section just says that Tealeaf needs to have session IDS in cookies and that you have to add this code if you are NOT already using something. Not really clear. Why isn't this automatic? Uses non-IBM Tealeaf session ID Configure your generated session IDs to be

used when sessions are enabled or new sessions started.

Hybrid application Configure your application to log request activity if you have a WebView in y our application.

Log screen layout for mobile app session replay

IBM Tealeaf has functions to log screen layouts for screenviews of native mobile app sessions. You can replay a mobile app session in cxImpact Browser Based Replay as you would an HTML web session instead of viewing the mobile app session as a series of screen captures.

The screen layouts of the native mobile app sessions are captured in IBM Tealeaf JSON format. The screen layouts are then sent back to replay server. The replay server uses a template engine, which interprets the JSON into HTML format. You can then replay the screen layout from the native mobile app session as HTML pages in cxImpact Browser Based Replay.

There are several advantages to using JSON data to replay mobile app session over screen captures.

v _{Reduce bandwidth. Screen captures for each screenview generate relatively large}

image data. It not only consumes large amounts of wireless and cellular

bandwidth, but it also consumes more memory inside the device. It also impacts the app performance.

v _{Mask sensitive information. You cannot mask sensitive information in a screen}

capture. When you use JSON data to replay mobile app sessions, you can mask EditTextsby adding View IDsto the MaskIdListattribute in

TLFConfigurableItems.properties.

v _{Draw user interactions (UI events) onto the HTML pages that are created from}

the JSON data.

For more information on mobile ap session replay templates, see "Native app session replay customization" in the IBM Tealeaf CX Configuration Manual.

TLFConfigurableItems.properties

changes

For native app session replay to be activated, you must set

LogViewLayoutOnScreenTransitionto true. If you do not, the library functions as it currently does.

(20)

#Capture native layout

LogViewLayoutOnScreenTransition=true

During predeployment, you must perform all the replay cases to collect all the images with GetImageDataOnScreenLayoutset to true. This creates a large payload sent to server that contains base64 images that are used for replay. When the application is ready to be deployed to Play Store, GetImageDataOnScreenLayout must be changed to false.

#Current only done on ImageView GetImageDataOnScreenLayout=true

Understand your activity

In Android, an Activity can be considered a page, which is displayed on mobile device. By default, you should record an activity that is displayed.

For more information, see http://developer.android.com/training/basics/activity-lifecycle/starting.html.

You can record an activity that is displayed, by placing the following information in theOnCreatemethod.

// this will indicate logical page name.

Tealeaf.logScreenview(activity, "Name", ScreenviewType.LOAD); // this will get layout of page after it being created. Tealeaf.logScreenLayoutOnCreate(activity, "Name"); If you need to log a layout, you can use the following. Tealeaf.logScreenLayout(activity, "Name", delayInMS);

Replaying AlertDialogs

You need to know when an alert dialog is displayed so it can be captured correctly. OnShowListeneris correct location to use for this.

// This will capture background and alert when it is displayed. Tealeaf.logScreenLayoutSetOnShowListener(activity, dialog); If there is already a OnShowListener, follow this example. // This is placed inside OnShowListener:

Tealeaf.logScreenLayout(activity, dialog);

To capture an alert dialog event, follow this example. public void onClick(DialogInterface dialog, int id) { Tealeaf.logDialogEvent(dialog, id);

Replaying keyboard events

Android does not provide an event to understand when a soft keyboard appears and disappears. Follow this example to make the necessary adjustments to TextViewbased controls.

public static void addFocusAndRegister(TextView textView, Activity activity) { textView.setOnFocusChangeListener(new OnFocusChangeListener() {

@Override

public void onFocusChange(View v, boolean hasFocus) { if (hasFocus) {

InputMethodManager imm = (InputMethodManager) v.getContext() .getSystemService(Context.INPUT_METHOD_SERVICE);

(21)

KeyboardView keyboardView = new KeyboardView(v.getContext() .getApplicationContext(), null); Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD_ DID_SHOW_NOTIFICATION); Tealeaf.logEvent(v, Tealeaf.TLF_ON_FOCUS_CHANGE_IN); } else { Tealeaf.logEvent(v, com.tl.uic.Tealeaf.TLF_ON_FOCUS_CHANGE_OUT); InputMethodManager imm = (InputMethodManager) v.getContext() .getSystemService(Context.INPUT_METHOD_SERVICE);

imm.hideSoftInputFromWindow(v.getWindowToken(), 0);

KeyboardView keyboardView = new KeyboardView(v.getContext() .getApplicationContext(), null); Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD _DID_HIDE_NOTIFICATION); } } }); Tealeaf.registerFormField(textView, activity); }

EditText et = (EditText) findViewById(R.id.editText1); addFocusAndRegister(et, this);

For more information, reviewControlsActivity3.javain the Sample Code project, UICAndroidControlsAppdarkHolo.

Supported controls

IBM Tealeaf replays controls that are extended from the following controls. For each control, IBM Tealeaf fills in the tlTypevalue in the json object that is sent back to the server.

ToggleButton and Switch Uses switch template RadioGroup and RadioButton

Uses radioButton template CheckBox

Uses checkBox template Button

Uses button template

Scroller, HorizontalScrollView, ScrollView Uses scroll template

AbsSeekBar

Uses slider template ProgressBar

Uses progressSpinner or progressBar template AbsSpinner

Uses selectList template EditText

Uses label template TextView

Uses switch template ImageView

(22)

FrameLayout, LinearLayout, ViewStub, View Uses canvas template

AbsListView

Uses grid template AlertDialog

Uses alert template TabWidget

Uses tabBar template TabHost

Uses tabContainer template

Integrate Tealeaf and Worklight

Worklight is IBM's Mobile First Platform for developing both Hybrid and Native Apps on multiple mobile platforms. For logging activities on your application, you might want to integrate the Tealeaf library inside of a Worklight "Hybrid"

application. Worklight provides an Eclipse plug-in called "Worklight Developer Studio" to help Developers create Mobile Apps more productively.

Development environment

To integrate Tealeaf with Worklight, you need these files:

v _{Eclipse IDE for Java EE Developers (Kepler): http://www.eclipse.org/}

downloads/packages/release/Kepler/SR2

v _{Worklight Developer Studio version 6.1. You need the compressed file} iws_update_site_wde.6.1.0.2.zip

v _{Worklight Developer Studio version 6.2. You need the compressed file} iws_eclipse_6.2.0.zip. Unless you need Worklight 6.1, you should integrate with Worklight 6.2.

You must also:

1. Install the Worklight Developer Studio inside Eclipse following the instructions in the Worklight documentation.

2. Install the Android ADT plug-in in your Eclipse instance.

3. Register the Tealeaf/Application in the AndroidManifest.xml

Worklight high-level single project

Within Worklight, you can create and manage Mobile project artifacts in a single, high-level project called "Worklight Project". Artifacts include server-side adapters, multiple android projects, and multiple iOS projects All artifacts in the single, high-level project have access to the same resources..

Differences between Worklight 6.1 and Worklight 6.2

In 6.1, Worklight and Tealeaf are packaged together. IN Worklight 6.2 they are no longer packaged together. For 6.2, you must do additional steps to integrate the two products.

Modify Tealeaf and Worklight classes

Part of integrating Tealeaf and Worklight 6.2 is extending and modfying Tealeaf and Worklight classes. This table lists the classes and methods that you modify and shows examples of the modifications:

(23)

Method or class Example

Tealeaf UICApplication class package com.HelloWorklight; import com.tl.uic.Tealeaf;

import com.tl.uic.app.UICApplication; public class TealeafApplication extends UICApplication { @Override

public void onCreate() { super.onCreate(); Tealeaf.enable(); }

}

Worklight CordovaActivity class public class HelloWorklight extends CordovaActivity implements

WLInitWebFrameworkListener { @Override

public void onCreate(Bundle savedInstanceState){

super.onCreate(savedInstanceState); //Tealeaf Integration

super.init();

// Tealeaf Integration: Log Screenview for this activity

Tealeaf.logScreenview(this, this.getClass().getName(), ScreenviewType.LOAD);

// Tealeaf Integration: Add bridge for Tealeaf data to be sent back

appView.addJavascriptInterface(new JavaScriptInterface(this. getBaseContext()), "tlBridge"); WL.createInstance(this); WL.getInstance().showSplashScreen(this); WL.getInstance().initializeWebFramework (getApplicationContext(), this); }

Tealeaf onResume, onPause, and onDestroy methods

//Tealeaf Integration public void onResume() {

// Handle Tealeaf during onResume event Tealeaf.onResume(this, this.getClass() .getName());

super.onResume(); }

public void onPause() {

// Handle Tealeaf during onPause event Tealeaf.onPause(this, this.getClass() .getName());

super.onPause(); }

public void onDestroy() {

// Handle Tealeaf during onResume event Tealeaf.onDestroy(this, this.getClass() .getName());

super.onDestroy(); }

Process

To integrate Tealeaf and Worklight, you:

1. Create a high-level Worklight project called "Worklight Project"

2. Add the Tealeaf SDK to the high-level "Worklight Project".

(24)

4. Modify activity and UIC classes for Tealeaf (for integration with Worklight 6.2 only)

5. Activate Tealeaf in the JavaScript layer.

6. Update to Tealeaf 9.0.0.13, if you have not already. (applies to Worklight 6.1 only)

Creating and configuring the high-level Worklight project:

You can manage your Tealeaf and Worklight integration with the high-level Worklight Project. To integrate Tealeaf and Worklight 6.1, you create the high-level Worklight project, add the Tealeaf SDK to the project, and activate Tealeaf in the JavaScript layer.

In this task, you work in the Eclipse environment. You modify your application and add libraries to the project.

1. Create the high-level Worklight project:

a. In Eclipse, selectNew>Project >Worklight Project.

b. Enter the name of the project, for example Worklight Projectand select Hybrid Application.

c. Enter the name of the Hybrid Application that you are creating. For example,HelloWorklight. The high-level project is created and a Hybrid application that is calledHelloWorklightis in theappsfolder.

2. Activate the Tealeaf SDK on the high-level Worklight project:

a. Open the fileapps/HelloWorklight/application-descriptor.xml.

b. SelectOptional Features>Add>IBM Tealeaf SDK

3. Create an Android project under the high-level Worklight Project:

a. Right click on theHelloWorklightfolder underApps.

b. SelectNew>Worklight Environment.

c. SelectAndroid phones and tablets.

4. Optional: For integrating Tealeaf and Worklight 6.2 only: Modify the classes and methods required for Tealeaf and Worklight integration:

a. Extend the Tealeaf UICApplication class

b. Modify the Worklight CordovaActivity class

c. Modify the Tealeaf onPause, onResume, and onDestroy methods.

5. Activate Tealeaf in the JavaScript layer:

a. Copy theconfiguretealeaf.jsfile from the Tealeaf 9.0.0.13 install package to the Worklight projectapps/HelloWorklight/andoid/jsfolder.

b. Modify theindex.html file and add<script src="js/

configuretealeaf.js"</script>before the break in the<body>element.

6. Right click theapps/HelloWorklight folder and selectRun As >Build All Environments

7. Optional: If you are a version of Tealeaf older than 9.0.0.13. upgrade to Tealeaf 3.0.0.13:

a. Copy theuicandroid.jarfile from the Tealeaf 9.0.0.13 install package into HelloWorklightHelloWorklightAndroid/libs folder.

b. Copy theTLFConfigurableItems.propertiesfile from the Tealeaf 9.0.0.13 install package into the HelloWorklightHelloWorklightAndroid/assets folder

(25)

Integrate Apache Cordova and PhoneGap applications using

Android classes without Tealeaf classes

This method has developers add code snippets that help the IBM Tealeaf capture library.

android.app.Application file code changes:

The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onLowMemory to disable library if you get a warning,onTerminateto clean up library, and onCreateto initialize the library. IBM Tealeaf recommends this as a best practice.

Locating the file that extends from android.app.Application

This file most likely will not exist so you must create it and add it to listen to the complete lifecycle of an Android application to control library and log information needed.

1. Create application class fromandroid.app.Applicationand add the following. If application class is found, then continue to the next steps.

2. Open the existing Java file that extends fromandroid.app.Applicationclass.

3. Add the following imports.

4. InonCreate():

a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the Tealeaf library with a reference to application instrumented.

b. AddTealeaf.enable();that initializes capture of user actions in the application.

5. InonLowMemory():

a. AddTealeaf.onLowMemory();before super so it can adjust library due to low memory.

6. InonTerminate()::

a. AddTealeaf.disable();before super so it can disable library.

7. AdjustAndroidManifest.xmlto indicate application class, by adding android:name=".MyApplication".

Example in Application class import android.app.Application; import com.tl.uic.Tealeaf;

public class MyApplication extends Application { @Override

public void onCreate() { super.onCreate();

Tealeaf tealeaf = new Tealeaf(this); Tealeaf.enable();

}

@Override

public void onLowMemory() { Tealeaf.onLowMemory(); super.onLowMemory(); }

(26)

@Override

public void onTerminate() { Tealeaf.disable(); super.onTerminate(); } } Example in AndroidManifest.xml <application android:label="@string/app_name" android:debuggable="true" android:icon="@drawable/icon" android:name=".TLWorklightTealeafApplication" >

Locating the file that extends from org.apache.cordova.DroidGap:

The file extends from Activity class, which manages the lifecycle of a page in a native Android application similar to what a page does in a web application. IBM Tealeaf listens to the following events onPause, which happen when application goes to the background,onResume, which happens when application goes to foreground, and onDestroywhen activity is no longer in memory and gets garbage collected.

1. Open the existing Java file that extends fromandroid.app.Activity.

2. Add these imports.

c. importcom.tl.uic.model.ScreenviewType;

3. Each activity needs a logical page name that helps indicate what activity is currently being displayed. If no logical page name is given, IBM Tealeaf

recommends to use class name that gives some indication what activity is being display. Add this code to the class:

private String logicalPageName = "MainPage";

4. In theonPause() method, add Tealeaf.onPause(this, logicalPageName);.

5. In theonResume() method, addTealeaf.onResume(this, logicalPageName);.

6. In theonDestroy() method, add Tealeaf.onDestroy(this, logicalPageName);.

7. In the onCreate()method, after super.onCreate(add

a. Tealeaf.logScreenview(this, logicalPageName, ScreenviewType.LOAD);

b. appView.addJavascriptInterface(new

JavaScriptInterface(this.getContext()), "tlBridge");

Implementing screenViews

For pages in which the state or context can be switched without re-rendering the page, IBM Tealeaf segments the data between states by using a screenView object. For example, if a page contains multiple tabs, each of which represents a different stage in a checkout process, you instrument each tab in the page as a distinct screenView.

To implement a screenView for a page, complete the following steps.

1. If you are extending fromUICActivity, set alogicalPageNameto indicate the use of the activity. Otherwise, logicalPageNameis set to the name of the class of the activity.

(27)

2. If the prior step is not complete, callTealeaf.logScreenviewand pass the logicalPageName. You must also indicate if the page being loaded and unloaded is optional. For example:

Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.LOAD); Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.UNLOAD);

Basic configuration

You must set up a target page on your web server. See âQuick start for server configurationâ on page 79.

Set the target page's address in the TLFConfigurableItems.properties configuration file under the keyPostMessageUrl.

See "Configuration File" in theIBM Tealeaf CX Mobile Android Logging Framework Guide.

Data privacy

IBM Tealeaf provides mechanisms for masking or blocking sensitive customer information, such as credit card numbers, from being transmitted and captured by IBM Tealeaf. Through the CX Mobile Android Logging Framework, you can specify the fields that need to be blocked or masked in your web application. When applied, data privacy ensures that these data elements are never transmitted to IBM Tealeaf.

Note: Due to changes in how client framework data is submitted to IBM Tealeaf for capture, the best method for masking or blocking sensitive data is to apply the filtering through the capturing client framework. While other IBM Tealeaf features to manage data privacy can be deployed, they are not easy to implement on the new format of data captured from the client frameworks. IBM Tealeaf recommends using the methods referenced below.

v _{See "Configuration File" in the}_{IBM Tealeaf CX Mobile Android Logging Framework} Guide.

v _{For more information about handling sensitive data in general, see "Managing}

Data Privacy in Tealeaf CX" in theIBM Tealeaf CX Installation Manual.

Configuring sessionization for Android applications on the client

The CX Mobile Android Logging Framework auto-generates a session ID if one is not provided. This session ID is used to identify the session on the IBM Tealeaf server.

IBM Tealeaf injects cookies to create session in the IBM Tealeaf system.

Note: When an Android native or hybrid application is placed into background, the library flushes the collected data and sleeps, instead of disabling it. This happens unless the session expired due to the session timeout property. The timeout property is indicated withSessionTimeoutin

TLFConfigurableItems.properties. The default value for this property is 30 minutes. After a 30-minute timeout, a new session identifier is created.

There are two ways to configure sessionization; either throughTLTSIDprovide by IBM Tealeaf, or through customer session ID, called JSESSIONID. Both methods function as a unique session identifier within the CX Mobile Android Logging Framework environment for IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer session ID orJSESSIONID.

(28)

The following is a typical setting inTLFConfigurableItems.propertiesusing customer session ID.

#Sessionization settings on customer cookies CookieUrl = http://www.sample.com CookieDomain = .sample.com CookiePath = / CookieParam = JSESSIONID CookieExpires = false SessionTimeout=30 SessoinTimeoutKillSwitch=false

In this example, the cookie expires 30 minutes from current time. When the session timeout occurs, CX Mobile Android Logging Framework retrieves the new cookie from your application server and posts the rest of request to application server using this new acquired cookie in request header. PCA groups all the used JSESSIONIDs into one single session even though theJSESSIONIDwas consistently changing. When using cookies generated from customer application server, SessoinTimeoutKillSwitchcan be set to true or false. Setting the

SessoinTimeoutKillSwitchto false means the session timeout user does not go to recheck on KillSwitchUrlto see if it is responding.

Network traffic used in application contains requests only:

CX Mobile Android Logging Framework uses cookies to add values to the TLFConfigurableItems.propertiesfile.

Uses session ID generated by IBM Tealeaf CX Mobile Android Logging Framework

CX Mobile Android Logging Framework uses cookies to add the following values in TLFConfigurableItems.properties.

v _CookieUrl_{is for url of site that is posted and getting cookie to sessionize on.} v _CookieParam_{is the parameter that has a session id.}

v _CookiePath_{is the path of the cookie.}

v _CookieDomain_{is the domain that the cookie belongs to.}

v _CookieSecure_{is to add a secure cookie that can only be posted to an https url}

that has a valid certificate.

v _{CookieExpiresFormat}_{can have the date format of ASCTIME, RFC1036, or}

RFC1123, which will have an expiration date of current time + session timeout indicated in the variable below.

v _{SessionTimeout}_{is session timeout is in minutes. When this value expires a new}

session id is created. An example follows. #Sessionization settings CookieUrl=http://m.ibm.com CookieParam=TLTSID CookiePath=/ CookieDomain=.ibm.com

#Whether you want to create a secure cookie which can only be sent using a https url in PostMessageUrl.

CookieSecure=false

#Valid date formats: ASCTIME, RFC1036, RFC1123 CookieExpiresFormat=ASCTIME

#When post is sent, expiration of cookie will be current time + session timeout #Session timeout is in minutes

(29)

Note: It is important to first call your server to get first cookie to sessionize on, which is automatically obtained when you enable the kill switch URL on the application. This is used to aggregate all the data on CX Passive Capture Application capture.

Configure requests in Android application

IBM Tealeaf needs all the requests to have the session id to be placed in the cookies of the request. This enables the IBM Tealeaf system to collect all the resources together in a single session.

If you are usingorg.apache.http.impl.client.DefaultHttpClient, you can use com.tl.uic.http.TLDefaultHttpClient, which adds the appropriate session id in the cookie of the request. If you decide not use the IBM Tealeaf extended class, then you must add the following code to the following classes.

Extend org.apache.http.impl.client.DefaultHTTPClient:

If you do not use the IBM Tealeaf extendedTLDefaultHttpClientclass, you must add the following code to the following classes.

import org.apache.http.conn.ClientConnectionManager; import org.apache.http.impl.client.DefaultHttpClient; import org.apache.http.params.HttpParams; /** * @author ohernandez * */

public class TLDefaultHttpClient extends DefaultHttpClient { /** * */ public TLDefaultHttpClient() { super(); this.init(null); } /**

* @param params Http parameters. */

public TLDefaultHttpClient(final HttpParams params) { super(params);

this.init(null); }

/**

* @param params Http parameters. * @param sessionId Tealeaf session id. */

public TLDefaultHttpClient(final HttpParams params, final String sessionId) {

super(params); this.init(sessionId); }

/**

* @param conman ClientConnectionManager. * @param params Http parameters.

*/

public TLDefaultHttpClient(final ClientConnectionManager conman, final HttpParams params) {

super(conman, params); this.init(null); }

(30)

/**

* @param sessionId Tealeaf session id. */

private void init(final String sessionId) {

final TLHttpRequestInterceptor tlHttpRequestInterceptor = new TLHttpRequestInterceptor(sessionId); this.addRequestInterceptor(tlHttpRequestInterceptor); this.addResponseInterceptor(new TLHttpResponseInterceptor (tlHttpRequestInterceptor)); } } Extend org.apache.http.HttpRequestInterceptor:

This class is used to inject session id as a cookie and additional headers that the IBM Tealeaf system uses.

import java.io.IOException; import java.util.Map.Entry; import org.apache.http.HttpException; import org.apache.http.HttpRequest; import org.apache.http.HttpRequestInterceptor; import org.apache.http.protocol.HttpContext; import android.webkit.CookieManager; import com.tl.uic.Tealeaf; import com.tl.uic.util.LogInternal; /** * @author ohernandez */

public class TLHttpRequestInterceptor implements HttpRequestInterceptor { private String url;

private final String sessionId; /** * Constructor. */ public TLHttpRequestInterceptor() { super(); this.sessionId = null; } /** * Constructor.

* @param sessionId Tealeaf session id. */

public TLHttpRequestInterceptor(final String sessionId) { this.sessionId = sessionId;

} /**

* Get url of the request. * @return Url of the request. */

public final String getUrl() { return url;

} /**

* Url of the request.

* @param url Url of the request. */

(31)

this.url = url; }

/**

* {@inheritDoc} */

public final void process(final HttpRequest request, final HttpContext context) throws HttpException, IOException {

try {

this.url = request.getRequestLine().getUri(); if (!request.containsHeader(Tealeaf.TLF_HEADER)) {

request.addHeader(Tealeaf.TLF_HEADER, "device (Android) Lib/" + Tealeaf.getLibraryVersion()); } if (!request.containsHeader(Tealeaf.TLF_PROPERTY_HEADER)) { request.addHeader(Tealeaf.TLF_PROPERTY_HEADER, Tealeaf.getHttpXTealeafProperty()); } if (Tealeaf.getAdditionalHeaders() != null) { for (final EntryString,<String> entry : Tealeaf.getAdditionalHeaders().entrySet()) {

request.addHeader(entry.getKey(), entry.getValue()); }

}

final StringBuffer cookies = new StringBuffer(Tealeaf. getTLCookie(this.sessionId));

if (this.getUrl() != null) {

final String extistingCookies = CookieManager.getInstance(). getCookie(this.getUrl()); if (extistingCookies != null) { cookies.append(â;â); cookies.append(extistingCookies); } } request.addHeader("Cookie", cookies.toString());

LogInternal.log("Session cookie:" + cookies.toString()); }catch (final Exception e) {

Tealeaf.logException(e); }

} }

Extend org.apache.http.HttpResponseInterceptor:

This class is used to get information to fill out a IBM Tealeaf connection object. import java.io.IOException; import java.util.Date; import org.apache.http.HttpException; import org.apache.http.HttpResponse; import org.apache.http.HttpResponseInterceptor; import org.apache.http.protocol.HttpContext; import com.tl.uic.TLFCache; import com.tl.uic.Tealeaf; import com.tl.uic.util.LogInternal; /** * @author ohernandez * */

(32)

public class TLHttpResponseInterceptor implements HttpResponseInterceptor { private final TLHttpRequestInterceptor tlHttpRequestInterceptor;

private final Date startTime; private final long initTime; /**

* Constructor. *

* @param tlHttpRequestInterceptor TLHttpRequestInterceptor used. */

public TLHttpResponseInterceptor(final TLHttpRequestInterceptor tlHttpRequestInterceptor) {

this.tlHttpRequestInterceptor = tlHttpRequestInterceptor; this.startTime = new Date();

this.initTime = TLFCache.timestampFromSession(); }

/**

* {@inheritDoc} */

public final void process(final HttpResponse response, final HttpContext context) throws HttpException, IOException {

try {

final Date endTime = new Date(); final Date startLoad = new Date();

final long loadTime = (new Date()).getTime() - startLoad.getTime(); final long responseTime = endTime.getTime() - this.startTime.getTime(); Tealeaf.logConnection(this.tlHttpRequestInterceptor.getUrl(), response, this.initTime, loadTime, responseTime);

} catch (final Exception e) { LogInternal.logException(e); }

} }

Uses non IBM Tealeaf session ID

You must get your generated session ID and use it when you enable or start a new session in CX Mobile Android Logging Framework.

// If enabling of Android Logging Framework use Tealeaf.enable();

Tealeaf.enable("your session id");

// If Android Logging Framework is enabled and a new session is to be created use Tealeaf.startSession();

Tealeaf.startSession("your session id");

Android application gestures

You can capture gestures that the users make on your Android application. Several types of gestures are captured.

Configuration

For any Activity class that you want Gesture logging, you edit

TLFConfigurableItems.propertiesfile and set the SetGestureDetectorproperty to true.

Touch event methods

You add your variables to one of these methods:

v _onTouchEvent_{- use this method if your activity is not using a customized gesture}

view.

v _{dispatchTouchEvent}_{- use this method if your activity is using a customized}

(33)

If your application uses a customized gesture view, onTouchEvent does not detect the gestures because they are already captured by the customized gesture view. If you are using a customized gesture view, you must use dispatchTouchEvent. You can use either theonTouchEventor thedispatchTouchEvent. If you use both, the gestures are captured twice.

Gesture events captured:

Gestures that are used to select items in an application or to adjust views in the application are captured by Tealeaf.

Tap gestures

This table lists and describes the tap gestures that are captured from web and mobile apps:

Note: The arrows that illustrate the direction of a swipe or pinch gesture are not supported by the Internet Explorer browser.

Table 1. Tap gestures

Gesture name Description Image displayed in Replay

Tap This gesture is a one-finger gesture.

For a tap gesture, one-finger taps and lifts from the screen in 1 location.

Tap and Hold This gesture is a one-finger gesture.

For a Tap and Hold gesture, one-finger presses and stays on the screen until information is displayed or an action occurs.

Note: The response to a Tap and Hold gesture can vary from one application to another. For example, a Tap and Hold gesture might display an

information bubble, magnify content under the finger, or present the user with a context menu. Double tap This gesture is a one-finger gesture.

For a double tap gesture, one-finger taps twice in close succession in 1 location of the screen.

Swipe gestures

This table lists and describes the swipe gestures that are captured from web and mobile apps:

(34)

Table 2. Swipe gestures

Gesture name Description Image displayed in Replay

Swipe vertically This gesture is a one-finger gesture. For a swipe vertically gesture, one-finger:

1. taps and holds in 1 location of screen,

2. continues to engage screen while it moves up or down

3. lifts from the screen in different location.

Note: The initial tap becomes lighter in color, while the destination is highlighted by a darker color Swipe

horizontally

This gesture is a one-finger gesture.

For a swipe horizontally gesture, one-finger:

1. taps and holds in 1 location of screen,

2. continues to engage screen while it moves left or right

3. lifts from the screen in different location.

Note: The initial tap becomes lighter in color, while the destination is highlighted by a darker color

Resize gestures

This table lists and describes the resize gestures that are captured from web and mobile apps:

Note: See theIBM Tealeaf Customer Experience 9.0.1 Release Notesfor information about a known limitation for handling some iOS pinch gestures.

Table 3. Resize gestures

Gesture name Description Image displayed in Replay

Pinch open Sometimes referred to as aspreadgesture, this is a two-finger gesture.

For a pinch open gesture, 2 fingers:

1. tap and hold in 1 location of the screen,

2. maintain contact with the screen while the fingers move apart from each other in any direction,

3. lift from the screen at a new location.

Note: Accompanying arrows indicate the direction (open or close) of the pinch

Pinch close This gesture is a two-finger gesture. For a pinch close resize gesture, 2 fingers:

1. tap and hold in 1 location on the screen,

2. maintain contact with the screen while the fingers move toward each other,

3. lift from the screen at a new location. Note: Accompanying arrows indicate the direction (open or close) of the pinch

(35)

Instrumenting your application for Android gestures:

You can enable your application to capture gestures that the user makes on your application. To enable gestures for an Activity class, you modify the Activity class. For example, you modify theMainActivity.javafile and call the

Tealeaf.dispatchTouchEventmethod inside dispatchTouchEventor onTouchEvent method.

To use the Android gestures module, you must the Android Support Library android-support-v4.jartogether with Tealeaf SDKuicandroid.jar. The

android-support-v4.jaris distributed within Android SDK. Download and install the Android Support Library from the Android Support Library site. The

installation installs the android-support-v4.jar at ${your Android SDK location}/extras/android/support/v4/android-support-v4.jar

1. Open the MainActivity.javafile for your application.

2. Override either thedispatchTouchEventor theonTouchEventmethod, depending on how you are using gestures in your application:

IF your application is... THEN...

using a customized gesture view Override thedispatchTouchEvent publc boolean dispatchTouchEvent ( MotionEvent e) {

Tealeaf.dispatchTouchEvent(this, e); return super.dispatchTouchEvent(e); }

not using a customized gesture view Override theonTouchEvent publc boolean onTouchEvent ( MotionEvent e) {

Tealeaf.dispatchTouchEvent(this, e); return super.onTouchEvent(e); }

This example shows the code snippets that are added in this task for an application that does not use a customized gesture view:

mport com.tl.uic.Tealeaf;

import com.tl.uic.app.UICActivity; import android.os.Bundle;

import android.view.MotionEvent;

public class MainActivity extends UICActivity{ @Override

protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);

setContentView(R.layout.activity_main);

Tealeaf.logScreenLayout(this, this.getLogicalPageName(), 1000); }

public boolean dispatchTouchEvent( MotionEvent e) { Tealeaf.dispatchTouchEvent(this,e);

return super.dispatchTouchEvent(e); }

(36)

Modifying the TLFConfiguratbleItems.properties file for gestures:

After you define the variables for gestures in your Activity class, you enable gesture capture by modifying the TLFConfiguratableItems.propertiesfile.

1. Edit theTLFConfiguratableItems.propertiesfile.

2. SetSetGestureDetectortotrue.

3. Save and exit theTLFConfiguratableItems.propertiesfile.

Log exceptions

Exceptions are the way that a system or framework communicates to the application that something is wrong. Tealeaf provides two mechanisms to log exceptions. You can manually log exceptions by using the logExceptionAPI, or Tealeaf SDK will automatically log uncaught exceptions. The exception information can be used for analytics.

Automatically log exceptions

When your application throws an uncaught exception, Tealeaf Android SDK records the stack trace and state of the device at the time the exception was thrown. Tealeaf Android SDK sends the crash information to your target servers for processing.

Manually log exceptions

In the Android SDK, you modify your catch block to report caught exceptions to the target server for processing. When you modify your catch block, you get the full stack trace and same device information that Tealeaf collects for fatal crashes. This table shows the method that is used to log exceptions and describes the parameters that are used in the method:

Method Parameters

public static Boolean logException(final

Throwable exception, final

HashMap<String, String> data,

final Boolean unhandled)

Where:

v _{@param exception - the exception to be}

logged.

v _{@param data - the value to be given to}

event.

v _{@param unhandled - whether the}

exception is unhandled.

v _{@return - whether exception was logged.}

Example

In this example, you have a method that causes an exception: public void clientMethod1( ) {

}

You add an @try,@catch, and the Tealeaf.logException(e, data, false)method to handle the exception:

public void clientMethod1( ) { try {

int[] array = new int[1];

int i = array[2]; // Index out of bound exception } Catch (Exception e) {

(37)

HashMap<String, String> data = new HashMap<String, String>(); data.put("extraMessage", "custom value1");

Tealeaf.logException(e, data, false); }

}

Logging exceptions:

Use the examples in this task as a guide to adding exception logging to your application.

1. Determine the method for which you want to log exceptions. For example, you have a method:

public void clientMethod1( ) { }

2. Optional: Add t

IBM Tealeaf CX Mobile Android Logging Framework Version 9 Release 0.1 December 4, IBM Tealeaf CX Mobile Android Logging Framework Guide