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

Transcription

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

2 Note Before using this information and the product it supports, read the information in Notices on page 155. This edition applies to version 9, release 0, modification 1 of IBM Tealeaf CX Mobile Android Logging Framework and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 1999, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents IBM Tealeaf CX Mobile Android Logging Framework Guide v Chapter 1. Tealeaf installation and implementation in an Android application Client Framework versions supported in this documentation Install the Tealeaf SDK for Android development in your application Tealeaf package contents Tealeaf sample application Android development environment requirements 3 Tealeaf impact on Android device resources... 4 Android project changes Configure Tealeaf properties Extended Android classes Implement Tealeaf Install the Eclipse Tealeaf plug-in for Android development in your application Tealeaf package contents Android development environment requirements 41 Tealeaf impact on Android device resources.. 43 Add Eclipse Tealeaf plug-in to your Eclipse Android project Configure Tealeaf properties Extended Android classes Implement Tealeaf Quick start for server configuration Target page for traffic capture Traffic volume management CX Passive Capture Application traffic capture verification Options for monitoring captures and processing 81 Configuring sessionization for Android applications in IBM Tealeaf Runtime configuration IBM Tealeaf events for CX Mobile Android Logging Framework Upgrading the CX Mobile Android Logging Framework Chapter 2. Configuration file Log level settings Kill switch settings Local cache file settings Post settings Masking settings Filter message type setting Cookie settings Session timeout setting Screen shot settings Internal settings: do not change Chapter 3. Sample applications Chapter 4. Guidelines Chapter 5. Reference UICActivity class UICApplication class Tealeaf class TLDefaultHttpClient class TLHttpRequestInterceptor class TLHttpResponseInterceptor class UICWebView class UICWebChromeClient Class UICWebViewClient Class Chapter 6. Sample Code How to instrument TextView based controls How to instrument ExpandableListView based controls How to instrument SlidingDrawer based controls 120 How to mask controls Server-Side KillSwitch sampling function Sampling Function for ASPX Sampling Function for JSP Sampling Function for PHP JSON message type schemas and examples Message header properties Message header properties schema Message header properties schema Client state (Type 1) messages ScreenView (Type 2) messages Connections (Type 3) messages Control (Type 4) messages Custom Event (Type 5) messages Exception (Type 6) messages Performance (Type 7) messages Web Storage (Type 8) messages Overstat Hover Event (Type 9) messages Layout (Type 10) messages Gesture (Type 11) messages DOM Capture (Type 12) messages Examples Chapter 7. Troubleshooting Debugging Tips Inclusion of raw request and response headers 151 Managing client-side issues Exceptions or crashes Power failures Kill switch Network issues Low memory or local storage Copyright IBM Corp. 1999, 2014 iii

4 Chapter 8. IBM Tealeaf documentation and help Privacy Policy Considerations Notices Trademarks iv IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

5 IBM Tealeaf CX Mobile Android Logging Framework Guide The IBM Tealeaf CX Mobile Android Logging Framework for mobile native applications requires the IBM Tealeaf CX Mobile license for Mobile App. For more information, contact your IBM Tealeaf representative. Licensees must implement in their apps code that is provided by IBM Tealeaf. For more information on downloading IBM Tealeaf, see IBM Passport Advantage Online. The IBM Tealeaf CX Mobile Android Logging Framework 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 CX Mobile Android Logging Framework software. Copyright IBM Corp. 1999, 2014 v

6 vi IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

7 Chapter 1. Tealeaf installation and implementation in an Android application You add the Tealeaf SDK to your application so that the CX Mobile Android Logging Framework can capture user interface and application events. There are two ways to install the Tealeaf SDK in your Android application. Supported Frameworks The installation and implementation instructions in this guide apply to the step-based version of JSON messaging from this client framework. The step-based version of JSON messaging from this client framework was introduced in Release 8.5. For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of submitting data from the client frameworks, which resulted in submitted data being split into individual hits in the Windows pipeline. In a future release, the hit-splitting method of processing data that is submitted from client frameworks is likely to be deprecated. The installation and implementation instructions for the legacy version are similar but require additional configuration in the Windows pipeline. Eclipse Tealeaf plug-in for Android development The Eclipse Tealeaf plug-in installs the Tealeaf SDK into your Eclipse workspace and includes basic configuration. You download the plug-in and install the plug-in with the Eclipse Install new 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 Copyright IBM Corp. 1999,

8 Client Framework versions supported in this documentation The installation and implementation instructions in this guide apply to the step-based version of JSON messaging from this client framework. The step-based version of JSON messaging from this client framework was introduced in Release 8.5. For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of submitting data from the client frameworks, which resulted in submitted data being split into individual hits in the Windows pipeline. Note: In a future release, the hit-splitting method of processing data that is submitted from client frameworks is likely to be deprecated. The installation and implementation instructions for the legacy version are similar but require additional configuration in the Windows pipeline. For more information about the earlier versions, including implementation steps, use the links that follow. Install the Tealeaf SDK for Android development in your application You add the Tealeaf SDK to your application so that the CX Mobile Android Logging Framework can capture user interface and application events. You manually install and configure the Tealeaf SDK in each application. Tealeaf SDK for Android development You manually install and configure the Tealeaf SDK. You download the Tealeaf installation package and you: 1. Move files to the proper locations in your application 2. Configure properties, including application-specific URLs 3. Extend Application and Activity classes Tealeaf package contents A single file contains the CX Mobile Android Logging Framework and its software components. IBM Tealeaf CX Mobile Android Logging Framework is delivered in the IBM Tealeaf CX Mobile Android Logging Framework 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 2 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

9 v v v v - killswitch.php: Page with logic. - config.ini: Configuration file that is used by the page. PipelineAgents - JSON parser for Android logging framework UICAndroid: uicandroid.jar: Android library JAR file that contains the CX Mobile Android Logging Framework. TLFConfigurableItems.properties: Configuration file. SampleCode: Contains the following versions of a sample Android application. UICSP_Clean: An Android application without IBM Tealeaf CX Mobile Android Logging Framework integrated. UICSP_ManualLog: An Android application with IBM Tealeaf CX Mobile Android Logging Framework integrated UICSP_ManualLog_ServerSessionID: An Android application with IBM Tealeaf CX Mobile Android Logging Framework integrated by using a session ID provided from a web application. See "Sample Code" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. AndroidEclipsePlugin - An Eclipse Plug-in to assist with Tealeaf Integration. tealeaf.plugin.android.site snapshot.zip The Plug-in archive to be added to your Eclipse IDE. tealeafandroidsdk.jar - Android Library JAR file that contains pre-instrumented Tealeaf widgets. Tealeaf sample application You deploy the sample application that is provided by IBM Tealeaf to test the capabilities and measure the effects of the CX Mobile Android Logging Framework. Instead of integrating the CX Mobile Android Logging Framework with your application in development, you deploy the sample application and complete any necessary configuration steps on the remainder of this page to begin to capture mobile app data into your instance of IBM Tealeaf. See Chapter 3, Sample applications, on page 93. Android development environment requirements To develop Android applications with the Android SDK, follow these system and software requirements. Minimum requirements Develop Android applications with a minimum API Level 8, which is Android 2.2 (Froyo). Consult the Google Android Dev Center for the latest Android technical documentation and tools. IBM Tealeaf client frameworks do not support forwarding of application data to third-party systems. Application data must be forwarded to the server that hosts the native application. Chapter 1. Tealeaf installation and implementation in an Android application 3

10 Supported operating systems Tealeaf supports these versions of the Windows, Mac, and Linux operating systems: v Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit) v Mac OS X 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:// Eclipse packages Several types of Eclipse packages are available for each platform. For developing Android applications, install one of these packages. v Eclipse IDE for Java Developers Java version 1.6. Java version 1.7 can be used in compatibility mode. v Eclipse Classic v Eclipse IDE for Java EE Developers JDK 5 or JDK 6 (JRE alone is not sufficient). Android Development Tools plug-in Not compatible with GNU Compiler for Java (gcj) Tealeaf impact on Android device resources In benchmark tests, the CX Mobile Android Logging Framework has the following effects on resources of the visitor's device. v v 2-3% more memory consumption Minimal effect on battery life 4 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

11 Android project changes After you acquire IBM Tealeaf CX Mobile Android Logging Framework, complete the following steps to install the CX Mobile Android Logging Framework libraries into an Android application project. Your Eclipse project must include the frameworks that follow. Testing of the CX Mobile Android Logging Framework involved Android 2.2 to Installation of UICAndroid.jar 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 CX Mobile Android Logging Framework cannot auto-instrument objects. You must apply instrumentation as part of your application development. Configure Tealeaf properties You configure several items for your app in Tealeaf, including how screen layouts are logged, Target page location, kill switch location, and whether gestures will be logged. TLFConfigurableItems.properties Everything that you configure is in the TLFConfigurableItems.properties file. This file is in the Install Package in the <what is the name of the install package for Tealeaf+Plugin?> file. Configurable properties There are many properties that you can configure in Tealeaf. At the minimum, you must configure: v Whether to display logcat messages. v The Target page URL. v Enable/disable the kill switch URL v The kill switch URL. Chapter 1. Tealeaf installation and implementation in an Android application 5

12 v v How screen layouts are logged. The logging level. For information to the other properties that you can configure, go to <link to reference topic that I don't have access to right now>. Whether to display logcat messages <need a description of what this really is>. Whether you see logcat messages is set with the 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 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 TLFConfigurableItems.properties file in the Assets folder of your Eclipse project. 1. In your Eclipse, open the TLFConfigurableItems.plist file. 6 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

13 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 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 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. 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 Chapter 1. Tealeaf installation and implementation in an Android application 7

14 How you extend the Activity class depends on whether you have a custom activity class for your application. If you: v v Do not have a custom Activity class for your application, use the Tealeaf UIActivity class. 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. 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 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 8 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

15 adds some functionality that is required by the IBM Tealeaf Logging Framework library to enable and disable asynchronous tasks, and to perform screen captures of the device after creation. To avoid capturing potentially private data, the CX Mobile Android Logging Framework takes screen captures as soon as the image was rendered on the device. As a result, no user-defined fields are populated in any captured screen image. Android does not support capture of pop-up windows. For hybrid applications, screen captures might be missing or out of order due to timing issues. The method in this task enables automatic capture of screen captures from the client application. If you do not enable this item through UICActivity, you can manually capture screen captures through the Logging Framework. See "Reference" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. The value for the black background color can be replaced by any color constant to set the color of the background of your screen captures. 1. Open the existing Java file that extends from android.app.activity class, and change it to extend from com.tl.uic.app.uicactivity instead of android.app.activity. 2. Add these imports: a. 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( ) //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 public void oncreate(bundle savedinstancestate) { this.settakesnapshotaftercreate(true); //To enable automatic screen shots setlogicalpagename("loginpage") //Recommended to identify page setimagebackground( ) //To set to back background of screenshot super.oncreate(savedinstancestate); Extending your custom Application class to point to the Tealeaf UICApplication class If you have a custom Application class in your application, point your custom class to the Tealeaf UICApplication class. The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onlowmemory to disable library if you get a warning, onterminate to clean up library, and oncreate to initialize the library.. Chapter 1. Tealeaf installation and implementation in an Android application 9

16 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(): 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. 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. 7. Add these permissions to 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 you add to the file that extends the Application class: import android.app.application; import com.tl.uic.tealeaf; public class MyApplication extends Application public void oncreate() { super.oncreate(); Tealeaf tealeaf = new Tealeaf(this); public void onlowmemory() { Tealeaf.onLowMemory(); 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 10 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

17 background, onresume, which happens when application goes to foreground, and ondestroy when activity is no longer in memory and gets garbage collected. Each activity needs a logical page name that helps indicate what activity is being displayed. If no logical page name is given, IBM Tealeaf recommends using class name that gives some indication what activity is being displayed. 1. Open the existing Java file that extends from android.app.activity class, and change it to extend from com.tl.uic.app.uicactivity instead of android.app.activity. 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(""))) { 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. * Logical page name of the Activity. public final String getlogicalpagename() { if ((this.logicalpagename == null) (this.logicalpagename.equals(""))) { this.logicalpagename = this.getclass().getname().substring(this.getclass(). getname().lastindexof(".") + 1); return this.logicalpagename; /** * Logical page name of the Activity. * logicalpagename * Logical page name of the Activity. public final void setlogicalpagename(final String logicalpagename) { this.logicalpagename = logicalpagename; Chapter 1. Tealeaf installation and implementation in an Android application 11

18 protected void onpause() { Tealeaf.onPause(this, getlogicalpagename()); super.onpause(); protected void onresume() { Tealeaf.onResume(this, getlogicalpagename()); super.onresume(); protected void ondestroy() { Tealeaf.onDestroy(this, getlogicalpagename()); super.ondestroy(); Implement Tealeaf After you install Tealeaf, you complete several tasks to implement Tealeaf functions in your application. These tasks involve modifying your application to capture controls, events, and screen views. Implementation tasks KT Comment - This is the overview topic that lists and describes all of the rest of the implementation tasks that the user has to do for the Android. All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf plug-in for Tealeaf to work. Just completing the installation is not enough. All of these tasks are manual. This table lists and describes the tasks that you perform to implement Tealeaf in your application: Task Log Screen Layout for Android Mobile App Replay Tealeaf SDK ONLY Integration for Apache Cordova, PhoneGap, and IBM Worklight applications using Android classes without IBM Tealeaf classes Implementing screenviews Target page configuration Data privacy Configuring sessionization for Android applications on the client 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. KT question - This task is part of initial configuration installation. Why is it repeated here in the docs? Specify the fields that are blocked or masked during capture. Configure how session IDs are generated. 12 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

19 Task Network traffic that is used in application contains requests only Configure requests in Android application Description KT comment - this section in the doc just says that Tealeaf does this, it doesn't include any information on what the user has to do, if anything. Configure Tealeaf to put session IDS in cookies. KT comment - again, this section just says that Tealeaf needs to have session IDS in cookies and that you have to add this code if you are NOT already using something. Not really clear. Why isn't this automatic? Uses non-ibm Tealeaf session ID Hybrid application 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 y our application. Log screen layout for mobile app session replay IBM Tealeaf has functions to log screen layouts for screenviews of native mobile app sessions. You can replay a mobile app session in cximpact Browser Based Replay as you would an HTML web session instead of viewing the mobile app session as a series of screen captures. The screen layouts of the native mobile app sessions are captured in IBM Tealeaf JSON format. The screen layouts are then sent back to replay server. The replay server uses a template engine, which interprets the JSON into HTML format. You can then replay the screen layout from the native mobile app session as HTML pages in cximpact Browser Based Replay. There are several advantages to using JSON data to replay mobile app session over screen captures. v v 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. 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 TLFConfigurableItems.properties. Draw user interactions (UI events) onto the HTML pages that are created from the JSON data. For more information on mobile ap session replay templates, see "Native app session replay customization" in the IBM Tealeaf CX Configuration Manual. TLFConfigurableItems.properties changes For native app session replay to be activated, you must set LogViewLayoutOnScreenTransition to true. If you do not, the library functions as it currently does. Chapter 1. Tealeaf installation and implementation in an Android application 13

20 #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 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); 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() 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); 14 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

21 KeyboardView keyboardview = new KeyboardView(v.getContext().getApplicationContext(), null); Tealeaf.logEvent(keyboardView, Tealeaf.TLF_UI_KEYBOARD_ DID_SHOW_NOTIFICATION); Tealeaf.logEvent(v, Tealeaf.TLF_ON_FOCUS_CHANGE_IN); else { Tealeaf.logEvent(v, com.tl.uic.tealeaf.tlf_on_focus_change_out); InputMethodManager imm = (InputMethodManager) v.getcontext().getsystemservice(context.input_method_service); imm.hidesoftinputfromwindow(v.getwindowtoken(), 0); KeyboardView keyboardview = new KeyboardView(v.getContext().getApplicationContext(), null); Tealeaf.logEvent(keyboardView, Tealeaf.TLF_UI_KEYBOARD _DID_HIDE_NOTIFICATION); ); Tealeaf.registerFormField(textView, activity); EditText et = (EditText) findviewbyid(r.id.edittext1); addfocusandregister(et, this); For more information, 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 Uses switch template ImageView Uses image template Chapter 1. Tealeaf installation and implementation in an Android application 15

22 FrameLayout, LinearLayout, ViewStub, View Uses canvas template AbsListView Uses grid template AlertDialog Uses alert template TabWidget Uses tabbar template TabHost Uses tabcontainer template Integrate Tealeaf and Worklight Worklight is IBM's Mobile First Platform for developing both Hybrid and Native Apps on multiple mobile platforms. For logging activities on your application, you might want to integrate the Tealeaf library inside of a Worklight "Hybrid" application. Worklight provides an Eclipse plug-in called "Worklight Developer Studio" to help Developers create Mobile Apps more productively. Development environment To integrate Tealeaf with Worklight, you need these files: v Eclipse IDE for Java EE Developers (Kepler): downloads/packages/release/kepler/sr2 v Worklight Developer Studio version 6.1. You need the compressed file iws_update_site_wde zip v Worklight Developer Studio version 6.2. You need the compressed file iws_eclipse_6.2.0.zip. Unless you need Worklight 6.1, you should integrate with Worklight 6.2. You must also: 1. Install the Worklight Developer Studio inside Eclipse following the instructions in the Worklight documentation. 2. Install the Android ADT plug-in in your Eclipse instance. 3. Register the Tealeaf/Application in the AndroidManifest.xml Worklight high-level single project Within Worklight, you can create and manage Mobile project artifacts in a single, high-level project called "Worklight Project". Artifacts include server-side adapters, multiple android projects, and multiple ios projects All artifacts in the single, high-level project have access to the same resources.. Differences between Worklight 6.1 and Worklight 6.2 In 6.1, Worklight and Tealeaf are packaged together. IN Worklight 6.2 they are no longer packaged together. For 6.2, you must do additional steps to integrate the two products. Modify Tealeaf and Worklight classes Part of integrating Tealeaf and Worklight 6.2 is extending and modfying Tealeaf and Worklight classes. This table lists the classes and methods that you modify and shows examples of the modifications: 16 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

23 Method or class Tealeaf UICApplication class Worklight CordovaActivity class Tealeaf onresume, onpause, and ondestroy methods Example package com.helloworklight; import com.tl.uic.tealeaf; import com.tl.uic.app.uicapplication; public class TealeafApplication extends UICApplication public void oncreate() { super.oncreate(); Tealeaf.enable(); public class HelloWorklight extends CordovaActivity implements WLInitWebFrameworkListener 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() { // Handle Tealeaf during onresume event Tealeaf.onDestroy(this, this.getclass().getname()); super.ondestroy(); Process To integrate Tealeaf and Worklight, you: 1. Create a high-level Worklight project called "Worklight Project" 2. Add the Tealeaf SDK to the high-level "Worklight Project". 3. Create an Android project under the high-level "Worklight Project" Chapter 1. Tealeaf installation and implementation in an Android application 17

24 4. Modify activity and UIC classes for Tealeaf (for integration with Worklight 6.2 only) 5. Activate Tealeaf in the JavaScript layer. 6. Update to Tealeaf , if you have not already. (applies to Worklight 6.1 only) Creating and configuring the high-level Worklight project: You can manage your Tealeaf and Worklight integration with the high-level Worklight Project. To integrate Tealeaf and Worklight 6.1, you create the high-level Worklight project, add the Tealeaf SDK to the project, and activate Tealeaf in the JavaScript layer. In this task, you work in the Eclipse environment. You modify your application and add libraries to the project. 1. Create the high-level Worklight project: a. In Eclipse, 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 configuretealeaf.js file from the Tealeaf install package to the Worklight project apps/helloworklight/andoid/js folder. b. Modify the index.html file and add <script src="js/ configuretealeaf.js"</script> before the break in the <body> element. 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 upgrade to Tealeaf : a. Copy the uicandroid.jar file from the Tealeaf install package into HelloWorklightHelloWorklightAndroid/libs folder. b. Copy the TLFConfigurableItems.properties file from the Tealeaf install package into the HelloWorklightHelloWorklightAndroid/assets folder 18 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

25 Integrate Apache Cordova and PhoneGap applications using Android classes without Tealeaf classes This method has developers add code snippets that help the IBM Tealeaf capture library. android.app.application file code changes: The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onlowmemory to disable library if you get a warning, 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. import com.tl.uic.tealeaf; b. import com.tl.uic.app.uicapplication; 4. In oncreate(): a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the Tealeaf library with a reference to application instrumented. b. Add Tealeaf.enable(); that initializes capture of user actions in the application. 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 public void oncreate() { super.oncreate(); Tealeaf tealeaf = new Tealeaf(this); public void onlowmemory() { Tealeaf.onLowMemory(); super.onlowmemory(); Chapter 1. Tealeaf installation and implementation in an Android application 19

26 @Override public void onterminate() { Tealeaf.disable(); super.onterminate(); Example in AndroidManifest.xml <application android:label="@string/app_name" android:debuggable="true" android:icon="@drawable/icon" android:name=".tlworklighttealeafapplication" > Locating the file that extends from org.apache.cordova.droidgap: The file extends from Activity class, which manages the lifecycle of a page in a native Android application similar to what a page does in a web application. IBM Tealeaf listens to the following events onpause, which happen when application goes to the background, onresume, which happens when application goes to foreground, and 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.tealeaf; b. 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. appview.addjavascriptinterface(new JavaScriptInterface(this.getContext()), "tlbridge"); Implementing screenviews For pages in which the state or context can be switched without re-rendering the page, IBM Tealeaf segments the data between states by using a screenview object. For example, if a page contains multiple tabs, each of which represents a different stage in a checkout process, you instrument each tab in the page as a distinct screenview. To implement a screenview for a page, complete the following steps. 1. If you are extending 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. 20 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

27 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 79. Set the target page's address in the TLFConfigurableItems.properties configuration file under the key PostMessageUrl. See "Configuration File" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. Data privacy IBM Tealeaf provides mechanisms for masking or blocking sensitive customer information, such as credit card numbers, from being transmitted and captured by IBM Tealeaf. Through the CX Mobile Android Logging Framework, you can specify the fields that need to be blocked or masked in your web application. When applied, data privacy ensures that these data elements are never transmitted to IBM Tealeaf. Note: Due to changes in how client framework data is submitted to IBM Tealeaf for capture, the best method for masking or blocking sensitive data is to apply the filtering through the capturing client framework. While other IBM Tealeaf features to manage data privacy can be deployed, they are not easy to implement on the new format of data captured from the client frameworks. IBM Tealeaf recommends using the methods referenced below. v v See "Configuration File" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. 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 CX Mobile Android Logging Framework auto-generates a session ID if one is not provided. This session ID is used to identify the session on the IBM Tealeaf server. IBM Tealeaf injects cookies to create session in the IBM Tealeaf system. Note: When an Android native or hybrid application is placed into background, the library flushes the collected data and sleeps, instead of disabling it. This happens unless the session expired due to the session timeout property. The timeout property is indicated with SessionTimeout in TLFConfigurableItems.properties. The default value for this property is 30 minutes. After a 30-minute timeout, a new session identifier is created. There are two ways to configure sessionization; either through TLTSID provide by IBM Tealeaf, or through customer session ID, called JSESSIONID. Both methods function as a unique session identifier within the CX Mobile Android Logging Framework environment for IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer session ID or JSESSIONID. Chapter 1. Tealeaf installation and implementation in an Android application 21

28 The following is a typical setting in TLFConfigurableItems.properties using customer session ID. #Sessionization settings on customer cookies CookieUrl = CookieDomain =.sample.com CookiePath = / CookieParam = JSESSIONID CookieExpires = false SessionTimeout=30 SessoinTimeoutKillSwitch=false In this example, the cookie expires 30 minutes from current time. When the session timeout occurs, CX Mobile Android Logging Framework retrieves the new cookie from your application server and posts the rest of request to application server using this new acquired cookie in request header. PCA groups all the used JSESSIONIDs into one single session even though 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: CX Mobile Android Logging Framework uses cookies to add values to the TLFConfigurableItems.properties file. Uses session ID generated by IBM Tealeaf CX Mobile Android Logging Framework CX Mobile Android Logging Framework uses cookies to add the following values in TLFConfigurableItems.properties. v CookieUrl is for url of site that is posted and getting cookie to sessionize on. v CookieParam is the parameter that has a session id. v CookiePath is the path of the cookie. v CookieDomain is the domain that the cookie belongs to. v v v CookieSecure is to add a secure cookie that can only be posted to an https url that has a valid certificate. 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. SessionTimeout is session timeout is in minutes. When this value expires a new session id is created. An example follows. #Sessionization settings CookieUrl= 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 22 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

29 Note: It is important to first call your server to get first cookie to sessionize on, which is automatically obtained when you enable the kill switch URL on the application. This is used to aggregate all the data on CX Passive Capture Application capture. Configure requests in Android application IBM Tealeaf needs all the requests to have the session id to be placed in the cookies of the request. This enables the IBM Tealeaf system to collect all the resources together in a single session. If you are 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; /** ohernandez * public class TLDefaultHttpClient extends DefaultHttpClient { /** * public TLDefaultHttpClient() { super(); this.init(null); /** params Http parameters. public TLDefaultHttpClient(final HttpParams params) { super(params); this.init(null); /** params Http parameters. sessionid Tealeaf session id. public TLDefaultHttpClient(final HttpParams params, final String sessionid) { super(params); this.init(sessionid); /** conman ClientConnectionManager. params Http parameters. public TLDefaultHttpClient(final ClientConnectionManager conman, final HttpParams params) { super(conman, params); this.init(null); Chapter 1. Tealeaf installation and implementation in an Android application 23

30 /** sessionid Tealeaf session id. private void init(final String sessionid) { final TLHttpRequestInterceptor tlhttprequestinterceptor = new TLHttpRequestInterceptor(sessionId); this.addrequestinterceptor(tlhttprequestinterceptor); this.addresponseinterceptor(new TLHttpResponseInterceptor (tlhttprequestinterceptor)); Extend org.apache.http.httprequestinterceptor: This class is used to inject session id as a cookie and additional headers that the IBM Tealeaf system uses. import java.io.ioexception; import java.util.map.entry; import org.apache.http.httpexception; import org.apache.http.httprequest; import org.apache.http.httprequestinterceptor; import org.apache.http.protocol.httpcontext; import android.webkit.cookiemanager; import com.tl.uic.tealeaf; import com.tl.uic.util.loginternal; /** ohernandez public class TLHttpRequestInterceptor implements HttpRequestInterceptor { private String url; private final String sessionid; /** * Constructor. public TLHttpRequestInterceptor() { super(); this.sessionid = null; /** * Constructor. sessionid Tealeaf session id. public TLHttpRequestInterceptor(final String sessionid) { this.sessionid = sessionid; /** * Get url of the request. Url of the request. public final String geturl() { return url; /** * Url of the request. url Url of the request. public final void seturl(final String url) { 24 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

31 this.url = url; /** * {@inheritdoc public final void process(final HttpRequest request, final HttpContext context) throws HttpException, IOException { try { this.url = request.getrequestline().geturi(); if (!request.containsheader(tealeaf.tlf_header)) { request.addheader(tealeaf.tlf_header, "device (Android) Lib/" + Tealeaf.getLibraryVersion()); if (!request.containsheader(tealeaf.tlf_property_header)) { request.addheader(tealeaf.tlf_property_header, Tealeaf.getHttpXTealeafProperty()); if (Tealeaf.getAdditionalHeaders()!= null) { for (final EntryString,<String> entry : Tealeaf.getAdditionalHeaders().entrySet()) { request.addheader(entry.getkey(), entry.getvalue()); final StringBuffer cookies = new StringBuffer(Tealeaf. gettlcookie(this.sessionid)); if (this.geturl()!= null) { final String extistingcookies = CookieManager.getInstance(). getcookie(this.geturl()); if (extistingcookies!= null) { cookies.append( ; ); cookies.append(extistingcookies); request.addheader("cookie", cookies.tostring()); LogInternal.log("Session cookie:" + cookies.tostring()); catch (final Exception e) { Tealeaf.logException(e); Extend org.apache.http.httpresponseinterceptor: This class is used to get information to fill out a IBM Tealeaf connection object. import java.io.ioexception; import java.util.date; import org.apache.http.httpexception; import org.apache.http.httpresponse; import org.apache.http.httpresponseinterceptor; import org.apache.http.protocol.httpcontext; import com.tl.uic.tlfcache; import com.tl.uic.tealeaf; import com.tl.uic.util.loginternal; /** ohernandez * Chapter 1. Tealeaf installation and implementation in an Android application 25

32 public class TLHttpResponseInterceptor implements HttpResponseInterceptor { private final TLHttpRequestInterceptor tlhttprequestinterceptor; private final Date starttime; private final long inittime; /** * Constructor. * tlhttprequestinterceptor TLHttpRequestInterceptor used. public TLHttpResponseInterceptor(final TLHttpRequestInterceptor tlhttprequestinterceptor) { this.tlhttprequestinterceptor = tlhttprequestinterceptor; this.starttime = new Date(); this.inittime = TLFCache.timestampFromSession(); /** * {@inheritdoc public final void process(final HttpResponse response, final HttpContext context) throws HttpException, IOException { try { final Date endtime = new Date(); final Date startload = new Date(); final long loadtime = (new Date()).getTime() - startload.gettime(); final long responsetime = endtime.gettime() - this.starttime.gettime(); Tealeaf.logConnection(this.tlHttpRequestInterceptor.getUrl(), response, this.inittime, loadtime, responsetime); catch (final Exception e) { LogInternal.logException(e); Uses non IBM Tealeaf session ID You must get your generated session ID and use it when you enable or start a new session in CX Mobile Android Logging Framework. // If enabling of Android Logging Framework use Tealeaf.enable(); Tealeaf.enable("your session id"); // If Android Logging Framework is enabled and a new session is to be created use Tealeaf.startSession(); Tealeaf.startSession("your session id"); Android application gestures You can capture gestures that the users make on your Android application. Several types of gestures are captured. Configuration For any Activity class that you want Gesture logging, you edit TLFConfigurableItems.properties 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. 26 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

33 If your application uses a customized gesture view, ontouchevent does not detect the gestures because they are already captured by the customized gesture view. If you are using a customized gesture view, you must use dispatchtouchevent. You can use either 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 Double tap 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. 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: Chapter 1. Tealeaf installation and implementation in an Android application 27

34 Table 2. Swipe gestures Gesture name Description Image displayed in Replay Swipe vertically This gesture is a one-finger gesture. For a swipe vertically gesture, one-finger: 1. taps and holds in 1 location of screen, 2. continues to engage screen while it moves up or down 3. lifts from the screen in different location. Note: The initial tap becomes lighter in color, while the destination is highlighted by a darker color Swipe horizontally This gesture is a one-finger gesture. For a swipe horizontally gesture, one-finger: 1. taps and holds in 1 location of screen, 2. continues to engage screen while it moves left or right 3. lifts from the screen in different location. Note: The initial tap becomes lighter in color, while the destination is highlighted by a darker color Resize gestures This table lists and describes the resize gestures that are captured from web and mobile apps: Note: See the IBM Tealeaf Customer Experience Release Notes for information about a known limitation for handling some ios pinch gestures. Table 3. Resize gestures Gesture name Description Image displayed in Replay Pinch open Sometimes referred to as 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. For a pinch close resize gesture, 2 fingers: 1. tap and hold in 1 location on the screen, 2. maintain contact with the screen while the fingers move toward each other, 3. lift from the screen at a new location. Note: Accompanying arrows indicate the direction (open or close) of the pinch Note: Accompanying arrows indicate the direction (open or close) of the pinch 28 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

35 Instrumenting your application for Android gestures: You can enable your application to capture gestures that the user makes on your application. To enable gestures for an Activity class, you modify the Activity class. For example, you modify 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.jar 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 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); Chapter 1. Tealeaf installation and implementation in an Android application 29

36 Modifying the TLFConfiguratbleItems.properties file for gestures: After you define the variables for gestures in your Activity class, you enable gesture capture by modifying the TLFConfiguratableItems.properties file. 1. Edit the TLFConfiguratableItems.properties file. 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: exception - the exception to be logged. data - the value to be given to event. unhandled - whether the exception is unhandled. - whether exception was logged. Example In this example, you have a method that causes an exception: public void clientmethod1( ) { You 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) { 30 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

37 HashMap<String, String> data = new HashMap<String, String>(); data.put("extramessage", "custom value1"); Tealeaf.logException(e, data, false); Logging exceptions: Use the examples in this task as a guide to adding exception logging to your application. 1. Determine the method for which you want to log exceptions. For example, you have a method: public void clientmethod1( ) { 2. Optional: Add the exception method to the method for which you want to log the 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>(); Tealeaf.logException(e, data, false); 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 CX Mobile Android Logging Framework Guide. Extend android.webkit.webview: The sample code that follows extends the base Android WebView with UICWebView. import java.util.date; import java.util.map; import org.apache.http.httpresponse; import android.annotation.suppresslint; 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.app.uicactivity; import com.tl.uic.javascript.javascriptinterface; Chapter 1. Tealeaf installation and implementation in an Android application 31

38 /** ohernandez 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; /** context Android context. public UICWebView(final Context context) { super(context); init(); /** context Android context. attrs an AttributeSet passed to our parent. public UICWebView(final Context context, final AttributeSet attrs) { super(context, attrs); init(); /** context Android context. attrs an AttributeSet passed to our parent. defstyle the default style resource ID. public UICWebView(final Context context, final AttributeSet attrs, final int defstyle) { super(context, attrs, defstyle); init(); /** * When page finished loading. When page finished loading. public final Date getendload() { return endload; /** * When page finished loading. endload When page finished loading. public final void setendload(final Date endload) { this.endload = endload; /** * When page starts loading. When page starts loading. public final Date getstartload() { return startload; /** * When page starts loading. startload When page starts loading. 32 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

39 public final void setstartload(final Date startload) { this.startload = startload; /** * HttpResponse from the connection. HttpResponse from the connection. public final HttpResponse gethttpresponse() { return httpresponse; /** * HttpResponse from the connection. httpresponse HttpResponse from the connection. public final void sethttpresponse(final HttpResponse httpresponse) { this.httpresponse = httpresponse; /** * Initial time from the connection. Initial time from the connection. public final Date getinittime() { return inittime; /** * Initial time from the connection. 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. Response time from the connection. public final long getresponsetime() { return responsetime; /** * Response time from the connection. responsetime Response time from the connection. public final void setresponsetime(final long responsetime) { this.responsetime = responsetime; /** * 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, ""); Chapter 1. Tealeaf installation and implementation in an Android application 33

40 /** * 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() { this.setwebviewclient(new UICWebViewClient()); this.addjavascriptinterface(new JavaScriptInterface (this.getcontext()), "tlbridge"); /** * Log the load time of the WebView. public final void logconnection() { final long loadtime = this.getendload().gettime() - this.getstartload().gettime(); 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. import android.webkit.webview; import android.webkit.webviewclient; /** ohernandez * public class UICWebViewClient extends WebViewClient { /** * public boolean shouldoverrideurlloading(final WebView view, final String url) { view.loadurl(url); return true; 34 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

41 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: { // 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 2. 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); Chapter 1. Tealeaf installation and implementation in an Android application 35

42 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 Example Enable Tealeaf Framework /** * Public API to enable Tealeaf framework. {void enabletealeafframework(); Disable Tealeaf Framework /** * Public API to disable Tealeaf framework. {void disabletealeafframework(); Log Screen Capture /** * Public API to add a screenshot capture. {void logscreencapture(); Start New Tealeaf Session /** * Public API to start a new Tealeaf session. {void startnewtlfsession(); Current Session ID /** * Public API to start get current Tealeaf session Id. {String Current session Id currentsessionid(); Default Value for Configurable Item /** * Public API to get default value of a configurable item in * TLFConfigurableItems.properties file. {String configitem This is the name of the configurable item. {String The value for the item. defaultvalueforconfigurableitem (configitem); 36 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

43 Method Example Value for Configurable Item /** * Public API to get the value of a configurable item either from * TLFConfigurableItems.properties file * or in memory data structure. {String configitem This is the name of the configurable item. {String The value for the item. valueforconfigurableitem(configitem); Set Configurable Item /** * Public API to set the value of a configurable item in TLFConfigurableItems.properties * file. {String configitem This is the name of the configurable item. {String value The value assign to the configitem. {boolean Wether item was set. setconfigurableitem(configitem, value); Add Additional HTTP Header /** * Public API to add additional http header. {String key This is the key of the configurable item. {String value The value assign to the configitem. {boolean Wether item was set. addadditionalhttpheader(key, value); Log Custom Event Bridge /** * Public API to log custom event. {String eventname A custom event name. {String jsondata JSON data string. {int loglevel Tealeaf library logging level for the event. {boolean Wether item was set. 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> Chapter 1. Tealeaf installation and implementation in an Android application 37

44 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" " <html xmlns=" > <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 ) { node = document.createtextnode(textdata + " returned: " + apiretval); else { 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 ); 38 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

45 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\ ; 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( ); Chapter 1. Tealeaf installation and implementation in an Android application 39

46 </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 = 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 40 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

47 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 CX Mobile Android Logging Framework and its software components. IBM Tealeaf CX Mobile Android Logging Framework is delivered in the IBM Tealeaf CX Mobile Android Logging Framework 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: uicandroid.jar: Android library JAR file that contains the CX Mobile Android Logging Framework. TLFConfigurableItems.properties: Configuration file. v SampleCode: Contains the following versions of a sample Android application. UICSP_Clean: An Android application without IBM Tealeaf CX Mobile Android Logging Framework integrated. UICSP_ManualLog: An Android application with IBM Tealeaf CX Mobile Android Logging Framework integrated UICSP_ManualLog_ServerSessionID: An Android application with IBM Tealeaf CX Mobile Android Logging Framework integrated by using a session ID provided from a web application. See "Sample Code" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. v AndroidEclipsePlugin - An Eclipse Plug-in to assist with Tealeaf Integration. tealeaf.plugin.android.site 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. Chapter 1. Tealeaf installation and implementation in an Android application 41

48 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 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:// 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). 42 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

49 Android Development Tools plug-in Not compatible with GNU Compiler for Java (gcj) Tealeaf impact on Android device resources In benchmark tests, the CX Mobile Android Logging Framework has the following effects on resources of the visitor's device. v v 2-3% more memory consumption Minimal effect on battery life Add Eclipse Tealeaf plug-in to your Eclipse Android project After you acquire IBM Tealeaf CX Mobile Android Logging Framework, install the CX Mobile Android Logging Framework libraries into an Android application project. Your Eclipse project must include the recommended frameworks. Testing of the CX Mobile Android Logging Framework involved Android 2.2 to 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 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. Chapter 1. Tealeaf installation and implementation in an Android application 43

50 Widget MultiAutoCompleteTextView RadioButton RadioGroup RatingBar RelativeLayout ScrollView SeekBar Spinner Switch TextView TimePicker ToggleButton Description 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. 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. 44 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

51 1. Extract the TLFLibRelease.zip file. The Tealeaf folder is extracted. The Tealeaf folder contains all necessary files for the CX Mobile Android Logging Framework and the plug-in. 2. Open your project in Eclipse. 3. From the Help menu, select Install New Software In the Install window, select Add 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. 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. TLFConfigurableItems.properties Everything that you configure is in the TLFConfigurableItems.properties file. This file is in the Install Package in the <what is the name of the install package for Tealeaf+Plugin?> file. Configurable properties There are many properties that you can configure in Tealeaf. At the minimum, you must configure: v Whether to display logcat messages. Chapter 1. Tealeaf installation and implementation in an Android application 45

52 v v v v v The Target page URL. Enable/disable the kill switch URL The kill switch URL. How screen layouts are logged. The logging level. For information to the other properties that you can configure, go to <link to reference topic that I don't have access to right now>. Whether to display logcat messages <need a description of what this really is>. Whether you see logcat messages is set with the 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 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. 46 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

53 All of the configuration in this task involves modifying settings in the TLFConfigurableItems.properties 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 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 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. 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 Chapter 1. Tealeaf installation and implementation in an Android application 47

54 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 v Do not have a custom Activity class for your application, use the Tealeaf UIActivity class. 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. 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 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. 48 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

55 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 CX Mobile Android Logging Framework takes screen captures as soon as the image was rendered on the device. As a result, no user-defined fields are populated in any captured screen image. Android does not support capture of pop-up windows. For hybrid applications, screen captures might be missing or out of order due to timing issues. The method in this task enables automatic capture of screen captures from the client application. If you do not enable this item through UICActivity, you can manually capture screen captures through the Logging Framework. See "Reference" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. The value for the black background color can be replaced by any color constant to set the color of the background of your screen captures. 1. Open the existing Java file that extends from android.app.activity class, and change it to extend from com.tl.uic.app.uicactivity instead of android.app.activity. 2. Add these imports: a. 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( ) //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 public void oncreate(bundle savedinstancestate) { this.settakesnapshotaftercreate(true); //To enable automatic screen shots setlogicalpagename("loginpage") //Recommended to identify page setimagebackground( ) //To set to back background of screenshot super.oncreate(savedinstancestate); Extending your custom Application class to point to the Tealeaf UICApplication class If you have a custom Application class in your application, point your custom class to the Tealeaf UICApplication class. The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onlowmemory to disable library if you get a warning, onterminate to clean up library, and oncreate to initialize the library.. Chapter 1. Tealeaf installation and implementation in an Android application 49

56 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(): 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. 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. 7. Add these permissions to 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 you add to the file that extends the Application class: import android.app.application; import com.tl.uic.tealeaf; public class MyApplication extends Application public void oncreate() { super.oncreate(); Tealeaf tealeaf = new Tealeaf(this); public void onlowmemory() { Tealeaf.onLowMemory(); 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 50 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

57 background, onresume, which happens when application goes to foreground, and ondestroy when activity is no longer in memory and gets garbage collected. Each activity needs a logical page name that helps indicate what activity is being displayed. If no logical page name is given, IBM Tealeaf recommends using class name that gives some indication what activity is being displayed. 1. Open the existing Java file that extends from android.app.activity class, and change it to extend from com.tl.uic.app.uicactivity instead of android.app.activity. 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(""))) { 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. * Logical page name of the Activity. public final String getlogicalpagename() { if ((this.logicalpagename == null) (this.logicalpagename.equals(""))) { this.logicalpagename = this.getclass().getname().substring(this.getclass(). getname().lastindexof(".") + 1); return this.logicalpagename; /** * Logical page name of the Activity. * logicalpagename * Logical page name of the Activity. public final void setlogicalpagename(final String logicalpagename) { this.logicalpagename = logicalpagename; Chapter 1. Tealeaf installation and implementation in an Android application 51

58 protected void onpause() { Tealeaf.onPause(this, getlogicalpagename()); super.onpause(); protected void onresume() { Tealeaf.onResume(this, getlogicalpagename()); super.onresume(); protected void ondestroy() { Tealeaf.onDestroy(this, getlogicalpagename()); super.ondestroy(); Implement Tealeaf After you install Tealeaf, you complete several tasks to implement Tealeaf functions in your application. These tasks involve modifying your application to capture controls, events, and screen views. Implementation tasks KT Comment - This is the overview topic that lists and describes all of the rest of the implementation tasks that the user has to do for the Android. All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf plug-in for Tealeaf to work. Just completing the installation is not enough. All of these tasks are manual. This table lists and describes the tasks that you perform to implement Tealeaf in your application: Task Log Screen Layout for Android Mobile App Replay Tealeaf SDK ONLY Integration for Apache Cordova, PhoneGap, and IBM Worklight applications using Android classes without IBM Tealeaf classes Implementing screenviews Target page configuration Data privacy Configuring sessionization for Android applications on the client 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. KT question - This task is part of initial configuration installation. Why is it repeated here in the docs? Specify the fields that are blocked or masked during capture. Configure how session IDs are generated. 52 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

59 Task Network traffic that is used in application contains requests only Configure requests in Android application Description KT comment - this section in the doc just says that Tealeaf does this, it doesn't include any information on what the user has to do, if anything. Configure Tealeaf to put session IDS in cookies. KT comment - again, this section just says that Tealeaf needs to have session IDS in cookies and that you have to add this code if you are NOT already using something. Not really clear. Why isn't this automatic? Uses non-ibm Tealeaf session ID Hybrid application 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 y our application. Log screen layout for mobile app session replay IBM Tealeaf has functions to log screen layouts for screenviews of native mobile app sessions. You can replay a mobile app session in cximpact Browser Based Replay as you would an HTML web session instead of viewing the mobile app session as a series of screen captures. The screen layouts of the native mobile app sessions are captured in IBM Tealeaf JSON format. The screen layouts are then sent back to replay server. The replay server uses a template engine, which interprets the JSON into HTML format. You can then replay the screen layout from the native mobile app session as HTML pages in cximpact Browser Based Replay. There are several advantages to using JSON data to replay mobile app session over screen captures. v v 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. 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 TLFConfigurableItems.properties. Draw user interactions (UI events) onto the HTML pages that are created from the JSON data. For more information on mobile ap session replay templates, see "Native app session replay customization" in the IBM Tealeaf CX Configuration Manual. TLFConfigurableItems.properties changes For native app session replay to be activated, you must set LogViewLayoutOnScreenTransition to true. If you do not, the library functions as it currently does. Chapter 1. Tealeaf installation and implementation in an Android application 53

60 #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 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); 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() 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); 54 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

61 KeyboardView keyboardview = new KeyboardView(v.getContext().getApplicationContext(), null); Tealeaf.logEvent(keyboardView, Tealeaf.TLF_UI_KEYBOARD_ DID_SHOW_NOTIFICATION); Tealeaf.logEvent(v, Tealeaf.TLF_ON_FOCUS_CHANGE_IN); else { Tealeaf.logEvent(v, com.tl.uic.tealeaf.tlf_on_focus_change_out); InputMethodManager imm = (InputMethodManager) v.getcontext().getsystemservice(context.input_method_service); imm.hidesoftinputfromwindow(v.getwindowtoken(), 0); KeyboardView keyboardview = new KeyboardView(v.getContext().getApplicationContext(), null); Tealeaf.logEvent(keyboardView, Tealeaf.TLF_UI_KEYBOARD _DID_HIDE_NOTIFICATION); ); Tealeaf.registerFormField(textView, activity); EditText et = (EditText) findviewbyid(r.id.edittext1); addfocusandregister(et, this); For more information, 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 Uses switch template ImageView Uses image template Chapter 1. Tealeaf installation and implementation in an Android application 55

62 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. 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. import com.tl.uic.tealeaf; b. import com.tl.uic.app.uicapplication; 4. In oncreate(): a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the Tealeaf library with a reference to application instrumented. b. Add Tealeaf.enable(); that initializes capture of user actions in the application. 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; 56 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

63 public class MyApplication extends Application public void oncreate() { super.oncreate(); Tealeaf tealeaf = new Tealeaf(this); public void onlowmemory() { Tealeaf.onLowMemory(); public void onterminate() { Tealeaf.disable(); super.onterminate(); Example in AndroidManifest.xml <application android:label="@string/app_name" android:debuggable="true" android:icon="@drawable/icon" android:name=".tlworklighttealeafapplication" > 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. Add the following imports. a. import com.tl.uic.tealeaf; b. 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); Chapter 1. Tealeaf installation and implementation in an Android application 57

64 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()), "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 = public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); // Log Screenview for this activity 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()), "tlbridge"); super.loadurl(getwebmainfilepath()); public void onpause() { // Handle Tealeaf during onpause event Tealeaf.onPause(this, logicalpagename); super.onpause(); public void onresume() { // Handle Tealeaf during onresume event Tealeaf.onResume(this, logicalpagename); super.onresume(); public void ondestroy() { // Handle Tealeaf during onresume event 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. 58 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

65 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 79. Set the target page's address in the TLFConfigurableItems.properties configuration file under the key PostMessageUrl. See "Configuration File" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. Data privacy IBM Tealeaf provides mechanisms for masking or blocking sensitive customer information, such as credit card numbers, from being transmitted and captured by IBM Tealeaf. Through the CX Mobile Android Logging Framework, you can specify the fields that need to be blocked or masked in your web application. When applied, data privacy ensures that these data elements are never transmitted to IBM Tealeaf. Note: Due to changes in how client framework data is submitted to IBM Tealeaf for capture, the best method for masking or blocking sensitive data is to apply the filtering through the capturing client framework. While other IBM Tealeaf features to manage data privacy can be deployed, they are not easy to implement on the new format of data captured from the client frameworks. IBM Tealeaf recommends using the methods referenced below. v v See "Configuration File" in the IBM Tealeaf CX Mobile Android Logging Framework Guide. 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 CX Mobile Android Logging Framework auto-generates a session ID if one is not provided. This session ID is used to identify the session on the IBM Tealeaf server. IBM Tealeaf injects cookies to create session in the IBM Tealeaf system. Note: When an Android native or hybrid application is placed into background, the library flushes the collected data and sleeps, instead of disabling it. This happens unless the session expired due to the session timeout property. The Chapter 1. Tealeaf installation and implementation in an Android application 59

66 timeout property is indicated with SessionTimeout in TLFConfigurableItems.properties. The default value for this property is 30 minutes. After a 30-minute timeout, a new session identifier is created. There are two ways to configure sessionization; either through TLTSID provide by IBM Tealeaf, or through customer session ID, called JSESSIONID. Both methods function as a unique session identifier within the CX Mobile Android Logging Framework environment for IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer session ID or JSESSIONID. The following is a typical setting in TLFConfigurableItems.properties using customer session ID. #Sessionization settings on customer cookies CookieUrl = CookieDomain =.sample.com CookiePath = / CookieParam = JSESSIONID CookieExpires = false SessionTimeout=30 SessoinTimeoutKillSwitch=false In this example, the cookie expires 30 minutes from current time. When the session timeout occurs, CX Mobile Android Logging Framework retrieves the new cookie from your application server and posts the rest of request to application server using this new acquired cookie in request header. PCA groups all the used JSESSIONIDs into one single session even though 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: CX Mobile Android Logging Framework uses cookies to add values to the TLFConfigurableItems.properties file. Uses session ID generated by IBM Tealeaf CX Mobile Android Logging Framework CX Mobile Android Logging Framework uses cookies to add the following values in TLFConfigurableItems.properties. v CookieUrl is for url of site that is posted and getting cookie to sessionize on. v CookieParam is the parameter that has a session id. v CookiePath is the path of the cookie. v CookieDomain is the domain that the cookie belongs to. v v v CookieSecure is to add a secure cookie that can only be posted to an https url that has a valid certificate. 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. SessionTimeout is session timeout is in minutes. When this value expires a new session id is created. An example follows. 60 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

67 #Sessionization settings CookieUrl= 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. 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; /** ohernandez * public class TLDefaultHttpClient extends DefaultHttpClient { /** * public TLDefaultHttpClient() { super(); this.init(null); /** params Http parameters. public TLDefaultHttpClient(final HttpParams params) { super(params); this.init(null); /** params Http parameters. sessionid Tealeaf session id. public TLDefaultHttpClient(final HttpParams params, Chapter 1. Tealeaf installation and implementation in an Android application 61

68 final String sessionid) { super(params); this.init(sessionid); /** conman ClientConnectionManager. params Http parameters. public TLDefaultHttpClient(final ClientConnectionManager conman, final HttpParams params) { super(conman, params); this.init(null); /** sessionid Tealeaf session id. private void init(final String sessionid) { final TLHttpRequestInterceptor tlhttprequestinterceptor = new TLHttpRequestInterceptor(sessionId); this.addrequestinterceptor(tlhttprequestinterceptor); this.addresponseinterceptor(new TLHttpResponseInterceptor (tlhttprequestinterceptor)); Extend org.apache.http.httprequestinterceptor: This class is used to inject session id as a cookie and additional headers that the IBM Tealeaf system uses. import java.io.ioexception; import java.util.map.entry; import org.apache.http.httpexception; import org.apache.http.httprequest; import org.apache.http.httprequestinterceptor; import org.apache.http.protocol.httpcontext; import android.webkit.cookiemanager; import com.tl.uic.tealeaf; import com.tl.uic.util.loginternal; /** ohernandez public class TLHttpRequestInterceptor implements HttpRequestInterceptor { private String url; private final String sessionid; /** * Constructor. public TLHttpRequestInterceptor() { super(); this.sessionid = null; /** * Constructor. sessionid Tealeaf session id. public TLHttpRequestInterceptor(final String sessionid) { this.sessionid = sessionid; 62 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

69 /** * Get url of the request. Url of the request. public final String geturl() { return url; /** * Url of the request. 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, Tealeaf.getHttpXTealeafProperty()); if (Tealeaf.getAdditionalHeaders()!= null) { for (final EntryString,<String> entry : Tealeaf.getAdditionalHeaders().entrySet()) { request.addheader(entry.getkey(), entry.getvalue()); final StringBuffer cookies = new StringBuffer(Tealeaf. gettlcookie(this.sessionid)); if (this.geturl()!= null) { final String extistingcookies = CookieManager.getInstance(). getcookie(this.geturl()); if (extistingcookies!= null) { cookies.append( ; ); cookies.append(extistingcookies); request.addheader("cookie", cookies.tostring()); LogInternal.log("Session cookie:" + cookies.tostring()); catch (final Exception e) { Tealeaf.logException(e); Extend org.apache.http.httpresponseinterceptor: This class is used to get information to fill out a IBM Tealeaf connection object. Chapter 1. Tealeaf installation and implementation in an Android application 63

70 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; /** ohernandez * public class TLHttpResponseInterceptor implements HttpResponseInterceptor { private final TLHttpRequestInterceptor tlhttprequestinterceptor; private final Date starttime; private final long inittime; /** * Constructor. * tlhttprequestinterceptor TLHttpRequestInterceptor used. public TLHttpResponseInterceptor(final TLHttpRequestInterceptor tlhttprequestinterceptor) { this.tlhttprequestinterceptor = tlhttprequestinterceptor; this.starttime = new Date(); this.inittime = TLFCache.timestampFromSession(); /** * {@inheritdoc public final void process(final HttpResponse response, final HttpContext context) throws HttpException, IOException { try { final Date endtime = new Date(); final Date startload = new Date(); final long loadtime = (new Date()).getTime() - startload.gettime(); final long responsetime = endtime.gettime() - this.starttime.gettime(); Tealeaf.logConnection(this.tlHttpRequestInterceptor.getUrl(), response, this.inittime, loadtime, responsetime); catch (final Exception e) { LogInternal.logException(e); Uses non IBM Tealeaf session ID You must get your generated session ID and use it when you enable or start a new session in CX Mobile Android Logging Framework. // If enabling of Android Logging Framework use Tealeaf.enable(); Tealeaf.enable("your session id"); // If Android Logging Framework is enabled and a new session is to be created use Tealeaf.startSession(); Tealeaf.startSession("your session id"); Android application gestures You can capture gestures that the users make on your Android application. Several types of gestures are captured. 64 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

71 Configuration For any Activity class that you want Gesture logging, you edit TLFConfigurableItems.properties 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. 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 4. 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. Chapter 1. Tealeaf installation and implementation in an Android application 65

72 Table 4. Tap gestures (continued) Gesture name Description Image displayed in Replay 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: Table 5. Swipe gestures Gesture name Description Image displayed in Replay Swipe vertically This gesture is a one-finger gesture. For a swipe vertically gesture, one-finger: 1. taps and holds in 1 location of screen, 2. continues to engage screen while it moves up or down 3. lifts from the screen in different location. Note: The initial tap becomes lighter in color, while the destination is highlighted by a darker color Swipe horizontally This gesture is a one-finger gesture. For a swipe horizontally gesture, one-finger: 1. taps and holds in 1 location of screen, 2. continues to engage screen while it moves left or right 3. lifts from the screen in different location. Note: The initial tap becomes lighter in color, while the destination is highlighted by a darker color Resize gestures This table lists and describes the resize gestures that are captured from web and mobile apps: Note: See the IBM Tealeaf Customer Experience Release Notes for information about a known limitation for handling some ios pinch gestures. 66 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

73 Table 6. Resize gestures Gesture name Description Image displayed in Replay Pinch open Pinch close Sometimes referred to as a spread gesture, this is a two-finger gesture. For a pinch open gesture, 2 fingers: 1. tap and hold in 1 location of the screen, 2. maintain contact with the screen while the fingers move apart from each other in any direction, 3. lift from the screen at a new location. This gesture is a two-finger gesture. For a pinch close resize gesture, 2 fingers: 1. tap and hold in 1 location on the screen, 2. maintain contact with the screen while the fingers move toward each other, 3. lift from the screen at a new location. Note: Accompanying arrows indicate the direction (open or close) of the pinch Note: Accompanying arrows indicate the direction (open or close) of the pinch Instrumenting your application for Android gestures: You can enable your application to capture gestures that the user makes on your application. To enable gestures for an Activity class, you modify the Activity class. For example, you modify 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.jar 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: Chapter 1. Tealeaf installation and implementation in an Android application 67

74 mport com.tl.uic.tealeaf; import com.tl.uic.app.uicactivity; import android.os.bundle; import android.view.motionevent; public class MainActivity extends 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. 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: 68 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

75 Method public static Boolean logexception(final Throwable exception, final HashMap<String, String> data, final Boolean unhandled) Parameters Where: exception - the exception to be logged. data - the value to be given to event. unhandled - whether the exception is unhandled. - whether exception was logged. Example In this example, you have a method that causes an exception: public void clientmethod1( ) { You 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); 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 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>(); Tealeaf.logException(e, data, false); Hybrid applications An application is considered to be hybrid if it contains a WebView in the Android application. Chapter 1. Tealeaf installation and implementation in an Android application 69

76 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 CX Mobile Android Logging Framework Guide. Extend android.webkit.webview: The sample code that follows extends the base Android WebView with UICWebView. import java.util.date; import java.util.map; import org.apache.http.httpresponse; import android.annotation.suppresslint; 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.app.uicactivity; import com.tl.uic.javascript.javascriptinterface; /** ohernandez 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; /** context Android context. public UICWebView(final Context context) { super(context); init(); /** context Android context. attrs an AttributeSet passed to our parent. public UICWebView(final Context context, final AttributeSet attrs) { super(context, attrs); init(); /** context Android context. attrs an AttributeSet passed to our parent. defstyle the default style resource ID. public UICWebView(final Context context, final AttributeSet attrs, final int defstyle) { super(context, attrs, defstyle); init(); 70 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

77 /** * When page finished loading. When page finished loading. public final Date getendload() { return endload; /** * When page finished loading. endload When page finished loading. public final void setendload(final Date endload) { this.endload = endload; /** * When page starts loading. When page starts loading. public final Date getstartload() { return startload; /** * When page starts loading. startload When page starts loading. public final void setstartload(final Date startload) { this.startload = startload; /** * HttpResponse from the connection. HttpResponse from the connection. public final HttpResponse gethttpresponse() { return httpresponse; /** * HttpResponse from the connection. httpresponse HttpResponse from the connection. public final void sethttpresponse(final HttpResponse httpresponse) { this.httpresponse = httpresponse; /** * Initial time from the connection. Initial time from the connection. public final Date getinittime() { return inittime; /** * Initial time from the connection. inittime Initial time from the connection. public final void setinittime(final Date inittime) { this.inittime = inittime; this.connectioninitfromsession = TLFCache.timestampFromSession(); Chapter 1. Tealeaf installation and implementation in an Android application 71

78 /** * Response time from the connection. Response time from the connection. public final long getresponsetime() { return responsetime; /** * Response time from the connection. responsetime Response time from the connection. public final void setresponsetime(final long responsetime) { this.responsetime = responsetime; /** * 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, ""); /** * 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() { this.setwebviewclient(new UICWebViewClient()); this.addjavascriptinterface(new JavaScriptInterface (this.getcontext()), "tlbridge"); /** * Log the load time of the WebView. public final void logconnection() { final long loadtime = this.getendload().gettime() - this.getstartload().gettime(); Tealeaf.logConnection(this.url, this.httpresponse, 72 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

79 this.connectioninitfromsession, loadtime, this.responsetime); Extend android.webkit.webviewclient: The sample code that follows extends the base Android WebViewClient with UICWebViewClient. import android.webkit.webview; import android.webkit.webviewclient; /** ohernandez * public class UICWebViewClient extends WebViewClient { /** * public boolean shouldoverrideurlloading(final WebView view, final String url) { view.loadurl(url); return true; 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: { // 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 Chapter 1. Tealeaf installation and implementation in an Android application 73

80 captured snaphot 2. 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); 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 Example Enable Tealeaf Framework /** * Public API to enable Tealeaf framework. {void enabletealeafframework(); Disable Tealeaf Framework /** * Public API to disable Tealeaf framework. {void disabletealeafframework(); Log Screen Capture /** * Public API to add a screenshot capture. {void logscreencapture(); 74 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

81 Method Example Start New Tealeaf Session /** * Public API to start a new Tealeaf session. {void startnewtlfsession(); Current Session ID /** * Public API to start get current Tealeaf session Id. {String Current session Id currentsessionid(); Default Value for Configurable Item /** * Public API to get default value of a configurable item in * TLFConfigurableItems.properties file. {String configitem This is the name of the configurable item. {String The value for the item. defaultvalueforconfigurableitem (configitem); Value for Configurable Item /** * Public API to get the value of a configurable item either from * TLFConfigurableItems.properties file * or in memory data structure. {String configitem This is the name of the configurable item. {String The value for the item. valueforconfigurableitem(configitem); Set Configurable Item /** * Public API to set the value of a configurable item in TLFConfigurableItems.properties * file. {String configitem This is the name of the configurable item. {String value The value assign to the configitem. {boolean Wether item was set. setconfigurableitem(configitem, value); Add Additional HTTP Header /** * Public API to add additional http header. {String key This is the key of the configurable item. {String value The value assign to the configitem. {boolean Wether item was set. addadditionalhttpheader(key, value); Chapter 1. Tealeaf installation and implementation in an Android application 75

82 Method Example Log Custom Event Bridge /** * Public API to log custom event. {String eventname A custom event name. {String jsondata JSON data string. {int loglevel Tealeaf library logging level for the event. {boolean Wether item was set. 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" " <html xmlns=" > <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 ) { node = document.createtextnode(textdata + " returned: " + apiretval); else { node = document.createtextnode(textdata ); 76 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

83 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") ); 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 ); Chapter 1. Tealeaf installation and implementation in an Android application 77

84 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. 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 = protected void oncreate(bundle savedinstancestate) { // Initialize tealeaf with a reference to application Tealeaf tealeaf = new Tealeaf(this.getApplication()); 78 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

85 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. 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 CX Mobile Android Logging Framework. 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 CX Mobile Android Logging Framework 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 87. Traffic volume management You can add a sampling function to work with the CX Mobile Android Logging Framework 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 CX Mobile Android Logging Framework 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. Chapter 1. Tealeaf installation and implementation in an Android application 79

86 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 CX Mobile Android Logging Framework. Note: Depending on the version of the CX Passive Capture Application you installed, the required content types may already be configured for capture. The CX Mobile Android Logging Framework 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 CX Mobile Android Logging Framework 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 97. When this option is enabled, you must configure the CX Passive Capture Application to capture these screen captures. By default, the CX Passive Capture 80 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

87 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. 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 CX Mobile Android Logging Framework 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. Chapter 1. Tealeaf installation and implementation in an Android application 81

88 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 CX Mobile Android Logging Framework, more configuration can be required. Review the following steps and complete any necessary ones to sessionize your mobile application. To enable sessionization of hits that are captured through the CX Mobile Android Logging Framework, 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_SESSION 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 CX Mobile Android Logging Framework, 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. 82 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

89 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 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 84 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 CX Mobile Android Logging Framework. 3. From the CX RealiTea Viewer menu, select Tools > Options Click the Profiles tab. See "RealiTea Viewer - Profile Options" in the IBM Tealeaf CX RealiTea Viewer User Manual. Chapter 1. Tealeaf installation and implementation in an Android application 83

90 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. 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. 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: 84 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

91 <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 CX Mobile Android Logging Framework Guide. IBM Tealeaf events for CX Mobile Android Logging Framework The JSON format is used to track data that is captured by the CX Mobile Android Logging Framework. 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 CX Mobile Android Logging Framework When you upgrade the IBM TealeafCX Mobile Android Logging Framework, 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 As an alternative to integrating the CX Mobile Android Logging Framework with your application in development, you can use the sample application that is provided by IBM Tealeaf. See Tealeaf sample application on page 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 Apply the basic configuration. Note: The latest version of the CX Mobile Android Logging Framework includes new configuration requirements. See Basic configuration on page 21. Chapter 1. Tealeaf installation and implementation in an Android application 85

92 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 79. 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 Test your upgraded solution. 86 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

93 Chapter 2. Configuration file Log level settings This configuration file for the CX Mobile Android Logging Framework library is placed into the asset folder of an Android application. It is named TLFConfigurableItems.properties, which is a Java properties file. The log level settings configure base logging settings. Table 7. Log level settings Item ID Description Values LoggingLevel The current logging level, applies only when log level is not indicated in log statement. 0 has the highest priority. Integer, 0-5 DisplayLogging LogViewLayout OnScreenTransition To disable logging, start Tealeaf.Disable(). See Chapter 5, Reference, on page 97. 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 8. Kill switch settings Item ID Description Values KillSwitchEnabled If true, the framework checks the kill switch target page before starting. You must specify the following properties. 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. The number of times the framework checks for the kill switch URL before giving up. This value should be set to at least 1. The time to wait before rechecking the kill switch URL if it is not responding URL Integer Seconds Copyright IBM Corp. 1999,

94 Table 8. Kill switch settings (continued) Item ID Description Values UseWhiteList If true and KillSwitchEnabled, the framework requires a phone id to assign before calling Enable to check the white list of phone ids. 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 9. Local cache file settings Item ID Description Values HasToPersistLocalCache If true, data is stored in local storage on the device, instead of in memory. The following settings must also be configured. true/false CachingLevel CachedFileMaxBytesSize The current caching level. Applies only when HasToPersistLocalCache is true. 0 has the highest priority. Maximum number of bytes to be stored on device. Integer, 0-5 Bytes Post settings These settings control the logging level, URL, volume, and frequency of posts to the target page. Table 10. Post settings Item ID Description Values PostMessageUrl 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 For more information about the target page, see Chapter 1, Tealeaf installation and implementation in an Android application, on page 1. URL PostMessageLevelWiFi PostMessageLevelCellular The logging level of events to be sent to the server over Wi-Fi when network performance is good. 0 has the highest priority. The logging level of events to be sent to the server over the cellular (3G) network. 0 has the highest priority IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

95 Table 10. Post settings (continued) Item ID Description Values MaxStringsLength 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. Integer ManualPostEnabled If true, the framework sends data to the server only when your application calls requestmanualserverpost. true/false DoPostOnIntervals PostMessageTimeIntervals PostMessageTimeout 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. 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. 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 11. Masking settings Item ID Description Values HasMasking It can be true or false to mask values of controls. If HasMasking=true, then complete next value. Boolean MaskIdList Comma delimited ids or regular String expressions to find ids. HasCustomMask It can be true or false to use next Boolean values below if true. SensitiveSmallCaseAlphabet Character to be used by small case String letter. SensitiveCapitalCaseAlphabet Character to be used by capital case String letter. SensitiveSymbol Character to be used by symbol. String Chapter 2. Configuration file 89

96 Table 11. Masking settings (continued) Item ID Description Values SensitiveNumber Character to be used by number. String Filter message type setting This setting controls the message types that are sent back to the server. Table 12. Filter message type setting Item ID Description Values FilterMessageTypes 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. TRUE/ FALSE Cookie settings These settings control cookies. Table 13. Cookie settings Item ID Description Values CookieSecure If set to TRUE, a secure parameter is added to the cookie. This can only be used in https post urls. TRUE/ FALSE CookieExpiresFormat This setting is used to indicate the cookie expiration format. Valid date formats: ASCTIME, RFC1036, or RFC1123 Session timeout setting This setting controls session timeouts. Table 14. Session timeout setting Item ID Description Values SessionTimeout When SessionTimeout is set, the expiration of cookie is the current time plus the session timeout value. 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 15. Screenshot settings Item ID Description Values ScreenshotFormat The format of the screen shot. PNG/ JPG 90 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

97 Table 15. Screenshot settings (continued) Item ID Description Values PercentOfScreenshotsSize The percentage of screen capture's original pixel dimensions at which posted screen captures are submitted, Integer PercentToCompressImage Percentage to compress image. This setting can only be used for JPG images. PNG images ignore this setting and default to 100. Integer Internal settings: do not change Do not change these settings unless directed to do so by IBM Tealeaf. Table 16. Internal settings: do not change Item ID Description Values PostMessageSocketTimeout 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 CompressPostMessage BufferLimit BufferPercent TimeIntervalBetweenSnapshots 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 true/ false Integer Percentage Seconds Chapter 2. Configuration file 91

98 92 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

99 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. Copyright IBM Corp. 1999,

100 94 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

101 Chapter 4. Guidelines Apply the following tips to your application development and integration of the IBM Tealeaf CX Mobile Android Logging Framework. v Use the kill switch to control logging of the Android application. See Chapter 6, Sample Code, on page 119. 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 CX Mobile Android Logging Framework. v v v v v v 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 Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual. Follow guidelines for the file that extends Application. See Chapter 1, Tealeaf installation and implementation in an Android application, on page 1. Follow guidelines for the file that extends Activity. See Chapter 1, Tealeaf installation and implementation in an Android application, on page 1. Debug locally in Eclipse by using LogCat. To see debug messages in the LogCat tab of Eclipse, enter the following string: tag:uicandroid. Follow guidelines for using TLDefaultHttpClient for requests and responses to get connection metrics. See TLDefaultHttpClient class on page 110. Follow guidelines for using text fields to get more metrics. See Tealeaf class on page 100. 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. Copyright IBM Corp. 1999,

102 96 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

103 Chapter 5. Reference UICActivity class This section contains class reference information about the IBM Tealeaf CX Mobile Android Logging Framework 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() Logical page name of the Activity. 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) Logical page name of the Activity. logicalpagename - Logical page name of the Activity. Copyright IBM Corp. 1999,

104 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. 98 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

105 Reference Table 17. UICActivity class Package Class Description com.tl.uic.app UICActivity UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication class Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class on page 100 IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class on page 111 TLHttpResponseInterceptor class on page 112 Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. Extends HttpResponseInterceptor to acquire details for the Tealeaf connection object. com.tl.uic.webkit UICWebView class on page 113 WebView used to add session ID to header requests. UICWebChromeClient Class on page 115 Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. UICWebViewClient Class on page 116 Extends WebViewClient to monitor when the URL loaded to add IBM Tealeaf headers for sessionization. UICApplication class The com.tl.uic.app.uicapplication class extends android.app.application. UICApplication helps capture user actions in an Android application. Chapter 5. Reference 99

106 Method detail gettealeaf public Tealeaf gettealeaf() Reference Get current instance of IBM Tealeaf. Returns the current instance of IBM Tealeaf. Table 18. UICApplication class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class on page 111 TLHttpResponseInterceptor class on page 112 Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. Extends HttpResponseInterceptor to acquire details for the IBM Tealeaf connection object. com.tl.uic.webkit UICWebView class on page 113 WebView used to add session ID to header requests. UICWebChromeClient Class on page 115 UICWebViewClient Class on page 116 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. 100 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

107 Fields Table 19. Tealeaf class Field Summary Description static java.lang.string static java.lang.string TLF_SESSION_HEADER TAG Header key that is used to sessionize on X-Tealeaf-Session. UICAndroid used in LogCat. Fields used in event handlers to get display user actions correctly Table 20. Tealeaf class Field Summary Description static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string TLF_ON_FOCUS_CHANGE_IN TLF_ON_FOCUS_CHANGE_OUT TLF_ON_GROUP_COLLAPSE TLF_ON_GROUP_EXPAND TLF_ON_DRAWER_OPENED TLF_ON_DRAWER_CLOSED 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 Table 21. Tealeaf class Field Summary Description static java.lang.string TLF_LOGGING_LEVEL Default log level. static java.lang.string static java.lang.string static java.lang.string static java.lang.string DISPLAY_LOGGING TLF_KILL_SWITCH_ENABLED TLF_KILL_SWITCH_URL TLF_KILL_SWITCH_MAX_NUMBER_OF_TRIES Whether to display debug statements in LogCat Whether kill switch is enabled. Url for kill switch. Maximum number of tries Chapter 5. Reference 101

108 Table 21. Tealeaf class (continued) Field Summary Description static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string TLF_KILL_SWITCH_TIME_INTERVAL TLF_USE_WHITE_LIST TLF_WHITE_LIST_PARAM TLF_USE_RANDOM_SAMPLE TLF_RANDOM_SAMPLE_PARAM TLF_HAS_TO_PERSIST_LOCAL_CACHE TLF_CACHED_LEVEL TLF_CACHED_FILE_MAX_BYTES_SIZE TLF_POST_MESSAGE_URL TLF_POST_MESSAGE_LEVEL_WIFI TLF_POST_MESSAGE_LEVEL_CELLULAR TLF_MAX_STRINGS_LENGTH TLF_MANUAL_POST_ENABLED TLF_DO_POSTS_ON_INTERVALS TLF_POST_MESSAGE_TIME_INTERVALS TLF_POST_MESSAGE_MAX_BYTES_SIZE TLF_HAS_MASKING Kill switch time interval to retry to access kill switch. Whether to use white list. Parameter that white list uses. Whether to use random sample. 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. 102 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

109 Table 21. Tealeaf class (continued) Field Summary Description static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string static java.lang.string TLF_MASK_ID_LIST TLF_HAS_CUSTOM_MASK TLF_SENSITIVE_SMALL_CASE_ALPHABET TLF_SENSITIVE_CAPITAL_CASE_ALPHABET TLF_SENSITIVE_SYMBOL TLF_SENSITIVE_NUMBER Comma-delimited string that can have IDs of controls or regular expression to find IDs of controls. 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) Chapter 5. Reference 103

110 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. 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. 104 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

111 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. 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. Chapter 5. Reference 105

112 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 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. 106 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

113 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) 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. Returns: Whether the layout was logged. 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. Chapter 5. Reference 107

114 v activity - Activity to be logged. v name - Name of the layout. Returns: Whether the layout was logged. 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) 108 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

115 Register form field that helps get statistics. v formfield - Form field to register. 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() Reference 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. Table 22. Tealeaf class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control library. UICApplication class on page 99 Application that is used to help control library. com.tl.uic TeaLeaf library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 Extends DefaultHttpClient to monitor when a URL was requested TLHttpRequestInterceptor class on page 111 TLHttpResponseInterceptor class on page 112 Extends HttpRequestInterceptor to add headers for sessionization Extends HttpResponseInterceptor to acquire details for the connection object com.tl.uic.webkit UICWebView class on page 113 WebView used to add session ID to header requests. UICWebChromeClient Class on page 115 UICWebViewClient Class on page 116 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 Chapter 5. Reference 109

116 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. Note: Instances of TlHttpRequestInterceptor class and TlHttpRequestInterceptor class are added to TLDefaultHttpClient to acquire details for IBM Tealeaf connection object. Reference Table 23. TLDefaultHttpClient class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication class on page 99 Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class on page 100 IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class on page 111 TLHttpResponseInterceptor class on page 112 Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. Extends HttpResponseInterceptor to acquire details for the IBM Tealeafconnection object. com.tl.uic.webkit UICWebView class on page 113 WebView used to add session ID to header requests. UICWebChromeClient Class on page 115 UICWebViewClient Class on page 116 Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. Extends WebViewClient to monitor when the URL was loaded to add IBM Tealeaf headers for sessionization. 110 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

117 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 Reference Table 24. TLHttpRequestInterceptor class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication class on page 99 Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class on page 100 IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 TLHttpRequestInterceptor TLHttpResponseInterceptor class on page 112 Extends DefaultHttpClient to monitor when a URL requested. Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. Extends HttpResponseInterceptor to acquire details for the Tealeaf connection object. com.tl.uic.webkit UICWebView class on page 113 WebView used to add session ID to header requests. UICWebChromeClient Class on page 115 UICWebViewClient Class on page 116 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 Tealeaf headers for sessionization. Chapter 5. Reference 111

118 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. Methods overridden v Process Reference Table 25. TLHttpResponseInterceptor class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication class on page 99 Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class on page 100 IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 TLHttpRequestInterceptor class on page 111 TLHttpResponseInterceptor Extends DefaultHttpClient to monitor when a URL was requested. Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. Extends HttpResponseInterceptor to acquire details for the IBM Tealeaf connection object. com.tl.uic.webkit UICWebView class on page 113 WebView used to add session ID to header requests. UICWebChromeClient Class on page 115 UICWebViewClient Class on page 116 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. 112 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

119 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) 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. Chapter 5. Reference 113

120 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() Reference Logs the current connection time of the webview. Table 26. UICWebView Class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication class on page 99 Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class on page 100 IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class on page 111 TLHttpResponseInterceptor class on page 112 Extends HttpRequestInterceptor to add CX Mobile Android Logging Framework headers for sessionization. Extends HttpResponseInterceptor to acquire details for the CX Mobile Android Logging Framework connection object. com.tl.uic.webkit UICWebView WebView used to add session ID to header requests. 114 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

121 Table 26. UICWebView Class (continued) Package Class Description UICWebChromeClient Class UICWebViewClient Class on page 116 Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. Extends WebViewClient to monitor when the URL loaded to add CX Mobile Android Logging Framework 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. Methods overridden v onprogresschanged Reference Table 27. UICWebChromeClient class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication class on page 99 Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class on page 100 IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 TLHttpRequestInterceptor class on page 111 Extends DefaultHttpClient to monitor when a URL was requested. Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. Chapter 5. Reference 115

122 Table 27. UICWebChromeClient class (continued) Package Class Description TLHttpResponseInterceptor class on page 112 Extends HttpResponseInterceptor to acquire details for the IBM Tealeaf connection object. com.tl.uic.webkit UICWebView class on page 113 WebView used to add session ID to header requests. UICWebChromeClient UICWebViewClient Class 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. 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. Methods overridden v shouldoverrideurlloading Reference Table 28. UICWebViewClient class Package Class Description com.tl.uic.app UICActivity class on page 97 UICActivity used to help control IBM Tealeaf CX Mobile Android Logging Framework library. UICApplication class on page 99 Application that is used to help control IBM Tealeaf CX Mobile Android Logging Framework library. com.tl.uic Tealeaf class on page 100 IBM Tealeaf CX Mobile Android Logging Framework library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class on page 110 TLHttpRequestInterceptor class on page 111 Extends DefaultHttpClient to monitor when a URL was requested. Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. 116 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

123 Table 28. UICWebViewClient class (continued) Package Class Description TLHttpResponseInterceptor class on page 112 com.tl.uic.webkit UICWebView class on page 113 UICWebChromeClient Class on page 115 UICWebViewClient Extends HttpResponseInterceptor to acquire details for the IBM Tealeaf connection object. WebView used to add session ID to header requests. Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. Extends WebViewClient to monitor when the URL loaded in to add IBM Tealeaf headers for sessionization. Chapter 5. Reference 117

124 118 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

125 Chapter 6. Sample Code This chapter contains sample code for IBM Tealeaf CX Mobile Android Logging Framework. 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); ); Copyright IBM Corp. 1999,

126 How to instrument SlidingDrawer based controls How to mask 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); ); 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 KillSwitch is enabled in the client configuration, the CX Mobile Android Logging Framework queries the KillSwitch URL to determine whether it is enabled or disabled for the session. If the CX Mobile Android Logging Framework is disabled, then the session is not captured and is excluded from the sampled data. In the code samples that follow, the KillSwitch URL returns 1 to enable the CX Mobile Android Logging Framework and 0 to disable the CX Mobile Android Logging Framework. 120 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

127 Sampling Function for ASPX killswitch.aspx This ASPX sample shows a return of 1 to enable the CX Mobile Android Logging Framework and of 0 to disable the CX Mobile Android Logging Framework. <%@ 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{ return 0; </script> <% if (ConfigurationManager.AppSettings["killswitchtype"].Equals("percentagesample")) { %> <%= Sampler() %> <% else{ %> Figure 1. killswitch.aspx web.config configuration file for ASPX <?xml version="1.0"?> <!-- For more information on how to configure your ASP.NET application, please visit --> <configuration> <appsettings> <add key="killswitchtype" value="percentagesample"/> <add key="rate" value="50"/> </appsettings> </configuration> Figure 2. web.config Sampling Function for JSP killswitch.jsp This JSP sample shows a return of 1 to enable the CX Mobile Android Logging Framework and of 0 to disable the CX Mobile Android Logging Framework. v If the request does not have parameters, the client framework is always disabled. v If the id request parameter exists, it is used to check the whitelist. v If the randomsample parameter exists, the percentage rate from the config.properties file is used to determine how the server responds. Chapter 6. Sample Code 121

128 Debug logs are generated if the debug property is set to true. page language="java" contenttype="text/html; charset=iso " pageencoding="iso "%> import="java.util.properties"%> import="java.util.date" %> page import="java.net.*"%> page import="java.io.*" errorpage=""%> <% 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); Figure 3. killswitch.jsp //always give the path from root. This way it almost always works. String nameoftextfile = props.getproperty("logfile"); PrintWriter pw; if (DEBUG) { 122 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

129 %> 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)) pw.println(debugstr + "\tdisable"); else pw.println(debugstr + "\tenable"); //clean up pw.close(); catch (IOException e) { out.println(e.getmessage()); WhiteListFile=whitelist.txt samplerate =50 debug=true logfile=/killswitchlog.txt Figure 4. config.properties web.config configuration file for JSP Sampling Function for PHP killswitch.php This PHP sample shows a return of 1 to enable the CX Mobile Android Logging Framework and of 0 to disable the CX Mobile Android Logging Framework. Chapter 6. Sample Code 123

130 <?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){?> Figure 5. killswitch.php ; This is a sample configuration file ; Comments start with ;, as in php.ini [configtype] killswitchtype=percentagesample [percentagesample] rate = 50 [whitelist] x y z Figure 6. config.ini web.config configuration file for PHP JSON message type schemas and examples JSON messages are categorized by type for processing. Tealeaf supports 12 JSON message types. This table lists and describes the supported JSON message types: Table 29. Schema by Message Type Type Message Type Description 1 Client state (Type 1) messages on page 127 Any object that shows the current state of client. 124 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

131 Table 29. Schema by Message Type (continued) Type Message Type Description 2 ScreenView (Type 2) messages on page Connections (Type 3) messages on page Control (Type 4) messages on page Custom Event (Type 5) messages on page Exception (Type 6) messages on page Performance (Type 7) messages on page Web Storage (Type 8) messages on page Overstat Hover Event (Type 9) messages on page Layout (Type 10) messages on page Gesture (Type 11) messages on page DOM Capture (Type 12) message example on page 147 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. User interface control that fires an event to which Tealeaf listens for capture. Any custom log event from any location in application. Any exception that the application can throw. Performance data from a browser. 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. Any object that contains serialized HTML data (DOM snapshot) of the page. 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. Note: All time measurements in the JSON object schema are in milliseconds. Message header properties schema "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", Chapter 6. Sample Code 125

132 "type": "boolean", "required": true,"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], description: "EXCEPTION" ], "required": true, Message header properties schema "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,"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], description: "EXCEPTION" ], "required": true, 126 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

133 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], description: "Keyboard hidden", "enum": [2], description: "Undefined" ], "required": true,, "battery": { "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", "required": true, "carrier": { "title": "Carrier of device", "type": "string", Chapter 6. Sample Code 127

134 "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", "type": "string", "required": true, "devicescale": { "title": "scaling factor for fitting 128 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

135 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,, "additionalproperties" : false 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": , "androidstate": { "keyboardstate": 0, "battery": 50, "freememory": , "connectiontype": "UMTS", "carrier": "Android", "networkreachability": "ReachableViaWWAN", "ip": " " 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. { "$ref" : "MessageHeader", "screenview/context": { "description": "Logical page being loaded or unloaded", "type": "object", "properties": { Chapter 6. Sample Code 129

136 "type": { "title": "Type of ScreenView - LOAD or UNLOAD", "type": "string", "required": true, "name": { "title": "Name of the logical page", "type": "string", "required": true, "url": { "title": "Url of the logical page", "type": "string", "required": true, "rendertime": { "title": "Time it took page to render, only used in LOAD", "type": "integer", "required": false, "referrer": { "title": "Previous logical page loaded, only used in LOAD", "type": "string", "required": false, "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. {, "type": 2, "offset": 0, "screenviewoffset": 0, "count": 1, "fromweb": true, "screenview": { "type": "LOAD", "name": "root", "url": "/", "referrer": "" { { "type": 2, "offset": 40824, "screenviewoffset": 0, "count": 12, "fromweb": true, "screenview": { "type": "UNLOAD", "name": "root", "url": "/", "referrer": "" "type": 2, "offset": 2144, "screenviewoffset": 0, "count": 9, 130 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

137 "fromweb": true, "screenview": { "type": "LOAD", "name": "Ford", "url": "/example/dynamic/", "referrer": "BMW", 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. { "$ref" : "MessageHeader", "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, "loadtime": { "title": "Load time from connection", "type": "number", "required": true, "additionalproperties" : false Connections example The following example provides information on the status code of the response returned from example.com. { "offset": 03829, "type": 3, "screenviewoffset": 45560, Chapter 6. Sample Code 131

138 "type": 3, "connection": { "statuscode": 200, "responsedatasize": 0272, "inittime": , "responsetime": 02237, "url": " "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. { "$ref" : "MessageHeader", "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, "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 132 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

139 default value of 0.5", "type": "string", "required": true for click events,, "additionalproperties" : false "id": { "title": "Id/Name/Tag of control", "type": "string", "required": true, idtype": { "title": "To indicate what id is based on id, name or xpath", "type": "integer", "required": only for UIC due to replay, "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", "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", Chapter 6. Sample Code 133

140 "type": "object", "required": true, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false, "additionalproperties" : 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, "additionalproperties" : false Control (Type 4) message example This is an example of a Control Type 4) message. This control message identifies the new value (MyDataEntry) of a textbox (id=com.tl.uiwidget:id\/edittext_c3_1), in which the visitor was dwelling for seconds. { "target": { "position": { "y": 38, "height": 96, "width": 720, "x": 0, "id": "com.tl.uiwidget:id\/edittext_c3_1", "dwell": 3586, "currstate": { "text": "MyDataEntry", "subtype": "TextView", "type": "EditText", "tltype": "textbox", "prevstate": { "text": "", "screenviewoffset": 4706, "focusinoffset": 23418, "offset": 27004, 134 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

141 "type": 4, "event": { "type": "OnFocusChange_Out", "tlevent": "textchange" 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. { "$ref" : "MessageHeader", "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": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false,, "additionalproperties" : 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, "screenviewoffset": 4556, "customevent": { "name": "MyEvent_1", "data": { "Foo": "Bar", "validationerror": "Invalid zipcode.", "ajaxperformance": Chapter 6. Sample Code 135

142 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. { "$ref" : "MessageHeader", "exception": { "description": "Exception description message", "type": "object", "properties": { "description": { "title": "Exception Name", "type": "string", "required": true, "name": { "title": "Exception name/type", "type": "string", "required": true, "stacktrace": { "title": "Exception stacktrace given by framework", "type": "string", "required": true,, "additionalproperties" : false Exception (Type 6) message example This is an example of an Exception (Type 6) message. This exception message indicates a divide-by-zero error and includes a stack trace from the client. { "offset": 0, "screenviewoffset": 4556, "type": 6, "exception": { "description": "divide by zero", "name": "class java.lang.arithmeticexception" "stacktrace": "java.lang.arithmeticexception: divide by zero\n\tat com.tl.uic.test.model.jsontest.testexception(jsontest.java:391)\n\tat java.lang.reflect.method.invokenative(native Method)\n\tat java.lang.reflect.method.invoke(method.java:507)\n\tat android.test.instrumentationtestcase.runmethod(instrumentationtestcase.java:204 )\n\tat android.test.instrumentationtestcase.runtest(instrumentationtestcase.java:194)\ n\tat android.test.activityinstrumentationtestcase2.runtest(activityinstrumentationte stcase2.java:186)\n\tat junit.framework.testcase.runbare(testcase.java:127)\n\tat junit.framework.testresult$1.protect(testresult.java:106)\n\tat junit.framework.testresult.runprotected(testresult.java:124)\n\tat junit.framework.testresult.run(testresult.java:109)\n\tat junit.framework.testcase.run(testcase.java:118)\n\tat android.test.androidtestrunner.runtest(androidtestrunner.java:169)\n\tat android.test.androidtestrunner.runtest(androidtestrunner.java:154)\n\tat android.test.instrumentationtestrunner.onstart(instrumentationtestrunner.java:5 29)\n\tat 136 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

143 android.app.instrumentation$instrumentationthread.run(instrumentation.java:1448 )\n", 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. { "$ref" : "MessageHeader", "performance": { "description": "Performance message", "type": "object", "properties": {, "additionalproperties" : false 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 Chapter 6. Sample Code 137

144 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, 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: IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

145 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. "$ref" : "MessageHeader", "layoutcontrol": { "description": "Control on application page", "type": "object", "properties": { "position": { "description": "Position of control", "type": "object", "properties": { "x": { "title": "X of the control", "type": "integer", "required": true, "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, "additionalproperties" : false "id": { "title": "Id/Name/Tag of control", "type": "string", "required": true, "type": { "title": "Type of control", "type": "string", "required": true, "subtype": { "title": "SubType of control", "type": "string", "required": true, "tltype": { "title": "tltype of control that normalizes the control type for eventing", "type": "string", "required": true, "currstate": { "title": "Current state of control", "type": "object", "required": true, "properties": { "?": { // Could be any variable name given by developer Chapter 6. Sample Code 139

146 "title": "Additional data in string format", "type": "string", "required": false, "style" : { "title": "Style of the control", "type": "object", "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, "additionalproperties" : false Layout (Type 10) message example This is an example of a Layout (Type 10 ) message. { "offset": 27004, "screenviewoffset": 4706, "count": 16, "fromweb": false, "type": 10, "layout": { "name": "loginpage", "controls": [ 140 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

147 { "position": { "y": 38, "height": 96, "width": 720, "x": 0, "id": "com.tl.uiwidget:id\/usernamelabel", "type": "UILabel", "subtype": "UIView", "tltype": "label", "currstate": { "text": "User name*", "style": { "textcolor": , "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. Chapter 6. Sample Code 141

148 Gesture (Type 11) message schema This is the schema for Gesture (Type 11) messages. Tap event schema This is the schema for tap events: { "$ref" : "MessageHeader", "event": { "description": "Event from control", "type": "object", "properties": { "tlevent": { "title": "Tealeaf type of event", "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 and ends with last object when finger is lifted from device.", "type": "array", "required": true, "$ref": "Touch" 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: { "$ref" : "MessageHeader", "event": { "description": "Event from control", "type": "object", "properties": { "tlevent": { "title": "Tealeaf type of event", "type": "string", "required": true, "type": { "title": "Type of event framework reports", "type": "string", "required": false, "touches": { "description": "Gestures touch objects per finger.", "type": "array", 142 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

149 "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": "The direction of the swipe which can be up, down. left or right.", "type": "string", "required": true, "velocityx": { "title": "The velocity of this measured in pixels per second along the x axis", "type": "float", "required": true, "velocityy": { "title": "The velocity of this measured in pixels per second along the y axis", "type": "float", "required": false 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: { "$ref" : "MessageHeader", "event": { "description": "Event from control", "type": "object", "properties": { "tlevent": { "title": "Tealeaf type of event", "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 and ends with last object when finger is lifted from device.", "type": "array", "required": true, "$ref": "Touch", Chapter 6. Sample Code 143

150 "direction": { "title": "Direction of pinch which can be open or close", "type": "string", "required": true Gesture (Type 11) message example This is an example of a Gesture (Type 11) message. Tap events This example is a gesture message for a tap event: { "type": 11, "offset": 2220, "screenviewoffset": 2022, "count": 6, "fromweb": false, "event": { "tlevent": "tap", "type": "ACTION_DOWN", "touches": [ [ { "position": { "y": 388, "x": 0, "control": { "position": { "height": 20, "width": 250, "relxy": "0.6,0.8", "id": "com.tl.uic.appdarkholo:id/textview1", "type": "TextView", "subtype": "View", "tltype": "label" ] ] 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: { "type": 11, "offset": 2220, "screenviewoffset": 2022, "count": 6, "fromweb": false, "event": { "tlevent": "swipe", "type": "ACTION_DOWN", "touches": [ [ { 144 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

151 "position": { "y": 388, "x": 400, "control": { "position": { "height": 100, "width": 100, "relxy": "0.4,0.7", "id": "com.tl.uic.appdarkholo:id/imageview1", "type": "ImageView", "subtype": "View", "tltype": "image" ] ], "direction": "right", "velocityx": 23.2, "velocityy": 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, "screenviewoffset": 2022, "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", "id": "com.tl.uic.appdarkholo:id/imageview1", "type": "ImageView", "subtype": "View", "tltype": "image", { "position": { "y": 388, "x": 400, "control": { "position": { "height": 100, "width": 100, Chapter 6. Sample Code 145

152 ], [ {, { ] ], "direction": "close" "relxy": "0.4,0.7", "id": "com.tl.uic.appdarkholo:id/imageview1", "type": "ImageView", "subtype": "View", "tltype": "image" "position": { "y": 388, "x": 800, "control": { "position": { "height": 100, "width": 100, "relxy": "0.6,0.8", "id": "com.tl.uic.appdarkholo:id/imageview1", "type": "ImageView", "subtype": "View", "tltype": "image" "position": { "y": 388, "x": 500, "control": { "position": { "height": 100, "width": 100, "relxy": "0.4,0.7", "id": "com.tl.uic.appdarkholo:id/imageview1", "type": "ImageView", "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. "$ref" : "MessageHeader", "domcapture": { "description": "Serialized HTML snapshot of the document.", "type": "object", "properties": { "dcid": { "title": "Unique identifier of this DOM snapshot.", "type": "string", "required": true 146 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

153 "charset": { "title": "Browser reported charset of the document.", "type": "string", "required": false, "root": { "title": "Serialized HTML of the 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, "root": { "title": "Serialized HTML of the document.", "type": "string", "required": true, "canvas" : { "title": "Serialized data of the canvas snapshot.", "type": "array", "required": false,, "additionalproperties" : false DOM Capture (Type 12) message example This is an example of a DOM Capture (Type 12) message. This example shows a DOM message without frame or iframe capture: Chapter 6. Sample Code 147

154 { // DOM Capture messages use type 12 "type": 12, // The standard UIC message properties "offset": 16821, "screenviewoffset": 16817, "count": 5, "fromweb": true, // The DOM Capture data is namespaced in the domcapture object "domcapture": { // The "root" contains the serialized HTML of the live DOM "root": "<html><body>hello, World</body></html>", // The "charset" contains the value of the document.charset property returned by the browser "charset": "ISO ", // The "dcid" property contains the unique string identifying this DOM Capture within the page instance. "dcid": "dcid " This example shows a DOM capture message with frame and iframe capture: { // DOM Capture messages use type 12 "type": 12, // The standard UIC message properties "offset": 16821, "screenviewoffset": 16817, "count": 5, "fromweb": true, // The DOM Capture data is namespaced in the domcapture object "domcapture": { // The "root" contains the serialized HTML of the live DOM "root": "<html><body>hello, World</body></html>", // The "charset" contains the value of the document.charset property returned by the browser "charset": "ISO ", // The "dcid" property contains the unique string identifying this DOM Capture within the page instance. "dcid": "dcid " 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, "screenviewoffset": 16817, "count": 5, "fromweb": true, // The DOM Capture data is namespaced in the domcapture object "domcapture": { 148 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

155 // 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 " Examples Below is an example of a message consisting of two sessions that uses all of the message types except the custom event message. { "serialnumber": 0, "messageversion": " ", "sessions": [ { "starttime": , "id": "945202AC4E93104E05EDADE1F6059B97", "messages": [ { "offset": 124, "screenviewoffset": 4556, "type": 2, "logicalpagename": "HomeActivity", { "offset": 667, "screenviewoffset": 66778, "type": 1, "mobilestate": { "orientation": 0, "freestorage": , "androidstate": { "keyboardstate": 0, "battery": 50, "freememory": , "connectiontype": "UMTS", "carrier": "Android", "networkreachability": "ReachableViaWWAN", "ip": " ", { "customevent": { "name": "Screenshot Taken for file: HomeActivity_ jpg", "offset": 855, "screenviewoffset": 4556, "type": 5 ] ], "clientenvironment": { "mobileenvironment": { "android": { "keyboardtype": "QWERTY", Chapter 6. Sample Code 149

156 "brand": "generic", "fingerprint": "generic/sdk/generic/ :2.2/FRF91/43546:eng/test-keys", "totalmemory": , "totalstorage": 12288, "orientationtype": "PORTRAIT", "appversion": "1.0.5", "manufacturer": "unknown", "userid": "android-build", "locale": "English (United States)", "devicemodel": "sdk", "language": "English", "width": 0, "height": 0, "osversion": "2.2" 150 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

157 Chapter 7. Troubleshooting Debugging Tips Inclusion of raw request and response headers For debugging purposes, you can include the raw request and the response headers in the data that is passed by the CX Passive Capture Application to the Canister. Managing client-side issues This method is useful if you are not seeing any JSON data that is parsed in IBM Tealeaf. Note: Including these headers in your IBM Tealeaf sessions can significantly increase the storage requirements for mobile sessions. Enable these options only for debugging purposes. In the CX Passive Capture Application 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 CX Passive Capture Application Manual. The section that follows describes how the IBM Tealeaf CX Mobile Android Logging Framework 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. See "Tealeaf JSON Object Schema Reference" in the IBM Tealeaf Client Framework Data Integration Guide. Power failures Power failures on a device cannot be anticipated or managed through software. The data is lost. Copyright IBM Corp. 1999,

158 Note: A TL Library Error: File Not Found exception may 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. v 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. v For more information about configuring the local cache size, see Chapter 2, Configuration file, on page 87. v For more information about configuring the POSTs from the client, see Chapter 2, Configuration file, on page 87. 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 v For GET issues as a result of application interruptions, an exception object is generated. 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 CX Mobile Android Logging Framework is disabled for the device. 152 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

159 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: Use the information in the following table to view the product documentation for IBM Tealeaf: Table 30. Getting help To view... Product documentation 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? > 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 Use the following table to view a list of available documents for all IBM Tealeaf products: Table 31. Available documentation for IBM Tealeaf products IBM Tealeaf products Available documents IBM Tealeaf CX 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 Copyright IBM Corp. 1999,

160 Table 31. Available documentation for IBM Tealeaf products (continued) IBM Tealeaf products Available documents IBM Tealeaf CX 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 v IBM Tealeaf cximpact User Manual IBM Tealeaf cximpact Reporting Guide IBM Tealeaf cxconnect v IBM Tealeaf cxconnect for Data Analysis Administration Manual v IBM Tealeaf cxconnect for Voice of Customer Administration Manual v IBM Tealeaf cxconnect for Web Analytics Administration Manual IBM Tealeaf cxoverstat IBM Tealeaf cxoverstat User Manual IBM Tealeaf cxreveal v IBM Tealeaf cxreveal Administration Manual IBM Tealeaf cxverify IBM Tealeaf cxview v IBM Tealeaf cxreveal API Guide v IBM Tealeaf cxreveal User Manual IBM Tealeaf cxverify Administration Manual IBM Tealeaf cxview User Manual IBM Tealeaf CX Mobile v IBM Tealeaf CX Mobile Android Logging Framework Guide v v v v v IBM Tealeaf Android Logging Framework Release Notes IBM Tealeaf CX Mobile Administration Manual IBM Tealeaf CX Mobile User Manual IBM Tealeaf CX Mobile ios Logging Framework Guide IBM Tealeaf ios Logging Framework Release Notes 154 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

161 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 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 , Nihonbashi-Hakozakicho, Chuo-ku Tokyo , 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. Copyright IBM Corp. 1999,

162 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: IBM Bay Area Lab 1001 E Hillsdale Boulevard Foster City, California 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 156 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

163 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 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: privacy/details/us/en section entitled "Cookies, Web Beacons and Other Technologies." Notices 157

164 158 IBM Tealeaf CX Mobile Android Logging Framework: IBM Tealeaf CX Mobile Android Logging Framework Guide

165

166 Printed in USA