IBM Android SDK Tealeaf User Guide

IBM Tealeaf

Version 9 Release 0.2

September 18, 2015

Android SDK Guide

IBM

Note

Before using this information and the product it supports, read the information in “Notices” on page 167.

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

© Copyright IBM Corporation 1999, 2015.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

IBM Tealeaf Android SDK Guide . . ..

v

Chapter 1. Tealeaf installation and implementation in an Android application . . . . . . . . . . . ..

1

Client Framework versions supported in this documentation.

.

.

.

.

.

.

.

.

.

.

.

..

2

Install the Tealeaf SDK for Android development in your application .

.

.

.

.

.

.

.

.

.

.

..

2

Tealeaf package contents .

.

.

.

.

.

.

..

2

Tealeaf sample application .

.

.

.

.

.

.

..

3

Android development environment requirements 3

Tealeaf impact on Android device resources .

..

4

Android project changes .

.

.

.

.

.

.

..

4

Configure Tealeaf properties .

.

.

.

.

.

..

5

Extended Android classes .

.

.

.

.

.

.

..

7

Implement Tealeaf .

.

.

.

.

.

.

.

.

..

12

Install the Eclipse Tealeaf plug-in for Android development in your application .

.

.

.

.

..

46

Tealeaf package contents .

.

.

.

.

.

.

..

46

Android development environment requirements 47

Tealeaf impact on Android device resources ..

48

Add Eclipse Tealeaf plug-in to your Eclipse

Android project .

.

.

.

.

.

.

.

.

.

..

49

Configure Tealeaf properties .

.

.

.

.

.

..

51

Extended Android classes .

.

.

.

.

.

..

52

Implement Tealeaf .

.

.

.

.

.

.

.

.

..

58

Quick start for server configuration .

.

.

.

..

88

Target page for traffic capture .

.

.

.

.

..

88

Traffic volume management .

.

.

.

.

.

..

88

CX Passive Capture Application traffic capture verification .

.

.

.

.

.

.

.

.

.

.

..

88

Options for monitoring captures and processing 90

Configuring sessionization for Android applications in IBM Tealeaf .

.

.

.

.

.

..

90

Runtime configuration.

.

.

.

.

.

.

.

..

93

IBM Tealeaf events for Android SDK .

.

.

.

..

94

Upgrading the Android SDK .

.

.

.

.

.

..

94

Chapter 2. Configuration file . . . ..

95

Log level settings .

.

.

.

.

.

.

.

.

.

..

95

Kill switch settings .

.

.

.

.

.

.

.

.

.

..

95

Local cache file settings .

.

.

.

.

.

.

.

..

96

Post settings .

.

.

.

.

.

.

.

.

.

.

.

..

96

Masking settings .

.

.

.

.

.

.

.

.

.

..

97

Filter message type setting .

.

.

.

.

.

.

..

98

Cookie settings .

.

.

.

.

.

.

.

.

.

.

..

98

Session timeout setting .

.

.

.

.

.

.

.

..

98

Screen shot settings.

.

.

.

.

.

.

.

.

.

..

98

Internal settings: do not change.

.

.

.

.

.

..

99

© Copyright IBM Corp. 1999, 2015

Chapter 3. Sample applications. . ..

101

Chapter 4. Guidelines . . . . . . ..

103

Chapter 5. Reference . . . . . . ..

105

UICActivity class .

.

.

.

.

.

.

.

.

.

..

105

UICApplication class .

.

.

.

.

.

.

.

.

..

107

Tealeaf class .

.

.

.

.

.

.

.

.

.

.

.

..

108

TLDefaultHttpClient class .

.

.

.

.

.

.

..

117

TLHttpRequestInterceptor class .

.

.

.

.

..

118

TLHttpResponseInterceptor class .

.

.

.

.

..

119

UICWebView class .

.

.

.

.

.

.

.

.

..

120

UICWebChromeClient Class .

.

.

.

.

.

..

122

UICWebViewClient Class .

.

.

.

.

.

.

..

123

Chapter 6. Sample Code. . . . . ..

125

How to instrument TextView based controls .

..

125

How to instrument ExpandableListView based controls .

.

.

.

.

.

.

.

.

.

.

.

.

..

125

How to instrument SlidingDrawer based controls 126

How to mask controls .

.

.

.

.

.

.

.

..

126

Server-Side KillSwitch Sampling Function .

.

..

126

Sampling function examples for ASPX .

.

..

126

Sampling Function for JSP .

.

.

.

.

.

..

127

Sampling Function for PHP .

.

.

.

.

..

129

JSON message type schemas and examples .

..

130

Message header properties .

.

.

.

.

.

..

131

Message header properties schema .

.

.

..

131

Client state (Type 1) messages .

.

.

.

.

..

132

ScreenView (Type 2) messages .

.

.

.

.

..

134

Connections (Type 3) messages .

.

.

.

..

136

Control (Type 4) messages .

.

.

.

.

.

..

137

Custom Event (Type 5) messages .

.

.

.

..

140

Exception (Type 6) messages .

.

.

.

.

..

141

Performance (Type 7) messages .

.

.

.

..

142

Web Storage (Type 8) messages .

.

.

.

..

143

Overstat Hover Event (Type 9) messages .

..

144

Layout (Type 10) messages .

.

.

.

.

.

..

144

Gesture (Type 11) messages.

.

.

.

.

.

..

147

DOM Capture (Type 12) messages .

.

.

..

156

GeoLocation (Type 13) messages .

.

.

.

..

161

Chapter 7. Troubleshooting . . . ..

163

Troubleshooting and debugging - enabling raw request and response headers .

.

.

.

.

.

..

163

Troubleshooting - managing client-side issues ..

163

Chapter 8. IBM Tealeaf documentation and help . . . . . . . . . . . ..

165

Notices . . . . . . . . . . . . ..

167

Trademarks .

.

.

.

.

.

.

.

.

.

.

.

..

168

Privacy Policy Considerations .

.

.

.

.

.

..

169

iii

iv

IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide

IBM Tealeaf Android SDK Guide

The IBM Tealeaf Android SDK 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.

The IBM Tealeaf Android SDK Guide provides 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 Android SDK software.


v

vi


Chapter 1. Tealeaf installation and implementation in an

Android application

You add the Tealeaf

®

SDK to your application so that the Android SDK 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 software option. 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.

Modify AndroidManifest.xml file 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

3.

Extend Application and Activity classes


1

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.

Install the Tealeaf SDK for Android development in your application

You add the Tealeaf SDK to your application so that the Android SDK 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 Android SDK and its software components.

IBM Tealeaf Android SDK is delivered in the IBM Tealeaf Android SDK 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

- 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 :

2


– uicandroid.jar: Android library JAR file that contains the Android SDK.

– TLFConfigurableItems.properties: Configuration file.

v SampleCode

: Contains the following versions of a sample Android application.

– UICSP_Clean: An Android application without IBM Tealeaf Android SDK integrated.

– UICSP_ManualLog: An Android application with IBM Tealeaf Android SDK integrated

– UICSP_ManualLog_ServerSessionID: An Android application with IBM Tealeaf

Android SDK integrated by using a session ID provided from a web application.

See "Sample Code" in the IBM Tealeaf Android SDK 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 Android SDK.

Instead of integrating the Android SDK 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 101.

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.

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.

Chapter 1. Tealeaf installation and implementation in an Android application

3

– 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 Android SDK has the following effects on resources of the visitor's device.

v

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

Android project changes

After you acquire IBM Tealeaf Android SDK, complete the following steps to install the Android SDK libraries into an Android application project.

Your Eclipse project must include the frameworks that follow. Testing of the

Android SDK involved Android 2.2 to 4.3.3.

Install the UICAndroid.jar

You install the uicandroid.jar in to your Android application to make the capture functions available in your application. There are two ways to install the uicandroid.jar

, either in Eclipse or in another build environment.

4


Using Eclipse to install the uicandroid.jar:

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

1.

In Eclipse, open the Android application to be instrumented.

2.

Place uicandroid.jar into the lib folder.

3.

Right-click uicandroid.jar and select Build Path.

4.

Click Add on Build Path.

Installation of the uicandroid.jar in another environment:

In integrated development environments other than Eclipse, you add the

UICAndroid.jar

into the build path of the application you want to instrument.

Installation of TLFConfigurableItems.properties

To install the TLFConfigurableItems.properties file, place it in the assets folder 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

Android SDK 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 the TLFConfigurableItems.properties file. The

TLFConfigurableItems.properties

file is in the Install Package.

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.

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

Whether you see logcat messages is set with the DisplayLogging property.


5

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 PostMessageUrl property.

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 the KillSwitchEnabled property. 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. Set GetImageDataOnScreenLayout to YES to capture base 64 data. Set

GetImageDataOnScreenLayout to NO to 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 LoggingLevel property.

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


file in the Assets folder of your Eclipse project.

1.

In your Eclipse, open the TLFConfigurableItems.plist file.

2.

Set the DisplayLogging to False.

3.

Set the PostMessageUrl to the URL of the target page for your app.

4.

Set the KillSwitchEnabled to True.

5.

Set the KillSwitchUrl to the URL for the kill switch for your app.

6.

Set the GetImageDataOnScreenLayout to False.

7.

Set the LoggingLevel to an appropriate level for development, testing, or production.

8.

Save and exit the TLFConfigurableItems.properties file.

6


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.

Modify AndroidManifest.xml file 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 garbage collected

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.


7

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 onCreate to 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 from com.tl.uic.app.UICApplication instead of android.app.Application

.

2.

Add these imports: a.

import com.tl.uic.Tealeaf; b.

import com.tl.uic.app.UICApplication;

3.

In onCreate() method, add Tealeaf.enable() that initializes capture of user actions in the application.

4.

Adjust AndroidManifest.xml to indicate application class. For example, if your application class is named MyApplication, you can add

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

5.

Add the following permissions in AndroidManifest.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.xml file: 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 events onPause, which happen when application goes to the background, onResume , which happens when application goes to foreground, and onDestroy 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 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 Android SDK 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.

8


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 the IBM Tealeaf Android SDK 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 from android.app.Activity class, and change it to extend from com.tl.uic.app.UICActivity instead of android.app.Activity

.

2.


Import com.tl.uic.Tealeaf; b.

Import com.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 screenshot because 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) screenshot

//To set to back background of 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, onTerminate to clean up library, and onCreate to initialize the library. .

1.

Open the existing Java file that extends from the android.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.

In onCreate(): a.

Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the IBM

Tealeaf library with a reference to application instrumented.

b.

Add Tealeaf.enable(); that initializes capture of user actions in the application.

4.

In onLowMemory():


9

a.

Add Tealeaf.onLowMemory(); before super so it can adjust the library due to low memory.

5.

In onTerminate(): a.

Add Tealeaf.disable(); before super so it can disable the library.

6.


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

7.

Add these permissions to AndroidManifest.xml.





This example shows the lines you add to the file that extends the Application class: import android.app.Application; import com.tl.uic.Tealeaf; public class MyApplication extends Application {


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 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.


.

2.

Add this import: a.

Import com.tl.uic.Tealeaf;

3.

Add the logical page name to the class:

10


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: import com.tl.uic.Tealeaf; 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);


}

/**


*

* @param logicalPageName

*

*/

Logical page name of the Activity.

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

} protected void onPause() {

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

} protected void onResume() {

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

} protected void onDestroy() {


11

}

}

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

After you install the SDK, you must complete more tasks to implement the SDK.

All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf plug-in for Tealeaf to work. All of these tasks are manual.

This table lists and describes the tasks that you complete to implement Tealeaf in your application:

Task

Log Screen Layout for Android Mobile App

Replay

Tealeaf SDK ONLY

Integration for Apache Cordova, PhoneGap, and IBM Worklight

® applications that use

Android classes without IBM Tealeaf classes

Implementing screenViews

Target page configuration

Data privacy

Description

Configure logging screen layout to use JSON data not screen captures. Includes configuring logical pages names, alert dialogs, and keyboard events.

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 as segments for pages in which the state or context can be switched without rerendering the page.

Set up the target page that acknowledges that events are captured.

Specify the fields that are blocked or masked during capture.

Configure how session IDs are generated.

Configuring sessionization for Android applications on the client

Network traffic that is used in application contains requests only

Configure requests in Android application

Uses non-IBM Tealeaf session ID

Hybrid application

Tealeaf supports network traffic that is used in applications that contain requests only.

Configure Tealeaf to put session identifiers in cookies.

Configure your generated session IDs to be used when sessions are enabled or new sessions started.

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

12


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

EditTexts by adding View IDs to the MaskIdList attribute in


.

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.


changes

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

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

#Capture native layout

LogViewLayoutOnScreenTransition=true

During predeployment, you must perform all the replay cases to collect all the images with GetImageDataOnScreenLayout set 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/activitylifecycle/starting.html.

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


13

// 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.

OnShowListener is 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

TextView based 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); imm.showSoftInput(v, InputMethodManager.SHOW_FORCED);

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);


.getSystemService(Context.INPUT_METHOD_SERVICE); imm.hideSoftInputFromWindow(v.getWindowToken(), 0);



Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD

_DID_HIDE_NOTIFICATION);

}

}

});

Tealeaf.registerFormField(textView, activity);

}

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

14


For more information, review ControlsActivity3.java in 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 tlType value 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


ImageView

Uses image template

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 IBM MobileFirst Platform Foundation

IBM MobileFirst Platform Foundation 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 IBM MobileFirst Platform Foundation "Hybrid" application. IBM


15

MobileFirst Platform Foundation provides an Eclipse plug-in called "IBM

MobileFirst Platform Foundation Developer Studio" to help Developers create

Mobile Apps more productively.

Development environment

To integrate Tealeaf with IBM MobileFirst Platform Foundation, you need these files: v Eclipse IDE for Java EE Developers (Kepler): http://www.eclipse.org/ downloads/packages/release/Kepler/SR2 v IBM MobileFirst Platform Foundation Developer Studio version 6.1. You need the compressed file iws_update_site_wde.6.1.0.2.zip

v IBM MobileFirst Platform Foundation Developer Studio version 6.2. You need the compressed file iws_eclipse_6.2.0.zip. Unless you need IBM MobileFirst

Platform Foundation 6.1, you should integrate with Worklight 6.2.

You must also:

1.

Install the IBM MobileFirst Platform Foundation 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

IBM MobileFirst Platform Foundation high-level single project

Within IBM MobileFirst Platform Foundation, you can create and manage Mobile project artifacts in a single, high-level project called "IBM MobileFirst Platform

Foundation 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 IBM MobileFirst Platform Foundation 6.1 and IBM

MobileFirst Platform Foundation 6.2

In 6.1, IBM MobileFirst Platform Foundation and Tealeaf are packaged together. IN

IBM MobileFirst Platform Foundation 6.2 they are no longer packaged together.

For 6.2, you must do additional steps to integrate the two products.

Modify Tealeaf and IBM MobileFirst Platform Foundation classes

Part of integrating Tealeaf and IBM MobileFirst Platform Foundation 6.2 is extending and modfying Tealeaf and IBM MobileFirst Platform Foundation classes.

This table lists the classes and methods that you modify and shows examples of the modifications:

Method or class

Tealeaf UICApplication class

Example

package com.HelloWorklight; import com.tl.uic.Tealeaf; import com.tl.uic.app.UICApplication; public class TealeafApplication extends UICApplication {


Tealeaf.enable();

}

}

16


Method or class

IBM MobileFirst Platform Foundation

CordovaActivity class

Tealeaf onResume, onPause, and onDestroy methods

Customize the onInitWebFrameworkComplete method

Example

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 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() {


Tealeaf.onDestroy(this, this.getClass()

.getName()); super.onDestroy();

} publicvoid onInitWebFrameworkComplete(

WLInitWebFrameworkResult result){ if (result.getStatusCode() ==

WLInitWebFrameworkResult.SUCCESS) { super.loadUrl(WL.getInstance()

.getMainHtmlFilePath());

//Tealeaf Integration

Tealeaf.logScreenLayout(this, this.getClass().getName(),

2000);

} else {

(result);

}

} handleWebFrameworkInitFailure


17

Process

To integrate Tealeaf and IBM MobileFirst Platform Foundation, you:

1.

Create a high-level IBM MobileFirst Platform Foundation project called "IBM

MobileFirst Platform Foundation Project"

2.

Add the Tealeaf SDK to the high-level "IBM MobileFirst Platform Foundation

Project".

3.

Create an Android project under the high-level "IBM MobileFirst Platform

Foundation Project"

4.

Modify activity and UIC classes for Tealeaf (for integration with IBM

MobileFirst Platform Foundation 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 IBM MobileFirst

Platform Foundation 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, select New > Project > Worklight Project.

b.

Enter the name of the project, for example Worklight Project and 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 called HelloWorklight is in the apps folder.

2.

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

Open the file apps/HelloWorklight/application-descriptor.xml.

b.

Select Optional Features > Add > IBM Tealeaf SDK

3.

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

Right click on the HelloWorklight folder under Apps.

b.

Select New > Worklight Environment.

c.

Select Android 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 the defaultconfiguration.js file from the Tealeaf 9.0.0.13 install package to the Worklight project apps/HelloWorklight/andoid/js folder.

b.

Modify the index.html file and add <script src="js/ defaultconfiguration.js"</script> before the break in the <body> element.

c.

Modify the defaultconfiguration.js file and set the DOM Capture options that you want to use:

18


replay: {

// DOM Capture configuration domCapture: { enabled: true,

// Filter object for matching rules is similar to the Privacy configuration

// It accepts a mandatory "event" followed by one or more optional targets

// as well as an optional delay after which to take the DOM snapshot.

triggers: [

{ event: "load"

}

],

// DOM Capture options options: { captureFrames: true, // Should child frames/iframes be captured removeScripts: true // Should script tags be removed from the captured snaphot

}

}

} d.

If DOM Capture does not fire on load, set DOM Capture to fire from your application by adding this code to your Native Android application for the screenview that you want to capture: if (TLT === undefined) { console.log(’TLT is undefined!’);

} else { if (TLT.logScreenviewLoad === undefined) { console.log(’Could not invoke TLT.logScreenviewLoad API!’);

} else {

TLT.logScreenviewLoad("root"); console.log(’logScreenviewLoad:’);

} if (TLT.logDOMCapture === undefined) { console.log(’Could not invoke TLT.logDOMCapture API!’);

} else { dcid = TLT.logDOMCapture(window.document, {}); console.log(’logDOMCapture:’ + dcid);

}

}

6.

Right click the apps/HelloWorklight folder and select Run 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 the uicandroid.jar file from the Tealeaf 9.0.0.13 install package into

HelloWorklightHelloWorklightAndroid/libs folder.

b.

Copy the TLFConfigurableItems.properties file from the Tealeaf 9.0.0.13

install package into the HelloWorklightHelloWorklightAndroid/assets folder

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


19

warning, onTerminate to clean up library, and onCreate to 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 from android.app.Application and add the following.

If application class is found, then continue to the next steps.

2.

Open the existing Java file that extends from android.app.Application class.

3.

Add the following imports.

a.



4.

In onCreate(): a.

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

b.


5.

In onLowMemory(): a.

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

6.

In onTerminate():: a.

Add Tealeaf.disable(); before super so it can disable library.

7.

Adjust AndroidManifest.xml to 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 {



Tealeaf.enable();

}



}

}



}

20


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 onDestroy when activity is no longer in memory and gets garbage collected.

1.

Open the existing Java file that extends from android.app.Activity.

2.

Add these imports.

a.


import com.tl.uic.app.UICApplication; c.

import com.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 the onPause() method, add Tealeaf.onPause(this, logicalPageName);.

5.

In the onResume() method, add Tealeaf.onResume(this, logicalPageName);.

6.

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

7.

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

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

new JavaScriptInterface(this.getContext(),

Tealeaf.getPropertyName(webviewObject).getId()), "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 from UICActivity, set a logicalPageName to indicate the use of the activity. Otherwise, logicalPageName is set to the name of the class of the activity.

2.

If the prior step is not complete, call Tealeaf.logScreenview and 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);


21

Basic configuration

You must set up a target page on your web server.

See “Quick start for server configuration” on page 88.

Set the target page's address in the TLFConfigurableItems.properties

configuration file under the key PostMessageUrl.

See "Configuration File" in the IBM Tealeaf Android SDK 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 Android SDK, 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 Android SDK Guide.

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

Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual.

Configuring sessionization for Android applications on the client

The Android SDK 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 with SessionTimeout in


. 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 through TLTSID provide by

IBM Tealeaf, or through customer session ID, called JSESSIONID. Both methods function as a unique session identifier within the Android SDK environment for

IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer session ID or JSESSIONID.

The following is a typical setting in TLFConfigurableItems.properties using customer session ID.

#Sessionization settings on customer cookies

CookieUrl = http://www.sample.com

CookieDomain = .sample.com

CookiePath = /

22


CookieParam = JSESSIONID

CookieExpires = false

SessionTimeout=30

SessoinTimeoutKillSwitch=false

In this example, the cookie expires 30 minutes from current time. When the session timeout occurs, Android SDK 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 the JSESSIONID was consistently changing. When using cookies generated from customer application server, SessoinTimeoutKillSwitch can be set to true or false. Setting the SessoinTimeoutKillSwitch to false means the session timeout user does not go to recheck on KillSwitchUrl to see if it is responding.

Network traffic used in application contains requests only:

Android SDK uses cookies to add values to the TLFConfigurableItems.properties

file.

Uses session ID generated by IBM Tealeaf Android SDK

Android SDK uses cookies to add the following values in


.

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

SessionTimeout=30

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.


23

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 using org.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 extended TLDefaultHttpClient class, 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 sessionId Tealeaf session id.

*/ public TLDefaultHttpClient(final HttpParams params, final String sessionId) { super(params); this.init(sessionId);

}

/**

* @param conman ClientConnectionManager.


*/ public TLDefaultHttpClient(final ClientConnectionManager conman, final HttpParams params) { super(conman, params); this.init(null);

}

/**


*/ private void init(final String sessionId) { final TLHttpRequestInterceptor tlHttpRequestInterceptor =

24


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;

/**


*/ public class TLHttpRequestInterceptor implements HttpRequestInterceptor { private String url; private final String sessionId;

/**

* Constructor.

*/ public TLHttpRequestInterceptor() { super(); this.sessionId = null;

}

/**

* Constructor.


*/ 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.

*/ public final void setUrl(final String url) { this.url = url;

}

/**

* {@inheritDoc}

*/


25

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);

}

}

}catch (final Exception e) {

Tealeaf.logException(e);

} request.addHeader("Cookie", cookies.toString());

LogInternal.log("Session cookie:" + cookies.toString());

}

}

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;

/**


*

*/ public class TLHttpResponseInterceptor implements HttpResponseInterceptor { private final TLHttpRequestInterceptor tlHttpRequestInterceptor; private final Date startTime; private final long initTime;

/**

26


public TLHttpResponseInterceptor(final TLHttpRequestInterceptor tlHttpRequestInterceptor) { this.tlHttpRequestInterceptor = tlHttpRequestInterceptor; this.startTime = new Date(); this.initTime = TLFCache.timestampFromSession();

}

* Constructor.

*

* @param tlHttpRequestInterceptor TLHttpRequestInterceptor used.

*/

/**

* {@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 Android SDK.

// 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


file and set the SetGestureDetector property 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 gesture view.

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.


27

You can use either the onTouchEvent or the dispatchTouchEvent. 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:

28


Table 2. Swipe gestures

Gesture name Description

Swipe vertically

Swipe horizontally

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


For a swipe horizontally gesture, one-finger:

1.


2.

continues to engage screen while it moves left or right

3.


Note:


Image displayed in Replay

Resize gestures

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

Note:

See the IBM Tealeaf Customer Experience 9.0.1 Release Notes for information about a known limitation for handling some iOS pinch gestures.

Table 3. Resize gestures


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


Pinch close

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.

This gesture is a two-finger gesture.

Note:

Accompanying arrows indicate the direction

(open or close) of the pinch

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.


Note:




29

Unresponsive gesture events captured

Unresponsive gestures are gestures that do not respond when a user tries to select items in an application or tries to adjust views in the application. Like other gesture events, unresponsive gestures are captured by Tealeaf.

Unresponsive gestures are displayed graphically in BBR as orange outlined icons accompanied by a circled "X" . The circled "X" denotes that the gesture was unresponsive. For example, if a double tap gesture did not yield a response in the mobile application, then at replay time that gesture is displayed with the following icon in BBR:

The following table lists the unresponsive gestures that are captured from web and mobile apps and shows the images that are displayed in BBR:

Table 4. Unresponsive gestures and icons

Unresponsive Gesture

Tap gestures


Unresponsive tap

Unresponsive double tap

Unresponsive tap and hold

Swipe gestures

30


Table 4. Unresponsive gestures and icons (continued)


Tap gestures

Swipe vertically


Swipe horizontally

Note:

Accompanying arrows indicate the direction of the swipe.

Resize gestures

Pinch open

Note:


Pinch close

Note:

Accompanying arrows indicate the direction of the pinch.

Note:


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.


31

For example, you modify the MainActivity.java file and call the

Tealeaf.dispatchTouchEvent method inside dispatchTouchEvent or onTouchEvent method.

To use the Android gestures module, you must the Android Support Library android-support-v4.jar

together with Tealeaf SDK uicandroid.jar. The android-support-v4.jar

is 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.ja

r

1.

Open the MainActivity.java file for your application.

2.

Override either the dispatchTouchEvent or the onTouchEvent method, depending on how you are using gestures in your application:

IF your application is...

using a customized gesture view not using a customized gesture view

THEN...

Override the dispatchTouchEvent publc boolean dispatchTouchEvent

( MotionEvent e) {

}

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

Override the onTouchEvent 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);

}

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.properties file.

1.

Edit the TLFConfiguratableItems.properties file.

32


2.

Set SetGestureDetector to true.

3.

Save and exit the TLFConfiguratableItems.properties file.

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 logException API, 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

public static Boolean logException(final

Throwable exception, final

HashMap<String, String> data,

final Boolean unhandled)

Parameters

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) {

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

Tealeaf.logException(e, data, false);


33

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 the exception method to the method for which you want to log the exceptions.

Add @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

}


HashMap<String, String> data = new HashMap<String, String>();

}


Android application geolocation

You can log geolocation information for the users of your applications. You can configure automatic geolocation logging when the application starts or you can use

APIs to log geolocation information at specific places in your application. Replay and reporting of geolocation data is not available currently.

Automatic logging

You configure automatic logging with the TLFConfigurableItems.properties file and the manifest file.

To give permission to the device to log geolocation data, add this line

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" > to the android manifest file. For example:





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

There are three configurable items you can set in the


:

Property

LogLocationEnabled

LogLocationTries

Description

Use this property to enable geolocation logging. Values are: v True - logging is enabled v False - logging is not enabled

Use this property to set the number of times the device tries to get the geolocation information when the device's signal is weak.

34


Property

LogLocationTimeout

Description

Use this property to set the amount of time between retries for the device to get the geolocation information when the device's signal is weak.

For example, when the device signal is weak you want the device to try 3 times to get the geolocation signal and for the device to wait 30 seconds between retries, you set the configurable items to these values:

#Auto Geolocation logging enabled or not

LogLocationEnabled=true

LogLocationTries=3

LogLocationTimeout=30

APIs

There are three APIs you can use to manually enable geolocation information logging in your application: v public static Boolean logGeolocation() - Use this API at a specific point in your application to log geolocation only at that point.

v public static GeoLocation logGeolocation(final Boolean getGeolocation) -

Use this API at a specific point in your application to return a geolocation object that contains latitude, longitude, and accuracy values.

v public static Boolean logGeolocation(final int logLevel) - Use this API at a specific point in your application to log geolocation information based on log level.

Logging geolocation information in your application automatically:

Before you begin this task you need to know: v The number of times you want the application to try to get the geolocation information when the signal is weak.

v The amount of time, in seconds, that you want the application to wait before again trying to get the geolocation information.

1.

In your application in Eclipse, open the TLFConfigurableItems.properties file.

a.

Set LogLocationEnabled to true.

b.

Set LogLocationTries to the number of times you want the application to try log the geolocation information.

c.

Set LogLocationTimeout to the number of seconds that the device should retry when the signal is weak.

d.

Save and exit the file.

2.

In your application in Eclipse, open the AndroidManifest.xml file.

a.

Add this line <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" > to the file.

b.

Save and exit the file.

Hybrid applications

An application is considered to be hybrid if it contains a WebView in the Android application.

If you use a WebView, you must use UICWebView to log request activity in the

WebView. UICWebView extends the base WebView from the Android Framework,


35

which inserts the IBM Tealeaf header with the current session ID for sessionization.

If you decide not to use UICWebView, then you need to extend a Webview to add sessionization.

See "UICWebView Class" in the IBM Tealeaf Android SDK Guide.

Extend android.webkit.WebView:

This sample code shows how the base Android WebView is extended with

UICWebView .

/*******************************************************************************

* Licensed Materials - Property of IBM

* (C) Copyright IBM Corp. 2015

* US Government Users Restricted Rights - Use, duplication or disclosure

* restricted by GSA ADP Schedule Contract with IBM Corp.

******************************************************************************/ package com.tl.uic.webkit; import java.util.Date; import java.util.Map; import org.apache.http.HttpResponse; import android.annotation.SuppressLint; import android.app.Activity; import android.content.Context; import android.util.AttributeSet; import android.webkit.WebView; import com.tl.uic.TLFCache; import com.tl.uic.Tealeaf; import com.tl.uic.javascript.JavaScriptInterface; import com.tl.uic.model.PropertyName;

/**

* @author ohernandezltmac

*/ public class UICWebView extends WebView { private Date endLoad; private Date startLoad; private String url; private HttpResponse httpResponse; private Date initTime; private long responseTime; private long connectionInitFromSession; private PropertyName webViewId;

/**

* @param context Android context.

*/ public UICWebView(final Context context) { super(context); init();

}

/**


* @param attrs an AttributeSet passed to our parent.

*/ public UICWebView(final Context context, final AttributeSet attrs) { super(context, attrs); init();

}

/**

36


public UICWebView(final Context context, final AttributeSet attrs, final int defStyle) { super(context, attrs, defStyle); init();

}



* @param defStyle the default style resource ID.

*/

/**

* When page finished loading.

*

* @return When page finished loading.

*/ public final Date getEndLoad() { return endLoad;

}

/**


*

* @param endLoad When page finished loading.

*/ public final void setEndLoad(final Date endLoad) { this.endLoad = endLoad;

}

/**

* When page starts loading.

*

* @return When page starts loading.

*/ public final Date getStartLoad() { return startLoad;

}

/**


*

* @param startLoad When page starts loading.

*/ public final void setStartLoad(final Date startLoad) { this.startLoad = startLoad;

}

/**

* HttpResponse from the connection.

*

* @return HttpResponse from the connection.

*/ public final HttpResponse getHttpResponse() { return httpResponse;

}

/**


*

* @param httpResponse HttpResponse from the connection.

*/ public final void setHttpResponse(final HttpResponse httpResponse) { this.httpResponse = httpResponse;

}

/**

* Initial time from the connection.

*


37

public final Date getInitTime() { return initTime;

}

* @return Initial time from the connection.

*/

/**


*

* @param initTime Initial time from the connection.

*/ public final void setInitTime(final Date initTime) { this.initTime = initTime; this.connectionInitFromSession = TLFCache.timestampFromSession();

}

/**

* Response time from the connection.

*

* @return Response time from the connection.

*/ public final long getResponseTime() { return responseTime;

}

/**


*

* @param responseTime Response time from the connection.

*/ public final void setResponseTime(final long responseTime) { this.responseTime = responseTime;

}

/**

* Get webview id.

*

* @return Webview id.

*/ public final PropertyName getWebViewId() { return webViewId;

}

/**

* Set webview id.

*

* @param webviewId Webview id.

*/ public final void setWebViewId(final PropertyName webviewId) { this.webViewId = webviewId;

}

/**

* {@inheritDoc}

*/

@SuppressWarnings("PMD.NullAssignment")

@Override public void loadData(final String data, final String mimeType, final String encoding) { this.url = null; this.initTime = null; this.connectionInitFromSession = 0; this.responseTime = 0; this.httpResponse = null; this.startLoad = new Date(); super.loadDataWithBaseURL(this.url, data, mimeType, encoding, "");

}

38


/**

* {@inheritDoc}

*/

@SuppressLint("NewApi")

@Override public void loadUrl(final String url) { loadUrl(url, null);

}

/**

* {@inheritDoc}

*/ public final void loadUrl(final String url, final Map<String, String> extraHeaders) { this.url = url;

Tealeaf.setTLCookie(this.url); super.loadUrl(url, extraHeaders);

}

/**

* Initializes WebView.

*/ private void init() { setStartLoad(new Date());

// Need it when in Eclipse editor mode if (!this.isInEditMode()) { this.setWebViewClient(new UICWebViewClient()); this.setWebChromeClient(new UICWebChromeClient((Activity) this.getContext())); this.setWebViewId(Tealeaf.getPropertyName(this)); this.addJavascriptInterface(new JavaScriptInterface(this.getContext(), getWebViewId().getId()), "tlBridge");

}

}

/**

* Log the load time of the WebView.

*

* @return If log connection was added to queue.

*/ public final Boolean logConnection() { final long endTime = this.getEndLoad() != null ?

this.getEndLoad().getTime() : 0; final long startTime = this.getStartLoad() != null ?

this.getStartLoad().getTime() : 0; final long loadTime = endTime - startTime; return Tealeaf.logConnection(this.url, this.httpResponse, this.connectionInitFromSession, loadTime, this.responseTime);

}

}

Extend android.webkit.WebViewClient:

The sample code that follows extends the base Android WebViewClient with

UICWebViewClient .

/*******************************************************************************





******************************************************************************/ package com.tl.uic.webkit; import android.annotation.SuppressLint; import android.os.Build;


39

import android.webkit.WebView; import android.webkit.WebViewClient;

/**


*

*/ public class UICWebViewClient extends WebViewClient {

/**

* {@inheritDoc}

*/

@Override public boolean shouldOverrideUrlLoading(final WebView view, final String url) { view.loadUrl(url); return true;

}

/**

* {@inheritDoc}

*/


@Override public void onPageFinished(final WebView view, final String url) {

// Get the call back mapping string to be evaluated/loaded as

Javascript code final String javascriptString = com.tl.uic.javascript.JavaScriptInterface.

hybridBridgeRegisterCallback(); if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) { view.evaluateJavascript(javascriptString, null);

} else { view.loadUrl("javascript:" + javascriptString);

}

}

}

Sessionization for PhoneGap based Applications:

Since there are no requests and responses being sent back to the server, IBM

Tealeaf does not require extending of WebView to add sessionization.

Configuring DOM Capture and Replay for Native Android applications that cannot use PCA:

You configure DOM capture for a Native iOS application that cannot use PCA by modifying the defaultconfiguration.js file. If the HTML page in the webview does not fire on page load or if the page changes dramatically, you need to fire

DOM capture from within your Native Android application.

Before you do this task you must install the UIC library in your native application.

All of the modifications that you make are in your Native Android application.

1.

Modify the defaultconfiguration.js file and set the DOM Capture options that you want to use: replay: {





40


triggers: [

{ event: "load"

}

],

// DOM Capture options removeScripts: true // Should script tags be removed from the captured snaphot

}

} options: { captureFrames: true, // Should child frames/iframes be captured

}

2.



} else {



} else { dcid = TLT.logDOMCapture(window.document, {}); console.log(’logDOMCapture:’ + dcid);

}

}

Hybrid application bridge for Android APIs:

An Android hybrid application is a native application that uses WebView control as part of the UI components. Tealeaf Android SDK provides JavaScript interface

APIs integrated with CX UI Capture j2, which can be started from JavaScript functions to access native methods in hybrid application.

Tealeaf Android SDK APIs available to JavaScript

When you develop hybrid applications, you embed WebView component within a larger Android application. You can access exposed Android native methods from the UI Capture j2 global JavaScript object called "TLT" with methods that you use in your JavaScript code. This table lists and gives examples of the methods that you can include in your JavaScript code:

Method

Enable Tealeaf Framework

Example

/**

* Public API to enable Tealeaf framework.

* @returns {void}

*/ enableTealeafFramework();


41

Method

Disable Tealeaf Framework

Log Screen Capture

Start New Tealeaf Session

Current Session ID

Default Value for Configurable Item

Value for Configurable Item

Example

/**

* Public API to disable Tealeaf framework.

* @returns {void}

*/ disableTealeafFramework();

/**

* Public API to add a screenshot capture.

* @returns {void}

*/ logScreenCapture();

/**

* Public API to start a new Tealeaf session.

* @returns {void}

*/ startNewTLFSession();

/**

* Public API to start get current

Tealeaf session Id.

* @returns {String} Current session

Id

*/ currentSessionId();

/**

* Public API to get default value of a configurable item in

* TLFConfigurableItems.properties

file.

* @param {String} configItem This is the name of the configurable item.

* @returns {String} The value for the item.

*/ defaultValueForConfigurableItem

(configItem);

/**

* Public API to get the value of a configurable item either from


file

* or in memory data structure.



*/ valueForConfigurableItem(configItem);

42


Method

Set Configurable Item

Add Additional HTTP Header

Log Custom Event Bridge

Example

/**

* Public API to set the value of a configurable item in


* file.


* @param {String} value The value assign to the configItem.

* @returns {boolean} Wether item was set.

*/ setConfigurableItem(configItem, value);

/**

* Public API to add additional http header.

* @param {String} key This is the key of the configurable item.



*/ addAdditionalHttpHeader(key, value);

/**

* Public API to log custom event.

* @param {String} eventName A custom event name.

* @param {String} jsonData JSON data string.

* @param {int} logLevel Tealeaf library logging level for the event.


*/ logCustomEventBridge(eventName, jsonData, logLevel);

Example of how a native Android API is started

This example shows how to start a native method to enable Tealeaf Framework on a UI Capture j2 "TLT" instance using JavaScript:

<script type="text/javascript">

// Example of calling the native API to enable Tealeaf Framework using Javascript

TLT.enableTealeafFramework();

</script>

Sample test HTML file that starts supported native methods in JavaScript

This example is an HTML file that starts supported native methods in JavaScript:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>

<script type="text/javascript" src="js/tealeaf.js"></script>

<script type="text/javascript" src="js/defaultconfiguration.js" ></script>

<title>test APIs</title>


43

<body>

<h2>Test page for Android bridge APIs in hybrid app</h2>

<h3>Click on below buttons to run tests:</h3>

<input type="button" style="width: 150px; height: 30px; font-size: 20px" value="Screen Capture" onclick="TLT.logScreenCapture();return false;"/>

<input type="button" style="width: 150px; height: 30px; font-size: 20px" value="Native APIs" onclick="runBridgeNativeTealeafAPIs();return false;"/>

<p/>

<p>Test native APIs output here:

<div id="queueData"></div>

</body>

<script type="text/javascript"> function htmlConsoleLog(textData, apiRetVal){ var para = document.createElement("p"); var node; if( apiRetVal !== undefined && apiRetVal !== null )

{

} else

{ node = document.createTextNode(textData + " returned: " + apiRetVal); node = document.createTextNode(textData );

} para.appendChild(node); var element = document.getElementById("queueData"); element.appendChild(para);

} function runBridgeNativeTealeafAPIs() { htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- Calling Tealeaf native APIs -----’ ); var apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf -----’ );

TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling disableTealeaf -----’ );

TLT.disableTealeafFramework(); var apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf -----’ );

TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling defaultValueForConfigurableItem

(PostMessageUrl) -----’ ); var PostMessageUrlVal = TLT.defaultValueForConfigurableItem

(’PostMessageUrl’); htmlConsoleLog( ’----- defaultValueForConfigurableItem -----’,

PostMessageUrlVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItem("PostMessageUrl",

"aValidPostUrl") -----’ );

44


apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, ’aValidPostUrl’); htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem

("PostMessageUrl") -----’ ); apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItem(PostMessageUrl,

’ + PostMessageUrlVal + ’) -----’ ); apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, PostMessageUrlVal ); htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem

("PostMessageUrl") -----’ ); apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling startNewTLFSession -----’ ); apiRetVal = TLT.startNewTLFSession(); htmlConsoleLog( ’----- startNewTLFSession -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling addAdditionalHttpHeader -----’ );

TLT.addAdditionalHttpHeader(’HeaderFromJavaScript’,

’HeaderValueFromJavaScript’); htmlConsoleLog( ’----- addAdditionalHttpHeader -----’ ); apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf again -----’ );

TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; var str = ’{\’key1AndroidBridge\’: \’value1AndroidBridge\’,

\’key2AndroidBridge\’: \’value2AndroidBridge\’}’; htmlConsoleLog( ’----- Calling logCustomEvent("Test Android Bridge Custom

Event",’ + str +’) -----’ ); apiRetVal = TLT.logCustomEventBridge(’Test Android Bridge Custom Event’, str, 0); htmlConsoleLog( ’----- logCustomEvent(Test Android Bridge Event, ’ + str +’ ) -----’, apiRetVal ); htmlConsoleLog( ’----- Done Calling Tealeaf native APIs -----’ ); htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- -------------------------------- -----’ );

}

</script>

</head>

</html>

Accessing native Android methods with JavaScript with Tealeaf customized WebView:

When you crate hybrid applications, you can access native Android methods with

JavaScript, you use the Tealeaf customized WebView.


45

Before you begin this task, you must:

1.

Install the most recent Tealeaf Android SDK.

2.

Implement the Android SDK following the instructions in the documentation.

3.

Include the most recent UI Capture j2 JavaScript source file.

1.

Add WebView to your application. Specify a length, height, weight, and ID that suits your application:

<WebView android:id="@+id/my_webview" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="1" />

2.

In your activity, locate the WebView and load your HTML file: public class MainActivity extends ActionBarActivity { private UICWebView mUICWebView; private String logicalPageName = "BridgeAppActivity";

@Override protected void onCreate(Bundle savedInstanceState) {

// Initialize tealeaf with a reference to application

Tealeaf tealeaf = new Tealeaf(this.getApplication()); super.onCreate(savedInstanceState); setContentView(R.layout.activity_main);

// Load HTML file from local resource in the UICWebview mUICWebView = (UICWebView) findViewById(R.id.uic_webview);

// Modify the Url for your hybrid app mUICWebView.loadUrl("file:///android_asset/www/test.html");

WebSettings webSettings = mUICWebView.getSettings(); webSettings.setJavaScriptEnabled(true);

}

3.

Copy the application's HTML and JavaScript files to the /assets/www folder in your Android project.

Install the Eclipse Tealeaf plug-in for Android development in your application

Use of the Tealeaf Logging Frameworks for mobile native applications requires the

Tealeaf CX Mobile license for Mobile App. For more information, contact your

Tealeaf representative. Licensees must implement in their apps code that is provided by Tealeaf. For more information on downloading IBM Tealeaf, see IBM

Passport Advantage Online.

Install process

To install and configure the Eclipse Tealeaf plug-in in your Eclipse project you:

1.

Add the Eclipse Tealeaf plug-in to your project

2.

Convert your project to an Android + Tealeaf project

3.

Configure initial Eclipse Tealeaf plug-in properties

4.

Extend Android classes with or without the extended IBM Tealeaf classes.

Tealeaf package contents

A single file contains the Android SDK and its software components.

IBM Tealeaf Android SDK is delivered in the IBM Tealeaf Android SDK 8.8 - iOS

Logging Framework for Windows within the IBM Passport Advantage Online.

46


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

- 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 Android SDK.

– TLFConfigurableItems.properties: Configuration file.

v SampleCode : Contains the following versions of a sample Android application.

– UICSP_Clean: An Android application without IBM Tealeaf Android SDK integrated.

– UICSP_ManualLog: An Android application with IBM Tealeaf Android SDK integrated

– UICSP_ManualLog_ServerSessionID: An Android application with IBM Tealeaf

Android SDK integrated by using a session ID provided from a web application.

See "Sample Code" in the IBM Tealeaf Android SDK 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.

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.


47

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 Android SDK has the following effects on resources of the visitor's device.

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

48


Add Eclipse Tealeaf plug-in to your Eclipse Android project

After you acquire IBM Tealeaf Android SDK, install the Android SDK libraries into an Android application project.

Your Eclipse project must include the recommended frameworks. Testing of the

Android SDK involved Android 2.2 to 4.3.3.

Plug-in installed widgets

When you install the Eclipse Tealeaf plug-in, several widgets are installed. These widgets already have Tealeaf logging setup. This table lists and describes the widgets that are installed:

Widget

AutoCompleteTextView

Button

CheckBox

DatePicker

EditText

ExpandableListView

HorizontalScrollView

ImageButton

ImageView

LinearLayout

ListView

MultiAutoCompleteTextView

RadioButton

RadioGroup

RatingBar

Description

An editable text view that shows completion suggestions automatically while the user is typing.

Represents a push-button widget.

A two-states button that can be either checked or unchecked.

A widget for selecting a date by selecting a year, month, and day.

A thin veneer over TextView that configures itself to be editable.

A view that shows items in a vertically scrolling two-level list.

Layout container for a view hierarchy that can be scrolled by the user, allowing it to be larger than the physical display.

Displays a button with an image (instead of text) that can be pressed or clicked by the user.

Displays an arbitrary image, such as an icon.

A Layout that arranges its children in a single column or a single row.

A view that shows items in a vertically scrolling list.

An editable text view, extending

AutoCompleteTextView , that can show completion suggestions for the substring of the text where the user is typing instead of necessarily for the entire thing.

A radio button is a two-states button that can be either checked or unchecked.

This class is used to create a multiple-exclusion scope for a set of radio buttons. Checking one radio button that belongs to a radio group clears any previously checked radio button within the same group.

An extension of SeekBar and ProgressBar that shows a rating in stars.


49

Widget

RelativeLayout

ScrollView

SeekBar

Spinner

Switch

TextView

TimePicker

ToggleButton

Description

A Layout where the positions of the children can be described in relation to each other or to the parent.

Layout container for a view hierarchy that can be scrolled by the user, allowing it to be larger than the physical display.

An extension of ProgressBar that adds a draggable thumb.

A view that displays one child at a time and lets the user pick among them.

A two-state toggle switch widget that can select between two options.

Displays text to the user and optionally allows them to edit it.

A view for selecting the time of day, in either 24 hour or AM/PM mode.

Displays checked/unchecked states as a button with a "light" indicator and by default is accompanied with the text "ON" or "OFF".

Adding the Eclipse Tealeaf plug-in to your project

You install the Eclipse Tealeaf plug-in JAR file in your Eclipse project to use Tealeaf with your project.

Before you begin, you must install: v Eclipse v Java v Android Development Toolkit

You must also have the location of the Eclipse Tealeaf plug-in installation files.

At the end of this task you are asked to restart Eclipse. Do this task when restarting Eclipse will not impact your work.

1.

Extract the TLFLibRelease.zip file. The Tealeaf folder is extracted. The Tealeaf folder contains all necessary files for the Android SDK and the plug-in.

2.

Open your project in Eclipse.

3.

From the Help menu, select Install New Software...

4.

In the Install window, select Add....

5.

In the Add window define the repository for the Eclipse Tealeaf plug-in files: a.

Enter a name for the Tealeaf and plug-in repository that you are creating.

b.

Enter the location of the files. If the files are on your local machine, select

Local...

and navigate to the files. If the files are in a compressed file or JAR file on your local machine, select Archive... and navigate to the files. If the files are on a website, enter the URL for the website in the Location: field.

c.

Click OK.

6.

In the Install window, select the files to install and click Next.

7.

Accept the license agreement.

8.

Click Finish to complete the installation.

50


9.

When prompted, restart Eclipse.

Converting your project to Android+Tealeaf

After you install the Tealeaf software in Eclipse and restart Eclipse, you convert your project to an Android + Tealeaf project. The convert process installs JAR and properties files in your project and installs a custom widgets library that you can use with your project. The first time you convert a project, you are prompted for the JAR file that installs the Tealeaf Android library file.

1.

Open your project in Eclipse.

2.

Right-click on your project and select Configure > Convert to Android +

Tealeaf project

.

3.

If this is the first time that you are using the plug-in you are asked for the

Tealeaf SDK: a.

Navigate to the repository where the Tealeaf software is located.

b.

Select the tealeafandroidsdk.jar file.

c.

Click Open.

4.

In your project, open the Custom & Library Views.

5.

Click Refresh to see the custom widgets that were added.

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.


Everything that you configure is in the TLFConfigurableItems.properties file. The


file is in the Install Package.

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.

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

Whether you see logcat messages is set with the DisplayLogging property.

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


51

page. The Target page is set with the PostMessageUrl property.

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 the KillSwitchEnabled property. 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. Set GetImageDataOnScreenLayout to YES to capture base 64 data. Set

GetImageDataOnScreenLayout to NO to 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 LoggingLevel property.

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


file in the Assets folder of your Eclipse project.

1.

In your Eclipse, open the TLFConfigurableItems.plist file.

2.

Set the DisplayLogging to False.

3.

Set the PostMessageUrl to the URL of the target page for your app.

4.

Set the KillSwitchEnabled to True.

5.

Set the KillSwitchUrl to the URL for the kill switch for your app.

6.

Set the GetImageDataOnScreenLayout to False.

7.

Set the LoggingLevel to an appropriate level for development, testing, or production.

8.

Save and exit the TLFConfigurableItems.properties file.

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

52


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.

Modify AndroidManifest.xml file 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 garbage collected

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 onCreate to initialize the library.


53

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 from com.tl.uic.app.UICApplication instead of android.app.Application

.

2.




3.

In onCreate() method, add Tealeaf.enable() that initializes capture of user actions in the application.

4.


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

5.

Add the following permissions in AndroidManifest.xml.





This example shows the lines that you add to the AdroidManifest.xml file: import com.tl.uic.Tealeaf; import com.tl.uic.app.UICApplication; public class MyApplication extends UICApplication {


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 events onPause, which happen when application goes to the background, onResume , which happens when application goes to foreground, and onDestroy 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 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 Android SDK 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.

54


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 the IBM Tealeaf Android SDK 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.


.

2.


Import com.tl.uic.Tealeaf; b.

Import com.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 screenshot because 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) screenshot

//To set to back background of super.onCreate(savedInstanceState);

Extending your custom Application class to point to the Tealeaf


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, onTerminate to clean up library, and onCreate to initialize the library. .

1.

Open the existing Java file that extends from the android.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.

In onCreate(): a.

Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the IBM

Tealeaf library with a reference to application instrumented.

b.


4.


Add Tealeaf.onLowMemory(); before super so it can adjust the library due to low memory.


55

5.

In onTerminate(): a.

Add Tealeaf.disable(); before super so it can disable the library.

6.


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

7.

Add these permissions to AndroidManifest.xml.





This example shows the lines you add to the file that extends the Application class: import android.app.Application; import com.tl.uic.Tealeaf; public class MyApplication extends Application {



Tealeaf.enable();

}



}

}



}

Extending your custom Activity class to point to the Tealeaf


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 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.


.

2.

Add this import: a.

Import com.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(""))) {

56


this.logicalPageName = this.getClass().getName().substring(this.getClass()

.getName().lastIndexOf(".") + 1);


}

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: import com.tl.uic.Tealeaf; public class BaseActivity extends Activity { private String logicalPageName;

/**


*

* @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);


}

/**


*

* @param logicalPageName


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

} 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();

}


57

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

After you install the SDK, you must complete more tasks to implement the SDK.

All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf plug-in for Tealeaf to work. All of these tasks are manual.

This table lists and describes the tasks that you complete to implement Tealeaf in your application:

Task

Log Screen Layout for Android Mobile App

Replay

Tealeaf SDK ONLY

Integration for Apache Cordova, PhoneGap, and IBM Worklight applications that use

Android classes without IBM Tealeaf classes

Implementing screenViews

Target page configuration

Data privacy

Configuring sessionization for Android applications on the client

Network traffic that is used in application contains requests only

Configure requests in Android application

Description

Configure logging screen layout to use JSON data not screen captures. Includes configuring logical pages names, alert dialogs, and keyboard events.

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 as segments for pages in which the state or context can be switched without rerendering the page.

Set up the target page that acknowledges that events are captured.

Specify the fields that are blocked or masked during capture.

Configure how session IDs are generated.

Uses non-IBM Tealeaf session ID

Hybrid application

Tealeaf supports network traffic that is used in applications that contain requests only.

Configure Tealeaf to put session identifiers in cookies.

Configure your generated session IDs to be used when sessions are enabled or new sessions started.

Configure your application to log request activity if you have a WebView in your 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

58


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

EditTexts by adding View IDs to the MaskIdList attribute in


.

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.


changes

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

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

#Capture native layout

LogViewLayoutOnScreenTransition=true

During predeployment, you must perform all the replay cases to collect all the images with GetImageDataOnScreenLayout set 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/activitylifecycle/starting.html.

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

// 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);


59

Replaying AlertDialogs

You need to know when an alert dialog is displayed so it can be captured correctly.

OnShowListener is 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

TextView based controls.

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

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


.getSystemService(Context.INPUT_METHOD_SERVICE); imm.showSoftInput(v, InputMethodManager.SHOW_FORCED);



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);


.getSystemService(Context.INPUT_METHOD_SERVICE); imm.hideSoftInputFromWindow(v.getWindowToken(), 0);



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, review ControlsActivity3.java in 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 tlType value in the json object that is sent back to the server.

60


ToggleButton and Switch


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


ImageView

Uses image template

FrameLayout, LinearLayout, ViewStub, View

Uses canvas template

AbsListView

Uses grid template

AlertDialog

Uses alert template

TabWidget

Uses tabBar template

TabHost

Uses tabContainer template

Integration for Apache Cordova, PhoneGap, and IBM Worklight applications using Android classes without IBM 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, onTerminate to clean up library, and onCreate to initialize the library. IBM

Tealeaf recommends this as a best practice.


61

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 from android.app.Application and add the following.

If application class is found, then continue to the next steps.

2.

Open the existing Java file that extends from android.app.Application class.

3.


a.



4.

In onCreate(): a.

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

b.


5.


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

6.

In onTerminate():: a.

Add Tealeaf.disable(); before super so it can disable library.

7.

Adjust AndroidManifest.xml to 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 {



Tealeaf.enable();

}



}

}



}

Example in AndroidManifest.xml

<application android:label="@string/app_name" android:debuggable="true" android:icon="@drawable/icon" android:name=".TLWorklightTealeafApplication" >

62


org.apache.cordova.DroidGap, com.worklight.androidgap.WLDroidGap file code changes:

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 onDestroy when activity is no longer in memory and gets garbage collected.

Locating the file that extends from org.apache.cordova.DroidGap, com.worklight.androidgap.WLDroidGap

1.

Open the existing Java file that extends from android.app.Activity.

2.


a.


import com.tl.uic.app.UICApplication; c.

import com.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 the following to class: private String logicalPageName = "MainPage";

4.

In onPause() method: a.

Add Tealeaf.onPause(this, logicalPageName);

5.

In onResume() method: a.

Add Tealeaf.onResume(this, logicalPageName);

6.

In onDestroy() method: a.

Add Tealeaf.onDestroy(this, logicalPageName);

7.

In onCreate(), add after super.onCreate( a.

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

appView.addJavascriptInterface(new

JavaScriptInterface(this.getContext(),

Tealeaf.getPropertyName(webviewObject).getId()), "tlBridge");

Example from IBM Worklight

package com.TLWorklightTealeaf; import android.os.Bundle; import com.tl.uic.Tealeaf; import com.tl.uic.javascript.JavaScriptInterface; import com.tl.uic.model.ScreenviewType; import com.worklight.androidgap.WLDroidGap; public class TLWorklightTealeaf extends WLDroidGap { private String logicalPageName = "MainPage";

@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);

// Log Screenview for this activity


63

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

//DeviceAuthManager.getInstance().setProvisioningDelegate(<Use default

ProvisioningDelegateImpl class or replace with your

IProvisioningDelegate implementation>);

// Add bridge for Tealeaf data to be sent back appView.addJavascriptInterface(new JavaScriptInterface(this.getContext(),

Tealeaf.getPropertyName(webviewObject).getId()), "tlBridge");

} super.loadUrl(getWebMainFilePath());

} public void onPause() {

// Handle Tealeaf during onPause event

Tealeaf.onPause(this, logicalPageName); super.onPause(); public void onResume() {


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

} public void onDestroy() {


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

}

}

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 from UICActivity, set a logicalPageName to indicate the use of the activity. Otherwise, logicalPageName is set to the name of the class of the activity.

2.

If the prior step is not complete, call Tealeaf.logScreenview and 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 88.

Set the target page's address in the TLFConfigurableItems.properties

configuration file under the key PostMessageUrl.


64


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 Android SDK, 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


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


Configuring sessionization for Android applications on the client

The Android SDK 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 with SessionTimeout in


. 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 through TLTSID provide by

IBM Tealeaf, or through customer session ID, called JSESSIONID. Both methods function as a unique session identifier within the Android SDK environment for

IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer session ID or JSESSIONID.

The following is a typical setting in TLFConfigurableItems.properties using 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, Android SDK 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 the JSESSIONID was consistently changing. When using cookies generated from customer application server, SessoinTimeoutKillSwitch can


65

be set to true or false. Setting the SessoinTimeoutKillSwitch to false means the session timeout user does not go to recheck on KillSwitchUrl to see if it is responding.

Network traffic used in application contains requests only:

Android SDK uses cookies to add values to the TLFConfigurableItems.properties

file.

Uses session ID generated by IBM Tealeaf Android SDK

Android SDK uses cookies to add the following values in


.

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

SessionTimeout=30

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 using org.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.

66


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

If you do not use the IBM Tealeaf extended TLDefaultHttpClient class, 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;

/**


*

*/ public class TLDefaultHttpClient extends DefaultHttpClient {

/**

*

*/ public TLDefaultHttpClient() { super(); this.init(null);

}

/**


*/ public TLDefaultHttpClient(final HttpParams params) { super(params); this.init(null);

}

/**



*/ public TLDefaultHttpClient(final HttpParams params, final String sessionId) { super(params); this.init(sessionId);

}

/**

* @param conman ClientConnectionManager.


*/ public TLDefaultHttpClient(final ClientConnectionManager conman, final HttpParams params) { super(conman, params); this.init(null);

}

/**


*/ 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.


67

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;

/**


*/ public class TLHttpRequestInterceptor implements HttpRequestInterceptor { private String url; private final String sessionId;

/**

* Constructor.

*/ public TLHttpRequestInterceptor() { super(); this.sessionId = null;

}

/**

* Constructor.


*/ 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.

*/ public final void setUrl(final String url) { 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,

68


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);

}

}

}catch (final Exception e) {

Tealeaf.logException(e);

} request.addHeader("Cookie", cookies.toString());

LogInternal.log("Session cookie:" + cookies.toString());

}

}

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;

/**


*

*/ 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();

}

/**


69

* {@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(); this.initTime, loadTime, responseTime);

} catch (final Exception e) {

LogInternal.logException(e);

} final long responseTime = endTime.getTime() - this.startTime.getTime();

Tealeaf.logConnection(this.tlHttpRequestInterceptor.getUrl(), response,

}

}

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 Android SDK.

// 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


file and set the SetGestureDetector property 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 gesture view.

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 the onTouchEvent or the dispatchTouchEvent. 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.

70


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 5. 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:


71

Table 6. Swipe gestures


Swipe vertically

Swipe horizontally


For a swipe vertically gesture, one-finger:

1.


2.

continues to engage screen while it moves up or down

3.


Note:



For a swipe horizontally gesture, one-finger:

1.


2.

continues to engage screen while it moves left or right

3.


Note:



Resize gestures

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

Note:

See the IBM Tealeaf Customer Experience 9.0.1 Release Notes for information about a known limitation for handling some iOS pinch gestures.

Table 7. Resize gestures


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


Pinch close

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.


This gesture is a two-finger gesture.

Note:



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.


Note:



72


Unresponsive gesture events captured

Unresponsive gestures are gestures that do not respond when a user tries to select items in an application or tries to adjust views in the application. Like other gesture events, unresponsive gestures are captured by Tealeaf.

Unresponsive gestures are displayed graphically in BBR as orange outlined icons accompanied by a circled "X" . The circled "X" denotes that the gesture was unresponsive. For example, if a double tap gesture did not yield a response in the mobile application, then at replay time that gesture is displayed with the following icon in BBR:

The following table lists the unresponsive gestures that are captured from web and mobile apps and shows the images that are displayed in BBR:

Table 8. Unresponsive gestures and icons


Tap gestures


Unresponsive tap

Unresponsive double tap

Unresponsive tap and hold

Swipe gestures


73

Table 8. Unresponsive gestures and icons (continued)


Tap gestures

Swipe vertically


Swipe horizontally

Note:


Resize gestures

Pinch open

Note:


Pinch close

Note:


Note:


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.

74


For example, you modify the MainActivity.java file and call the

Tealeaf.dispatchTouchEvent method inside dispatchTouchEvent or onTouchEvent method.

To use the Android gestures module, you must the Android Support Library android-support-v4.jar

together with Tealeaf SDK uicandroid.jar. The android-support-v4.jar

is 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.ja

r

1.

Open the MainActivity.java file for your application.

2.

Override either the dispatchTouchEvent or the onTouchEvent method, depending on how you are using gestures in your application:

IF your application is...

using a customized gesture view not using a customized gesture view

THEN...

Override the dispatchTouchEvent publc boolean dispatchTouchEvent

( MotionEvent e) {

}

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

Override the onTouchEvent 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);

}

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.properties file.

1.

Edit the TLFConfiguratableItems.properties file.


75

2.

Set SetGestureDetector to true.

3.

Save and exit the TLFConfiguratableItems.properties file.

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 logException API, 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

public static Boolean logException(final

Throwable exception, final

HashMap<String, String> data,

final Boolean unhandled)

Parameters

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

}

}


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


76


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 the exception method to the method for which you want to log the exceptions.

Add @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

}


HashMap<String, String> data = new HashMap<String, String>();

}


Hybrid applications

An application is considered to be hybrid if it contains a WebView in the Android application.

If you use a WebView, you must use UICWebView to log request activity in the

WebView. UICWebView extends the base WebView from the Android Framework, which inserts the IBM Tealeaf header with the current session ID for sessionization.

If you decide not to use UICWebView, then you need to extend a Webview to add sessionization.

See "UICWebView Class" in the IBM Tealeaf Android SDK Guide.

Extend android.webkit.WebView:

This sample code shows how the base Android WebView is extended with

UICWebView .

/*******************************************************************************





******************************************************************************/ package com.tl.uic.webkit; import java.util.Date; import java.util.Map; import org.apache.http.HttpResponse; import android.annotation.SuppressLint; import android.app.Activity; import android.content.Context; import android.util.AttributeSet; import android.webkit.WebView; import com.tl.uic.TLFCache; import com.tl.uic.Tealeaf;


77

import com.tl.uic.javascript.JavaScriptInterface; import com.tl.uic.model.PropertyName;

/**


*/ public class UICWebView extends WebView { private Date endLoad; private Date startLoad; private String url; private HttpResponse httpResponse; private Date initTime; private long responseTime; private long connectionInitFromSession; private PropertyName webViewId;

/**


*/ public UICWebView(final Context context) { super(context); init();

}

/**



*/ public UICWebView(final Context context, final AttributeSet attrs) { super(context, attrs); init();

}

/**



* @param defStyle the default style resource ID.

*/ public UICWebView(final Context context, final AttributeSet attrs, final int defStyle) { super(context, attrs, defStyle); init();

}

/**


*

* @return When page finished loading.

*/ public final Date getEndLoad() { return endLoad;

}

/**


*

* @param endLoad When page finished loading.

*/ public final void setEndLoad(final Date endLoad) { this.endLoad = endLoad;

}

/**


*

* @return When page starts loading.

*/

78


public final Date getStartLoad() { return startLoad;

}

/**


*

* @param startLoad When page starts loading.

*/ public final void setStartLoad(final Date startLoad) { this.startLoad = startLoad;

}

/**


*

* @return HttpResponse from the connection.

*/ public final HttpResponse getHttpResponse() { return httpResponse;

}

/**


*

* @param httpResponse HttpResponse from the connection.

*/ public final void setHttpResponse(final HttpResponse httpResponse) { this.httpResponse = httpResponse;

}

/**


*

* @return Initial time from the connection.

*/ public final Date getInitTime() { return initTime;

}

/**


*

* @param initTime Initial time from the connection.

*/ public final void setInitTime(final Date initTime) { this.initTime = initTime; this.connectionInitFromSession = TLFCache.timestampFromSession();

}

/**


*

* @return Response time from the connection.

*/ public final long getResponseTime() { return responseTime;

}

/**


*

* @param responseTime Response time from the connection.

*/ public final void setResponseTime(final long responseTime) { this.responseTime = responseTime;

}


79

/**

* Get webview id.

*

* @return Webview id.

*/ public final PropertyName getWebViewId() { return webViewId;

}

/**

* Set webview id.

*

* @param webviewId Webview id.

*/ public final void setWebViewId(final PropertyName webviewId) { this.webViewId = webviewId;

}

/**

* {@inheritDoc}

*/

@SuppressWarnings("PMD.NullAssignment")

@Override public void loadData(final String data, final String mimeType, final String encoding) { this.url = null; this.initTime = null; this.connectionInitFromSession = 0; this.responseTime = 0; this.httpResponse = null; this.startLoad = new Date(); super.loadDataWithBaseURL(this.url, data, mimeType, encoding, "");

}

/**

* {@inheritDoc}

*/


@Override public void loadUrl(final String url) { loadUrl(url, null);

}

/**

* {@inheritDoc}

*/ public final void loadUrl(final String url, final Map<String, String> extraHeaders) { this.url = url;

Tealeaf.setTLCookie(this.url); super.loadUrl(url, extraHeaders);

}

/**

* Initializes WebView.

*/ private void init() { setStartLoad(new Date());

// Need it when in Eclipse editor mode if (!this.isInEditMode()) { this.setWebViewClient(new UICWebViewClient()); this.setWebChromeClient(new UICWebChromeClient((Activity) this.getContext())); this.setWebViewId(Tealeaf.getPropertyName(this)); this.addJavascriptInterface(new JavaScriptInterface(this.getContext(), getWebViewId().getId()), "tlBridge");

80


}

}

/**

* Log the load time of the WebView.

*

* @return If log connection was added to queue.

*/ public final Boolean logConnection() { final long endTime = this.getEndLoad() != null ?

this.getEndLoad().getTime() : 0; final long startTime = this.getStartLoad() != null ?

this.getStartLoad().getTime() : 0; final long loadTime = endTime - startTime; return Tealeaf.logConnection(this.url, this.httpResponse, this.connectionInitFromSession, loadTime, this.responseTime);

}

}

Extend android.webkit.WebViewClient:

The sample code that follows extends the base Android WebViewClient with

UICWebViewClient .

/*******************************************************************************





******************************************************************************/ package com.tl.uic.webkit; import android.annotation.SuppressLint; import android.os.Build; import android.webkit.WebView; import android.webkit.WebViewClient;

/**


*

*/ public class UICWebViewClient extends WebViewClient {

/**

* {@inheritDoc}

*/

@Override public boolean shouldOverrideUrlLoading(final WebView view, final String url) { view.loadUrl(url); return true;

}

/**

* {@inheritDoc}

*/


@Override public void onPageFinished(final WebView view, final String url) {

// Get the call back mapping string to be evaluated/loaded as

Javascript code final String javascriptString = com.tl.uic.javascript.JavaScriptInterface.

hybridBridgeRegisterCallback(); if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) { view.evaluateJavascript(javascriptString, null);

} else {


81

view.loadUrl("javascript:" + javascriptString);

}

}

}

Sessionization for PhoneGap based Applications:

Since there are no requests and responses being sent back to the server, IBM

Tealeaf does not require extending of WebView to add sessionization.

Configuring DOM Capture and Replay for Native Android applications that cannot use PCA:

You configure DOM capture for a Native iOS application that cannot use PCA by modifying the defaultconfiguration.js file. If the HTML page in the webview does not fire on page load or if the page changes dramatically, you need to fire

DOM capture from within your Native Android application.

Before you do this task you must install the UIC library in your native application.

All of the modifications that you make are in your Native Android application.

1.

Modify the defaultconfiguration.js file and set the DOM Capture options that you want to use: replay: {





triggers: [

{ event: "load" options: { captureFrames: true, // Should child frames/iframes be captured removeScripts: true // Should script tags be removed from the captured snaphot

}

}

}

],

// DOM Capture options

}

2.



} else {



} else {

82


dcid = TLT.logDOMCapture(window.document, {}); console.log(’logDOMCapture:’ + dcid);

}

}

Hybrid application bridge for Android APIs:

An Android hybrid application is a native application that uses WebView control as part of the UI components. Tealeaf Android SDK provides JavaScript interface

APIs integrated with CX UI Capture j2, which can be started from JavaScript functions to access native methods in hybrid application.

Tealeaf Android SDK APIs available to JavaScript

When you develop hybrid applications, you embed WebView component within a larger Android application. You can access exposed Android native methods from the UI Capture j2 global JavaScript object called "TLT" with methods that you use in your JavaScript code. This table lists and gives examples of the methods that you can include in your JavaScript code:

Method

Enable Tealeaf Framework

Disable Tealeaf Framework

Log Screen Capture

Start New Tealeaf Session

Current Session ID

Example

/**

* Public API to enable Tealeaf framework.

* @returns {void}

*/ enableTealeafFramework();

/**

* Public API to disable Tealeaf framework.

* @returns {void}

*/ disableTealeafFramework();

/**

* Public API to add a screenshot capture.

* @returns {void}

*/ logScreenCapture();

/**

* Public API to start a new Tealeaf session.

* @returns {void}

*/ startNewTLFSession();

/**

* Public API to start get current

Tealeaf session Id.

* @returns {String} Current session

Id

*/ currentSessionId();


83

Method

Default Value for Configurable Item

Value for Configurable Item

Set Configurable Item

Add Additional HTTP Header

Log Custom Event Bridge

Example

/**

* Public API to get default value of a configurable item in


file.



*/ defaultValueForConfigurableItem

(configItem);

/**

* Public API to get the value of a configurable item either from


file

* or in memory data structure.



*/ valueForConfigurableItem(configItem);

/**

* Public API to set the value of a configurable item in


* file.




*/ setConfigurableItem(configItem, value);

/**

* Public API to add additional http header.

* @param {String} key This is the key of the configurable item.



*/ addAdditionalHttpHeader(key, value);

/**

* Public API to log custom event.

* @param {String} eventName A custom event name.

* @param {String} jsonData JSON data string.

* @param {int} logLevel Tealeaf library logging level for the event.


*/ logCustomEventBridge(eventName, jsonData, logLevel);

84


Example of how a native Android API is started

This example shows how to start a native method to enable Tealeaf Framework on a UI Capture j2 "TLT" instance using JavaScript:

<script type="text/javascript">

// Example of calling the native API to enable Tealeaf Framework using Javascript

TLT.enableTealeafFramework();

</script>

Sample test HTML file that starts supported native methods in JavaScript

This example is an HTML file that starts supported native methods in JavaScript:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>

<script type="text/javascript" src="js/tealeaf.js"></script>

<script type="text/javascript" src="js/defaultconfiguration.js" ></script>

<title>test APIs</title>

<body>

<h2>Test page for Android bridge APIs in hybrid app</h2>

<h3>Click on below buttons to run tests:</h3>

<input type="button" style="width: 150px; height: 30px; font-size: 20px" value="Screen Capture" onclick="TLT.logScreenCapture();return false;"/>

<input type="button" style="width: 150px; height: 30px; font-size: 20px" value="Native APIs" onclick="runBridgeNativeTealeafAPIs();return false;"/>

<p/>

<p>Test native APIs output here:

<div id="queueData"></div>

</body>

<script type="text/javascript"> function htmlConsoleLog(textData, apiRetVal){ var para = document.createElement("p"); var node; if( apiRetVal !== undefined && apiRetVal !== null )

{

} else

{ node = document.createTextNode(textData + " returned: " + apiRetVal); node = document.createTextNode(textData );

} para.appendChild(node); var element = document.getElementById("queueData"); element.appendChild(para);

} function runBridgeNativeTealeafAPIs() { htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- Calling Tealeaf native APIs -----’ ); var apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf -----’ );

TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null;


85

htmlConsoleLog( ’----- Calling disableTealeaf -----’ );

TLT.disableTealeafFramework(); var apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf -----’ );

TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling defaultValueForConfigurableItem

(PostMessageUrl) -----’ ); var PostMessageUrlVal = TLT.defaultValueForConfigurableItem

(’PostMessageUrl’); htmlConsoleLog( ’----- defaultValueForConfigurableItem -----’,

PostMessageUrlVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItem("PostMessageUrl",

"aValidPostUrl") -----’ ); apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, ’aValidPostUrl’); htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem

("PostMessageUrl") -----’ ); apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItem(PostMessageUrl,

’ + PostMessageUrlVal + ’) -----’ ); apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, PostMessageUrlVal ); htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem

("PostMessageUrl") -----’ ); apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling startNewTLFSession -----’ ); apiRetVal = TLT.startNewTLFSession(); htmlConsoleLog( ’----- startNewTLFSession -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling addAdditionalHttpHeader -----’ );

TLT.addAdditionalHttpHeader(’HeaderFromJavaScript’,

’HeaderValueFromJavaScript’); htmlConsoleLog( ’----- addAdditionalHttpHeader -----’ ); apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf again -----’ );

TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; var str = ’{\’key1AndroidBridge\’: \’value1AndroidBridge\’,

\’key2AndroidBridge\’: \’value2AndroidBridge\’}’;

86


htmlConsoleLog( ’----- Calling logCustomEvent("Test Android Bridge Custom

Event",’ + str +’) -----’ ); apiRetVal = TLT.logCustomEventBridge(’Test Android Bridge Custom Event’, str, 0); htmlConsoleLog( ’----- logCustomEvent(Test Android Bridge Event, ’ + str +’ ) -----’, apiRetVal ); htmlConsoleLog( ’----- Done Calling Tealeaf native APIs -----’ ); htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- -------------------------------- -----’ );

}

</script>

</head>

</html>

Accessing native Android methods with JavaScript with Tealeaf customized WebView:

When you crate hybrid applications, you can access native Android methods with

JavaScript, you use the Tealeaf customized WebView.

Before you begin this task, you must:

1.

Install the most recent Tealeaf Android SDK.

2.

Implement the Android SDK following the instructions in the documentation.

3.

Include the most recent UI Capture j2 JavaScript source file.

1.

Add WebView to your application. Specify a length, height, weight, and ID that suits your application:

<WebView android:id="@+id/my_webview" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="1" />

2.

In your activity, locate the WebView and load your HTML file: public class MainActivity extends ActionBarActivity { private UICWebView mUICWebView; private String logicalPageName = "BridgeAppActivity";

@Override protected void onCreate(Bundle savedInstanceState) {

// Initialize tealeaf with a reference to application

Tealeaf tealeaf = new Tealeaf(this.getApplication()); super.onCreate(savedInstanceState); setContentView(R.layout.activity_main);

// Load HTML file from local resource in the UICWebview mUICWebView = (UICWebView) findViewById(R.id.uic_webview);

// Modify the Url for your hybrid app mUICWebView.loadUrl("file:///android_asset/www/test.html");

WebSettings webSettings = mUICWebView.getSettings(); webSettings.setJavaScriptEnabled(true);

}

3.

Copy the application's HTML and JavaScript files to the /assets/www folder in your Android project.


87

Quick start for server configuration

This section describes the basic steps to configure the IBM Tealeaf CX Passive

Capture Application and Windows based servers to capture and process data that is submitted from the Android SDK.

To enable processing of submitted data, you complete the steps in the following sections.

Target page for traffic capture

IBM Tealeaf is designed to capture traffic between a client and a web server. To facilitate capture, you must add a target page to your web server environment to which the Android SDK can submit posts.

You can use the same target page that is available for IBM Tealeaf CX UI Capture for AJAX.

See "UI Capture for Ajax Installation and Implementation" in the IBM Tealeaf CX UI

Capture for AJAX Guide.

After you add the target page to your web environment and enable the appropriate access permissions, you must configure the URL for the target page in the TLFConfigurableItems.properties page.

Note:

If needed, you can configure the client framework to submit by HTTPS by

adding the protocol identifier to the post URL. See Chapter 2, “Configuration file,” on page 95.

Traffic volume management

You can add a sampling function to work with the Android SDK KillSwitch. You can use this sampling function to throttle the sampling rate and thus the volume of traffic that is forwarded for capture.

For more information about sampling functions for various server environments, see "Sample Code" in the IBM Tealeaf Android SDK Guide.

CX Passive Capture Application traffic capture verification

You verify that the IBM Tealeaf CX Passive Capture Application in your IBM

Tealeaf environment is configured to capture and process the data that is submitted from the Logging Frameworks.

The data is submitted using specific content types, which the CX Passive Capture

Application is typically configured to capture by default. You must verify that these content types were enabled for capture through the CX Passive Capture

Application Web Console.

Note:

After the completion of the steps in this section, data is processed by IBM

Tealeaf.

Verifying CX Passive Capture Application capture type configuration

You use this procedure to verify that the CX Passive Capture Application is configured to capture the content types submitted by the Android SDK.

88


Note:

Depending on the version of the CX Passive Capture Application you installed, the required content types may already be configured for capture.

The Android SDK submits messages using the text/json content type.

Note:

Each IBM Tealeaf Logging Framework can use a different content type for submitting events for capture to IBM Tealeaf. Be sure to review and verify the content type for each deployed client framework.

1.

Log in to the CX Passive Capture Application web console:

<PCAServer>:8080 where

<PCAServer> is the host name of the CX Passive Capture Application server.

2.

Click the Pipeline tab.

3.

Click Edit Type Lists.

4.

In the Capture All POST Types box, verify that the following values ae included: text/json text/x-json application/json application/x-json

5.

Click Add.

6.

The CX Passive Capture Application is now configured to capture the required content types. All subsequent hits of this type are captured.

7.

Save changes.

See "PCA Web Console - Pipeline Tab" in the IBM TealeafCX Passive Capture

Application Manual.

Configuring CX Passive Capture Application for Logging

Framework screen captures

Optionally, you can enable the Android SDK to capture screen captures during the initial load of each view or screen of your web application. These screen captures are forwarded to the IBM Tealeaf Target Page in .PNG format for capture and use during session display.

See “UICActivity class” on page 105.

When this option is enabled, you must configure the CX Passive Capture

Application to capture these screen captures. By default, the CX Passive Capture

Application drops capture of binary or static content, so you must configure it to capture these images that are submitted as binary POSTs to the target page.

1.

Log in to the CX Passive Capture Application web console:

<PCAServer>:8080

Where

<PCAServer> is the host name of the CX Passive Capture Application server.

2.

Click the Pipeline tab.

3.

Click Edit Type Lists.

4.

In the Excluded File Extensions list, verify that png is listed.

5.

In the Included File Extensions list, verify that png is not listed.


89

Note:

If a file extension is included in this list, then all instances that are sent as responses are captured, which greatly expands the volume of data that is captured by the CX Passive Capture Application. Capture in this manner is not required.

6.

In the Binary POST Types box, enter the following value: image/png

7.

Click Add.

8.

The image/png POST type is added and enabled for capture. This setting allows the PNG posts to be captured by the CX Passive Capture Application.

9.

Save changes.

See "PCA Web Console - Pipeline Tab" in the IBM Tealeaf CX Passive Capture

Application Manual.

Enabling automated extraction of compressed POSTs

The Android SDK automatically compresses POST data. You must configure the

CX Passive Capture Application to extract them.

Note:

For CX Passive Capture Application Build 3502 or later, this decompression is done automatically. If you are using one of these CX Passive Capture

Application builds, this configuration step is not necessary.

1.

In the CX Passive Capture Application Web Console, click the Pipeline tab.

2.

Select Inflate compressed requests and responses.

3.

Save changes.

The compress POSTs are now automatically extracted by the CX Passive Capture

Application and processed normally.

Options for monitoring captures and processing

You use different tools for testing your configuration and monitoring captures on an ongoing basis.

At target page

You can test the basic functionality of the target page by triggering GET and POST actions on the URL where the target page was installed.

See "UI Capture for Ajax Installation and Implementation" in the IBM Tealeaf CX UI

Capture for AJAX Guide.

In Windows pipeline

You can monitor the capture and processing of hits in the Windows pipeline in real time through the IBM Tealeaf Management System. See "TMS Pipeline Status Tab" in the IBM Tealeaf cxImpact Administration Manual.

Configuring sessionization for Android applications in IBM

Tealeaf

IBM Tealeaf provides multiple mechanisms for identifying and tracking individual visitor sessions. For the Android SDK, more configuration can be required.

Review the following steps and complete any necessary ones to sessionize your mobile application.

90


To enable sessionization of hits that are captured through the Android SDK, you must deploy the Sessioning session agent. See "Sessioning Session Agent" in the

IBM Tealeaf CX Configuration Manual

1.

Log in to the Portal as an administrator.

2.

From the Portal menu, select Tealeaf > TMS. The IBM Tealeaf Management

System opens.

See "Tealeaf Management System" in the IBM Tealeaf cxImpact Administration

Manual.

3.

Click the WorldView tab.

4.

For the View, select Servers.

See "TMS WorldView Tab" in the IBM Tealeaf cxImpact Administration Manual.

5.

Click the Transport Service node.

6.

Select Transport Service configuration. Then, click View/Edit.

7.

The Pipeline Editor opens.

Note:

Verify that the Sessioning session agent was installed.

v If it was not installed, drag it from the Available SessionAgents window to the pipeline.

v For more information about deploying it, see "TMS Pipeline Editor" in the

IBM Tealeaf cxImpact Administration Manual.

8.

Select the Sessioning session agent. Click Edit.

9.

In the Sessioning session agent configuration, modify the PrimarySessField value as follows:

PrimarySessField=AppEnv:SessionID,env:HTTP_X_TEALEAF

10.

Save the configuration file.

11.

Push the change to all servers. A restart is needed for the new sessionization keys to take effect.

Android view name as URL during replay

Errors that can occur during session replay can be resolved by using the Android view name as the URL during replay.

When you attempt to replay a session captured by the Android SDK, an error message can indicate that there are no viewable pages in the session. This error is related to the manner in which pages on Android devices are mapped.

Instead of displaying the URL during replay, you can configure IBM Tealeaf replay clients to show the Android view name instead, which eliminates this cosmetic error message.

To use the Android view name as the URL when you replay the session, complete the following steps to configure the appropriate replay profile rule.

Note:

Currently, configuration of this rule must be applied through the replay profile that is stored on the Replay Server. Instructions follow.

When this change is applied, the Navigable Pages list in Replay view in Browser

Based Replay and CX RealiTea Viewer is populated with the Android view name as the URL, instead of the generic IBM Tealeaf Target page URL.

v Browser Based Replay, or BBR


91

This web-based replay client is accessible through the IBM Tealeaf Portal and retrieves its sessions through the Replay Server in your IBM Tealeaf environment.

– See "CX Browser Based Replay" in the IBM Tealeaf cxImpact User Manual.

– See "Configuring the Replay Server" in the IBM Tealeaf CX Configuration

Manual.

v IBM Tealeaf CX RealiTea Viewer, or RTV

This replay client is a stand-alone Windows application that must be installed separately on your desktop. Through CX RealiTea Viewer, you can search for and replay sessions that are stored in your IBM Tealeaf environment.

See the IBM Tealeaf CX RealiTea Viewer User Manual.

To change the replay profile, you can use these options.

v

“Applying the view name change locally”

You can apply the change locally through the IBM Tealeaf CX RealiTea Viewer, a desktop application for viewing and replaying events. You can use this option to test the change before you reconfigure the Replay Server.

v

“Applying the view name change to the Replay Server” on page 93

If you do not have access to CX RealiTea Viewer, you can change server settings.

Note:

CX RealiTea Viewer users must synchronize their local replay profiles to the server profile to acquire the change.

Applying the view name change locally:

Complete the following steps in CX RealiTea Viewer to make changes locally and test use of the Android view name during replay.

1.

Start the CX RealiTea Viewer application on your local desktop.

Note:

CX RealiTea Viewer must be installed locally on your Windows desktop. See "RealiTea Viewer (RTV) User Manual" in the IBM Tealeaf CX

RealiTea Viewer User Manual.

2.

Load a session that is captured from the Android SDK.

3.

From the CX RealiTea Viewer menu, select Tools > Options....

4.

Click the Profiles tab.

See "RealiTea Viewer - Profile Options" in the IBM Tealeaf CX RealiTea Viewer

User Manual.

5.

If you did not do so already, enter the name of the Replay Server that controls the replay profile in the Server check box. Click Check for Updates Now.

If a server version of the profile is available, your local version is synchronized to it.

6.

Click Edit Raw Profile.

7.

Complete the editing steps that are listed in the section that follows. You are

editing the raw XML file that is stored on your local desktop. See “Applying the view name change to the Replay Server” on page 93.

8.

After editing the profile as required, click Save Changes & Exit.

9.

Click OK.

10.

Replay the session. Click Replay in the toolbar.

11.

In the Navigable Pages list, the listed URLs reflect the Android view name for the screen.

92


12.

If the Navigable Pages list is being populated accurately, you can send your changes back to the Replay Server for deployment to other replay users.

a.

From the RTV menu, select Tools > Options.

b.

Click the Profiles tab.

c.

Click Upload Settings to Server.

Applying the view name change to the Replay Server:

Complete the following steps on the Replay Server so that all Browser Based

Replay users see the Android view name during replay.

In the following steps, you apply the change to the Replay Server by accessing the server and editing the appropriate file. This change is then available to all users of the Replay Server's profile, which includes all Browser Based Replay users.

1.

Log in to the server hosting the Replay Server as an administrator.

2.

Edit the following file:

<Tealeaf_install_directory>\system\ReplayServerProfile.xml

3.

Locate the RequestMapping section, which should be near the top of the file.

4.

Add a Request Mapping, URL element entry. Locate the following header:

<RequestEntry name="URL">

5.

Add the following key name as a new entry to the list of entries:

<Key name="HTTP_X_TEALEAF_VIEW_CLASS" enabled="1"/>

6.

Save the file.

Runtime configuration

As needed, you can change server-side settings from the client application. All configuration items can be configured dynamically from the client.

You can plan to manage server configuration during initialization of the application, then update it selectively and as needed during run time.

See "TeaLeaf Class" in the IBM Tealeaf Android SDK Guide.


93

IBM Tealeaf events for Android SDK

The JSON format is used to track data that is captured by the Android SDK.

Data type

Description

Client Framework data (JSON)

If you are using step-based eventing, data from the client framework is submitted in JSON format and is available through Browser Based Replay for review and eventing. See "Step-Based Eventing" in the IBM Tealeaf Event

Manager Manual.

For a walk-through of how to capture this data into IBM Tealeaf events, see "Integrating Client Framework Data into Tealeaf" in the IBM Tealeaf

Client Framework Data Integration Guide.

Client Framework data (hit-splitting)

See “Client Framework versions supported in this documentation” on page

2.

Upgrading the Android SDK

When you upgrade the IBM TealeafAndroid SDK, you complete the following general tasks.

Note:

Some steps can vary depending on your development and application environments.

1.

Review current requirements. See Minimum requirements.

2.

Review the package contents. See “Tealeaf package contents” on page 2.

3.

As an alternative to integrating the Android SDK with your application in development, you can use the sample application that is provided by IBM

Tealeaf. See “Tealeaf sample application” on page 3.

4.

Verify that your application environment is configured to meet the project requirements.

5.

Verify that the requirement code changes were applied. See “Android project changes” on page 4.

6.

Apply the basic configuration.

Note:

The latest version of the Android SDK includes new configuration

requirements. See “Basic configuration” on page 22.

7.

Verify that the appropriate content types are being captured and forwarded by

the IBM Tealeaf CX Passive Capture Application. See “CX Passive Capture

Application traffic capture verification” on page 88.

Note:

This step turns on the switch to begin capturing and processing data from the mobile application into Tealeaf. Depending on the volume of data,

you can use the kill switch. See “Traffic volume management” on page 88.

8.

Test your upgraded solution.

94


Chapter 2. Configuration file

This configuration file for the Android SDK library is placed into the asset folder of an Android application. It is named TLFConfigurableItems.properties, which is a Java properties file.

Log level settings

The log level settings configure base logging settings.

Table 9. Log level settings

Item ID

LoggingLevel

Description

The current logging level, applies only when log level is not indicated in log statement. 0 has the highest priority.

Values

Integer, 0-5

DisplayLogging

LogViewLayout

OnScreenTransition

To disable logging, start Tealeaf.Disable().

See Chapter 5, “Reference,” on page 105.

When set to true, debug log statements are displayed in LogCat. Filter for the

UICAndroid tag.

When set to true, UICAndroid logs the screen layout. When set to False, the screen layout is not logged.

Boolean

Boolean

Kill switch settings

These settings control the kill switch and whether to use a white list of phone whose events can be captured.

Table 10. Kill switch settings

Item ID

KillSwitchEnabled

Description

If true, the framework checks the kill switch target page before starting. You must specify the following properties.

Values

true

/false

KillSwitchUrl

KillSwitchMaxNumberOfTries

KillSwitchTimeInterval

If KillSwitchEnabled=false, the framework always starts.

Defines the URL to check for the kill switch. The framework requires a successful response to initialize when KillSwitchEnabled is set to true .

URL

The number of times the framework checks for the kill switch URL before giving up. This value should be set to at least 1.

Integer

The time to wait before rechecking the kill switch URL if it is not responding

Seconds


95

Table 10. Kill switch settings (continued)

Item ID

UseWhiteList

Description

If true and KillSwitchEnabled, the framework requires a phone id to assign before calling Enable to check the white list of phone ids.

Values

true /false

WhiteListParam

If false and KillSwitchEnabled, the framework defaults to use random sampling.

Parameter that is used to send the white list ID corresponding to the phone ID.

Current white list server uses id

Local cache file settings

You use these settings to configure use of the device's local cache.

Table 11. Local cache file settings

Item ID

HasToPersistLocalCache

CachingLevel

CachedFileMaxBytesSize

Description

If true, data is stored in local storage on the device, instead of in memory.

The following settings must also be configured.

The current caching level. Applies only when HasToPersistLocalCache is true.

0 has the highest priority.

Maximum number of bytes to be stored on device.

Values

true

/false

Integer, 0-5

Bytes

Post settings

These settings control the logging level, URL, volume, and frequency of posts to the target page.

Table 12. Post settings

Item ID

PostMessageUrl

Description

The URL for posting data to your server.

Note:

To enable secure transport between the logging framework and the target page, configure this URL to begin with https://

. For more information about the

target page, see Chapter 1, “Tealeaf installation and implementation in an

Android application,” on page 1.

PostMessageLevelWiFi The logging level of events to be sent to the server over Wi-Fi when network performance is good. 0 has the highest priority.

PostMessageLevelCellular The logging level of events to be sent to the server over the cellular (3G) network.

0 has the highest priority.

Values

URL

0 -5

0 -5

96


Table 12. Post settings (continued)

Item ID

MaxStringsLength

ManualPostEnabled

Description

Maximum string length to be sent to target page per value in log statements.

Prevents long strings from taking up storage and bandwidth.

Note:

This value must be set to at least 1.

If true, the framework sends data to the server only when your application calls requestManualServerPost .

Values

Integer true /false

DoPostOnIntervals

If set to false, you must configure the following settings.

Note:

You cannot enable this setting and

DoPostOnIntervals together.

If true, the framework sends data to the server at regular time intervals that are specified by PostMessageTimeIntervals when the application is in the foreground.

This value must be set to true if

ManualPostEnabled=false

.

Note:

You cannot enable this setting and

ManualPostEnabled together.

PostMessageTimeIntervals How often the framework sends data to the server when DoPostOnIntervals is set to true.

Note:

This value must be set to be greater than PostMessageTimeout plus

PostMessageDelayTimeToSendData

.

PostMessageTimeout The timeout for the framework's posts to the server. While the framework does not receive a server response within this timeframe, the framework keeps trying to send data.

true /false

Seconds

Seconds

Masking settings

These settings control privacy masking.

Table 13. Masking settings

Item ID

HasMasking

MaskIdList

HasCustomMask

SensitiveSmallCaseAlphabet

SensitiveCapitalCaseAlphabet

SensitiveSymbol

Description

It can be true or false to mask values of controls. If

HasMasking=true

, then complete next value.

Comma delimited ids or regular expressions to find ids.

It can be true or false to use next values below if true.

Character to be used by small case letter.

Character to be used by capital case letter.

Character to be used by symbol.

Values

Boolean

String

Boolean

String

String

String

Chapter 2. Configuration file

97

Table 13. Masking settings (continued)

Item ID

SensitiveNumber

Description

Character to be used by number.

Values

String

Filter message type setting

This setting controls the message types that are sent back to the server.

Table 14. Filter message type setting

Item ID

FilterMessageTypes

Description

If set to TRUE, only the MessageTypes included in the comma-separated list are sent back to the server. If set to

FALSE , all message types are sent back to the server.

Values

TRUE

/ FALSE

Cookie settings

These settings control cookies.

Table 15. Cookie settings

Item ID

CookieSecure

CookieExpiresFormat

Description

If set to TRUE, a secure parameter is added to the cookie. This can only be used in https post urls.

This setting is used to indicate the cookie expiration format.

Values

TRUE / FALSE

Valid date formats:

ASCTIME , RFC1036, or RFC1123

Session timeout setting

This setting controls session timeouts.

Table 16. Session timeout setting

Item ID

SessionTimeout

Description

When SessionTimeout is set, the expiration of cookie is the current time plus the session timeout value.

Values

Minutes

Screen shot settings

These settings control screen shots.

Note:

You can store screen shots in memory instead of in local memory on the device. To enable screen shots to save in memory, you must set

HasToPersistLocalCache to false in the local cache file settings.

Table 17. Screenshot settings

Item ID

ScreenshotFormat

Description

The format of the screen shot.

Values

PNG / JPG

98


Table 17. Screenshot settings (continued)

Item ID

PercentOfScreenshotsSize

PercentToCompressImage

Description

The percentage of screen capture's original pixel dimensions at which posted screen captures are submitted, 1-100.

Percentage to compress image. This setting can only be used for JPG images. PNG images ignore this setting and default to 100.

Values

Integer 1-100

Integer 1-100

Internal settings: do not change

Do not change these settings unless directed to do so by IBM Tealeaf.

Table 18. Internal settings: do not change

Item ID

PostMessageSocketTimeout

CompressPostMessage

BufferLimit

BufferPercent

TimeIntervalBetweenSnapshots

Description Values

The socket timeout for the framework's posts to the server. While the framework does not receive a server response within this timeframe, the framework keeps trying to send data.

Seconds true / false When set to true, HTTP POSTs submitted from the framework are compressed in compress format.

Note:

To extract the compressed

POSTs, some additional server-side configuration can be required. See

Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1.

The number of messages to store in memory to be sent to server.

Percentage to remove from BufferLimit before it gets saved to cache if enabled.

The time interval for taking snapshots of environmental data

Integer

Percentage

Seconds

Chapter 2. Configuration file

99

100


Chapter 3. Sample applications

The sample code that is provided with the software distribution contains an

Android application that can be used to test the IBM Tealeaf system.

There is one version of code provided.

Version

Description

UICAndroidControlsAppDarkHolo

An Android application, which has the current supported controls that you can replay in BBR with examples of how to use event listeners with Tealeaf api.


101

102


Chapter 4. Guidelines

Apply the following tips to your application development and integration of the

IBM Tealeaf Android SDK.

v

Use the kill switch to control logging of the Android application. See Chapter 6,

“Sample Code,” on page 125.

v Add IDs for all UI controls that you want to capture.

v Apply privacy masking or blocking of all sensitive customer data through the

Android SDK.

Note:

In Release 8.5, IBM Tealeaf introduced step-based eventing, which simplifies and unifies event capture from all client frameworks, while it enhances performance. Due to changes in how the data is bundled, you now apply data privacy through the individual client frameworks, instead of using the IBM Tealeaf server methods for data privacy.

– See Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1.

– For more information about managing privacy in general, see "Managing


v

Follow guidelines for the file that extends Application. See Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1.

v

Follow guidelines for the file that extends Activity. See Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1.

v

Debug locally in Eclipse by using LogCat.

To see debug messages in the LogCat tab of Eclipse, enter the following string: tag:UICAndroid .

v Follow guidelines for using TLDefaultHttpClient for requests and responses to

get connection metrics. See “TLDefaultHttpClient class” on page 117.

v

Follow guidelines for using text fields to get more metrics. See “Tealeaf class” on page 108.

v Due to the way JSON messages are captured and transmitted, force a submission of all queued messages before you allow users of your mobile native application to open a web view. If this step is not done, hits can appear to be out of order during replay in IBM Tealeaf.

See "Search and Replay for Mobile App" in the IBM Tealeaf CX Mobile User

Manual.


103

104


Chapter 5. Reference

This section contains class reference information about the IBM Tealeaf Android

SDK library.


The com.tl.uic.app.UICActivity class extends com.tl.uic.app.Activity.

UICActivity helps capture user actions in an Android application and enables screen capture after the Activity is created.

Note:

To enable capture of screens into IBM Tealeaf, you must configure the PCA

to capture binary POSTs of png images. See Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1.

Method detail

getTakeSnapshotAfterCreate

public Boolean getTakeSnapshotAfterCreate()

Whether to take the snapshot after create.

Returns whether to take the snapshot after create.

setTakeSnapshotAfterCreate

public void setTakeSnapshotAfterCreate(final

Boolean takeSnapshotAfterCreate)

Whether to take the snapshot after create.

takeSnapshotAfterCreate - Whether to take the snapshot after create.

getTookImage

public Boolean getTookImage()

Whether screen capture was taken.

setTookImage

public void setTookImage(final Boolean tookImage)

Whether screen capture was taken.

tookImage

- Whether screen capture was taken.

getLogicalPageName

public String getLogicalPageName()


Returns the logical page name of the Activity. If none was assigned, it receives a name from the class of Activity, and an underscore (_) with current time in milliseconds is added.

setLogicalPageName

public void setLogicalPageName(final String logicalPageName)


logicalPageName - Logical page name of the Activity.


105

getImageBackground

public int getImageBackground()

Background color of the image of the screen capture.

Returns the background color of the image of the screen capture.

setImageBackground

public void setImageBackground(final int imageBackground)

Background color of the image of the screen capture.

imageBackground

- Background color of the image of the screen capture.

getView

public View getView()

View to use for screen capture.

Returns the view to use for screen capture.

setView

public void setView(final View view)

View to use for screen capture.

view - View to use for screen capture.

getNumOnGlobalLayoutListener

public int getNumOnGlobalLayoutListener()

Number of OnGlobalLayoutListener set on views.

Returns the number of milliseconds to delay before snapshot is taken because more time is needed to render properly.

setNumOnGlobalLayoutListener

public void setNumOnGlobalLayoutListener(final

int numOnGlobalLayoutListener)

Number of OnGlobalLayoutListener set on views.

millisecondSnapshotDelay

- Milliseconds to delay before snapshot is taken because more time is needed to render properly.

getMillisecondSnapshotDelay

public long getMillisecondSnapshotDelay()

Milliseconds to delay before snap shot is taken because more time is needed to render properly.

Returns the number of milliseconds to delay before snapshot is taken because more time is needed to render properly.

setMillisecondSnapshotDelay

public void setMillisecondSnapshotDelay(final

long millisecondSnapshotDelay)

Milliseconds to delay before snap shot is taken because more time is needed to render properly.

millisecondSnapshotDelay - Milliseconds to delay before snap shot is taken because more time is needed to render properly.

106


Reference

Table 19. UICActivity class

Package

com.tl.uic.app

com.tl.uic

com.tl.uic.http

com.tl.uic.webkit

Class Description

UICActivity

“UICApplication class”

“Tealeaf class” on page 108

IBM Tealeaf Android

SDK library that is used to capture user actions.

“TLDefaultHttpClient class” on page 117

Extends

DefaultHttpClient to monitor when a URL was requested.

“TLHttpRequestInterceptor class” on page

118

Extends

HttpRequestInterceptor to add IBM Tealeaf headers for sessionization.

“TLHttpResponseInterceptor class” on page 119

UICActivity used to help control IBM Tealeaf

Android SDK library.

Application that is used to help control IBM

Tealeaf Android SDK library.

“UICWebView class” on page 120

Extends

HttpResponseInterceptor to acquire details for the

Tealeaf connection object.

WebView used to add session ID to header requests.

“UICWebChromeClient Class” on page 122 Extends

WebChromeClient to monitor when browser finished render after which screen capture is enabled.

“UICWebViewClient Class” on page 123

Extends WebViewClient to monitor when the

URL loaded to add IBM

Tealeaf headers for sessionization.


The com.tl.uic.app.UICApplication class extends android.app.Application.

UICApplication helps capture user actions in an Android application.

Method detail

getTealeaf

public Tealeaf getTealeaf()

Get current instance of IBM Tealeaf.

Returns the current instance of IBM Tealeaf.

Chapter 5. Reference

107

Reference

Table 20. UICApplication class

Package

com.tl.uic.app

Class

“UICActivity class” on page 105

com.tl.uic

com.tl.uic.http

com.tl.uic.webkit

UICApplication

“Tealeaf class”

“TLDefaultHttpClient class” on page

117

“TLHttpRequestInterceptor class” on page 118



“UICWebChromeClient Class” on page 122

“UICWebViewClient Class” on page

123

Description



Application that is used to help control IBM Tealeaf


IBM Tealeaf Android SDK library that is used to capture user actions.

Extends DefaultHttpClient to monitor when a URL was requested.

Extends


Extends

HttpResponseInterceptor to acquire details for the IBM



Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled.

Extends WebViewClient to monitor when the URL loaded to add IBM Tealeaf headers for sessionization.

Tealeaf class

The com.tl.uic.TeaLeaf class extends java.lang.Object. The Tealeaf library helps capture user actions in an Android application.

Fields

Table 21. Tealeaf class

Field

static java.lang.String

Summary

TLF_SESSION_HEADER static java.lang.String

TAG

Description

Header key that is used to sessionize on

X-Tealeaf-Session .

UICAndroid used in

LogCat.

108


Fields used in event handlers to get display user actions correctly


Field


Summary

TLF_ON_FOCUS_CHANGE_IN static java.lang.String





TLF_ON_FOCUS_CHANGE_OUT

TLF_ON_GROUP_COLLAPSE

TLF_ON_GROUP_EXPAND

TLF_ON_DRAWER_OPENED

TLF_ON_DRAWER_CLOSED

Description

Used in TextView based controls to indicate focus in.

Used in TextView based controls to indicate focus out.

Used in

ExpandableListView based controls to indicate group is collapsed.

Used in

ExpandableListView based controls to indicate group is expanded.

Used in SlidingDrawer based controls to indicate drawer is opened.

Used in SlidingDrawer based controls to indicate drawer is closed.

Fields used to access configuration file values


Field



Summary

TLF_LOGGING_LEVEL

DISPLAY_LOGGING static java.lang.String







Description

Default log level.

Whether to display debug statements in

LogCat

Whether kill switch is enabled.

Url for kill switch.

TLF_KILL_SWITCH_ENABLED

TLF_KILL_SWITCH_URL

TLF_KILL_SWITCH_MAX_NUMBER_OF_TRIES Maximum number of tries

TLF_KILL_SWITCH_TIME_INTERVAL Kill switch time interval to retry to access kill switch.

TLF_USE_WHITE_LIST

TLF_WHITE_LIST_PARAM

TLF_USE_RANDOM_SAMPLE

Whether to use white list.

Parameter that white list uses.

Whether to use random sample.


109

Table 23. Tealeaf class (continued)

Field


Summary

TLF_RANDOM_SAMPLE_PARAM

TLF_HAS_TO_PERSIST_LOCAL_CACHE static java.lang.String



TLF_CACHED_LEVEL

TLF_CACHED_FILE_MAX_BYTES_SIZE static java.lang.String





TLF_POST_MESSAGE_URL

TLF_POST_MESSAGE_LEVEL_WIFI

TLF_POST_MESSAGE_LEVEL_CELLULAR

TLF_MAX_STRINGS_LENGTH

TLF_MANUAL_POST_ENABLED static java.lang.String





TLF_DO_POSTS_ON_INTERVALS

TLF_POST_MESSAGE_TIME_INTERVALS

TLF_POST_MESSAGE_MAX_BYTES_SIZE

TLF_HAS_MASKING

TLF_MASK_ID_LIST

Description

Parameter that random sample uses.

Whether it is able to save cache to device.

Cache level to be saved to device.

Maximum cache byte size to be saved to device.

Url of the target page.

Log level if current connection level is WiFi.

Log level if current connection level is cellular.

Maximum string length.

Whether to enable control of posting to target page.

Developer is responsible for posting to target page.

Whether to have framework post at a set interval.

Time interval between posts.

Maximum byte size for posting a message.

Whether to mask values of controls.

Comma-delimited string that can have IDs of controls or regular expression to find

IDs of controls.

110


Table 23. Tealeaf class (continued)

Field






Summary

TLF_HAS_CUSTOM_MASK

TLF_SENSITIVE_SMALL_CASE_ALPHABET

TLF_SENSITIVE_CAPITAL_CASE_ALPHABET

TLF_SENSITIVE_SYMBOL

TLF_SENSITIVE_NUMBER

Description

Whether to use custom mask values to replace.

If set to false,

Logging

Framework returns an empty string.

Small letter to replace during custom mask.

Capital letter to replace during custom mask.

Symbol to replace during custom mask.

Number to replace during custom mask.

Constructor

Public Tealeaf (Application app)

Tealeaf is a library to help capture user actions in an Android application.

Parameters: v application - Reference to current Android application.

Method detail

getCurrentSessionId

public static java.lang.String getCurrentSessionId()

Get current session ID.

getDeviceId

public static java.lang.String getDeviceId()

Get device ID used with the whitelist on the kill switch server.

getPhoneId This method has been deprecated. Use getDeviceId instead.

public static java.lang.String getPhoneId()

Get phone ID used with the whitelist on the kill switch server.

setDeviceId

public static void setDeviceId(java.lang.String deviceId)

Set device ID that is used with the whitelist on the kill switch server.

setPhoneId - This method has been deprecated. Use setDeviceId instead.

public static void setPhoneId(java.lang.String phoneId)

Set phone ID that is used with the whitelist on the kill switch server.


111

isEnabled

public static java.lang.Boolean isEnabled()

To enable library.

Returns whether Tealeaf library was enabled.

getApplication()

public static android.app.Application getApplication()

Reference to current Android Application.

Returns reference to current Android Application.

getMessageVersion()

public static String getMessageVersion()

Get current JSON message version.

Returns current JSON message version.

getLibraryVersion()

public static java.lang.String getLibraryVersion()

Reference to current library version.

Returns reference to current library version.

enable

public static java.ladng.Boolean enable() public static java.lang.Boolean enable(sessionId)

To enable library with a given session ID or a generated one.

v sessionId

- Given session ID to use.

Returns if Tealeaf library was enabled.

disable

public static java.lang.Boolean disable()

To disable library.

Returns if library was disabled.

onPause

public static Boolean onPause(final Activity activity, final String logicalPageName)

If not using UICActivity, add this call on your Activity file onPause method before calling super.

v activity - Activity that calls onPause.

v logicalPageName - Descriptive name of the activity that calls onPause.

Returns True/False whether it was able to pause properly.

onResume

public static Boolean onResume(final Activity activity, final String logicalPageName)

If not using UICActivity, add this call on your Activity file onResume method before calling super.

v activity

- Activity that calls onResume.

v logicalPageName - Descriptive name of the activity that calls onResume.

112


Returns True/False whether it was able to resume properly.

onDestroy

public static Boolean onDestroy(final Activity activity, final String logicalPageName)

If not using UICActivity, add this call on your Activity file onDestroy method before calling super.

v activity - Activity that calls onResume.

v logicalPageName - Descriptive name of the activity that calls onResume.

Returns True/False whether it was able to destroy properly.

OnLowMemory

public static java.lang.Boolean OnLowMemory()

If not using UICApplication, add this call on your Application file

OnLowMemory method before calling super.

Returns:

True /False whether it was able to properly clean up.

terminate

public static java.lang.Boolean terminate()

If not using UICApplicaion, add this call on your Application file on terminate method before calling super.

Returns True/False whether it was able to terminate properly.

flush

public static java.lang.Boolean flush()

To be used to flush data.

Returns:

True

/False whether it was able to flush data back to server.

logEvent

public static java.lang.Boolean logEvent(final View view)public static java.lang.

Boolean logEvent(final View view, final java.lang.String eventType)public static java.lang.Boolean logEvent(final View view, final java.lang.String eventType, final

int logLevel)

Log an event from an event handler.

v view - Control from event handler.

v eventType - Event type of event handler.

v logLevel - Log level for TeaLeaf library.

Returns True/False whether it was able to log event.

logCustomEvent

public static java.lang.Boolean logCustomEvent(final java.lang.String eventName) public static java.lang.Boolean logCustomEvent(final java.lang.String eventName, final int logLevel)public static java.lang.Boolean logCustomEvent(final java.lang.String eventName, final


113

java.util.HashMap<java.lang.String, final java.lang.

String> data)public static java.lang.

Boolean

logCustomEvent(final java.lang.String eventName, final java.util.HashMap<java.lang.String, java.lang.

String> data, final int logLevel)

Log a custom event.

v eventName - Event name to be logged.

v data - Key and value pair to be logged.

v logLevel - Log level for TeaLeaf library.

Returns True/False whether it was able to log event.

logException

public static java.lang.Boolean logException(final java.lang.Throwable exception) public static java.lang.Boolean logException(final java.lang.Throwable exception, final HashMap<String, String> data) public static java.lang.Boolean logException(final java.lang.

Throwable exception, final HashMap<String, String> data, final boolean unhandled)

Log an exception.

v exception - Exception to be logged.

v data - The HashMap data to be logged. Values for this parameter are key-value pairs.

v unhandled

- Whether the exception is handled. Values are True or False.

Returns True or Falsewhether exception was logged.

logScreenview

public static Boolean logScreenview(final Activity activity, final String logicalPageName, final ApplicationContextType applicationContextType) public static Boolean logScreenview(final Activity activity, final String logicalPageName, final ApplicationContextType applicationContextType, final String referrer)

Log an application context (screenView).

v activity - Activity with an application context (screenView) change.

v logicalPageName

- Activity's name or descriptive name that was created on device.

v applicationContextType - ApplicationContextType of the application context.

v referrer - Referrer page that logical page uses.

Returns True/False whether exception was logged.

logScreenLayout

public static Boolean logScreenLayout(final Activity activity)

Log the layout of activity immediately without a layout name.

public static Boolean logScreenLayout(final Activity activity,final

String name)

114


Log the layout of activity immediately with a layout name.

public static Boolean logScreenLayout(final Activity activity,final

String name, final int delayMS)

Log the layout of an activity with a time delay on run.

v activity - Activity to be logged.

v name - Name of the layout.

v delayMS - Number, in milliseconds, to delay the call.

Returns: Whether the layout was logged.

public static Boolean logScreenLayout(final Activity activity, final AlertDialog alertDialog, final String title, final String message) public static Boolean logScreenLayout(final Activity activity, final AlertDialog alertDialog, final String name, final String title, final String message)

Log the layout of the alert dialog.

v activity - Activity where AlertDialog is to be logged.

v alertDialog - AlertDialog to be logged.

v name - Screenview name of where alert appears.

v title - Title displayed on the alert dialog.

v message - Message displayed on alert dialog.

Returns: Whether it was able to log the layout.

logScreenLayoutSetOnShowListener

public static Boolean logScreenLayoutSetOnShowListener

(final Activity activity, final AlertDialog alertDialog, final String title, final String message) public static Boolean logScreenLayoutSetOnShowListener

(final Activity activity, final AlertDialog alertDialog, final String name, final String title, final String message)

Log the layout of the alert dialog.

v activity - Activity where AlertDialog is to be logged.

v alertDialog - AlertDialog to be logged.

v name - Screenview name of where the alert appears.

v title - Title displayed on alert dialog.

v message

- Message displayed on alert dialog.


logScreenLayoutSetOnCreate

public static Boolean logScreenLayoutOnCreate(final Activity activity, final String name)

Log the layout of the activity with OnGlobalLayoutListener to know when the view is complete.

v activity - Activity to be logged.

v name - Name of the layout.



115

logConnection

public static java.lang.Boolean logConnection(final java.lang.String url, final org.apache.http.HttpResponse

httpResponse, final java.util.Date initTime, final long loadTime, final

long responseTime)

Log a connection.

v url - Url of the connection.

v httpResponse - HttpResponse of the connection.

v initTime - Initial time of the response.

v loadTime - Load time of the response.

v responseTime - Response time.

Returns True/False whether connection was logged.

takeScreenShot

public static java.lang.Boolean takeScreenShot(final View view,final java.lang.

String imageFileName)

Take screen capture of given view.

Note: This method requires to be able to save to device to take screen capture.

v view - View to take screen capture.

v imageFileName - Name of the image.

Returns True/False whether screen capture was taken.

startSession

public static void startSession() public static void startSession(final sessionId)

Indicate to start with a given session ID or a generated one.

v sessionId - session ID to use.

requestManualServerPost

public static java.lang.Boolean requestManualServerPost()

Post current logged data.

Returns True/False whether data was posted.

getApplicationContextOffset

public static long getApplicationContextOffset()

The current application context offset.

Returns long: The current application context offset.

registerFormField

public static Boolean registerFormField(final View formField, final Activity activity) public static Boolean registerFormField(final View formField, final Activity activity, final int logLevel)

Register form field that helps get statistics.

v formField - Form field to register.

116


v activity - Activity that has form field.

v logLevel - Log level for library.

Returns True/False whether form field was registered.

isApplicationInBackground

public static Boolean isApplicationInBackground()

Returns whether application was moved to background by not having any activity that is displayed in the foreground.

Returns True/False whether application was moved to background.

Reference


Package

com.tl.uic.app

com.tl.uic

com.tl.uic.http

com.tl.uic.webkit

Class


“UICApplication class” on page 107

TeaLeaf

“TLDefaultHttpClient class”

Description

UICActivity used to help control library.

Application that is used to help control library.

library that is used to capture user actions.

Extends

DefaultHttpClient to monitor when a URL was requested



Extends

HttpRequestInterceptor to add headers for sessionization

Extends

HttpResponseInterceptor to acquire details for the connection object


“UICWebChromeClient Class” on page

122


Extends

WebChromeClient to monitor when browser has finished render, after which screen capture is enabled


Extends WebViewClient to monitor when the URL was loaded to add headers for sessionization

TLDefaultHttpClient class

The com.tl.uic.http.TLDefaultHttpClient class extends org.apache.http.impl.client.DefaultHttpClient

. You use TLDefaultHttpClient to understand when a URL value was retrieved to add the IBM Tealeaf connection object.


117

Note:

Instances of TlHttpRequestInterceptor class and TlHttpRequestInterceptor class are added to TLDefaultHttpClient to acquire details for IBM Tealeaf connection object.

Reference

Table 25. TLDefaultHttpClient class

Package

com.tl.uic.app

com.tl.uic

com.tl.uic.http

com.tl.uic.webkit

Class




TLDefaultHttpClient

“TLHttpRequestInterceptor class”




122


123

Description







Extends


Extends


IBM Tealeafconnection object.



Extends WebViewClient to monitor when the URL was loaded to add IBM


TLHttpRequestInterceptor class

The com.tl.uic.http.TLHttpRequestInterceptor class extends org.apache.http.HttpRequestInterceptor

. You use TLHttpRequestInterceptor to add Tealeaf headers for sessionizing.

Methods overridden

v process

118


Reference

Table 26. TLHttpRequestInterceptor class

Package

com.tl.uic.app

com.tl.uic

com.tl.uic.http

com.tl.uic.webkit











117

TLHttpRequestInterceptor

Extends DefaultHttpClient to monitor when a URL requested.

Extends


“TLHttpResponseInterceptor class”




123

Extends




Extends

WebChromeClient to monitor when browser was finished render after which screen capture is enabled.

Extends WebViewClient to monitor when the URL loaded in to add IBM


TLHttpResponseInterceptor class

The com.tl.uic.http.TLHttpResponseInterceptor class extends org.apache.http.HttpResponseInterceptor

. You use TLHttpResponseInterceptor to acquire details for the IBM Tealeaf connection object.


v Process


119

Reference

Table 27. TLHttpResponseInterceptor class

Package

com.tl.uic.app

com.tl.uic

com.tl.uic.http

com.tl.uic.webkit






117








Extends


TLHttpResponseInterceptor

“UICWebView class”

Extends


IBM Tealeaf connection object.



122


“UICWebViewClient Class” on page 123 Extends WebViewClient to

monitor when the URL loaded to add IBM Tealeaf headers for sessionization.

UICWebView class

The com.tl.uic.webkit.UICWebView class extends android.webkit.WebView. You use

UICWebView to add a session ID to header requests for purposes of sessionization.

This class also adds a connection object to provide information of WebView.

Method detail

getEndLoad

public Date getEndLoad()

When page finished loading.

Returns Date: When page finished loading.

setEndLoad

public void setEndLoad(final Date endLoad)

120


When page finished loading.

endLoad

- When page finished loading.

getStartLoad

public Date getStartLoad()

When page starts loading.

Returns Date: When page starts loading.

setStartLoad

public void setStartLoad(final Date startLoad)

When page starts loading.

StartLoad - When page starts loading.

getHttpResponse

public HttpResponse getHttpResponse()

HttpResponse from the connection.

Returns HttpResponse: HttpResponse from the connection.

setHttpResponse

public void setHttpResponse

(final HttpResponse httpResponse)

HttpResponse from the connection.

httpResponse - HttpResponse from the connection.

getInitTime

public Date getInitTime()

Initial time from the connection.

Returns Date: Initial time from the connection.

setInitTime

public void setInitTime

(final Date initTime)

Initial time from the connection.

InitTime - Initial time from the connection.

getResponseTime

public long getResponseTime()

Response time from the connection.

long

: Response time from the connection.

setResponseTime

public void setResponseTime

(final long responseTime)

Response time from the connection.

ResponseTime - Response time from the connection.

logConnection

public void logConnection()


121

Logs the current connection time of the webview.

Reference

Table 28. UICWebView Class

Package Class Description

com.tl.uic.app

com.tl.uic

com.tl.uic.http

com.tl.uic.webkit







“TLHttpRequestInterceptor class” on page

118

Extends

HttpRequestInterceptor to add Android SDK headers for sessionization.






UICWebView

Extends


Android SDK connection object.


“UICWebChromeClient Class”


Extends


Extends WebViewClient to monitor when the URL loaded to add Android

SDK headers for sessionization.

UICWebChromeClient Class

The com.tl.uic.webkit.UICWebChromeClient class extends android.webkit.WebChromeClient

. You use UICWebChromeClient to monitor when progress of the browser finished in order to capture a screen capture of the device screen.


v onProgressChanged

122


Reference

Table 29. UICWebChromeClient class

Package

com.tl.uic.app

Class


com.tl.uic

com.tl.uic.http

com.tl.uic.webkit




117




UICWebChromeClient

“UICWebViewClient Class”

Description






Extends

DefaultHttpClient to monitor when a URL was requested.

Extends


Extends


IBM Tealeaf connection object.


Extends


Extends WebViewClient to monitor when the URL loaded to add IBM


UICWebViewClient Class

The com.tl.uic.webkit.UICWebViewClient class extends android.webkit.WebViewClient

. You use UICWebViewClient to monitor when a URL is loading in order to add IBM Tealeaf headers for sessionizing.


v shouldOverrideUrlLoading


123

Reference

Table 30. UICWebViewClient class

Package Class Description

com.tl.uic.app

com.tl.uic

com.tl.uic.http


“UICApplication class” on page

107



UICActivity used to help control

IBM Tealeaf Android SDK library.

Application that is used to help control IBM Tealeaf Android SDK library.





Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization.

Extends HttpResponseInterceptor to acquire details for the IBM


com.tl.uic.webkit “UICWebView class” on page 120




UICWebViewClient Extends WebViewClient to monitor when the URL loaded in to add

IBM Tealeaf headers for sessionization.

124


Chapter 6. Sample Code

This chapter contains sample code for IBM Tealeaf Android SDK.

How to instrument TextView based controls

Because TextView based controls are used for text fields, to get dwell time and other data you instrument the OnFocusChangeListener to know when a user starts and completes typing.

// Get TextView based control final EditText nameEditText = (EditText) findViewById(R.id.nameEditText);

// Create a OnFocusChangeListener

OnFocusChangeListener focusListen = new OnFocusChangeListener () { public void onFocusChange(View view, boolean hasFocus){ if(hasFocus == false){

Tealeaf.logEvent(view, Tealeaf.TLF_ON_FOCUS_CHANGE_OUT);

} else{

Tealeaf.logEvent(view, Tealeaf.TLF_ON_FOCUS_CHANGE_IN);

}

}

});

// Set OnFocusChangeListener on TextView based control nameEditText.setOnFocusChangeListener(focusListen);

// Register TextView based control

Tealeaf.registerFormField(nameEditText, this);

How to instrument ExpandableListView based controls

For ExpandableListView controls, in order to know when a user expands or collapses a control you instrument the OnGroupCollapseListener and

OnGroupExpandListener.

// Get ExpandableListView based control final ExpandableListView elv = (ExpandableListView) findViewById(R.id.elv); elv.setOnChildClickListener(new OnChildClickListener() { public boolean onChildClick(ExpandableListView parent, View view,

int groupPosition, int childPosition, long id) {

Tealeaf.logEvent(view); return true;

}

}); elv.setOnGroupCollapseListener(new OnGroupCollapseListener() { public void onGroupCollapse(int groupPosition) {

Tealeaf.logEvent(elv, Tealeaf.TLF_ON_GROUP_COLLAPSE);

}

}); elv.setOnGroupExpandListener(new OnGroupExpandListener(){ public void onGroupExpand(int groupPosition) {

Tealeaf.logEvent(elv, Tealeaf.TLF_ON_GROUP_EXPAND);

}

});


125

How to instrument SlidingDrawer based controls

For SlidingDrawer controls, to know when a user opens or closes a control you instrument the OnDrawerOpenListener and OnDrawerCloseListener.

// Get SlidingDrawer based control final SlidingDrawer sd = (SlidingDrawer) findViewById(R.id.sd); sd.setOnDrawerOpenListener(new OnDrawerOpenListener() { public void onDrawerOpened(){

Tealeaf.logEvent(slidingDrawer_c5, Tealeaf.TLF_ON_DRAWER_OPENED);

}

}); sd.setOnDrawerCloseListener(new OnDrawerCloseListener(){ public void onDrawerClosed(){

Tealeaf.logEvent(slidingDrawer_c5, Tealeaf.TLF_ON_DRAWER_CLOSED);

}

});

How to mask controls

Custom masking is a feature that matches specified IDs and regular expressions and then does character substitutions. In the example that follows, custom masking converts actual values to the letters that are supplied as replacements. If custom masking is set to false, it returns an empty string. You specify masking in the

TLFConfigurableItem.properties

file that is in the assets folder of the Android application.

#Masking settings

HasMasking=true

#It can be a series of ids and regular expressions comma delimited

MaskIdList=com.tealeaf.sp:id\/EditText*,com.tealeaf.sp:id\/login.password

#If set to false it will return an empty string

HasCustomMask=true

#It will turn small letters to value given

SensitiveSmallCaseAlphabet=x

#It will turn capital letters to value given

SensitiveCapitalCaseAlphabet=X

#It will turn symbols to value given

SensitiveSymbol=#

#It will turn digits to value given

SensitiveNumber=9

Server-Side KillSwitch Sampling Function

When the KillSwitch feature is enabled in the client configuration, the Framework queries the KillSwitch URL to determine whether to enable or disable the framework for that session. The KillSwitch URL can be .aspx, .jsp or .php.

If the Android logging framework is disabled, then the session is not captured and is excluded from the sampled data.

The KillSwitch URL returns 1 to enable the Framework and 0 to disable the

Framework. Each KillSwitch URL has a corresponding web.config configuration file.

Sampling function examples for ASPX

These examples show the killswitch.aspx and web.config configuration file for

ASPX

126


Example killswitch.aspx

This example shows the killswitch.aspx:

<%@ Page Language="C#" AutoEventWireup="true"%>

<script runat="server"> public int Sampler()

{

Random rand = new Random(); int nextRandom = rand.Next(1,100); int samplepercent = Convert.ToInt32(ConfigurationManager.AppSettings

["rate"]); if(nextRandom <= samplepercent){ return 1;

} else{ return0;

}

}

</script>

<% if (ConfigurationManager.AppSettings["killswitchtype"].Equals

("percentagesample")) {

%>

<%= Sampler() %>

<% } else { } %>

Example web.config configuration file for ASPX

This example shows the web.config configuration file for the killswitch.aspx:

<?xml version="1.0"?>



<configuration>

<appSettings>

<add key="killswitchtype" value="percentagesample"/>

<add key="rate" value="50"/>

</appSettings>

</configuration>

Sampling Function for JSP

These examples show the killswitch.jsp and web.config configuration file for JSP.

For the JSP, if the: v request does not have parameters, then the client framework is always disabled.

v id request parameter exists, it is used to check the whitelist.

v randomsample parameter exists, the percentage rate from the config.properties

file is used to determine how the server responds.

Example killswitch.jsp

This example shows the killswitch.jsp:

<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>

<%@page import="java.util.Properties"%>

<%@page import="java.util.Date" %>

<%@ page import="java.net.*"%>

<%@ page import="java.io.*" errorPage=""%>

Chapter 6. Sample Code

127

<%

InputStream stream = application

.getResourceAsStream("/config.properties");

Properties props = new Properties(); props.load(stream);

Boolean DEBUG = false;

DEBUG = ("true").equals(props.getProperty("debug"));

String id = request.getParameter("id");

String randomsample = request.getParameter("randomsample");

String killSwitchResponse = "";

String debugstr = "";

// white list if (id != null && !id.isEmpty()) {

InputStream whitestream = application.getResourceAsStream(props

.getProperty("WhiteListFile"));

BufferedReader input = new BufferedReader( new InputStreamReader(whitestream));

String line = "";

Boolean match = false; while ((line = input.readLine()) != null) { line = line.trim(); if (line.equals(id)) { killSwitchResponse = "1"; match = true; break;

}

} input.close(); if (!match) { killSwitchResponse = "0";

}

}

// If kill switch is by sample rate else if (randomsample != null) { int rand = (int) (Math.random() * 100); int sampleRate = Integer.parseInt(props

.getProperty("samplerate")); if (rand <= sampleRate) { killSwitchResponse = "1";

} else { killSwitchResponse = "0";

}

} else { killSwitchResponse = "0";

} out.print(killSwitchResponse);

//always give the path from root. This way it almost always works.

String nameOfTextFile = props.getProperty("logfile");

PrintWriter pw; if (DEBUG) { try { pw = new PrintWriter(new FileOutputStream(nameOfTextFile, true));

Date date = new java.util.Date(); debugstr = date.toString() + "\t"; if (request.getQueryString() != null) { debugstr += request.getQueryString();

} if("0".equals(killSwitchResponse)) else pw.println(debugstr + "\tDisable");

128


pw.println(debugstr + "\tEnable");

//clean up pw.close();

} catch (IOException e) { out.println(e.getMessage());

}

%>

}

Example web.config

configuration file

This example shows the web.config configuration file for the killswitch.jsp:

WhiteListFile=whitelist.txt

samplerate =50 debug=true logfile=/killswitchlog.txt

Sampling Function for PHP

These examples show the killswitch.php and web.config configuration file for

PHP.

Example killswitch.php

This example shows the killswitch.php:

<?php

$ini_array = parse_ini_file("config.ini", true);

//print_r($ini_array);

// if sample by percent if($ini_array[’configtype’][’killswitchtype’] === ’percentagesample’){

$sampleRate = intval($ini_array[’percentagesample’][’rate’]); killbysamplerate($sampleRate);

}

// if sample by whitelist else {

}

?>

} function killbysamplerate($sampleRate){

$randomnumber = rand(1,100); if($randomnumber <= $sampleRate){ echo ’1’;

} else { echo ’0’;

}

} function killbywhitelist($whitelistpath){

Example web.config

configuration file

This example shows the web.config configuration file for the killswitch.php:

; This is a sample configuration file

; Comments start with ’;’, as in php.ini

[configtype] killswitchtype=percentagesample


129

[percentagesample] rate = 50 y z

[whitelist] x

JSON message type schemas and examples

JSON messages are categorized by type for processing. Tealeaf supports 12 JSON message types.

Message header properties

All messages contain message header properties consisting of two properties that contain the message type and the time that is offset from the start of the session in milliseconds. All time measurements in the JSON object schema are in milliseconds.

Message list

This table lists and describes the supported JSON message types:

Table 31. Schema by Message Type

Type

1

2

3

4

5

6

7

8

9

10

11

Message Type

“Overstat Hover Event (Type 9) messages” on page 144

“Layout (Type 10) messages” on page 144

“Gesture (Type 11) messages” on page 147

Description

“Client state (Type 1) messages” on page 132

“ScreenView (Type 2) messages” on page 134

“Connections (Type 3) messages” on page 136

Any object that shows the current state of client.

Any message that indicates changes in view on the "screen". The "screen" is the page, view, or activity where the visitor is in the application.

Any request or response that the application performs during capture.

“Control (Type 4) messages” on page

137

User interface control that fires an event to which Tealeaf listens for capture.

“Custom Event (Type 5) messages” on page 140

“Exception (Type 6) messages” on page 141

“Performance (Type 7) messages” on page 142

Any custom log event from any location in application.

Any exception that the application can throw.

Performance data from a browser.

“Web Storage (Type 8) messages” on page 143

Any object that contains information about local storage information on the browser.

Any object that contains information about mouse hover and hover-to-click activity.

Any message that shows the current display layout of a native page.

Any message that shows a gesture that fires a higher touch event that

Tealeaf listens to for capture.

130


Table 31. Schema by Message Type (continued)

Type

12

13

Message Type

“DOM Capture (Type 12) message example” on page 159

“GeoLocation (Type 13) messages” on page 161

Description

Any object that contains serialized

HTML data (DOM snapshot) of the page.

Messages that contain the geolocation information about the device.

Message header properties

All messages contain message header properties consisting of two properties that contain the message type and the time that is offset from the start of the session in milliseconds.

All time measurements in the JSON object schema are in milliseconds.

Message header properties schema

This example shows the schema for the JSON message headers.

"offset": {

"title": "Milliseconds offset from start of stream",

"type": "integer",

"required": true

},"screenViewOffset": {

"title": "Milliseconds offset from start of ScreenView",

"type": "integer",

"required": true

},"count": {

"title": "The number of the message being sent",

"type": "integer",

"required": only used for UIC

},"fromWeb": {

"title": "Used to identify if it came from Web or Native application",

"type": "boolean",

"required": true

},"webviewId": {

"title": "Used to identify which webview it came from. This is only used when fromWeb is true and it is a hybrid application ",

"type":"string",

"required": true only when fromWeb is true and it is a hybrid application

},"type": {

"title": "Message header type",

"type": [ {

"enum": [1], description: "CLIENT_STATE"

},

"enum": [2], description: "APPLICATION_CONTEXT"

}],

"enum": [3], description: "CONNECTION"

},

"enum": [4], description: "CONTROL"

},

"enum": [5], description: "CUSTOM_EVENT"

}],

"enum": [6],


131

}, description: "EXCEPTION"

}],

"required": true

Client state (Type 1) messages

Client state messages are delivered on a schedule basis or on changes to the environment state on the client. These are Type 1 JSON messages.

Note:

Replay of client state messages is not supported, except for scroll events.

Replay of scroll events that are captured from the client is supported for mobile sessions only in BBR only. See Search and Replay for Mobile Web.

Client State (Type 1) message schema

This is the schema for the Client State (Type 1) messages.

{

"$ref" : "MessageHeader",

"mobileState": {

"description": "Logical page being loaded for iOS and Android",

"type": "object",

"properties": {

"orientation": {

"title": "Current orientation of the device",

"type": "integer",

"required": true

},

"freeStorage": {

"title": "Amount of available storage in Mbytes",

"type": "number",

"required": true

},

"androidState": {

"description": "Current state in an Android device",

"type": "object",

"properties": {

"keyboardState": {

"title": "Current keyboard state",

"type": [ {

"enum": [0], description: "Keyboard not hidden"

},

"enum": [1],

},

}

},

"battery": { description: "Keyboard hidden"

},

"enum": [2], description: "Undefined"

}],

"required": true

"title": "Battery level from 0 to 100",

"type": "number",

"required": true

},

"freeMemory": {

"title": "Amount of available memory in Mbytes",

"type": "number",

"required": true

},

"connectionType": {

"title": "Current connection type",

"type": "string",

132


"required": true

},

"carrier": {

"title": "Carrier of device",

"type": "string",

"required": true

},

"networkReachability": {

"title": "Current network reachability",

"type": [ {

"enum": [0], description: "Unknown"

},

"enum": [1], description: "NotReachable"

},

"enum": [2], description: "ReachableViaWIFI"

},

"enum": [3], description: "ReachableViaWWAN"

}],

"required": true

},

"ip": {

"title": "Ip address of device",

"type": "string",

"required": true

}

},

"additionalProperties" : false

"clientState": {

"description": "Logical web page being loaded for UIC",

"type": "object",

"properties": {

"pageWidth": {

"title": "Width of the document of the web page",

"type": "integer",

"required": true

},

"pageHeight": {

"title": "Height of the document of the web page",

"type": "integer",

"required": true

},

"viewPortWidth": {

"title": "Width of viewport",

"type": "integer",

"required": true

},

"viewPortHeight": {

"title": "Height of viewport",

"type": "integer",

"required": true

},

"viewPortX": {

"title": "x position of scrollbar on viewport",

"type": "integer",

"required": true

},

"viewPortY": {

"title": "y position of scrollbar on viewport",

"type": "integer",

"required": true

},

"event": {

"title": "event that triggered the client state",


133

}

"type": "string",

"required": true

},

"deviceScale": {

"title": "scaling factor for fitting page into window for replay",

"type": "integer",

"required": true

},

"viewTime": {

"title": "time in milliseconds user was on the event triggered",

"type": "integer",

"required": true

},

"viewPortXStart": {

"title": "initial start x position of scrollbar on viewport",

"type": "integer",

"required": only used in scroll events

},

"viewPortYStart": {

"title": "initial start y position of scrollbar on viewport",

"type": "integer",

"required": only used in scroll events

},

},


}

Client State (Type 1) message example

This is an example of a Client State (Type 1) message. This example comes from an

Android native application.

{

"offset": 667,

"screenViewOffset": 4556,

"type": 1,

"mobileState": {

"orientation": 0,

"freeStorage": 33972224,

"androidState": {

"keyboardState": 0

},

"battery": 50,

"freeMemory": 64630784,

"connectionType": "UMTS",

"carrier": "Android",

"networkReachability": "ReachableViaWWAN",

"ip": "0.0.0.0"

}

}

ScreenView (Type 2) messages

ScreenView messages indicate steps in a visitor's experience with your application.

These steps can be logical page views in a web application, screen changes in a mobile application, or steps in a business process. ScreenView messages are Type 2

JSON messages.

In Release 8.5 and earlier, these messages were called Application Context messages.

ScreenView (Type 2) message schema

This is the schema for the ScreenView (Type 2) JSON messages.

134


{


"dcid": {

"title": "Unique identifier that is used to match the corresponding

DOM Capture message associated with this message.",

"type": "string",

"required": false

},

"screenview/context": {

"description": "Logical page being loaded or unloaded",

"type": "object",

"properties": {

"type": {

"title": "Type of application context - LOAD or UNLOAD",

"type": "string",

"required": true

},

"name": {

"title": "Name of the logical page. This is given by customer or it uses name of the class used by the page.",

"type": "string",

"required": true

},

"url": {

"title": "URL path of the logical page",

"type": "string",

"required": false only used in UIC

},

"host": {

"title": "URL Host of the logical page",

"type": "string",

"required": false only used in UIC

},

"referrer": {

"title": "Previous logical page loaded, only used in LOAD",

"type": "string",

"required": false

},

"referrerUrl": {

"title": "Url of the previous logical page loaded",

"type": "string",

"required": false, not used in UIC

}

},

"additionalProperties" : false,

"required": false

}

}

ScreenView (Type 2) message example

This is an example of a ScreenView (Type 2) message. This example contains three

ScreenView messages, indicating page load and page unload events.

{

"offset": 124,

"contextOffset": 4556,

"type": 2,

"context": {

"type": "LOAD",

"name": "PAGE 2",

"referrer": "PAGE 1"

}

}

{


135

"type": 2,

"offset": 19216

"context": {

"type": "UNLOAD",

"name": "PAGE 2"

}

}

{

"type": 2,

"offset": 2144,

"contextOffset": 0,

"count": 9,

"fromWeb": true,

"webviewId": "webview1",

"screenview": {

"type": "LOAD",

"name": "Ford",

"url": "/dynamic/ford.aspx",

"host": "http://www.cartest.com",

"referrer": "BMW",

"referrerUrl": "/dynamic/bmw.aspx"

}

}

Connections (Type 3) messages

Connection messages provide information about how requests or responses are managed by the client application. Connections messages are Type 3 JSON messages.

Connections (Type 3) messages schema

This is the schema for Connections (Type 3) JSON messages.

{


"connection": {

"description": "Connection in application",

"type": "object",

"properties": {

"statusCode": {

"title": "Status code of connection",

"type": "integer",

"required": true

},

"responseDataSize": {

"title": "Response data size",

"type": "number",

"required": true

},

"initTime": {

"title": "Initial time of connection",

"type": "number",

"required": true

},

"responseTime": {

"title": "Response time of connection",

"type": "number",

"required": true

},

"url": {

"title": "Url of connection",

"type": "string",

"required": true

136


},

"loadTime": {

"title": "Load time from connection",

"type": "number",

"required": true

}

},


}

}

Connections (Type 3) message example

This example shows the Connections (Type 3) JSON message.

{

"offset": 03829,

"type": 3,


"type": 3,

"connection": {

"statusCode": 200,

"responseDataSize": 0272,

"initTime": 01333669478556,

"responseTime": 02237,

"url": "http://google.com",

"url": "/store/js/tealeaf/

TeaLeafTarget.php??width=540&height=960&orientation=0",

"loadTime": 0

}

}

Control (Type 4) messages

Control messages are used to log user action and behavior. These messages consist of a control identifier and a value that is returned by the identified control. Control messages are Type 4 JSON messages.

The control identifiers are mapped to specific controls for the submitting client framework. The value can be a number, a text string, or structured data.

Control (Type 4) message schema

This is the schema for Control (Type 4) messages.

The X and Y properties are not present in the UI Capture frameworks.

{


"offset": {

"title": "Milliseconds offset from offset for when focusIn of text fields occur",

"type": "integer",

"required": true

},

"target": {

"description": "Control being logged",

"type": "object",

"properties": {

"position": {

"description": "Position of control being logged",

"type": "object",

"properties": {

"x": {

"title": "X of the control",

"type": "integer",

"required": true

},


137

"y": {

"title": "Y of the control",

"type": "integer",

"required": true

},

"height": {

"title": "height of control",

"type": "integer",

"required": true

},

"width": {

"title": "width of control",

"type": "integer",

"required": true

},

"relXY": {

"title": "relative X & Y ratio that can be from 0 to 1 with a default value of 0.5",

"type": "string",

"required": true for click events

},

},


}

"id": {

"title": "Id/Name/Tag of control",

"type": "string",

"required": true

}, idType": { attribute): -1,

"title": "Indicates what id is based on: Native id (e.g. HTML ’id’ xPath: -2, or Custom attribute for UIC and

Hashcode value for Native: -3, or xPath for Native iOS/Android: -4",

"type": "integer",

"required": true

},

"dwell": {

"title": "Dwell time of control",

"type": "integer value that is in milliseconds",

"required": false

},

"visitedCount": {

"title": "Number of times a form control has been visited to be filled by user.",

"type": "integer",

"required": false

},

"isParentLink": {

"title": "To indicate if control a A type tag",

"type": "boolean",

"required": false only in UIC for usability

},

"name": {

"title": "Name of control",

"type": "string",

"required": true in UIC

},

"type": {

"title": "Type of control",

"type": "string",

"required": true

},

"subType": {

"title": "SubType of control",

"type": "string",

138


"required": true

},

"tlType": {

"title": "tlType of control that normalizes the control type for eventing",

"type": "string",

"required": true

},

"prevState": {

"title": "Previous state of control",

"type": "object",

"required": true,

"properties": {

"?": { // Could be any variable name given by developer

"title": "Additional data in string format",

"type": "string",

"required": false

}

},

"currState": {

"title": "Current state of control",

"type": "object",

"required": true,

"properties": {



"type": "string",

"required": false

}

}

},


}

"event": {

"description": "Event from control",

"type": "object",

"properties": {

"tlEvent": {

"title": "Tealeaf type of event",

"type": "string",

"required": true

},

"type": {

"title": "Type of event",

"type": "string",

"required": true

},

"subType": {

"title": "Subtype of event",

"type": "string",

"required": true

}

},


}

}

Control (Type 4) message example

This is an example of a Control (Type 4) message.

This example shows a control with an idType of XPATH, which means no id was assigned to the control in the application so Tealeaf traversed the layout and created an XPATH id for the control:,


139

{

},

"screenviewOffset":380,

"target":{

"id":"[KV,0]",

"position":{

"y":331,

"x":0,

"width":320,

"height":202

},

"idType":"-4",

"currState":{

"y":"0",

"x":"0"

},

"style":{

"paddingTop":2,

"textBGAlphaColor":255,

"bgAlphaColor":255,

"paddingBottom":0,

"paddingLeft":0,

"hidden":false,

"paddingRight":0

},

"subType":"View",

"type":"KeyboardView",

"tlType":"keyboard"

},

"type":4,

"offset":728,

"count":3,

"fromWeb":false,

"event":{

"type":"UIKeyboardDidShowNotification",

"tlEvent": "kbDisplayed"

}

Custom Event (Type 5) messages

The Custom Event messages are used to custom log any event from any place in the application. Custom Event messages are Type 5 JSON messages.

Custom Event (Type 5) message schema

This is the schema for the Custom Event (Type 5) messages.

The only required field is the name of the custom event (name value).

Application-specific code must be created to process this logged message type.

{


"customEvent": {

"description": "Custom event message",

"type": "object",

"properties": {

"name": {

"title": "Exception name/type",

"type": "string",

"required": true

},

"data": "Additional properties given by developer",

"type": "object",

"required": truefalse,

"properties": {



140


"type": "string",

"required": false

}

},

},


}

}

Custom Event (Type 5) message example

This is an example of a Custom Event (Type 5) message. This custom event message provides the name of the custom event (MyEvent_1) and several custom properties in the data section.

{

"type": 5,

"offset": 17981,


"customEvent": {

"name": "MyEvent_1",

"data": {

"Foo": "Bar",

"validationError": "Invalid zipcode.",

"ajaxPerformance": 56734

}

}

}

Exception (Type 6) messages

The exceptions messages type records the name and description of an exception occurring on the client application. Exception messages are Type 6 JSON messages.

Exception (Type 6) message schema

This is the schema for the Exception (Type 6) messages.

{


"exception": {

"description": "Exception description message",

"type": "object",

"properties": {

"description": {

"title": "Exception message from api call",

"type": "string",

"required": true

},

"name": {

"title": "Exception name/type",

"type": "string",

"required": true, not for UIC

},

"stackTrace": {

"title": "Exception stacktrace given by framework",

"type": "string",


},

"url": {

"title": "Url where exception ocurred",

"type": "string",

"required": true for UIC

},

"fileName": {

"title": "File name where exception ocurred",

"type": "string",

"required": true for iOS, not for UIC

},


141

"line": {

"title": "Line number where eception occurred.",

"type": "string",

"required": true for UIC and iOS

},

"unhandled": {

"title": "Whether exception had a try catch around it.",

"type": "boolean",


},

"data": {

"title": "User defined data being passed with user info from system",

"type": "object",

"required": true for iOS, not for UIC

"properties": {

"userInfo": {

"type": "object",

"title": "OS information from error or exception",

"required": iOS optional (data is JSON serializable or not)

},

"message": {

"type": "string",

"title":"User supplied message on error event",

"required":iOS optional (not on exceptions required on error)

}

},

},

},


}

}

Exception (Type 6) message example

This is an example of an Exception (Type 6) message. This example exception indicates an attempt to read a property named 'type' of a variable or value which is undefined.

{

"type" : 6,

"offset" : 4606,

"screenviewOffset" : 4603,

"count" : 3,

"fromWeb" : true,

"exception" : {

"description" : "Uncaught TypeError: Cannot read property ’type’ of undefined",

"url" : "http://www.xyz.com/js/badscript.js",

"line" : 258

}

}

Performance (Type 7) messages

Performance messages show performance data from a browser. Performance messages are Type 7 JSON messages.

Performance (Type 7) message schema

This is the schema for Performance (Type 7) messages.

142


{


"performance": {

"description": "Performance message",

"type": "object",

"properties": {

},


}

}

Performance (Type 7) message example

This is an example of a Performance (Type 7) message.

{

"type": 7,

"offset": 9182,

"screenviewOffset": 9181,

"count": 3,

"fromWeb": true,

"performance": {

"timing": {

"redirectEnd": 0,

"secureConnectionStart": 0,

"domainLookupStart": 159,

"domContentLoadedEventStart": 2531,

"domainLookupEnd": 159,

"domContentLoadedEventEnd": 2551,

"fetchStart": 159,

"connectEnd": 166,

"responseEnd": 1774,

"domComplete": 2760,

"responseStart": 728,

"requestStart": 166,

"redirectStart": 0,

"unloadEventEnd": 0,

"domInteractive": 2531,

"connectStart": 165,

"unloadEventStart": 0,

"domLoading": 1769,

"loadEventStart": 2760,

"navigationStart": 0,

"loadEventEnd": 2780,

"renderTime": 986

}

},

"navigation": {

"type": "NAVIGATE",

"redirectCount": 0

}

}

Web Storage (Type 8) messages

Web Storage messages are any objects that contain information about local storage information on the browser. Web Storage messages are Type 8 JSON messages.

Web Storage (Type 8) message schema

This is the schema for the Web Storage (Type 8) messages.

"$ref" : "MessageHeader", webStorage: { key : “string”, value: “string”,

}


143

Web Storage (Type 8) message example

This is an example of a Web Storage (Type 8) message.

{ type: 8, offset: 25, screenviewOffset: 23, count: 2, fromWeb: true, webStorage: { key: "vistCount" value: "5"

}

}

Overstat Hover Event (Type 9) messages

Overstat

®

Hover Event messages are any object containing information about mouse hover and hover-to-click activity. Overstat Hover Event messages are Type 9

JSON messages.

Overstat Hover Event (Type 9) message schema

This is the schema for Overstat Hover Event (Type 9) messages

"$ref" : "MessageHeader", event: { xPath: "string", hoverDuration: int, hoverToClick: boolean, gridPosition: { x: int, y: int

}

}

Overstat Hover Event (Type 9) message example

This is an example of a Overstat Hover Event (Type 9) message.

{ type: 9, offset: 25, screenviewOffset: 23, count: 2, fromWeb: true, event: { xPath: "[\"ii\"]", hoverDuration: 5457, hoverToClick: false, gridPosition: { x: 3, y: 2

}

}

Layout (Type 10) messages

Layout messages show the current display layout of a native page. Layout messages are Type 10 JSON messages.

Layout (Type 10) message schema

This is the schema for Layout (Type 10) messages.


"version": {

"description": "Message Version, must be in x.x format",

"type": "string",

"required": true

144


},

"layoutControl": {

"description": "Control on application page",

"type": "object",

"properties": {

"position": {

"description": "Position of control",

"type": "object",

"properties": {

"x": {


"type": "integer",

"required": true

},

"y": {


"type": "integer",

"required": true

},

"height": {


"type": "integer",

"required": true

},

"width": {


"type": "integer",

"required": true

},

}


}

"id": {


"type": "string",

"required": true

},

"type": {


"type": "string",

"required": true

},

"subType": {


"type": "string",

"required": true

},

"tlType": {


"type": "string",

"required": true

},

"currState": {


"type": "object",

"required": true,

"properties": {



"type": "string",

"required": false

}

}

},

"style" : {

"title": "Style of the control",

"type": "object",


145

}

"required": true,

"properties": {

"textColor": {

"title": "Text color",

"type": "string",

"required": true

},

"textAlphaColor": {

"title": "Text alpha color",

"type": "string",

},

"required": true

"textBGColor": {

"title": "Text background color",

"type": "string",

"required": true

},

"textBGAlphaColor": {

"title": "Text background alpha color",

"type": "string",

"required": true

},

"bgColor": {

"title": "Background color",

"type": "string",

"required": true

},

"bgAlphaColor": {

"title": "Background alpha color",

"type": "string",

"required": true

}

}

},

}


Layout (Type 10) message example

This is an example of a Layout (Type 10 ) message.

{

"offset": 27004,


"count": 16,

"fromWeb": false,

"type": 10,

"version" : "1.0",

"orientation" : 0,

"deviceHeight": 592,

"deviceWidth": 360,

"layout": {

"name": "loginPage",

"class": "loginPageActivty",

"controls": [

{

"position": {

"y": 38,

"height": 96,

"width": 720,

"x": 0

},

"id": "com.tl.uiwidget:id\/userNameLabel",

"idType": -1,

"type": "UILabel",

"subType": "UIView",

146


}

},

{...},

{...}

"tlType": "label",

"currState": {

"text": "User name*"

},

"style": {

"textColor": 16777215,

"textAlphaColor": 1,

"textBGColor": 0,

"textBGAlphaColor": 0,

"bgColor": 0,

"bgAlphaColor": 0

]

}

}

Gesture (Type 11) messages

Gesture messages are used to log user action and behavior. A Gesture message consists of a control identifier and a the value returned by that control. The control identifiers are mapped to specific controls on the client logging platform. The value can be a number, a text string or structured data. Gesture messages are Type 12

JSON messages.

Gesture (Type 11) message schema

This is the schema for Gesture (Type 11) messages.

Touch events

This is a JSON object that represents a gesture finger that is linked to control underneath the finger. It is reused in targets property of gesture type 11.This is the schema for touch events:

{


"focusInOffset": {

"title": "Milliseconds offset from offset for when focusIn of text fields occur",

"type": "integer",

"required": false

},

"target": {

"description": "Control being logged",

"type": "object",

"properties": {

"position": {

"description": "Position of control being logged",

"type": "object",

"properties": {

"x": {


"type": "integer",

"required": true

},

"y": {


"type": "integer",

"required": true

},

"height": {


"type": "integer",


147

"required": true

},

"width": {


"type": "integer",

"required": true

},

"relXY": {

"title": "relative X & Y ratio that can be from 0 to 1 with a default value of 0.5",

"type": "string",

"required": true for click events

},

"scrollX": {

"title": "scroll X of the page",

"type": "integer",

"required": true

},

"scrollY": {

"title": "scroll Y of the page",

"type": "integer",

"required": true

},

},


}

"id": {


"type": "string",

"required": true

},

"idType":{

"title": "Indicates what id is based on: Native id (e.g. HTML

’id’ attribute): -1, xPath: -2, or Custom attribute for

UIC and Hashcode value for Native: -3, or xPath for Native iOS/Android: -4",

"type": "integer",

"required": true

},

"dwell": {

"title": "Dwell time of control",


"required": false

},

"focusInOffset": {

"title": "Offset when control got focus",



},

"visitedCount": {

"title": "Number of times a form control has been visited to be filled by user.",

"type": "integer",

"required": false

},

"isParentLink": {

"title": "To indicate if control a A type tag",

"type": "boolean",

"required": false only in UIC for usability

},

"name": {

"title": "Name of control",

"type": "string",


},

148


"type": {


"type": "string",

"required": true

},

"subType": {


"type": "string",

"required": true

},

"tlType": {


"type": "string",

"required": true

},

"prevState": {

"title": "Previous state of control",

"type": "object",

"required": false,

"properties": {



"type": "string",

"required": false

}

}

},

"currState": {


"type": "object",

"required": true,

"properties": {



"type": "string",

"required": false

}

}

}

},


}

"event": {


"type": "object",

"properties": {

"tlEvent": {


"type": "string",

"required": true

},

"type": {

"title": "Type of event",

"type": "string",

"required": false

},

"subType": {

"title": "Subtype of event",

"type": "string",

"required": false

}

},


}}


149

Tap event schema

This contains only one touch object. This is the schema for tap events:

{ and ends with last object when finger is lifted from device.",

"type": "array",

"required": true,

"$ref": "Touch"

}

}

}

}


"event": {


"type": "object",

"properties": {

"tlEvent": {


"type": "string",

"required": true

},

"type": {

"title": "Type of event framework reports",

"type": "string",

"required": false

}

}

},

"touches": {

"description": "Gestures touch objects per finger.",

"type": "array",

"required": true

"items": {

"description": "Touch objects per finger starting with intial

Swipe event schema

The swipe event contains only one touch object which will be the initial location with its corresponding direction and velocity. This is the schema for swipe events:

{


"event": {


"type": "object",

"properties": {

"tlEvent": {


"type": "string",

"required": true

},

"type": {


"type": "string",

"required": false

}

}

},

"touches": {


"type": "array",

"required": true

"items": {

"description": "Touch objects per finger starting with intial and ends with last object when finger is lifted from device.",

150


right.",

"title": "The direction of the swipe which can be up, down. left or

"type": "string",

"required": true

},

"velocityX": { x axis",

"title": "The velocity of this measured in pixels per second along the

"type": "float",

"required": true

},

"velocityY": { y axis",

"title": "The velocity of this measured in pixels per second along the

"type": "float",

"required": false

}

}

"type": "array",

"required": true,

"$ref": "Touch"

}

}

},

"direction": {

Pinch events

The pinch event contains only an initial touch object per finger and the last touch object per finger, with the corresponding direction. This is the schema for pinch events:

{


"event": {


"type": "object",

"properties": {

"tlEvent": {


"type": "string",

"required": true

},

"type": {


"type": "string",

"required": false

}

}

},

"touches": {


"type": "array",

"required": true

"items": {

"description": "Touch objects per finger starting with intial and ends with last object when finger is lifted from device.",

"type": "array",

"required": true,

"$ref": "Touch"

}

}

},

"direction": {

"title": "Direction of pinch which can be open or close",


151

"type": "string",

"required": true

}

}

Gesture (Type 11) message example

These are examples of UIC SDK Gesture (Type 11) messages.

Tap events

This example is a gesture message for a tap event:

{

"fromWeb": false,

"type": 11,

"offset": 46788,


"count": 14,

"event": {

"type": "ACTION_DOWN",

"tlEvent": "tap"

},

"touches": [

[

{

"position": {

"x": 179,

"y": 543

},

"control": {

"position": {

"height": 184,

"width": 1080,

"relXY": "0.17,0.93"

"scrollX": 10

"scrollY": 15

},

"id": "[RL,0]",

"idType": -4,

"type": "RelativeLayout",

"subType": "ViewGroup",

"tlType": "canvas"

}

}

]

]

}

Double tap events

This example is a gesture message for a double tap event:

{

"fromWeb": false,

"type": 11,

"offset": 49585,


"count": 15,

"event": {


"tlEvent": "doubleTap"

},

"touches": [

[

{

"position": {

152


}

]

]

}

"x": 182,

"y": 520

},

"control": {

"position": {

"height": 184,

"width": 1080,

"relXY": "0.17,0.8"

"scrollX": 10

"scrollY": 15

},

"id": "[RL,0]",

"idType": -4,



"tlType": "canvas"

}

Tap hold events

This example is a gesture message for a tap hold event:

{

"fromWeb": false,

"type": 11,

"offset": 52389,


"count": 16,

"event": {


"tlEvent": "tapHold"

},

"touches": [

[

{

"position": {

"x": 182,

"y": 536

},

"control": {

"position": {

"height": 184,

"width": 1080,

"relXY": "0.17,0.89"

"scrollX": 10

"scrollY": 15

},

"id": "[RL,0]",

"idType": -4,



"tlType": "canvas"

}

}

]

]

}


153

Swipe event example

The swipe event contains only one touch object which will be the initial location with its corresponding direction and velocity. This example is a message for a swipe event:

{

"fromWeb": false,

"type": 11,

"offset": 54409,


"count": 17,

"event": {


"tlEvent": "swipe"

},

"direction": "right",

"velocityX": 7762.8466796875,

"velocityY": 127.47991943359375,

"touches": [

[

{

"position": {

"x": 75,

"y": 538

},

"control": {

"position": {

"height": 184,

"width": 1080,

"relXY": "0.07,0.9"

"scrollX": 10

"scrollY": 15

},

"id": "[RL,0]",



"tlType": "canvas"

},

}

{

"position": {

"x": 212,

"y": 526

},

"control": {

"position": {

"height": 184,

"width": 1080,

"relXY": "0.2,0.84"

"scrollX": 10

"scrollY": 15

},

"id": "[RL,0]",

"idType": -4,



"tlType": "canvas"

}

}

]

]

}

154


Pinch events

The pinch event contains only an initial touch object per finger and the last touch object per finger, with the corresponding direction. This example is a message for a pinch event:

{

"type": 11,

"offset": 2220,


"count": 6,

"fromWeb": false,

"event": {

"tlEvent": "pinch",

"type": "onScale"

},

"touches": [

[

{

"position": {

"y": 388,

"x": 0

},

"control": {

"position": {

"height": 100,

"width": 100,

"relXY": "0.6,0.8"

"scrollX": 10

"scrollY": 15

},

"id": "com.tl.uic.appDarkHolo:id/imageView1",

"idType": -1,

"type": "ImageView",

"subType": "View",

"tlType": "image"

}

},

{

"position": {

"y": 388,

"x": 400

},

"control": {

"position": {

"height": 100,

"width": 100,

"relXY": "0.4,0.7"

"scrollX": 10

"scrollY": 15

},


"idType": -1,


"subType": "View",

"tlType": "image"

}

}

],

[

{

"position": {

"y": 388,

"x": 800

},

"control": {

"position": {


155

}

"height": 100,

"width": 100,

"relXY": "0.6,0.8"

"scrollX": 10

"scrollY": 15

},


"idType": -1,


"subType": "View",

"tlType": "image"

}

},

{

"position": {

"y": 388,

"x": 500

},

"control": {

"position": {

"height": 100,

"width": 100,

"relXY": "0.4,0.7"

"scrollX": 10

"scrollY": 15

},

}

}

]

],

"direction": "close"


"idType": -1,


"subType": "View",

"tlType": "image"

DOM Capture (Type 12) messages

DOM Capture messages are objects that contain serialized HTML data (DOM snapshot) of the page. DOM Capture Messages are Type 12 JSON messages.

DOM Capture (Type 12) message schema

This is the schema for the DOM Capture (Type 12) messages.


"domCapture": {

"description": "Serialized HTML snapshot of the document.",

"type": "object",

"properties": {

"dcid": {

"title": "Unique identifier of this DOM snapshot.",

"type": "string",

"required": true

} a full DOM or a DOM diff.",

"type": "boolean",

"required": false

},

"fullDOM": {

"title": "Flag indicating if the contents of this message contain

"charset": {

"title": "Browser reported charset of the document.",

"type": "string",

"required": false

},

156


"root": {

"title": "Serialized HTML of the document.",

"type": "string",

"required": false

},

"diffs": {

"title": "List of DOM diff entries. Each entry can contain a HTML Diff or an attribute diff.",

"type": "array",

"required": false,

"Item": {

"title": "An object containing the DOM diff. The diff can be a HTML diff or an attribute diff.",

"type": "object",

"required": false,

"properties": {

"xpath": {

"title": "The xpath of the node.",

"type": "string",

"required": true

},

"root": {

"title": "Serialized HTML of the node referred by the xpath. Presence of this property constitutes a HTML diff.",

"type": "string",

"required": false

},

"attributes": {

"title": "List of attribute diff entries. Each entry contains a single attribute diff corresponding to the node referred by the xpath. Presence of this property constitutes an attribute diff.",

"type": "array",

"required": false,

"Item": {

"title": "An object containing the attribute diff.",

"type": "object",

"required": true,

"properties": {

"name": {

"title": "The attribute name.",

"type": "string",

"required": true

},

"value": {

"title": "The attribute value.",

"type": "string",

"required": true

}

}

}

}

}

},

"eventOn": {

}

"title": "Flag indicating if Tealeaf eventing should be enabled for this DOM Capture snapshot.",

"type": "boolean",

"required": false

},

"url": {

"title": "URL path of the snapshot document",

"type": "string",

"required": false

},


157

"host": {

"title": "URL Host of the snapshot document",

"type": "string",

"required": false

},

"error": {

"title": "Error message",

"type": "string",

"required": false

},

"errorCode": {

"title": "Error code corresponding to the error message.",

"type": "integer",

"required": false

},

"frames": {

"title": "Serialized HTML of any child frames of the document",

"type": "array",

"required": false,

"Item": {

"title": "An object containing serialized HTML of the frame",

"type": "object",

"required": false,

"properties": {

"tltid": {

"title": "Unique identifier for this frame. Same tltid is added to the serialized HTML source of the parent."

"type": "string",

"required": true

},

"charset": {

"title": "Browser reported charset of the document.",

"type": "string",

"required": true

},

"url": {

"title": "URL path of the snapshot document",

"type": "string",

"required": true

},

"host": {

"title": "URL Host of the snapshot document",

"type": "string",

"required": true

},

}

}

},

"canvas" : {

"root": {

"title": "Serialized HTML of the document.",

"type": "string",

"required": true

}

"title": "Serialized data of the canvas snapshot.",

"type": "array",

"required": false,

}

},


}

158


DOM Capture (Type 12) message example

This is an example of a DOM Capture (Type 12) message.

This example shows a DOM message with full DOM capture enabled:

{

// DOM Capture messages use type 12

"type": 12,

// The standard UIC message properties

"offset": 16821,


"count": 5,

"fromWeb": true,

"domCapture": {

"dcid": "dcid-3"

"fullDOM":true

"charset": "ISO-8859-1",

"root": "<html><body><iframe id="greeting.html" tltid="tlt-4"/>

</body></html>",

"host": "http://www.uictest.com",

"url": "/h4/dcTest.html",

"eventOn": true,

"frames": [

{

"tltid": "tlt-4",

"root": "<html><body>Hello, World!</body></html>",

"charset": "ISO-8859-1",

"host": "http://www.uictest.com",

"url": "/h4/greeting.html"

}

],

"canvas": []

}

}

This example shows a DOM capture message with DOM diff enabled:

{

"type": 12,

"offset": 13874,


"count": 6,

"fromWeb": true,

"domCapture": {

"fullDOM": false,

"diffs": [

{

"xpath": "[[\"html\",0],[\"body\",0],[\"div\",1]]",

"root": "<div class=\"bluebg\"><div><div>Input 1<input type=\"text\" name=\"ip-x-1\" value=\"\"></div></div></div>"

}

],

"dcid": "dcid-3.1437256358764",

"eventOn": false

}

}

DOM Diff (with HTML and attribute diff):

{

"type": 12,

"offset": 5794,



159

"count": 8,

"fromWeb": true,

"domCapture": {

"fullDOM": false,

"diffs": [

{

"xpath": "[[\"html\",0],[\"body\",0],[\"div\",2],[\"div\",1]]",

"root": "<div>Select List:<select name=\"select.pvt\"><option value=\"O1\" selected=\"selected\">1</option><option value=\"O2\">2</option>

<option value=\"O3\">3</option></select></div>"

},

{

"xpath": "[[\"cb1\"]]",

"attributes": [

{

"name": "style",

"value": "height: 13px; width: 13px; visibility: hidden;"

}

]

},

{

"xpath": "[[\"container_1\"],[\"table\",0],[\"tbody\",0],

[\"tr\",2],[\"td\",1],[\"select\",0]]",

"attributes": [

{

"name": "style",

"value": "visibility: hidden;"

}

]

}

],

"dcid": "dcid-3.1437256879815",

"eventOn": false

}

}

This example shows the error message when the captured DOM message length exceeds the configured threshold:

{

// DOM Capture messages use type 12

"type": 12,

// The standard UIC message properties

"offset": 16821,


"count": 5,

"fromWeb": true,

// The DOM Capture data is namespaced in the domCapture object

"domCapture": {

// The "error" contains the verbose error message explaining why the

DOM Capture couldn’t be performed.

"error": "Captured length (18045) exceeded limit (10000).",

// The "errorCode" contains the numeric code for this error message.

Currently, there is only 1 error message.

"errorCode": 101,

// The "dcid" property contains the unique string identifying this

DOM Capture within the page instance.

"dcid": "dcid-1.1414088027401"

}

}

160


GeoLocation (Type 13) messages

A GeoLocation message logs a user's location information. The message consists of a control identifier and a GeoLocation value. If the user has given the permission to use location data, GeoLocation returns latitude, longitude, accuracy values. If the user has not given permission to use location data, GeoLocation returns an error code and error string.

GeoLocation (Type 13) message schemas

This is the schema for the GeoLocation (Type 13) JSON messages:

This is the schema for messages from a device that the user has given permission to use location data:


"geolocation": {

"lat": double,

"long": double,

"accuracy": float

}

This is the schema for messages from a device that the user has not given permission to use location data:


"geolocation": {

"errorCode": int,

"error": "string",

}

GeoLocation (Type 13) message examples

This is an example of the GeoLocation (Type 13) JSON message.

This is an example of a message from a device that the user has given permission to use location data:

{ "type": 13,

"geolocation": {

"lat": 37.5680,

"long": -122.3292,

"accuracy": 65

}

}

This is an example of a message from a device that the user has not given permission to use location data:

{ "type": 13,

"geolocation": {

"errorCode": 201,

"error": "permission denied",

}

}


161

162


Chapter 7. Troubleshooting

Troubleshooting and debugging - enabling raw request and response headers

For debugging purposes, it may be useful to include the raw request and the response headers in the data that is passed by the PCA to the Canister. This method is useful if you are not seeing any JSON data that is parsed in Tealeaf.

Including these sections in your Tealeaf sessions can significantly increase the storage requirements for mobile sessions. These options should be enabled only for debugging purposes.

In the PCA Pipeline tab, set the following properties:

Setting Value

Include Raw Request

true

Include Response Headers

true

See "PCA Web Console - Pipeline Tab" in the IBM Tealeaf Passive Capture Application

Manual section.

Troubleshooting - managing client-side issues

The section that follows describes how the IBM Tealeaf Android SDK manages application crashes, exceptions, or other issues that can occur on the mobile device or the network.

Exceptions or crashes

Application exceptions are logged and reported to IBM Tealeaf in JSON format.

For devices that run iOS, a transmission of the current exception to the server is attempted. A copy is added to the set of messages queued locally and is sent the next time that the application is started.

For Android devices, all local data in the device is flushed. The exception object is transmitted to the server.

Power failures

A TL Library Error: File Not Found exception might be caused by disruption to the monitored application. If the user turned off the application or if it is closed, the posting task is disabled. When the application restarts, the library begins sending the queued JSON messages. However, if some of these reference images that are no longer available, the File Not Found error is generated.

If power failures are a persistent problem, you can configure the client application to save to local disk at smaller intervals, sending to server at more frequent intervals. You can modify the local cache size and POSTs from the client. These settingssettings are managed with the configuration file.


163

Kill switch

If the device is unable to connect to the target page, the device does not capture data.

Network issues

If there are network connectivity issues, these events are logged as connection objects with details on the issues.

v For GET issues as a result of application interruptions, an exception object is generated.

v If the network connection is interrupted, user actions are saved and sent later.

Low memory or local storage

If low memory or low local storage conditions occur, a custom log message is generated.

For devices that run iOS, user data is trimmed in memory until more memory becomes available.

For Android devices, all collected data on the device is flushed, and the Android

SDK is disabled for the device.

164


Chapter 8. IBM Tealeaf documentation and help

IBM Tealeaf provides documentation and help for users, developers, and administrators.

Viewing product documentation

All IBM Tealeaf product documentation is available at the following website: https://tealeaf.support.ibmcloud.com/

Use the information in the following table to view the product documentation for

IBM Tealeaf:

Table 32. Getting help

To view...

Product documentation

IBM Tealeaf Knowledge Center

Help for a page on the IBM Tealeaf Portal

Help for IBM Tealeaf CX PCA

Do this...

On the IBM Tealeaf portal, go to ? > Product

Documentation

.

On the IBM Tealeaf portal, go to ? > Product

Documentation

and select IBM Tealeaf

Customer Experience in the ExperienceOne

Knowledge Center.

On the IBM Tealeaf portal, go to ? > Help

for This Page

.

On the IBM Tealeaf CX PCA web interface, select Guide to access the IBM Tealeaf CX

PCA Manual.

Available documents for IBM Tealeaf products

The following table is a list of available documents for all IBM Tealeaf products:

Table 33. Available documentation for IBM Tealeaf products.

IBM Tealeaf products

IBM Tealeaf CX

Available documents

v

IBM Tealeaf Customer Experience Overview

Guide

v

IBM Tealeaf CX Client Framework Data

Integration Guide

v

IBM Tealeaf CX Configuration Manual

v

IBM Tealeaf CX Cookie Injector Manual

v

IBM Tealeaf CX Databases Guide

v

IBM Tealeaf CX Event Manager Manual

v

IBM Tealeaf CX Glossary

v

IBM Tealeaf CX Installation Manual

v

IBM Tealeaf CX PCA Manual

v

IBM Tealeaf CX PCA Release Notes


165

Table 33. Available documentation for IBM Tealeaf products (continued).

IBM Tealeaf products

IBM Tealeaf CX

Available documents

v

IBM Tealeaf CX RealiTea Viewer Client Side

Capture Manual

v

IBM Tealeaf CX RealiTea Viewer User

Manual

v

IBM Tealeaf CX Release Notes

v

IBM Tealeaf CX Release Upgrade Manual

v

IBM Tealeaf CX Support Troubleshooting

FAQ

v

IBM Tealeaf CX Troubleshooting Guide

v

IBM Tealeaf CX UI Capture j2 Guide

v

IBM Tealeaf CX UI Capture j2 Release Notes

IBM Tealeaf cxImpact v

IBM Tealeaf cxImpact Administration Manual

v

IBM Tealeaf cxImpact User Manual

v

IBM Tealeaf cxImpact Reporting Guide

IBM Tealeaf cxConnect

IBM Tealeaf cxOverstat

IBM Tealeaf cxReveal v

IBM Tealeaf cxConnect for Data Analysis

Administration Manual

v

IBM Tealeaf cxConnect for Voice of Customer


v

IBM Tealeaf cxConnect for Web Analytics


IBM Tealeaf cxOverstat User Manual

v

IBM Tealeaf cxReveal Administration Manual

v

IBM Tealeaf cxReveal API Guide

v

IBM Tealeaf cxReveal User Manual

IBM Tealeaf cxVerify

IBM Tealeaf cxView

IBM Tealeaf CX Mobile v

IBM Tealeaf cxVerify Installation Guide

v

IBM Tealeaf cxVerify User's Guide

IBM Tealeaf cxView User's Guide

v

IBM Tealeaf CX Mobile Android Logging

Framework Guide

v

IBM Tealeaf Android Logging Framework

Release Notes

v

IBM Tealeaf CX Mobile Administration

Manual

v

IBM Tealeaf CX Mobile User Manual

v

IBM Tealeaf CX Mobile iOS Logging

Framework Guide

v

IBM Tealeaf iOS Logging Framework Release

Notes

166


Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY

10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd.

19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL

BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"

WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR

PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:


167

IBM Bay Area Lab 1001 E Hillsdale Boulevard Foster City, California 94404 U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement,

IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources.

IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products.

Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to

IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.

Trademarks

IBM, the IBM logo, and ibm.com

® are trademarks or registered trademarks of

International Business Machines Corp., registered in many jurisdictions worldwide.

Other product and service names might be trademarks of IBM or other companies.

A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.

168


Privacy Policy Considerations

IBM Software products, including software as a service solutions, ("Software

Offerings") may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user or for other purposes. A cookie is a piece of data that a web site can send to your browser, which may then be stored on your computer as a tag that identifies your computer. In many cases, no personal information is collected by these cookies. If a Software Offering you are using enables you to collect personal information through cookies and similar technologies, we inform you about the specifics below.

Depending upon the configurations deployed, this Software Offering may use session and persistent cookies that collect each user's user name, and other personal information for purposes of session management, enhanced user usability, or other usage tracking or functional purposes. These cookies can be disabled, but disabling them will also eliminate the functionality they enable.

Various jurisdictions regulate the collection of personal information through cookies and similar technologies. If the configurations deployed for this Software

Offering provide you as customer the ability to collect personal information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for providing notice and consent where appropriate.

IBM requires that Clients (1) provide a clear and conspicuous link to Customer's website terms of use (e.g. privacy policy) which includes a link to IBM's and

Client's data collection and use practices, (2) notify that cookies and clear gifs/web beacons are being placed on the visitor's computer by IBM on the Client's behalf along with an explanation of the purpose of such technology, and (3) to the extent required by law, obtain consent from website visitors prior to the placement of cookies and clear gifs/web beacons placed by Client or IBM on Client's behalf on website visitor's devices

For more information about the use of various technologies, including cookies, for these purposes, See IBM's Online Privacy Statement at: http://www.ibm.com/ privacy/details/us/en section entitled "Cookies, Web Beacons and Other

Technologies."

Notices

169

170


IBM®

Printed in USA

IBM Android SDK Tealeaf User Guide

Assistant Bot

IBM Tealeaf

Android SDK Guide

Contents

IBM Tealeaf Android SDK Guide

Chapter 1. Tealeaf installation and implementation in an

Android application

Supported Frameworks

Eclipse Tealeaf plug-in for Android development

Tealeaf SDK for Android development

Client Framework versions supported in this documentation

Install the Tealeaf SDK for Android development in your application

Tealeaf SDK for Android development

Tealeaf package contents

Tealeaf sample application

Android development environment requirements

Minimum requirements

Supported operating systems

Eclipse platforms

Eclipse packages

Tealeaf impact on Android device resources

Android project changes

Install the UICAndroid.jar

Installation of TLFConfigurableItems.properties

Auto-instrumentation not supported

Configure Tealeaf properties

TLFConfigurableItems.properties

Configurable properties

Whether to display logcat messages

Set Target URL

Enable and set kill switch

How screen layouts are logged

Set logging level

Auto-instrumentation

Configuring Tealeaf properties for your application

Extended Android classes

Application class

Application class and the Eclipse Tealeaf plug-in

Activity class

Extending the Application class with the Tealeaf UICApplication class

Extending the Activity class with the Tealeaf UICActivity class

Extending your custom Application class to point to the Tealeaf

UICApplication class

Extending your custom Activity class to point to the Tealeaf

UICActivity class

Implement Tealeaf

Implementation tasks

Log screen layout for mobile app session replay

changes

Understand your activity

Replaying AlertDialogs

Replaying keyboard events

Supported controls

Integrate Tealeaf and IBM MobileFirst Platform Foundation

Development environment

IBM MobileFirst Platform Foundation high-level single project

Differences between IBM MobileFirst Platform Foundation 6.1 and IBM

MobileFirst Platform Foundation 6.2

Modify Tealeaf and IBM MobileFirst Platform Foundation classes

Process

Integrate Apache Cordova and PhoneGap applications using

Android classes without Tealeaf classes

Implementing screenViews

Basic configuration

Data privacy

Configuring sessionization for Android applications on the client

Configure requests in Android application

Uses non IBM Tealeaf session ID

Android application gestures

Configuration

Touch event methods

Log exceptions

Automatically log exceptions

Manually log exceptions

Example

Android application geolocation

Automatic logging

APIs

Hybrid applications