Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
IBM Tealeaf Version 10 Release 2.1.54 November 2016 Android SDK Guide IBM Note Before using this information and the product it supports, read the information in “Notices” on page 175. This edition applies to version 10, release 2.1, modification 54 of IBM Tealeaf Android SDK with EOCore 2.0.0.59, TeaCuts 2.0.0.15, and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright IBM Corporation 1999, 2016. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents IBM Tealeaf Android SDK Guide . . . . v Internal settings: do not change . Chapter 1. Tealeaf installation and implementation in an Android application . . . . . . . . . . . . . 1 Chapter 3. Application images and replay. . . . . . . . . . . . . . . 103 Client Framework versions supported in this documentation. . . . . . . . . . . . . . 2 Install the Tealeaf SDK for Android development in your application . . . . . . . . . . . . . 2 Tealeaf package contents . . . . . . . . . 2 Tealeaf sample application . . . . . . . . . 3 Android development environment requirements 3 Tealeaf impact on Android device resources . . . 4 Installing the IBM Tealeaf Android SDK with Rakefile . . . . . . . . . . . . . . . 4 Android Auto Instrumentation (AAI) . . . . . 5 Installing IBM Tealeaf Android SDK manually. . 12 How log levels work . . . . . . . . . . 13 Configure Tealeaf properties . . . . . . . . 14 Extended Android classes . . . . . . . . 16 Enabling screen logging in fragments . . . . . 21 Implement Tealeaf . . . . . . . . . . . 21 Install the Eclipse Tealeaf plug-in for Android development in your application . . . . . . . 54 Tealeaf package contents . . . . . . . . . 55 Android development environment requirements 56 Tealeaf impact on Android device resources . . 57 Add Eclipse Tealeaf plug-in to your Eclipse Android project . . . . . . . . . . . . 57 Configure Tealeaf properties . . . . . . . . 59 Extended Android classes . . . . . . . . 62 Implement Tealeaf . . . . . . . . . . . 67 Quick start for server configuration . . . . . . 89 Target page for traffic capture . . . . . . . 89 Traffic volume management . . . . . . . . 89 CX Passive Capture Application traffic capture verification . . . . . . . . . . . . . 90 Options for monitoring captures and processing 91 Configuring sessionization for Android applications in IBM Tealeaf . . . . . . . . 92 Runtime configuration. . . . . . . . . . 95 IBM Tealeaf events for Android SDK . . . . . . 95 Upgrading the Android SDK . . . . . . . . 95 Chapter 2. Configuration file . . . . . 97 Application key . . . . 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 . . . . . . . . . . . . . . . . . . . . . . © Copyright IBM Corp. 1999, 2016 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 . 97 . 98 . 98 . 99 . 100 . 100 . 100 . 101 . 101 . . . Target Simulator . . . . . . . . . Collecting images from your application the Target Simulator . . . . . . . Android Image Capture Tool . . . . . Collecting images from your application the Android Image Capture Tool . . . . . . . with . . . . with . . . 101 . 104 . 105 . 106 . 107 Chapter 4. Sample applications. . . . 109 Chapter 5. Guidelines . . . . . . . . 111 Chapter 6. Reference . . . . . . . . 113 UICActivity class . . . . UICApplication class . . . Tealeaf class . . . . . . UICWebView class . . . UICWebChromeClient Class UICWebViewClient Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 115 116 126 128 129 Chapter 7. Sample Code. . . . . . . 131 How to instrument TextView based controls . . How to instrument ExpandableListView based controls . . . . . . . . . . . . . . How to instrument SlidingDrawer based controls How to mask controls . . . . . . . . . How to implement AdvertisingId in your application to capture Google Advertising ID (GAID) data . . . . . . . . . . . . . Server-Side KillSwitch Sampling Function . . . Sampling function examples for ASPX . . . Sampling Function for JSP . . . . . . . Sampling Function for PHP . . . . . . JSON message type schemas and examples . . Message header properties . . . . . . . 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 . . . . GeoLocation (Type 13) messages . . . . . Cookie (Type 14) message schema . . . . . 131 . 131 132 . 132 . . . . . . . . . . . . . . . . . . . . . . 132 133 133 134 136 137 138 138 139 141 143 144 147 148 149 150 151 151 154 163 168 168 iii Chapter 8. Troubleshooting . . . . . 171 Troubleshooting and debugging - enabling raw request and response headers . . . . . . . Troubleshooting - managing client-side issues . . 171 . 171 Chapter 9. IBM Tealeaf documentation and help . . . . . . . . . . . . . 173 Notices . . . . . . . . . . . . . . 175 Trademarks . iv . . . . . . . . . . . . . 176 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Privacy Policy Considerations . . . . . . . . 177 IBM Tealeaf Android SDK Guide The IBM Tealeaf Android SDK for mobile native applications requires the IBM Tealeaf CX Mobile license for Mobile App. For more information, contact your IBM Tealeaf representative. Licensees must implement in their apps code that is provided by IBM Tealeaf. For more information on downloading IBM Tealeaf, see IBM® Passport Advantage® Online. The IBM Tealeaf Android SDK Guide provides guidance on how to enable the capture of mobile application data directly from the application that is installed on the visitor's Android-enabled device. Note: Whenever possible, use the latest version of the IBM Tealeaf Android SDK software. © Copyright IBM Corp. 1999, 2016 v vi IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 1. Tealeaf installation and implementation in an Android application You add the Tealeaf® SDK to your application so that the Android SDK can capture user interface and application events. There are two ways to install the Tealeaf SDK in your Android application. Supported Frameworks The installation and implementation instructions in this guide apply to the step-based version of JSON messaging from this client framework. The step-based version of JSON messaging from this client framework was introduced in Release 8.5. For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of submitting data from the client frameworks, which resulted in submitted data being split into individual hits in the Windows pipeline. In a future release, the hit-splitting method of processing data that is submitted from client frameworks is likely to be deprecated. The installation and implementation instructions for the legacy version are similar but require additional configuration in the Windows pipeline. Eclipse Tealeaf plug-in for Android development Note: The Android SDK is no longer supported with Eclipse. Android Studio should be used to integrate the Android SDK with your mobile application. The following references to integrating the Android SDK using Eclipse should only be used as a reference. 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 © Copyright IBM Corp. 1999, 2016 1 2. Configure properties, including application-specific URLs 3. Extend Application and Activity classes Client Framework versions supported in this documentation The installation and implementation instructions in this guide apply to the step-based version of JSON messaging from this client framework. The step-based version of JSON messaging from this client framework was introduced in Release 8.5. For Release 8.5 and later, IBM Tealeaf continues to support the legacy method of submitting data from the client frameworks, which resulted in submitted data being split into individual hits in the Windows pipeline. Note: In a future release, the hit-splitting method of processing data that is submitted from client frameworks is likely to be deprecated. The installation and implementation instructions for the legacy version are similar but require additional configuration in the Windows pipeline. Install the Tealeaf SDK for Android development in your application You add the Tealeaf SDK to your application so that the Android SDK can capture user interface and application events. You manually install and configure the Tealeaf SDK in each application . Tealeaf SDK for Android development You manually install and configure the Tealeaf SDK. You download the Tealeaf installation package and you: 1. Move files to the proper locations in your application 2. Configure properties, including application-specific URLs 3. Extend Application and Activity classes If you are upgrading from a previous version of the SDK, see “Upgrading the Android SDK” on page 95. Tealeaf package contents A single file contains the Android SDK and its software components. IBM Tealeaf Android SDK is delivered in the IBM Tealeaf Android SDK - 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. 2 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide – PHP - killswitch.php: Page with logic. - config.ini: Configuration file that is used by the page. v Tealeaf Mod: – eocore.jar: Android Core library JAR file used by module system. – tealeafmod.jar: Android library JAR file that contains the CX Mobile Android SDK. – EOCoreBasicConfig.properties: Configuration file. – TealeafBasicConfig.properties: Configuration file. – EOCoreAdvancedConfig.json: Configuration file. – TealeafAdvancedConfig.json: Configuration file. v SampleCode: Contains the following versions of a sample Android application. – DarkHoloAuto: An Android application with IBM Tealeaf CX Mobile Android SDK integrated and auto-instrumentation. – DarkHoloManual: An Android application with IBM Tealeaf CX Mobile Android SDK integrated which requires manual instrumentation. – HybridHTMLEmbedded: An Android application with IBM Tealeaf CX Mobile Android SDK integrated with a hybrid application. See "Sample Code" in the IBM Tealeaf Android SDK Guide. v AndroidEclipsePlugin: An Eclipse plug-in to assist with Tealeaf integration. – tealeaf.plugin.android.site-1.0.0-SNAPSHOT.zip: The plug-in archive to be added to your Eclipse IDE. – tealeafandroidsdk.jar: Android library JAR file that contains pre-instrumented Tealeaf widgets. v TealeafTargetSimulator – target_sim.js: Image extractor from posts in real time. v AndroidImageCaptureTool – Rakefile.rb: Image extractor and tagger for replay. v TeaCuts – teacuts.jar: Automation library. – TeaCutsBasicConfig.properties: Configuration file that stores basic configuration settings to assist with auto instrumentation. – TeaCutsAdvancedConfig.json: Configuration file that stores advanced library settings to assist with auto instrumentation. Tealeaf sample application You deploy the sample application that is provided by IBM Tealeaf to test the capabilities and measure the effects of the Android SDK. Instead of integrating the Android SDK with your application in development, you deploy the sample application and complete any necessary configuration steps on the remainder of this page to begin to capture mobile app data into your instance of IBM Tealeaf. See Chapter 4, “Sample applications,” on page 109. 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 3 Minimum requirements Develop Android applications with a minimum Android 4.1 or later. Consult the Google Android Dev Center for the latest Android technical documentation and tools. IBM Tealeaf client frameworks do not support forwarding of application data to third-party systems. Application data must be forwarded to the server that hosts the native application. Supported operating systems Tealeaf supports these versions of the Windows, Mac, and Linux operating systems: v Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit) v Mac OS X 10.5.8 or later (x86 only) v Linux (tested on Ubuntu Linux, Lucid Lynx) – GNU C Library (glibc) 2.7 or later is required. – 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. Android Studio Tealeaf supports the latest version of Android Studio. Android Framework API Tealeaf requires Android Framework API level 23 or higher. Tealeaf impact on Android device resources In benchmark tests, the Android SDK has the following effects on resources of the visitor's device. v 2-3% more memory consumption Note: If the Tealeaf server is unreachable, the SDK saves Tealeaf data to memory until the Tealeaf server is reachable. By default the SDK will store up to 512000 bytes to the device memory. If the cache grows larger than 512000 bytes, the oldest data is truncated from cache and is deleted. The cache size is managed through the CachedFileMaxBytesSize setting in EOCoreAdvancedConfig.json. v Minimal effect on battery life Installing the IBM Tealeaf Android SDK with Rakefile You can use Rakefile to install the IBM Tealeaf Android SDK into an Android application as a package. Using Rakefile to install the SDK eases the installation and integration process by automatically performing most integration steps that would otherwise be performed manually. 4 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide The following items must already be installed before you can use Rakefile to install the Android SDK: v Ruby v1.9.3 v Ruby gems For more information on these requirements, see https://www.ruby-lang.org/en/ documentation/installation/ and https://rubygems.org/pages/download. IBM Tealeaf (on-premises): From a command line, use the following Rakefile command to complete a new SDK integration with Android Studio for an IBM Tealeaf on-premises installation. rake modulePath="/Users/<username>/dev/RTC_Production/AndroidSrc/FragManualClean/app" postMessageUrl="http://<target_URL>/store/js/tealeaf/TealeafTarget.php" killswitchUrl="http://<target_URL>/store/js/tealeaf/killswitch.php" Tealeaf Customer Experience on Cloud: From a command line, use the following Rakefile command to complete a new SDK integration with Android Studio for an Tealeaf Customer Experience on Cloud installation. rake modulePath="/Users/<username>/dev/RTC_Production/AndroidSrc/FragManualClean/app" postMessageUrl="http://<target_URL>/store/js/tealeaf/TealeafTarget.php" killswitchUrl="http://<target_URL>/store/js/tealeaf/killswitch.php" appKey="111111111111111111111" Where: v modulePath: Defines the path where Android Studio module is located. Note: In the example, replace <username> with the active user name. v postMessageUrl: Points to the URL POST of the target page. Note: In the example, replace <target_URL> with the IP address for the target page. v killSwitchUrl: Points to the URL of the kill switch. Note: In the example, replace <target_URL> with the URL for the kill switch. v appKey: Defines the application key value for Tealeaf Customer Experience on Cloud. Android Auto Instrumentation (AAI) The Android SDK supports limited auto-instrumentation for new applications. The SDK uses the TeaCuts library module and AspectJ to support auto-instrumentation for the Activity, Application, and UI aspects. This simplifies the number of API calls that you must make in your application to instrument Tealeaf. By implementing the library, the application developer does not need to add additional code to troubleshoot errors that are related to: TeaCuts library The TeaCuts library is part of the Tealeaf android package. You add the library to the Inpath for your application with an AspectJ build. This weaves the Tealeaf library into your application and produces a final android APK that adds logging functions to your application. Chapter 1. Tealeaf installation and implementation in an Android application 5 Supported aspects The TeaCuts library incorporates logging functions for: v Navigation logging (Type 10 screen layout) v UI event logging (Type 4 UI events) Implementing Auto Instrumentation into your application project Complete the following steps before you implement the auto instrumentation library into your application. Eclipse implementation: Complete the following steps before you implement the auto instrumentation library into your Eclipse application. 1. Install the Eclipse Mars or later IDE from https://eclipse.org/downloads/ packages/release/Mars/R. 2. Install and setup AspectJ in your Eclipse project. For more information, see https://eclipse.org. 3. Enable JDT weaving in the Eclipse IDE. Select Eclipse > Preferences > JDT Weaving > Enable. Begin the implementation process for Eclipse: 1. Copy and paste the following .jar files from the distribution folder to the libs folder for your project: v AndroidRelease/Tealeaf/TealeafMod/eocore.jar v AndroidRelease/Tealeaf/TealeafMod/tealeafmod.jar v AndroidRelease/Tealeaf/TeaCuts/teacuts.jar 2. Right-click on the project in the Package Explorer to bring up the context menu. 3. Click Configure > Convert to AspectJ project. 4. Add the runtime library by clicking Preferences > Java Build Path > Libraries. 5. Add the Tealeaf AspectJ library called teacuts.jar to your project by clicking Eclipse > Preference > AspectJ Build > Add JARs. Android Studio implementation: Before you begin implementing AAI into Android Studio, install the Android Studio IDE 1.4.1 or later IDE from https://developer.android.com/sdk/index.html Begin the implementation process for Android Studio: 1. Copy and paste the following jar files from the distribution folder to your moduleslibs folder: v AndroidRelease/Tealeaf/TealeafMod/eocore.jar v AndroidRelease/Tealeaf/TealeafMod/tealeafmod.jar v AndroidRelease/Tealeaf/TeaCuts/teacuts.jar 2. Install and setup the required Tealeaf libraries in the gradle file (build.gradle): a. Insert the following imports to the top of build.gradle: v import org.aspectj.bridge.IMessage v import org.aspectj.bridge.MessageHandler v import org.aspectj.tools.ajc.Main b. Insert the following snippet into the dependencies section: 6 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide dependencies { compile files(’libs/eocore.jar’) compile files(’libs/tealeafmod.jar’) compile files(’libs/teacuts.jar’) compile ’org.aspectj:aspectjrt:1.8.8’ compile ’com.android.support:support-v4:xx.x.x’ } Replace xx.x.x with the version number of the Android library instance. c. Insert the following snippet to use jars that are managed by Maven Central. buildscript { repositories { mavenCentral() } dependencies { classpath ’org.aspectj:aspectjtools:1.8.8’ } } d. Insert the following snippet to the end of the file to enable weaving during AspectJ compiling. android.libraryVariants.all { variant > LibraryPlugin plugin = project.plugins.getPlugin(LibraryPlugin) JavaCompile javaCompile = variant.javaCompile javaCompile.doLast { String[] args = ["-showWeaveInfo", "-1.5", "-inpath", javaCompile.destinationDir.toString(), "-aspectpath", javaCompile.classpath.asPath, "-d", javaCompile.destinationDir.toString(), "-classpath", javaCompile.classpath.asPath, "-bootclasspath", plugin.project.android.bootClasspath.join( File.pathSeparator)] MessageHandler handler = new MessageHandler(true); new Main().run(args, handler) def log = project.logger for (IMessage message : handler.getMessages(null, true)) { switch (message.getKind()) { case IMessage.ABORT: case IMessage.ERROR: case IMessage.FAIL: log.error message.message,message.thrown break; case IMessage.WARNING: case IMessage.INFO: log.info message.message, message.thrown break; case IMessage.DEBUG: log.debug message.message, message.thrown break; } } } } Overriding standard classes with Tealeaf AAI classes Extending and overriding standard classes to enable the Tealeaf AAI hook into the application and activity lifecycle events. If you want to trace events through Tealeaf AAI, you should use the following code samples to override the extended application and activity classes. Note: You can import a sample application from the distribution folder AndroidRelease/Tealeaf/SampleCode/DarkHoloAuto. Prerequisites: 1. Copy and paste the following configuration files from the distribution folder to your project assets folder: v AndroidRelease/Tealeaf/TealeafMod/TealeafBasicConfig.properties Chapter 1. Tealeaf installation and implementation in an Android application 7 v AndroidRelease/Tealeaf/TealeafMod/EOCoreBasicConfig.properties v AndroidRelease/Tealeaf/TealeafMod/TealeafAdvancedConfig.json v AndroidRelease/Tealeaf/TealeafMod/EOCoreAdvancedConfig.json v AndroidRelease/Tealeaf/TeaCuts/TeaCutsAdvancedConfig.json v AndroidRelease/Tealeaf/TeaCuts/TeaCutsBasicConfig.properties 2. Make sure that DisableAutoInstrumentation is set to DisableAutoInstrumentation=false in TealeafBasicConfig.properties. Sample base Application class: public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); // Enable Tealeaf library Tealeaf.enable(this) } @Override public void onLowMemory() { super.onLowMemory(); } @Override public void onTerminate() { super.onTerminate(); } } Sample base Activity class public class BaseActivity extends Activity { private String logicalPageName; /** * Logical page name of the Activity. * * @return Logical page name of the Activity. */ public final String getLogicalPageName() { if ((this.logicalPageName == null) || (this.logicalPageName.equals(""))) { this.logicalPageName = BaseActivity.class.getSimpleName(); } return this.logicalPageName; } /** * Logical page name of the Activity. * * @param logicalPageName * Logical page name of the Activity. */ public final void setLogicalPageName(final String logicalPageName) { this.logicalPageName = logicalPageName; } /** * {@inheritDoc} */ public void onPause() { super.onPause(); } /** * {@inheritDoc} */ public void onResume() { super.onResume(); } /** * {@inheritDoc} 8 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide */ public void onDestroy() { super.onDestroy(); } } Once the Tealeaf AAI integration steps are complete and the SDK library is enabled, the following logcat message is displayed when the app is launched in the emulator. LogCat output: "Auto Instrumentation is turned on successfully." Disabling lifecycle events for activities and fragments during auto instrumentation If auto instrumentation is turned on with AspectJ, each lifecycle event methods such as onResume or onPause defined in source code are used as hooks to enable auto layout. To avoid duplicate API calls, you can disable the lifecycle events during auto instrumentation by editing TeaCutsBasicConfig.properties. By default, lifecycle events are enabled. To disable lifecycle events for activities and fragments, add the following snippet to TeaCutsBasicConfig.properties. ActivityLifecycleEnabled=false FragmentLifecycleEnabled=false Use the manual instrumentation steps to log screen views and screen layouts. The following example shows two activity classes which override the lifecycle events. // Base Activity public class BaseActivity extends Activity { public void onPause() { super.onPause(); } public void onResume() { super.onResume(); // Business logic } public void onDestroy() { super.onDestroy(); // Business logic } } // ControlsActivity1 public class ControlsActivity1 extends BaseActivity { public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.controls1); } public void onPause() { super.onPause(); } public void onResume() { super.onResume(); } Chapter 1. Tealeaf installation and implementation in an Android application 9 public void onDestroy() { super.onDestroy(); } } Using the AutoLayout controller to enable type 10 screen logging for native mobile applications Screen logging for a native mobile application can be enabled by configuring the AutoLayout controller instead of adding custom code to enable screen logging in your application. The IBM Tealeaf Android SDK can use the settings that are defined in TealeafLayoutConfig.json to log type 10 screen layouts for screenviews of native mobile application sessions. The AutoLayout controller also enables the application to automatically continue logging type 10 screen layouts when it resumes to the foreground. 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. TealeafLayoutConfig.json is in the assets folder and is formatted as a JSON file. Edit TealeafLayoutConfig.json to configure Autolayout to log screen layouts. Each AutoLayout entry has the following sub entries: Table 1. AutoLayout sub entries. Sub entry Description do Boolean value Indicates if the screen should be logged or not. v true: Logs the screen. v false: Does not log the screen. Eaxmple: "do": true enables logging for the screen. screenViewName String value Used to provide a custom identifying name that is assigned to the logged screen in JSON. For example, the screenViewName for a login screen might be "LoginScreen". Example: screenViewName": "LoginScreen" sets the value of screenViewName to LoginScreen. delay Numeric value The amount of time, in milliseconds, that is used to delay the screen logging action. Increasing the value of this setting increases the amount of time that must pass between when the screen is loaded and when the screen logging action occurs. The delay value is used for do and takeScreenShot. Example: "delay": 500 sets the delay between screen load and screen logging to 500 milliseconds. 10 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 1. AutoLayout sub entries. (continued) Sub entry Description takeScreenShot Boolean Indicates if a screen capture should be taken for the controller class. v true: Performs a screen capture. v false: Does not perform a screen capture. Example: "takeScreenShot": true turns on screen capturing for the screen activity. AppendMapIds JSON Assigns an identifier to a target item. You can assign a readable identifier to the mid that maps to the target item. You can then configure events to fire when the identifier is encountered. You can use the same identifier for Android devices as well as iOS devices. When you assign the same identifier to your Android and iOS devices, you can create a single event in Event Manager that fires on the identifier. The event fires for both Android and iOS devices. Example: "AppendMapIds": { "[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": { "mid": "LoginButton" }, "ibm.com.demoapp.main_activity_login:id\/send": { "mid": "LoginButton" } Uses the mid setting to assign an identifier to two targets. The first target is for an iOS device and the second target is for an Android device. The target for both devices is identified as LoginButton. You can create a single event that fires when LoginButton is encountered in either application. The following snippet shows an example of the TealeafLayoutConfig.json file. { "AutoLayout": { "UICAndroidControlsAppActivity": { "do": false, "screenViewName": "UICAndroidControlsAppActivity", "delay": 1, "takeScreenShot": false }, "ControlsActivity1": { "do": true, "screenViewName": "CA1", "delay": 500, "takeScreenShot": false }, "ControlsActivity2": { "do": true, "screenViewName": "CA2", "delay": 1, "takeScreenShot": false }, "ControlsActivity3": { "do": true, "screenViewName": "CA3", "delay": 1, Chapter 1. Tealeaf installation and implementation in an Android application 11 "takeScreenShot": false }, "ControlsActivity4": { "do": true, "screenViewName": "CA4", "delay": 1, "takeScreenShot": false }, "ControlsActivity5": { "do": true, "screenViewName": "CA5", "delay": 1, "takeScreenShot": false }, "ControlsActivity6": { "do": true, "screenViewName": "CA6", "delay": 1, "takeScreenShot": false }, "ControlsActivity7": { "do": true, "screenViewName": "CA7", "delay": 1, "takeScreenShot": false }, "ControlsActivity8": { "do": true, "screenViewName": "CA8", "delay": 1, "takeScreenShot": false } }, "AppendMapIds": { "[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": { "mid": "LoginButton" }, "ibm.com.demoapp.main_activity_login:id\/send": { "mid": "LoginButton" } } } }, Installing IBM Tealeaf Android SDK manually After you acquire IBM Tealeaf Android SDK, you can install the SDK as a package using Rakefile or you can manually install the SDK into your application project. Complete the following steps to manually install the Android SDK libraries into an Android application project. Your Eclipse project must include the frameworks that follow. Install the EOCore.jar and TealeafMod.jar Install EOcore.jar and TealeafMod.jar in to the libs folder of your Android application to make the capture functions available in your application. Add the files into the build path of the application you want to instrument. Integrate Tealeaf SDK files into your Android project Integrate the SDK files into your Android project by copying the following Tealeaf SDK files to the specified folder for your Android project. 12 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 2. SDK integration files File name Android project location TealeafBasicConfig.properties assets folder TealeafAdvancedConfig.json assets folder TealeafLayoutConfig.json assets folder EOCoreBasicConfig.properties assets folder EOCoreAdvancedConfig.json assets folder eocore.jar libs folder tealeafmod.jar libs folder Note: In Android Studio, you will need to add the following files to the build.gradle file. Use the following snippet as an example of how to add the files to build.gradle. dependencies { compile ’com.android.support:appcompat-v7:xx.x.x’ compile files(’libs/eocore.jar’) compile files(’libs/tealeafmod.jar’)} Replace xx.x.x with the version number of the Android library instance. Register the Tealeaf SDK in AndroidManifest.xml After you have integrated the Tealeaf SDK files with your Android project, use the following procedure to register the Tealeaf SDK files in AndroidManifest.xml. 1. Open AndroidManifest.xml in an editor. 2. Add the following permissions: <uses-permission <uses-permission <uses-permission <uses-permission android:name="android.permission.INTERNET" /> android:name="android.permission.ACCESS_NETWORK_STATE" /> android:name="android.permission.ACCESS_WIFI_STATE" /> android:name="android.permission.READ_PHONE_STATE"/> 3. If you want to enable geolocation data, add the following permission: <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> 4. If you want to enable debugging, add the following permission: <uses-permission android:name="android.permission.SET_DEBUG_APP" /> 5. Save and close AndroidManifest.xml. How log levels work A log level is given to each message that goes to the message queue. The value that is assigned to the log level determines importance of the logged message. The log level can be set from 0 to 3. Messages that are assigned a value of 0 are not logged. Messages that are assigned a value of 1 are logged as the most important message. Messages that are assigned a value of 3 are logged as the least important. Examples: v If a device is set to a log level of 2: – A message with 0 or 3 is not logged. – A message with 1 or 2 is logged. v If a device is set to a log level of 1: Chapter 1. Tealeaf installation and implementation in an Android application 13 – A message with 0 is not logged. – A message with 1 is logged. – A message with 2 or 3 is not logged. The log level in the library is based on the network connection that the device is using. v If the device configured for WIFI and cellular data, then WIFI will assign log level. v If the device is configured for WIFI only, then WIFI will assign log level. v If the device is configured for cellular only, then cellular will assign log level. v If the device is configured for no network, then: – If you use the kill switch, the library does not start at all because it cannot establish a connection to the KillSwitch URL. The KillSwitch URL is used to enable or disable the kill switch. – If the kill switch is not used, the default log level is used. Configure Tealeaf properties You must configure several items for your app for use with Tealeaf, including how screen layouts are logged, target-page location, kill-switch location, and whether to log gestures. EOCoreBasicConfig.properties and TealeafBasicConfig.properties are located in the Assets folder and contain configuration settings. To customize your configuration, you can use a text editor to modify the values for each property in EOCoreBasicConfig.properties and TealeafBasicConfig.properties. Note: The following table provides a list of Tealeaf properties that must be configured to work with your application: Table 3. Tealeaf properties that must be configured. Required Tealeaf property Description Whether to display logcat messages. This setting is enabled or disabled with the DisplayLogging property in EOCoreBasicConfig.properties. v To display logcat messages, set DisplayLogging=true. v To disable logcat messages, set DisplayLogging=false. The logcat messages are disabled by default. Set the logging level You can set the logging level based on where your project is in the development cycle. For example, you can set the level high for development and testing; then, lower the logging level for production. The logging level is set with the LoggingLevel property. The logging level can be set from 0 through 3, where: v 0 turns off logging. v 1 is the lowest logging level. LoggingLevel=1 is the default setting. v 3 is the highest logging level. 14 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 3. Tealeaf properties that must be configured. (continued) Required Tealeaf property Description 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 theKillSwitchEnabled property. The kill switch URL is set with the KillSwitchUrl property in TealeafBasicConfig.properties. v To enable the kill switch: 1. Set KillSwitchEnabled=true. 2. Set KillSwitchUrl=<URL> to the URL for the kill switch for your application. v To disable the kill switch, set KillSwitchEnabled=false. 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 in TealeafBasicConfig.properties. Set how screen layouts are logged Tealeaf can log screen images as Base64 or as MD5 checksum with PNG or JPG images. v To capture Base64 data, set GetImageDataOnScreenLayout=true in TealeafBasicConfig.properties. v To log MD5 checksum and PNG or JPG images, set GetImageDataOnScreenLayout=false in TealeafBasicConfig.properties. Note: Setting GetImageDataOnScreenLayout=false creates smaller payloads in production and is the recommended setting. 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. Chapter 1. Tealeaf installation and implementation in an Android application 15 All of the configuration in this task involves modifying settings in the EOCoreBasicConfig.properties and TealeafBasicConfig.properties file in the Assets folder of your project. 1. In your project, open the EOCoreBasicConfig.properties file. 2. Set the LoggingLevel to an appropriate level for development, testing, or production. 3. Open the TealeafBasicConfig.properties file. 4. Set the DisplayLogging to false for production and to true for development. 5. Set the PostMessageUrl to the URL of the target page for your app. 6. Set the KillSwitchEnabled to true. 7. Set the KillSwitchUrl to the URL for the kill switch for your app. 8. Set the GetImageDataOnScreenLayout to false for production and to true for development. 9. Set the LoggingLevel to an appropriate level for development, testing, or production. 10. Save and exit the both files. 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 manually change your files to integrate Tealeaf snippets into the library. If you install the Tealeaf SDK, you must extend the Application and Activity classes. When you install the Eclipse Tealeaf plug-in, you must extend only the Activity class. How you extend the classes depends on whether you have custom Application or Activity classes. Application class You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Tealeaf listens to these events: v onLowMemory - disable the library when you get a LowMemory warning v onCreate - initialize the library when the application starts v onTerminate - clean up the library when the application is terminated How you extend the Application class depends on whether you have a custom activity class for your application. If you: v Do not Tealeaf Tealeaf Tealeaf have a custom Application class for your application, use the IBM class UIApplication. You do this only if you are not using the Eclipse plug-in. The plug-in automatically extends the Application class with the UICApplication class. v Have a custom Activity class for your application, modify your custom Application class to point to the Tealeaf UICApplication class. Application class and the Eclipse Tealeaf plug-in After you install the Eclipse Tealeaf plug-in, if you decide to use a custom Application class in your application, you need to change the Application class automatically added by the plug-in: 1. Create the custom Application class. 2. Modify AndroidManifest.xml file for the application and change the application class name to the name of Application class you created. 16 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Activity class You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Tealeaf listens to these events: v onPause - what happens when the application goes to the background v onResume - what happens when the application goes to the foreground v onDestroy - what happens when the activity is no longer in memory and gets garbage collected How you extend the Activity class depends on whether you have a custom activity class for your application. If you: v Do not have a custom Activity class for your application, use the Tealeaf UIActivity class. v Have a custom Activity class for your application, modify your custom Activity class to point to the Tealeaf UICActivity class. Extending the Application class with the Tealeaf UICApplication class If you do not have a custom Application class, you can use the IBM Tealeaf UICApplication class to extend the Application class. The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onLowMemory to disable library if you get a warning, onTerminate to clean up library, and onCreate to initialize the library. 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.READ_PHONE_STATE" /> This example shows the lines that you add to the AdroidManifest.xml file: import com.tl.uic.Tealeaf; import com.tl.uic.app.UICApplication; public class MyApplication extends UICApplication { @Override public void onCreate() { super.onCreate(); Tealeaf.enable(); } } Chapter 1. Tealeaf installation and implementation in an Android application 17 Extending the Activity class with the Tealeaf UICActivity class The activity file manages the lifecycle of a page in a native Android application similar to what a page does in a web application. IBM Tealeaf listens to the following events onPause, which happen when application goes to the background, onResume, which happens when application goes to foreground, and onDestroy when activity is no longer in memory and gets garbage collected. On each activity files that you want to log, extend it using UICActivity. Using UICActivity extends the base Activity from the Android framework. UICActivity adds some functionality that is required by the IBM Tealeaf Logging Framework library to enable and disable asynchronous tasks, and to perform screen captures of the device after creation. To avoid capturing potentially private data, the Android SDK takes screen captures as soon as the image was rendered on the device. As a result, no user-defined fields are populated in any captured screen image. Android does not support capture of pop-up windows. For hybrid applications, screen captures might be missing or out of order due to timing issues. The method in this task enables automatic capture of screen captures from the client application. If you do not enable this item through UICActivity, you can manually capture screen captures through the Logging Framework. See "Reference" in the IBM Tealeaf Android SDK Guide. The value for the black background color can be replaced by any color constant to set the color of the background of your screen captures. 1. Open the existing Java file that extends from android.app.Activity class, and change it to extend from com.tl.uic.app.UICActivity instead of android.app.Activity. 2. 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(-16777216) //To set to black background of screenshot because the screen capture background is transparent. This example shows the lines that you add to the file that extends the Activity class: import com.tl.uic.app.UICActivity; public class LoginActivity extends UICActivity { @Override public void onCreate(Bundle savedInstanceState) { this.setTakeSnapshotAfterCreate(true); //To enable automatic screen shots setLogicalPageName("LoginPage") //Recommended to identify page setImageBackground(-16777216) //To set to back background of screenshot super.onCreate(savedInstanceState); 18 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Extending your custom Application class to point to the Tealeaf UICApplication class If you have a custom Application class in your application, point your custom class to the Tealeaf UICApplication class. The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onLowMemory to disable library if you get a warning, onTerminate to clean up library, and onCreate to initialize the library. . 1. Open the existing Java file that extends from the android.app.Application class. If this file does not exist, you must create it and have it listen to the complete lifecycle of an Android application to control library and log information needed. 2. Add this import: import com.tl.uic.Tealeaf; 3. In onCreate(): a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the IBM Tealeaf library with a reference to application instrumented. b. Add Tealeaf.enable(); that initializes capture of user actions in the application. 4. In onLowMemory(): 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.READ_PHONE_STATE" /> 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 { @Override public void onCreate() { super.onCreate(); Tealeaf tealeaf = new Tealeaf(this); Tealeaf.enable(); } @Override public void onLowMemory() { Tealeaf.onLowMemory(); super.onLowMemory(); } @Override public void onTerminate() { Tealeaf.disable(); super.onTerminate(); } } Chapter 1. Tealeaf installation and implementation in an Android application 19 Extending your custom Activity class to point to the Tealeaf UICActivity class If you have a custom Activity class, extend it to point to the Tealeaf UICActivity class. The activity file manages the lifecycle of a page in a native Android application similar to what a page does in a web application. IBM Tealeaf listens to the following events onPause, which happen when application goes to the background, onResume, which happens when application goes to foreground, and onDestroy when activity is no longer in memory and gets garbage collected. Each activity needs a logical page name that helps indicate what activity is being displayed. If no logical page name is given, IBM Tealeaf recommends using class name that gives some indication what activity is being displayed. 1. 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. * * @return Logical page name of the Activity. */ public final String getLogicalPageName() { if ((this.logicalPageName == null) || (this.logicalPageName.equals(""))) { this.logicalPageName = this.getClass().getName().substring(this.getClass(). getName().lastIndexOf(".") + 1); } return this.logicalPageName; } /** 20 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide * Logical page name of the Activity. * * @param logicalPageName * Logical page name of the Activity. */ public final void setLogicalPageName(final String logicalPageName) { this.logicalPageName = logicalPageName; } protected void onPause() { Tealeaf.onPause(this, getLogicalPageName()); super.onPause(); } protected void onResume() { Tealeaf.onResume(this, getLogicalPageName()); super.onResume(); } protected void onDestroy() { Tealeaf.onDestroy(this, getLogicalPageName()); super.onDestroy(); } } Enabling screen logging in fragments IBM Tealeaf cannot automatically identify when a fragment is rendered. If your application uses fragments, place the following code into each fragment to enable screen logging for the fragment. /** * {@inheritDoc} */ @Override public void onResume(){ super.onResume(); Tealeaf.onResumeFragment(getActivity(), "", this); } /** * {@inheritDoc} */ @Override public void onPause(){ super.onPause(); Tealeaf.onPauseFragment(getActivity(), "", this); } Implement Tealeaf After you install Tealeaf, you complete several tasks to implement Tealeaf functions in your application. These tasks involve modifying your application to capture controls, events, and screen views. Implementation tasks After you install the SDK, you must complete more tasks to implement the SDK. All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf plug-in for Tealeaf to work. All of these tasks are manual. This table lists and describes the tasks that you complete to implement Tealeaf in your application: Chapter 1. Tealeaf installation and implementation in an Android application 21 Task Description Log Screen Layout for Android Mobile App Replay Configure logging screen layout to use JSON data not screen captures. Includes configuring logical pages names, alert dialogs, and keyboard events. Tealeaf SDK ONLY 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. Integration for Apache Cordova, PhoneGap, and IBM Worklight® applications that use Android classes without IBM Tealeaf classes Implementing screenViews Implementing screenViews as segments for pages in which the state or context can be switched without rerendering the page. Target page configuration Set up the target page that acknowledges that events are captured. Data privacy Specify the fields that are blocked or masked during capture. Configuring sessionization for Android applications on the client Configure how session IDs are generated. Network traffic that is used in application contains requests only Tealeaf supports network traffic that is used in applications that contain requests only. Configure requests in Android application Configure Tealeaf to put session identifiers in cookies. Uses non-IBM Tealeaf session ID Configure your generated session IDs to be used when sessions are enabled or new sessions started. Hybrid application Configure your application to log request activity if you have a WebView in your application. Log screen layout for mobile app session replay IBM Tealeaf has functions to log screen layouts for screenviews of native mobile app sessions. You can replay a mobile app session in cxImpact Browser Based Replay as you would an HTML web session instead of viewing the mobile app session as a series of screen captures. The screen layouts of the native mobile app sessions are captured in IBM Tealeaf JSON format. The screen layouts are then sent back to replay server. The replay server uses a template engine, which interprets the JSON into HTML format. You can then replay the screen layout from the native mobile app session as HTML pages in cxImpact Browser Based Replay. There are several advantages to using JSON data to replay mobile app session over screen captures. v Reduce bandwidth. Screen captures for each screenview generate relatively large image data. It not only consumes large amounts of wireless and cellular bandwidth, but it also consumes more memory inside the device. It also impacts the app performance. v Mask sensitive information. You cannot mask sensitive information in a screen capture. When you use JSON data to replay mobile app sessions, you can mask EditTexts by adding View IDs to the MaskIdList attribute in TealeafBasicConfig.properties. 22 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide v Draw user interactions (UI events) onto the HTML pages that are created from the JSON data. For more information on mobile app session replay templates, see "Native app session replay customization" in the IBM Tealeaf CX Configuration Manual. TealeafBasicConfig.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. #Capture native layout LogViewLayoutOnScreenTransition=true During predeployment, you must perform all the replay cases to collect all the images with GetImageDataOnScreenLayout set to true. This creates a large payload sent to server that contains base64 images that are used for replay. When the application is ready to be deployed to Play Store, GetImageDataOnScreenLayout must be changed to false. #Current only done on ImageView GetImageDataOnScreenLayout=true Understand your activity In Android, an Activity can be considered a page, which is displayed on mobile device. By default, you should record an activity that is displayed. For more information, see http://developer.android.com/training/basics/activitylifecycle/starting.html. You can record an activity that is displayed, by placing the following information in the OnCreate method. // this will indicate logical page name. Tealeaf.logScreenview(activity, "Name", ScreenviewType.LOAD); // this will get layout of page after it being created. Tealeaf.logScreenLayoutOnCreate(activity, "Name"); If you need to log a layout, you can enable the AutoLayout controller in your application which gives that ability to log a screen layout without making additional changes to your application code. The IBM Tealeaf Android SDK can use the settings that are defined in TealeafLayoutConfig.json to log type 10 screen layouts for screenviews of native mobile application sessions. The AutoLayout controller also enables the application to automatically continue logging type 10 screen layouts when it resumes to the foreground. 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. TealeafLayoutConfig.json is in the assets folder and is formatted as a JSON file. Edit TealeafLayoutConfig.json to configure Autolayout to log screen layouts. Each AutoLayout entry has the following sub entries: Chapter 1. Tealeaf installation and implementation in an Android application 23 Table 4. AutoLayout sub entries. Sub entry Description do Boolean value Indicates if the screen should be logged or not. v true: Logs the screen. v false: Does not log the screen. Eaxmple: "do": true enables logging for the screen. screenViewName String value Used to provide a custom identifying name that is assigned to the logged screen in JSON. For example, the screenViewName for a login screen might be "LoginScreen". Example: screenViewName": "LoginScreen" sets the value of screenViewName to LoginScreen. delay Numeric value The amount of time, in milliseconds, that is used to delay the screen logging action. Increasing the value of this setting increases the amount of time that must pass between when the screen is loaded and when the screen logging action occurs. The delay value is used for do and takeScreenShot. Example: "delay": 500 sets the delay between screen load and screen logging to 500 milliseconds. takeScreenShot Boolean Indicates if a screen capture should be taken for the controller class. v true: Performs a screen capture. v false: Does not perform a screen capture. Example: "takeScreenShot": true turns on screen capturing for the screen activity. 24 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 4. AutoLayout sub entries. (continued) Sub entry Description AppendMapIds JSON Assigns an identifier to a target item. You can assign a readable identifier to the mid that maps to the target item. You can then configure events to fire when the identifier is encountered. You can use the same identifier for Android devices as well as iOS devices. When you assign the same identifier to your Android and iOS devices, you can create a single event in Event Manager that fires on the identifier. The event fires for both Android and iOS devices. Example: "AppendMapIds": { "[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": { "mid": "LoginButton" }, "ibm.com.demoapp.main_activity_login:id\/send": { "mid": "LoginButton" } Uses the mid setting to assign an identifier to two targets. The first target is for an iOS device and the second target is for an Android device. The target for both devices is identified as LoginButton. You can create a single event that fires when LoginButton is encountered in either application. The following snippet shows an example of the TealeafLayoutConfig.json file. { "AutoLayout": { "UICAndroidControlsAppActivity": { "do": false, "screenViewName": "UICAndroidControlsAppActivity", "delay": 1, "takeScreenShot": false }, "ControlsActivity1": { "do": true, "screenViewName": "CA1", "delay": 500, "takeScreenShot": false }, "ControlsActivity2": { "do": true, "screenViewName": "CA2", "delay": 1, "takeScreenShot": false }, "ControlsActivity3": { "do": true, "screenViewName": "CA3", "delay": 1, "takeScreenShot": false }, "ControlsActivity4": { "do": true, "screenViewName": "CA4", "delay": 1, "takeScreenShot": false }, "ControlsActivity5": { "do": true, Chapter 1. Tealeaf installation and implementation in an Android application 25 "screenViewName": "CA5", "delay": 1, "takeScreenShot": false }, "ControlsActivity6": { "do": true, "screenViewName": "CA6", "delay": 1, "takeScreenShot": false }, "ControlsActivity7": { "do": true, "screenViewName": "CA7", "delay": 1, "takeScreenShot": false }, "ControlsActivity8": { "do": true, "screenViewName": "CA8", "delay": 1, "takeScreenShot": false } }, "AppendMapIds": { "[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": { "mid": "LoginButton" }, "ibm.com.demoapp.main_activity_login:id\/send": { "mid": "LoginButton" } } } }, You can also manually configure a screen to log a layout by adding the following code snippet. Tealeaf.logScreenLayout(activity, "Name", delayInMS); Replaying AlertDialogs You need to know when an alert dialog is displayed so that it can be captured when the IBM Tealeaf API is called. The following examples show how to log the AlertDialog. The following example shows how to log the AlertDialog if you have defined a onShowListener: AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext); setCancelable(false); alertDialogBuilder.setNegativeButton("OK", new DialogInterface.OnClickListener() { @Override public void onClick(DialogInterface dialog, int which) { Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick"); dialog.dismiss(); Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10); } }); AlertDialog dialog = alertDialogBuilder.create(); dialog.setOnShowListener(new OnShowListener() { @Override public void onShow(DialogInterface dialog) { 26 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide // Tealeaf API to log AlertDialog’s layout final DialogLogScreenTask dialogLogScreenTask = new DialogLogScreenTask (getActivity().getParent(), "AlertDialog", (Dialog)dialog); dialogLogScreenTask.execute(); } }); The following example shows how to log the AlertDialog if you have not defined a onShowListener: AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext); setCancelable(false); alertDialogBuilder.setNegativeButton("Ok", new DialogInterface.OnClickListener() { @Override public void onClick(DialogInterface dialog, int which) { Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick"); dialog.dismiss(); Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10); } }); AlertDialog dialog = alertDialogBuilder.create(); // Tealeaf API hooks into the onShowListener and logs the AlertDialog’s layout Tealeaf.logScreenLayoutSetOnShowListener(activity.getParent(), dialog); dialog.show(); Additional sample projects are included with the distribution in the AndroidRelease/Tealeaf/SampleCode/EclipseProjects folder. Replaying keyboard events Android does not provide an event to understand when a soft keyboard appears and disappears. Follow this example to make the necessary adjustments to TextView based controls. public static void addFocusAndRegister(TextView textView, Activity activity) { textView.setOnFocusChangeListener(new OnFocusChangeListener() { @Override public void onFocusChange(View v, boolean hasFocus) { if (hasFocus) { InputMethodManager imm = (InputMethodManager) v.getContext() .getSystemService(Context.INPUT_METHOD_SERVICE); imm.showSoftInput(v, InputMethodManager.SHOW_FORCED); KeyboardView keyboardView = new KeyboardView(v.getContext() .getApplicationContext(), null); Tealeaf.logEvent(keyboardView , Tealeaf.TLF_UI_KEYBOARD_ DID_SHOW_NOTIFICATION); Tealeaf.logEvent(v, Tealeaf.TLF_ON_FOCUS_CHANGE_IN); } else { Tealeaf.logEvent(v, com.tl.uic.Tealeaf.TLF_ON_FOCUS_CHANGE_OUT); 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); } } }); Chapter 1. Tealeaf installation and implementation in an Android application 27 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 the 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. Control Description ToggleButton and Switch Uses switch template Note: At the time of this publication, Switch is not supported with replay when using an IBM Tealeaf on-premise Replay server. RadioGroup and RadioButton Uses RadioButton template Note: At the time of this publication, RadioButton is not supported with replay when using an IBM Tealeaf on-premise Replay server. 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 FrameLayout, LinearLayout, ViewStub, View Uses canvas template AbsListView Uses grid template AlertDialog Uses alert template TabWidget Uses tabBar template TabHost Uses tabContainer template Integrate Tealeaf and IBM MobileFirst Platform Foundation with Eclipse IBM MobileFirst™ Platform Foundation is IBM's MobileFirst Platform for developing both hybrid and native applications on multiple mobile platforms. IBM MobileFirst Platform Foundation provides an Eclipse plug-in called "IBM MobileFirst Platform Foundation Developer Studio" to help Developers create Mobile Apps more productively. For logging activities on your application, you might want to integrate the Tealeaf library with your MobileFirst "Hybrid" application. 28 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Use the following steps to integrate Tealeaf and IBM MobileFirst into an Eclipse development environment. 1. Install and setup Eclipse. 2. Install and setup your MobileFirst development environment with Eclipse. For more information on how to setup your development environment, see https://mobilefirstplatform.ibmcloud.com/tutorials/en/foundation/7.1/ setting-up-your-development-environment/setting-up-the-mobilefirstdevelopment-environment/. 3. In Eclipse, import your MobileFirst project into Eclipse. Right-click Project Explorer and select Import > Import > Existing Projects into Workspace; then, select your MobileFirst project. 4. Copy the Tealeaf defaultConfiguration.js file to the \apps\demoApp\common folder. Static assets are located in \apps\demoApp\common and are shared across all hybrid applications. Additionally, .css and image files are located in \apps\demoApp\common. 5. Add a reference to defaultConfiguration.js in your index.html file so that it loads when the application starts. 6. Copy the contents of \apps\demoApp\common to the Replay server. For most installations, copy the contents to the \Apps\App_name\App_version\www\default on the Replay server. The files are referenced during Replay. 7. Build the project for your preferred mobile platform. As part of the build process, MobileFirst generates a separate project. 8. Test the new application by running the MobileFirst project that was created in step 7. Note: In order for replay to work with your MobileFirst application, make sure that the contents of \apps\demoApp\common are copied to the Replay server. For most Tealeaf installations, copy the contents to the \Apps\App_name\App_version\ www\default on the Replay server. Complete the integration with Tealeaf by extending the Java classes. Extending the MobileFirst Java classes for Tealeaf: After your MobileFirst development environment is configured, you need to extend the Java classes for integration with Tealeaf. Use the following snippets to extend the Java classes for Tealeaf integration with MobileFirst. 1. Extend the org.apache.cordova.CordovaChromeClient class using the following snippet. public class MyChromeClient extends CordovaChromeClient { /** * Constructor. * * @param cordova */ public MyChromeClient(CordovaInterface cordova) { super(cordova); } /** * Constructor. * * @param ctx * @param app */ Chapter 1. Tealeaf installation and implementation in an Android application 29 public MyChromeClient(CordovaInterface ctx, CordovaWebView app) { super(ctx, app); } /** * {@inheritDoc} */ public final void onConsoleMessage(final String message, final int lineNumber, final String sourceID) { super.onConsoleMessage(message, lineNumber, sourceID); LogInternal.log("WebView: " + message + " -- From line " + lineNumber + " of" + sourceID); } } 2. Extend the Extendorg.apache.cordova.CordovaWebView class using the following snippet. public class MyWebView extends CordovaWebView { private PropertyName webViewId; private MyWebViewClient myWebViewClient; private MyChromeClient myChromeClient; /** * @param context */ public MyWebView(Context context) { super(context); init(); } /** * @param context * @param attrs */ public MyWebView(Context context, AttributeSet attrs) { super(context, attrs); init(); } /** * @param context * @param attrs * @param defStyle */ public MyWebView(Context context, AttributeSet attrs, int defStyle) { super(context, attrs, defStyle); init(); } /** * Get webview id. * * @return Webview id. */ public final PropertyName getWebViewId() { return webViewId; } /** * Set webview id. * * @param webviewId Webview id. */ public final void setWebViewId(final PropertyName webviewId) { this.webViewId = webviewId; } 30 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide /** * {@Override} */ public void loadUrl(final String url) { loadUrl(url, null); } /** * {@inheritDoc} */ public final void loadUrl(final String url, final Map<String, String> extraHeaders) { Tealeaf.setTLCookie(url); super.loadUrl(url, extraHeaders); } public MyWebViewClient getMyWebViewClient() { return myWebViewClient; } public MyChromeClient getMyChromeClient() { return myChromeClient; } /** * Initializes WebView. */ private void init() { CordovaInterface cordovaInterface = (CordovaInterface)this.getContext(); this.myWebViewClient = new MyWebViewClient(cordovaInterface, this); this.myChromeClient = new MyChromeClient(cordovaInterface, this); this.setWebViewClient(this.myWebViewClient); this.setWebChromeClient(this.myChromeClient); this.setWebViewId(Tealeaf.getPropertyName(this)); // This sets up the javascript bridge to communicate from web to native to collect data this.addJavascriptInterface(new JavaScriptInterface(this.getContext(), getWebViewId().getId()), "tlBridge"); } } 3. Extend the Extend org.apache.cordova.CordovaWebViewClient class using the following snippet. public class MyWebViewClient extends CordovaWebViewClient { public MyWebViewClient(CordovaInterface cordova, CordovaWebView view) { super(cordova, view); } /** * {@inheritDoc} */ @Override public void onPageFinished(final WebView view, final String url) { view.loadUrl("javascript:TLT.registerBridgeCallbacks([ " + "{enabled: true, cbType: ’screenCapture’, cbFunction: function() {tlBridge.screenCapture();}}," + " {enabled: true, cbType: ’messageRedirect’, cbFunction: function (data) {tlBridge.addMessage(data);}}]);"); } } 4. Integrate your WebView into your CordovaActivity with the following snippet. @Override public void onCreate(Bundle savedInstanceState){ super.onCreate(savedInstanceState); //Tealeaf Integration MyWebView myWebView = new MyWebView(this); Chapter 1. Tealeaf installation and implementation in an Android application 31 MyWebViewClient myWebViewClient = myWebView.getMyWebViewClient(); MyChromeClient myChromeClient = myWebView.getMyChromeClient(); super.init(myWebView, myWebViewClient, myChromeClient); WL.createInstance(this); WL.getInstance().showSplashScreen(this); WL.getInstance().initializeWebFramework(getApplicationContext(), this); } 5. Integrate the Tealeaf ScreenLayout API call into your CordovaActivity with the following snippet. /** * The IBM MobileFirst Platform calls this method after its initialization is complete and web resources are ready to be used. */ public void onInitWebFrameworkComplete(WLInitWebFrameworkResult result){ if (result.getStatusCode() == WLInitWebFrameworkResult.SUCCESS){ super.loadUrl(WL.getInstance().getMainHtmlFilePath()); //Tealeaf Integration Tealeaf.logScreenLayout(this, this.getClass().getName(), 30000); } else { handleWebFrameworkInitFailure(result); } } 6. Add the standard Tealeaf callbacks with the following snippet. //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(); } Implementing screenViews For pages in which the state or context can be switched without re-rendering the page, IBM Tealeaf segments the data between states by using a screenView object. For example, if a page contains multiple tabs, each of which represents a different stage in a checkout process, you instrument each tab in the page as a distinct screenView. To implement a screenView for a page, complete the following steps. 1. If you are extending from UICActivity, set a logicalPageName to indicate the use of the activity. Otherwise, logicalPageName is set to the name of the class of the activity. 2. If the prior step is not complete, call Tealeaf.logScreenview and pass the logicalPageName. You must also indicate if the page being loaded and unloaded is optional. For example: Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.LOAD); Tealeaf.logScreenview(activity, logicalPageName, ScreenviewType.UNLOAD); 32 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Basic configuration You must set up a target page on your web server. See “Quick start for server configuration” on page 89. Set the target page's address in the TealeafBasicConfig.properties configuration file under the key PostMessageUrl. See "Configuration File" in the IBM Tealeaf Android SDK Guide. Data privacy IBM Tealeaf provides mechanisms for masking or blocking sensitive customer information, such as credit card numbers, from being transmitted and captured by IBM Tealeaf. Through the Android SDK, you can specify the fields that need to be blocked or masked in your web application. When applied, data privacy ensures that these data elements are never transmitted to IBM Tealeaf. Note: Due to changes in how client framework data is submitted to IBM Tealeaf for capture, the best method for masking or blocking sensitive data is to apply the filtering through the capturing client framework. While other IBM Tealeaf features to manage data privacy can be deployed, they are not easy to implement on the new format of data captured from the client frameworks. IBM Tealeaf recommends using the methods referenced below. v See "Configuration File" in the IBM Tealeaf Android SDK Guide. v For more information about handling sensitive data in general, see "Managing Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual. Configuring sessionization for Android applications on the client The Android SDK auto-generates a session ID if one is not provided. This session ID is used to identify the session on the IBM Tealeaf server. IBM Tealeaf injects cookies to create session in the IBM Tealeaf system. Note: When an Android native or hybrid application is placed into background, the library flushes the collected data and sleeps, instead of disabling it. This happens unless the session expired due to the session timeout property. The timeout property is indicated with SessionTimeout in TealeafBasicConfig.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 Android SDK environment for IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer session ID or JSESSIONID. The following is a typical setting in TealeafBasicConfig.properties using customer session ID. #Sessionization settings on customer cookies CookieUrl = http://www.sample.com CookieDomain = .sample.com CookiePath = / Chapter 1. Tealeaf installation and implementation in an Android application 33 CookieParam = JSESSIONID CookieExpires = false SessionTimeout=30 SessoinTimeoutKillSwitch=false In this example, the cookie expires 30 minutes from current time. When the session timeout occurs, Android SDK retrieves the new cookie from your application server and posts the rest of request to application server using this new acquired cookie in request header. PCA groups all the used JSESSIONIDs into one single session even though the JSESSIONID was consistently changing. When using cookies generated from customer application server, SessoinTimeoutKillSwitch can be set to true or false. Setting the SessoinTimeoutKillSwitch to false means the session timeout user does not go to recheck on KillSwitchUrl to see if it is responding. Network traffic used in application contains requests only: Android SDK uses cookies to add values to the TLFConfigurableItems.properties file. Uses session ID generated by IBM Tealeaf Android SDK Android SDK uses cookies to add the following values in TLFConfigurableItems.properties. v CookieUrl is for url of site that is posted and getting cookie to sessionize on. v CookieParam is the parameter that has a session id. v CookiePath is the path of the cookie. v CookieDomain is the domain that the cookie belongs to. v CookieSecure is to add a secure cookie that can only be posted to an https url that has a valid certificate. v CookieExpiresFormat can have the date format of ASCTIME, RFC1036, or RFC1123, which will have an expiration date of current time + session timeout indicated in the variable below. v SessionTimeout is session timeout is in minutes. When this value expires a new session id is created. An example follows. #Sessionization settings CookieUrl=http://m.ibm.com CookieParam=TLTSID CookiePath=/ CookieDomain=.ibm.com #Whether you want to create a secure cookie which can only be sent using a https url in PostMessageUrl. CookieSecure=false #Valid date formats: ASCTIME, RFC1036, RFC1123 CookieExpiresFormat=ASCTIME #When post is sent, expiration of cookie will be current time + session timeout #Session timeout is in minutes 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. 34 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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 CX PCA to collect all the resources together in a single captured session. Add the following cookie into the GET and POST requests to enable the PCA to listen to requests and responses. httpClient.setRequestProperty("Cookie", Tealeaf.getTLCookie(Tealeaf.getCurrentSessionId())); Uses non IBM Tealeaf session ID You must get your generated session ID and use it when you enable or start a new session in Android SDK. // If enabling of Android Logging Framework use Tealeaf.enable(); Tealeaf.enable("your session id"); // If Android Logging Framework is enabled and a new session is to be created use Tealeaf.startSession(); Tealeaf.startSession("your session id"); Android application gestures You can capture gestures that the users make on your Android application. Several types of gestures are captured. Configuration For any Activity class that you want Gesture logging, you edit TealeafBasicConfig.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. Chapter 1. Tealeaf installation and implementation in an Android application 35 Table 5. Tap gestures. Gesture name Description Tap This gesture is a one-finger gesture. Image displayed in Replay For a tap gesture, one-finger taps and lifts from the screen in 1 location. Tap and Hold This gesture is a one-finger gesture. For a Tap and Hold gesture, one-finger presses and stays on the screen until information is displayed or an action occurs. Note: The response to a Tap and Hold gesture can vary from one application to another. For example, a Tap and Hold gesture might display an information bubble, magnify content under the finger, or present the user with a context menu. Double tap This gesture is a one-finger gesture. For a double tap gesture, one-finger taps twice in close succession in 1 location of the screen. Swipe gestures This table lists and describes the swipe gestures that are captured from web and mobile apps: Table 6. Swipe gestures Gesture name Description 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 36 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Image displayed in Replay Table 6. Swipe gestures (continued) Gesture name Description Swipe horizontally Image displayed in Replay 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 9.0.1 Release Notes for information about a known limitation for handling some iOS pinch gestures. Table 7. Resize gestures Gesture name Description Image displayed in Replay Pinch open 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, Note: Accompanying arrows indicate the direction (open or close) of the pinch 3. lift from the screen at a new location. Pinch close This gesture is a two-finger gesture. For a pinch close resize gesture, 2 fingers: 1. tap and hold in 1 location on the screen, 2. maintain contact with the screen while the fingers move toward each other, 3. lift from the screen at a new location. Note: Accompanying arrows indicate the direction (open or close) of the pinch Unresponsive gesture events captured Unresponsive gestures are gestures that do not respond when a user tries to select items in an application or tries to adjust views in the application. Like other gesture events, unresponsive gestures are captured by Tealeaf. Unresponsive gestures are displayed graphically in BBR as orange outlined icons accompanied by a circled "X" . The circled "X" denotes that the gesture was unresponsive. For example, if a double tap gesture did not yield a response in the mobile application, then at replay time that gesture is displayed with the following icon in BBR: Chapter 1. Tealeaf installation and implementation in an Android application 37 The following table lists the unresponsive gestures that are captured from web and mobile apps and shows the images that are displayed in BBR: Table 8. Unresponsive gestures and icons Unresponsive Gesture Image displayed in Replay Tap gestures Unresponsive tap Unresponsive double tap Unresponsive tap and hold Swipe gestures Swipe vertically Note: Accompanying arrows indicate the direction of the swipe. Swipe horizontally Note: Accompanying arrows indicate the direction of the swipe. 38 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 8. Unresponsive gestures and icons (continued) Unresponsive Gesture Image displayed in Replay Tap gestures Resize gestures Pinch open Note: Accompanying arrows indicate the direction of the pinch. Pinch close Note: Accompanying arrows indicate the direction 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... THEN... using a customized gesture view Override the dispatchTouchEvent publc boolean dispatchTouchEvent ( MotionEvent e) { Tealeaf.dispatchTouchEvent(this, e); return super.dispatchTouchEvent(e); } Chapter 1. Tealeaf installation and implementation in an Android application 39 IF your application is... THEN... not using a customized gesture view Override the onTouchEvent publc boolean onTouchEvent ( MotionEvent e) { Tealeaf.dispatchTouchEvent(this, e); return super.onTouchEvent(e); } This example shows the code snippets that are added in this task for an application that does not use a customized gesture view: mport com.tl.uic.Tealeaf; import com.tl.uic.app.UICActivity; import android.os.Bundle; import android.view.MotionEvent; public class MainActivity extends UICActivity{ @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); Tealeaf.logScreenLayout(this, this.getLogicalPageName(), 1000); } public boolean dispatchTouchEvent( MotionEvent e) { Tealeaf.dispatchTouchEvent(this,e); return super.dispatchTouchEvent(e); } } Modifying the TealeafBasicConfig.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 TealeafBasicConfig.properties file. 2. Set SetGestureDetector to true. 3. Save and exit the TealeafBasicConfig.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. 40 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Manually log exceptions In the Android SDK, you modify your catch block to report caught exceptions to the target server for processing. When you modify your catch block, you get the full stack trace and same device information that Tealeaf collects for fatal crashes. This table shows the method that is used to log exceptions and describes the parameters that are used in the method: Method Parameters public static Boolean logException(final Throwable exception, final HashMap<String, String> data, final Boolean unhandled) Where: v @param exception - the exception to be logged. v @param data - the value to be given to event. v @param unhandled - whether the exception is unhandled. v @return - whether exception was logged. Example In this example, you have a method that causes an exception: public void clientMethod1( ) { } You add an @try , @catch, and the Tealeaf.logException(e, data, false) method to handle the exception: public void clientMethod1( ) { try { int[] array = new int[1]; int i = array[2]; // Index out of bound exception } Catch (Exception e) { 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 exceptions. Add @try , @catch, and the Tealeaf.logException(e, data, false) method to handle the exception: public void clientMethod1( ) { try { int[] array = new int[1]; int i = array[2]; // Index out of bound exception Chapter 1. Tealeaf installation and implementation in an Android application 41 } Catch (Exception e) { HashMap<String, String> data = new HashMap<String, String>(); data.put("extraMessage", "custom value1"); Tealeaf.logException(e, data, false); } } Android application geolocation You can log geolocation information for the users of your applications. You can configure automatic geolocation logging when the application starts or you can use APIs to log geolocation information at specific places in your application. Replay and reporting of geolocation data is not available currently. Automatic logging You configure automatic logging with the TealeafBasicConfig.properties file and the manifest file. To give permission to the device to log geolocation data, add <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" > and <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> to the android manifest file. For example: <uses-permission <uses-permission <uses-permission <uses-permission <uses-permission <uses-permission android:name="android.permission.INTERNET" /> android:name="android.permission.ACCESS_NETWORK_STATE" /> android:name="android.permission.ACCESS_WIFI_STATE" /> android:name="android.permission.ACCESS_FINE_LOCATION" /> android:name="android.permission.ACCESS_COARSE_LOCATION"/> android:name="android.permission.READ_PHONE_STATE" /> There are three configurable items you can set in the TealeafBasicConfig.properties: Property Description LogLocationEnabled Use this property to enable geolocation logging. Values are: v True - logging is enabled v False - logging is not enabled LogLocationTries Use this property to set the number of times the device tries to get the geolocation information when the device's signal is weak. LogLocationTimeout Use this property to set the amount of time between retries for the device to get the geolocation information when the device's signal is weak. For example, when the device signal is weak you want the device to try 3 times to get the geolocation signal and for the device to wait 30 seconds between retries, you set the configurable items to these values: #Auto Geolocation logging enabled or not LogLocationEnabled=true LogLocationTries=3 LogLocationTimeout=30 42 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide APIs There are three APIs you can use to manually enable geolocation information logging in your application: v public static Boolean logGeolocation() - Use this API at a specific point in your application to log geolocation only at that point. v public static GeoLocation logGeolocation(final Boolean getGeolocation) Use this API at a specific point in your application to return a geolocation object that contains latitude, longitude, and accuracy values. v public static Boolean logGeolocation(final int logLevel) - Use this API at a specific point in your application to log geolocation information based on log level. Disable geolocation capture in the Web application Note: The UI Capture library typically tracks geolocation information within the Web application. When geolocation is enabled in a hybrid mobile application, the geolocation tracking feature in the Web application should be disabled and the application should use the native SDK capture the geolocation information. To disable geolocation capture in the Web application: 1. Locate the UI Capture library configuration. The configuration is typically at the end of the UI Capture SDK file as part of the call to the TLT.init() API. 2. Locate the geolocation configuration section in the replay module configuration object (modules.replay.geolocation). 3. If the geolocation configuration section does not exist, the feature is disabled automatically. If the section does exist, then ensure that the enabled setting is set to false. The following example shows the geolocation section for the UI Capture SDK with geolocation disabled. geolocation: { enabled: false, triggers: [ { event: "load" } ] }, Logging geolocation information in your application automatically: Before you begin this task you need to know: v The number of times you want the application to try to get the geolocation information when the signal is weak. v The amount of time, in seconds, that you want the application to wait before again trying to get the geolocation information. 1. In your application in Eclipse, open the TealeafBasicConfig.properties file. a. Set LogLocationEnabled to true. b. Set LogLocationTries to the number of times you want the application to try log the geolocation information. c. Set LogLocationTimeout to the number of seconds that the device should retry when the signal is weak. d. Save and exit the file. 2. In your application in Eclipse, open the AndroidManifest.xml file. Chapter 1. Tealeaf installation and implementation in an Android application 43 a. Add this line <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" > to the file. b. Save and exit the file. Hybrid applications An application is considered to be hybrid if it contains a WebView in the Android application. If you use a WebView, you must use UICWebView to log request activity in the WebView. UICWebView extends the base WebView from the Android Framework, which inserts the IBM Tealeaf header with the current session ID for sessionization. If you decide not to use UICWebView, then you need to extend a Webview to add sessionization. See "UICWebView Class" in the IBM Tealeaf Android SDK Guide. Extend android.webkit.WebView: This sample code shows how the base Android WebView is extended with UICWebView. /******************************************************************************* * Licensed Materials - Property of IBM * (C) Copyright IBM Corp. 2015 * US Government Users Restricted Rights - Use, duplication or disclosure * restricted by GSA ADP Schedule Contract with IBM Corp. ******************************************************************************/ package com.tl.uic.webkit; import java.util.Date; import java.util.Map; import org.apache.http.HttpResponse; import import import import import android.annotation.SuppressLint; android.app.Activity; android.content.Context; android.util.AttributeSet; android.webkit.WebView; import import import import com.tl.uic.TLFCache; com.tl.uic.Tealeaf; com.tl.uic.javascript.JavaScriptInterface; com.tl.uic.model.PropertyName; /** * @author ohernandezltmac */ public class UICWebView extends WebView { private Date endLoad; private Date startLoad; private String url; private HttpResponse httpResponse; private Date initTime; private long responseTime; private long connectionInitFromSession; private PropertyName webViewId; /** * @param context Android context. */ public UICWebView(final Context context) { super(context); init(); 44 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide } /** * @param context Android context. * @param attrs an AttributeSet passed to our parent. */ public UICWebView(final Context context, final AttributeSet attrs) { super(context, attrs); init(); } /** * @param context Android context. * @param attrs an AttributeSet passed to our parent. * @param 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. * * @return When page finished loading. */ public final Date getEndLoad() { return endLoad; } /** * When page finished loading. * * @param endLoad When page finished loading. */ public final void setEndLoad(final Date endLoad) { this.endLoad = endLoad; } /** * When page starts loading. * * @return When page starts loading. */ public final Date getStartLoad() { return startLoad; } /** * When page starts loading. * * @param startLoad When page starts loading. */ public final void setStartLoad(final Date startLoad) { this.startLoad = startLoad; } /** * HttpResponse from the connection. * * @return HttpResponse from the connection. */ public final HttpResponse getHttpResponse() { return httpResponse; } Chapter 1. Tealeaf installation and implementation in an Android application 45 /** * HttpResponse from the connection. * * @param httpResponse HttpResponse from the connection. */ public final void setHttpResponse(final HttpResponse httpResponse) { this.httpResponse = httpResponse; } /** * Initial time from the connection. * * @return Initial time from the connection. */ public final Date getInitTime() { return initTime; } /** * Initial time from the connection. * * @param initTime Initial time from the connection. */ public final void setInitTime(final Date initTime) { this.initTime = initTime; this.connectionInitFromSession = TLFCache.timestampFromSession(); } /** * Response time from the connection. * * @return Response time from the connection. */ public final long getResponseTime() { return responseTime; } /** * Response time from the connection. * * @param responseTime Response time from the connection. */ public final void setResponseTime(final long responseTime) { this.responseTime = responseTime; } /** * Get webview id. * * @return Webview id. */ public final PropertyName getWebViewId() { return webViewId; } /** * Set webview id. * * @param webviewId Webview id. */ public final void setWebViewId(final PropertyName webviewId) { this.webViewId = webviewId; } /** * {@inheritDoc} */ 46 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide @SuppressWarnings("PMD.NullAssignment") @Override public void loadData(final String data, final String mimeType, final String encoding) { this.url = null; this.initTime = null; this.connectionInitFromSession = 0; this.responseTime = 0; this.httpResponse = null; this.startLoad = new Date(); super.loadDataWithBaseURL(this.url, data, mimeType, encoding, ""); } /** * {@inheritDoc} */ @SuppressLint("NewApi") @Override public void loadUrl(final String url) { loadUrl(url, null); } /** * {@inheritDoc} */ public final void loadUrl(final String url, final Map<String, String> extraHeaders) { this.url = url; Tealeaf.setTLCookie(this.url); super.loadUrl(url, extraHeaders); } /** * Initializes WebView. */ private void init() { setStartLoad(new Date()); // Need it when in Eclipse editor mode if (!this.isInEditMode()) { this.setWebViewClient(new UICWebViewClient()); this.setWebChromeClient(new UICWebChromeClient((Activity) this.getContext())); this.setWebViewId(Tealeaf.getPropertyName(this)); this.addJavascriptInterface(new JavaScriptInterface(this.getContext(), getWebViewId().getId()), "tlBridge"); } } /** * Log the load time of the WebView. * * @return If log connection was added to queue. */ public final Boolean logConnection() { final long endTime = this.getEndLoad() != null ? this.getEndLoad().getTime() : 0; final long startTime = this.getStartLoad() != null ? this.getStartLoad().getTime() : 0; final long loadTime = endTime - startTime; return Tealeaf.logConnection(this.url, this.httpResponse, this.connectionInitFromSession, loadTime, this.responseTime); } } Chapter 1. Tealeaf installation and implementation in an Android application 47 Extend android.webkit.WebViewClient: The sample code that follows extends the base Android WebViewClient with UICWebViewClient. /******************************************************************************* * Licensed Materials - Property of IBM * (C) Copyright IBM Corp. 2015 * US Government Users Restricted Rights - Use, duplication or disclosure * restricted by GSA ADP Schedule Contract with IBM Corp. ******************************************************************************/ package com.tl.uic.webkit; import import import import android.annotation.SuppressLint; android.os.Build; android.webkit.WebView; android.webkit.WebViewClient; /** * @author ohernandezltmac * */ public class UICWebViewClient extends WebViewClient { /** * {@inheritDoc} */ @Override public boolean shouldOverrideUrlLoading(final WebView view, final String url) { view.loadUrl(url); return true; } /** * {@inheritDoc} */ @SuppressLint("NewApi") @Override public void onPageFinished(final WebView view, final String url) { // Get the call back mapping string to be evaluated/loaded as Javascript code final String javascriptString = com.tl.uic.javascript.JavaScriptInterface. hybridBridgeRegisterCallback(); if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) { view.evaluateJavascript(javascriptString, null); } else { view.loadUrl("javascript:" + javascriptString); } } } Sessionization for PhoneGap based Applications: Since there are no requests and responses being sent back to the server, IBM Tealeaf does not require extending of WebView to add sessionization. Configuring DOM Capture and Replay for native Android applications that cannot use PCA: You configure DOM capture for a native Android 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. 48 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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: { /** * NOTE: Enabling DOM Capture has significant implications on data * transmission and infrastructure. This feature should be enabled * judiciously. If enabled, it requires further configuration * to only perform the DOM Capture based on specific events and * elements. Refer to the documentation for more details. */ enabled: true, triggers: [ { event: "load" } ] } } Note: In UI Capture version 5.0.0 and later, DOM Diff is automatically enabled when DOM Capture is enabled. DOM diff is not supported with Hybrid Mobile replay. Complete the following steps to disable DOM Diff: a. In the UI Capture SDK configuration, locate the domCapture service configuration object in the services object. b. Set the diffEnabled flag to false. Example: domCapture: { diffEnabled: false, // DOM Capture options options: { maxLength: 1000000, captureFrames: true, removeScripts: true // If this threshold is exceeded, the snapshot will not be sent // Should child frames/iframes be captured // Should script tags be removed from the captured snapshot } } 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 49 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: 50 Method Example Enable Tealeaf Framework /** * Public API to enable Tealeaf framework. * @returns {void} */ enableTealeafFramework(); Disable Tealeaf Framework /** * Public API to disable Tealeaf framework. * @returns {void} */ disableTealeafFramework(); Log Screen Capture /** * Public API to add a screenshot capture. * @returns {void} */ logScreenCapture(); Start New Tealeaf Session /** * Public API to start a new Tealeaf session. * @returns {void} */ startNewTLFSession(); Current Session ID /** * Public API to start get current Tealeaf session Id. * @returns {String} Current session Id */ currentSessionId(); Default Value for Configurable Item /** * Public API to get default value of a configurable item in * TLFConfigurableItems.properties file. * @param {String} configItem This is the name of the configurable item. * @returns {String} The value for the item. */ defaultValueForConfigurableItem (configItem); IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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. * @param {String} configItem This is the name of the configurable item. * @returns {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. * @param {String} configItem This is the name of the configurable item. * @param {String} value The value assign to the configItem. * @returns {boolean} Wether item was set. */ setConfigurableItem(configItem, value); Add Additional HTTP Header /** * Public API to add additional http header. * @param {String} key This is the key of the configurable item. * @param {String} value The value assign to the configItem. * @returns {boolean} Wether item was set. */ addAdditionalHttpHeader(key, value); Log Custom Event Bridge /** * Public API to log custom event. * @param {String} eventName A custom event name. * @param {String} jsonData JSON data string. * @param {int} logLevel Tealeaf library logging level for the event. * @returns {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 51 Sample test HTML file that starts supported native methods in JavaScript This example is an HTML file that starts supported native methods in JavaScript: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head> <script type="text/javascript" src="js/tealeaf.js"></script> <script type="text/javascript" src="js/defaultconfiguration.js" ></script> <title>test APIs</title> <body> <h2>Test page for Android bridge APIs in hybrid app</h2> <h3>Click on below buttons to run tests:</h3> <input type="button" style="width: 150px; height: 30px; font-size: 20px" value="Screen Capture" onclick="TLT.logScreenCapture();return false;"/> <input type="button" style="width: 150px; height: 30px; font-size: 20px" value="Native APIs" onclick="runBridgeNativeTealeafAPIs();return false;"/> <p/> <p>Test native APIs output here: <div id="queueData"></div> </body> <script type="text/javascript"> function htmlConsoleLog(textData, apiRetVal){ var para = document.createElement("p"); var node; if( apiRetVal !== undefined && apiRetVal !== null ) { 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 ); 52 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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( htmlConsoleLog( htmlConsoleLog( htmlConsoleLog( ’----’----’----’----- Done Calling Tealeaf native APIs ---------------------------------------------------------------------------------------------- -----’ -----’ -----’ -----’ ); ); ); ); Chapter 1. Tealeaf installation and implementation in an Android application 53 } </script> </head> </html> Accessing native Android methods with JavaScript with Tealeaf customized WebView: When you create hybrid applications, you can access native Android methods with JavaScript, you use the Tealeaf customized WebView. Before you begin this task, you must: 1. Install the most recent Tealeaf Android SDK. 2. Implement the Android SDK following the instructions in the documentation. 3. Include the most recent UI Capture j2 JavaScript source file. 1. Add WebView to your application. Specify a length, height, weight, and ID that suits your application: <WebView android:id="@+id/my_webview" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="1" /> 2. In your activity, locate the WebView and load your HTML file: public class MainActivity extends ActionBarActivity { private UICWebView mUICWebView; private String logicalPageName = "BridgeAppActivity"; @Override protected void onCreate(Bundle savedInstanceState) { // Initialize tealeaf with a reference to application Tealeaf tealeaf = new Tealeaf(this.getApplication()); super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // Load HTML file from local resource in the UICWebview mUICWebView = (UICWebView) findViewById(R.id.uic_webview); // Modify the Url for your hybrid app mUICWebView.loadUrl("file:///android_asset/www/test.html"); WebSettings webSettings = mUICWebView.getSettings(); webSettings.setJavaScriptEnabled(true); } 3. Copy the application's HTML and JavaScript files to the /assets/www folder in your Android project. 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. 54 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Install process Note: The Android SDK is no longer supported with Eclipse. Android Studio should be used to integrate the Android SDK with your mobile application. The following references to integrating the Android SDK using Eclipse should only be used as a reference. To install and configure the Eclipse Tealeaf plug-in in your Eclipse project you: 1. Add the Eclipse Tealeaf plug-in to your project 2. Convert your project to an Android + Tealeaf project 3. Configure initial Eclipse Tealeaf plug-in properties 4. Extend Android classes with or without the extended IBM Tealeaf classes. Tealeaf package contents A single file contains the Android SDK and its software components. IBM Tealeaf Android SDK is delivered in the IBM Tealeaf Android SDK - 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 Tealeaf Mod: – eocore.jar: Android Core library JAR file used by module system. – tealeafmod.jar: Android library JAR file that contains the CX Mobile Android SDK. – EOCoreBasicConfig.properties: Configuration file. – TealeafBasicConfig.properties: Configuration file. – EOCoreAdvancedConfig.json: Configuration file. – TealeafAdvancedConfig.json: Configuration file. v SampleCode: Contains the following versions of a sample Android application. – DarkHoloAuto: An Android application with IBM Tealeaf CX Mobile Android SDK integrated and auto-instrumentation. – DarkHoloManual: An Android application with IBM Tealeaf CX Mobile Android SDK integrated which requires manual instrumentation. – HybridHTMLEmbedded: An Android application with IBM Tealeaf CX Mobile Android SDK integrated with a hybrid application. See "Sample Code" in the IBM Tealeaf Android SDK Guide. v AndroidEclipsePlugin: An Eclipse plug-in to assist with Tealeaf integration. Chapter 1. Tealeaf installation and implementation in an Android application 55 – tealeaf.plugin.android.site-1.0.0-SNAPSHOT.zip: The plug-in archive to be added to your Eclipse IDE. – tealeafandroidsdk.jar: Android library JAR file that contains pre-instrumented Tealeaf widgets. v TealeafTargetSimulator – target_sim.js: Image extractor from posts in real time. v AndroidImageCaptureTool – Rakefile.rb: Image extractor and tagger for replay. v TeaCuts – teacuts.jar: Automation library. – TeaCutsBasicConfig.properties: Configuration file that stores basic configuration settings to assist with auto instrumentation. – TeaCutsAdvancedConfig.json: Configuration file that stores advanced library settings to assist with auto instrumentation. 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 Android 4.1 or later. Consult the Google Android Dev Center for the latest Android technical documentation and tools. IBM Tealeaf client frameworks do not support forwarding of application data to third-party systems. Application data must be forwarded to the server that hosts the native application. Supported operating systems Tealeaf supports these versions of the Windows, Mac, and Linux operating systems: v Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit) v Mac OS X 10.5.8 or later (x86 only) v Linux (tested on Ubuntu Linux, Lucid Lynx) – GNU C Library (glibc) 2.7 or later is required. – 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. Android Studio Tealeaf supports the latest version of Android Studio. Android Framework API Tealeaf requires Android Framework API level 23 or higher. 56 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Tealeaf impact on Android device resources In benchmark tests, the Android SDK has the following effects on resources of the visitor's device. v 2-3% more memory consumption Note: If the Tealeaf server is unreachable, the SDK saves Tealeaf data to memory until the Tealeaf server is reachable. By default the SDK will store up to 512000 bytes to the device memory. If the cache grows larger than 512000 bytes, the oldest data is truncated from cache and is deleted. The cache size is managed through the CachedFileMaxBytesSize setting in EOCoreAdvancedConfig.json. v Minimal effect on battery life Add Eclipse Tealeaf plug-in to your Eclipse Android project After you acquire IBM Tealeaf Android SDK, install the Android SDK libraries into an Android application project. Your Eclipse project must include the recommended Android SDK frameworks. 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 Description AutoCompleteTextView An editable text view that shows completion suggestions automatically while the user is typing. Button Represents a push-button widget. CheckBox A two-states button that can be either checked or unchecked. DatePicker A widget for selecting a date by selecting a year, month, and day. EditText A thin veneer over TextView that configures itself to be editable. ExpandableListView A view that shows items in a vertically scrolling two-level list. HorizontalScrollView Layout container for a view hierarchy that can be scrolled by the user, allowing it to be larger than the physical display. ImageButton Displays a button with an image (instead of text) that can be pressed or clicked by the user. ImageView Displays an arbitrary image, such as an icon. LinearLayout A Layout that arranges its children in a single column or a single row. ListView A view that shows items in a vertically scrolling list. Chapter 1. Tealeaf installation and implementation in an Android application 57 Widget Description MultiAutoCompleteTextView 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. RadioButton A radio button is a two-states button that can be either checked or unchecked. RadioGroup 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. RatingBar An extension of SeekBar and ProgressBar that shows a rating in stars. RelativeLayout A Layout where the positions of the children can be described in relation to each other or to the parent. ScrollView Layout container for a view hierarchy that can be scrolled by the user, allowing it to be larger than the physical display. SeekBar An extension of ProgressBar that adds a draggable thumb. Spinner A view that displays one child at a time and lets the user pick among them. Switch A two-state toggle switch widget that can select between two options. TextView Displays text to the user and optionally allows them to edit it. TimePicker A view for selecting the time of day, in either 24 hour or AM/PM mode. ToggleButton Displays checked/unchecked states as a button with a "light" indicator and by default is accompanied with the text "ON" or "OFF". Adding the Eclipse Tealeaf plug-in to your project You install the Eclipse Tealeaf plug-in JAR file in your Eclipse project to use Tealeaf with your project. Before you begin, you must install: v Eclipse v Java v Android Development Toolkit You must also have the location of the Eclipse Tealeaf plug-in installation files. At the end of this task you are asked to restart Eclipse. Do this task when restarting Eclipse will not impact your work. 1. Extract the TLFLibRelease.zip file. The Tealeaf folder is extracted. The Tealeaf folder contains all necessary files for the Android SDK and the plug-in. 58 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 2. Open your project in Eclipse. 3. From the Help menu, select Install New Software... 4. In the Install window, select Add.... 5. In the Add window define the repository for the Eclipse Tealeaf plug-in files: a. Enter a name for the Tealeaf and plug-in repository that you are creating. b. Enter the location of the files. If the files are on your local machine, select Local... and navigate to the files. If the files are in a compressed file or JAR file on your local machine, select Archive... and navigate to the files. If the files are on a website, enter the URL for the website in the Location: field. c. Click OK. 6. In the Install window, select the files to install and click Next. 7. Accept the license agreement. 8. Click Finish to complete the installation. 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 must configure several items for your app for use with Tealeaf, including how screen layouts are logged, target-page location, kill-switch location, and whether to log gestures. EOCoreBasicConfig.properties and TealeafBasicConfig.properties are located in the Assets folder and contain configuration settings. To customize your configuration, you can use a text editor to modify the values for each property in EOCoreBasicConfig.properties and TealeafBasicConfig.properties. Note: The following table provides a list of Tealeaf properties that must be configured to work with your application: Chapter 1. Tealeaf installation and implementation in an Android application 59 Table 9. Tealeaf properties that must be configured. Required Tealeaf property Description Whether to display logcat messages. This setting is enabled or disabled with the DisplayLogging property in EOCoreBasicConfig.properties. v To display logcat messages, set DisplayLogging=true. v To disable logcat messages, set DisplayLogging=false. The logcat messages are disabled by default. Set the logging level You can set the logging level based on where your project is in the development cycle. For example, you can set the level high for development and testing; then, lower the logging level for production. The logging level is set with the LoggingLevel property. The logging level can be set from 0 through 3, where: v 0 turns off logging. v 1 is the lowest logging level. LoggingLevel=1 is the default setting. v 3 is the highest logging level. 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 theKillSwitchEnabled property. The kill switch URL is set with the KillSwitchUrl property in TealeafBasicConfig.properties. v To enable the kill switch: 1. Set KillSwitchEnabled=true. 2. Set KillSwitchUrl=<URL> to the URL for the kill switch for your application. v To disable the kill switch, set KillSwitchEnabled=false. Set target URL 60 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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 in TealeafBasicConfig.properties. Table 9. Tealeaf properties that must be configured. (continued) Required Tealeaf property Description Set how screen layouts are logged Tealeaf can log screen images as Base64 or as MD5 checksum with PNG or JPG images. v To capture Base64 data, set GetImageDataOnScreenLayout=true in TealeafBasicConfig.properties. v To log MD5 checksum and PNG or JPG images, set GetImageDataOnScreenLayout=false in TealeafBasicConfig.properties. Note: Setting GetImageDataOnScreenLayout=false creates smaller payloads in production and is the recommended setting. 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 EOCoreBasicConfig.properties and TealeafBasicConfig.properties file in the Assets folder of your project. 1. In your project, open the EOCoreBasicConfig.properties file. 2. Set the LoggingLevel to an appropriate level for development, testing, or production. 3. Open the TealeafBasicConfig.properties file. 4. Set the DisplayLogging to false for production and to true for development. 5. Set the PostMessageUrl to the URL of the target page for your app. 6. Set the KillSwitchEnabled to true. 7. Set the KillSwitchUrl to the URL for the kill switch for your app. 8. Set the GetImageDataOnScreenLayout to false for production and to true for development. 9. Set the LoggingLevel to an appropriate level for development, testing, or production. 10. Save and exit the both files. How to dynamically update configuration values You can manually update configuration values by editing EOCoreBasicConfig.properties and TealeafBasicConfig.properties, or you can dynamically update the configuration values through an API. Use the following API call structure to update a configuration value: EOCore.updateConfig(final String key, final String value, final EOLifecycleObjectName module) Examples: Chapter 1. Tealeaf installation and implementation in an Android application 61 The following API call can be used to update a configuration value that is stored in EOCoreBasicConfig.properties: EOCore.updateConfig(“key”, “value”, EOCore.getInstance()) Where key is the configuration property that you want to update and value is the value that you want to assigned to the configuration property. The following API call can be used to update a Tealeaf configuration value that is stored in TealeafBasicConfig.properties: EOCore.updateConfig(“key”, “value”, TealeafEOLifecycleObject.getInstance()) Where key is the configuration property that you want to update and value is the value that you want to assigned to the configuration property. 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 manually change your files to integrate Tealeaf snippets into the library. If you install the Tealeaf SDK, you must extend the Application and Activity classes. When you install the Eclipse Tealeaf plug-in, you must extend only the Activity class. How you extend the classes depends on whether you have custom Application or Activity classes. Application class You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Tealeaf listens to these events: v onLowMemory - disable the library when you get a LowMemory warning v onCreate - initialize the library when the application starts v onTerminate - clean up the library when the application is terminated How you extend the Application class depends on whether you have a custom activity class for your application. If you: v Do not have a custom Application class for your application, use the IBM Tealeaf class UIApplication. You do this only if you are not using the Eclipse Tealeaf plug-in. The plug-in automatically extends the Application class with the Tealeaf UICApplication class. v Have a custom Activity class for your application, modify your custom Application class to point to the Tealeaf UICApplication class. Application class and the Eclipse Tealeaf plug-in After you install the Eclipse Tealeaf plug-in, if you decide to use a custom Application class in your application, you need to change the Application class automatically added by the plug-in: 1. Create the custom Application class. 2. Modify AndroidManifest.xml file for the application and change the application class name to the name of Application class you created. Activity class You extend the Activity class to automatically capture points the lifecycle of a native Android application page. Tealeaf listens to these events: 62 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide v onPause - what happens when the application goes to the background v onResume - what happens when the application goes to the foreground v onDestroy - what happens when the activity is no longer in memory and gets garbage collected How you extend the Activity class depends on whether you have a custom activity class for your application. If you: v Do not have a custom Activity class for your application, use the Tealeaf UIActivity class. v Have a custom Activity class for your application, modify your custom Activity class to point to the Tealeaf UICActivity class. Extending the Application class with the Tealeaf UICApplication class If you do not have a custom Application class, you can use the IBM Tealeaf UICApplication class to extend the Application class. The application file manages the lifecycle of an Android application. IBM Tealeaf manages the library by listening to onLowMemory to disable library if you get a warning, onTerminate to clean up library, and onCreate to initialize the library. 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.READ_PHONE_STATE" /> This example shows the lines that you add to the AdroidManifest.xml file: import com.tl.uic.Tealeaf; import com.tl.uic.app.UICApplication; public class MyApplication extends UICApplication { @Override public void onCreate() { super.onCreate(); Tealeaf.enable(); } } Extending the Activity class with the Tealeaf UICActivity class The activity file manages the lifecycle of a page in a native Android application similar to what a page does in a web application. IBM Tealeaf listens to the following events onPause, which happen when application goes to the background, Chapter 1. Tealeaf installation and implementation in an Android application 63 onResume, which happens when application goes to foreground, and onDestroy when activity is no longer in memory and gets garbage collected. On each activity files that you want to log, extend it using UICActivity. Using UICActivity extends the base Activity from the Android framework. UICActivity adds some functionality that is required by the IBM Tealeaf Logging Framework library to enable and disable asynchronous tasks, and to perform screen captures of the device after creation. To avoid capturing potentially private data, the Android SDK takes screen captures as soon as the image was rendered on the device. As a result, no user-defined fields are populated in any captured screen image. Android does not support capture of pop-up windows. For hybrid applications, screen captures might be missing or out of order due to timing issues. The method in this task enables automatic capture of screen captures from the client application. If you do not enable this item through UICActivity, you can manually capture screen captures through the Logging Framework. See "Reference" in the IBM Tealeaf Android SDK Guide. The value for the black background color can be replaced by any color constant to set the color of the background of your screen captures. 1. Open the existing Java file that extends from android.app.Activity class, and change it to extend from com.tl.uic.app.UICActivity instead of android.app.Activity. 2. 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(-16777216) //To set to black background of screenshot because the screen capture background is transparent. This example shows the lines that you add to the file that extends the Activity class: import com.tl.uic.app.UICActivity; public class LoginActivity extends UICActivity { @Override public void onCreate(Bundle savedInstanceState) { this.setTakeSnapshotAfterCreate(true); //To enable automatic screen shots setLogicalPageName("LoginPage") //Recommended to identify page setImageBackground(-16777216) //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 64 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide onLowMemory to disable library if you get a warning, onTerminate to clean up library, and onCreate to initialize the library. . 1. Open the existing Java file that extends from the android.app.Application class. If this file does not exist, you must create it and have it listen to the complete lifecycle of an Android application to control library and log information needed. 2. Add this import: import com.tl.uic.Tealeaf; 3. In onCreate(): a. Add Tealeaf tealeaf = new Tealeaf(this);, which initializes the IBM Tealeaf library with a reference to application instrumented. b. Add Tealeaf.enable(); that initializes capture of user actions in the application. 4. In onLowMemory(): 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.READ_PHONE_STATE" /> 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 { @Override public void onCreate() { super.onCreate(); Tealeaf tealeaf = new Tealeaf(this); Tealeaf.enable(); } @Override public void onLowMemory() { Tealeaf.onLowMemory(); super.onLowMemory(); } @Override public void onTerminate() { Tealeaf.disable(); super.onTerminate(); } } Extending your custom Activity class to point to the Tealeaf UICActivity class If you have a custom Activity class, extend it to point to the Tealeaf UICActivity class. The activity file manages the lifecycle of a page in a native Android Chapter 1. Tealeaf installation and implementation in an Android application 65 application similar to what a page does in a web application. IBM Tealeaf listens to the following events onPause, which happen when application goes to the background, onResume, which happens when application goes to foreground, and onDestroy when activity is no longer in memory and gets garbage collected. Each activity needs a logical page name that helps indicate what activity is being displayed. If no logical page name is given, IBM Tealeaf recommends using class name that gives some indication what activity is being displayed. 1. 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. * * @return Logical page name of the Activity. */ public final String getLogicalPageName() { if ((this.logicalPageName == null) || (this.logicalPageName.equals(""))) { this.logicalPageName = this.getClass().getName().substring(this.getClass(). getName().lastIndexOf(".") + 1); } return this.logicalPageName; } /** * Logical page name of the Activity. * * @param logicalPageName * Logical page name of the Activity. */ 66 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide public final void setLogicalPageName(final String logicalPageName) { this.logicalPageName = logicalPageName; } protected void onPause() { Tealeaf.onPause(this, getLogicalPageName()); super.onPause(); } protected void onResume() { Tealeaf.onResume(this, getLogicalPageName()); super.onResume(); } protected void onDestroy() { Tealeaf.onDestroy(this, getLogicalPageName()); super.onDestroy(); } } Implement Tealeaf After you install Tealeaf, you complete several tasks to implement Tealeaf functions in your application. These tasks involve modifying your application to capture controls, events, and screen views. Implementation tasks After you install the SDK, you must complete more tasks to implement the SDK. All of these tasks must be done for both the Tealeaf SDK and Eclipse Tealeaf plug-in for Tealeaf to work. All of these tasks are manual. This table lists and describes the tasks that you complete to implement Tealeaf in your application: Task Description Log Screen Layout for Android Mobile App Replay Configure logging screen layout to use JSON data not screen captures. Includes configuring logical pages names, alert dialogs, and keyboard events. Tealeaf SDK ONLY 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. Integration for Apache Cordova, PhoneGap, and IBM Worklight applications that use Android classes without IBM Tealeaf classes Implementing screenViews Implementing screenViews as segments for pages in which the state or context can be switched without rerendering the page. Target page configuration Set up the target page that acknowledges that events are captured. Data privacy Specify the fields that are blocked or masked during capture. Configuring sessionization for Android applications on the client Configure how session IDs are generated. Network traffic that is used in application contains requests only Tealeaf supports network traffic that is used in applications that contain requests only. Chapter 1. Tealeaf installation and implementation in an Android application 67 Task Description Configure requests in Android application Configure Tealeaf to put session identifiers in cookies. Uses non-IBM Tealeaf session ID Configure your generated session IDs to be used when sessions are enabled or new sessions started. Hybrid application Configure your application to log request activity if you have a WebView in your application. Log screen layout for mobile app session replay IBM Tealeaf has functions to log screen layouts for screenviews of native mobile app sessions. You can replay a mobile app session in cxImpact Browser Based Replay as you would an HTML web session instead of viewing the mobile app session as a series of screen captures. The screen layouts of the native mobile app sessions are captured in IBM Tealeaf JSON format. The screen layouts are then sent back to replay server. The replay server uses a template engine, which interprets the JSON into HTML format. You can then replay the screen layout from the native mobile app session as HTML pages in cxImpact Browser Based Replay. There are several advantages to using JSON data to replay mobile app session over screen captures. v Reduce bandwidth. Screen captures for each screenview generate relatively large image data. It not only consumes large amounts of wireless and cellular bandwidth, but it also consumes more memory inside the device. It also impacts the app performance. v Mask sensitive information. You cannot mask sensitive information in a screen capture. When you use JSON data to replay mobile app sessions, you can mask EditTexts by adding View IDs to the MaskIdList attribute in TealeafBasicConfig.properties. v Draw user interactions (UI events) onto the HTML pages that are created from the JSON data. For more information on mobile app session replay templates, see "Native app session replay customization" in the IBM Tealeaf CX Configuration Manual. TealeafBasicConfig.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. #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 68 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Understand your activity In Android, an Activity can be considered a page, which is displayed on mobile device. By default, you should record an activity that is displayed. For more information, see http://developer.android.com/training/basics/activitylifecycle/starting.html. You can record an activity that is displayed, by placing the following information in the OnCreate method. // this will indicate logical page name. Tealeaf.logScreenview(activity, "Name", ScreenviewType.LOAD); // this will get layout of page after it being created. Tealeaf.logScreenLayoutOnCreate(activity, "Name"); If you need to log a layout, you can enable the AutoLayout controller in your application which gives that ability to log a screen layout without making additional changes to your application code. The IBM Tealeaf Android SDK can use the settings that are defined in TealeafLayoutConfig.json to log type 10 screen layouts for screenviews of native mobile application sessions. The AutoLayout controller also enables the application to automatically continue logging type 10 screen layouts when it resumes to the foreground. 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. TealeafLayoutConfig.json is in the assets folder and is formatted as a JSON file. Edit TealeafLayoutConfig.json to configure Autolayout to log screen layouts. Each AutoLayout entry has the following sub entries: Table 10. AutoLayout sub entries. Sub entry Description do Boolean value Indicates if the screen should be logged or not. v true: Logs the screen. v false: Does not log the screen. Eaxmple: "do": true enables logging for the screen. screenViewName String value Used to provide a custom identifying name that is assigned to the logged screen in JSON. For example, the screenViewName for a login screen might be "LoginScreen". Example: screenViewName": "LoginScreen" sets the value of screenViewName to LoginScreen. Chapter 1. Tealeaf installation and implementation in an Android application 69 Table 10. AutoLayout sub entries. (continued) Sub entry Description delay Numeric value The amount of time, in milliseconds, that is used to delay the screen logging action. Increasing the value of this setting increases the amount of time that must pass between when the screen is loaded and when the screen logging action occurs. The delay value is used for do and takeScreenShot. Example: "delay": 500 sets the delay between screen load and screen logging to 500 milliseconds. takeScreenShot Boolean Indicates if a screen capture should be taken for the controller class. v true: Performs a screen capture. v false: Does not perform a screen capture. Example: "takeScreenShot": true turns on screen capturing for the screen activity. AppendMapIds JSON Assigns an identifier to a target item. You can assign a readable identifier to the mid that maps to the target item. You can then configure events to fire when the identifier is encountered. You can use the same identifier for Android devices as well as iOS devices. When you assign the same identifier to your Android and iOS devices, you can create a single event in Event Manager that fires on the identifier. The event fires for both Android and iOS devices. Example: "AppendMapIds": { "[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": { "mid": "LoginButton" }, "ibm.com.demoapp.main_activity_login:id\/send": { "mid": "LoginButton" } Uses the mid setting to assign an identifier to two targets. The first target is for an iOS device and the second target is for an Android device. The target for both devices is identified as LoginButton. You can create a single event that fires when LoginButton is encountered in either application. The following snippet shows an example of the TealeafLayoutConfig.json file. { "AutoLayout": { "UICAndroidControlsAppActivity": { "do": false, "screenViewName": "UICAndroidControlsAppActivity", "delay": 1, "takeScreenShot": false }, "ControlsActivity1": { "do": true, "screenViewName": "CA1", "delay": 500, "takeScreenShot": false 70 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide }, "ControlsActivity2": { "do": true, "screenViewName": "CA2", "delay": 1, "takeScreenShot": false }, "ControlsActivity3": { "do": true, "screenViewName": "CA3", "delay": 1, "takeScreenShot": false }, "ControlsActivity4": { "do": true, "screenViewName": "CA4", "delay": 1, "takeScreenShot": false }, "ControlsActivity5": { "do": true, "screenViewName": "CA5", "delay": 1, "takeScreenShot": false }, "ControlsActivity6": { "do": true, "screenViewName": "CA6", "delay": 1, "takeScreenShot": false }, "ControlsActivity7": { "do": true, "screenViewName": "CA7", "delay": 1, "takeScreenShot": false }, "ControlsActivity8": { "do": true, "screenViewName": "CA8", "delay": 1, "takeScreenShot": false } }, "AppendMapIds": { "[PWDV,0][ABOL,0][FL,0][TH,0][LL,0][TW,0][LL,1][LL,0]": { "mid": "LoginButton" }, "ibm.com.demoapp.main_activity_login:id\/send": { "mid": "LoginButton" } } } }, You can also manually configure a screen to log a layout by adding the following code snippet. Tealeaf.logScreenLayout(activity, "Name", delayInMS); Replaying AlertDialogs You need to know when an alert dialog is displayed so that it can be captured when the IBM Tealeaf API is called. The following examples show how to log the AlertDialog. Chapter 1. Tealeaf installation and implementation in an Android application 71 The following example shows how to log the AlertDialog if you have defined a onShowListener: AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext); setCancelable(false); alertDialogBuilder.setNegativeButton("OK", new DialogInterface.OnClickListener() { @Override public void onClick(DialogInterface dialog, int which) { Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick"); dialog.dismiss(); Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10); } }); AlertDialog dialog = alertDialogBuilder.create(); dialog.setOnShowListener(new OnShowListener() { @Override public void onShow(DialogInterface dialog) { // Tealeaf API to log AlertDialog’s layout final DialogLogScreenTask dialogLogScreenTask = new DialogLogScreenTask (getActivity().getParent(), "AlertDialog", (Dialog)dialog); dialogLogScreenTask.execute(); } }); The following example shows how to log the AlertDialog if you have not defined a onShowListener: AlertDialog.Builder alertDialogBuilder = new AlertDialog.Builder(mContext); setCancelable(false); alertDialogBuilder.setNegativeButton("Ok", new DialogInterface.OnClickListener() { @Override public void onClick(DialogInterface dialog, int which) { Tealeaf.logDialogEvent(dialog, which, "DialogButtonClick"); dialog.dismiss(); Tealeaf.logScreenLayout(activity.getParent(), "pageName", 10); } }); AlertDialog dialog = alertDialogBuilder.create(); // Tealeaf API hooks into the onShowListener and logs the AlertDialog’s layout Tealeaf.logScreenLayoutSetOnShowListener(activity.getParent(), dialog); dialog.show(); Additional sample projects are included with the distribution in the AndroidRelease/Tealeaf/SampleCode/EclipseProjects folder. Replaying keyboard events Android does not provide an event to understand when a soft keyboard appears and disappears. Follow this example to make the necessary adjustments to TextView based controls. public static void addFocusAndRegister(TextView textView, Activity activity) { textView.setOnFocusChangeListener(new OnFocusChangeListener() { @Override public void onFocusChange(View v, boolean hasFocus) { if (hasFocus) { InputMethodManager imm = (InputMethodManager) v.getContext() .getSystemService(Context.INPUT_METHOD_SERVICE); imm.showSoftInput(v, InputMethodManager.SHOW_FORCED); 72 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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 the 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. Control Description ToggleButton and Switch Uses switch template Note: At the time of this publication, Switch is not supported with replay when using an IBM Tealeaf on-premise Replay server. RadioGroup and RadioButton Uses RadioButton template Note: At the time of this publication, RadioButton is not supported with replay when using an IBM Tealeaf on-premise Replay server. 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 FrameLayout, LinearLayout, ViewStub, View Uses canvas template AbsListView Uses grid template AlertDialog Uses alert template Chapter 1. Tealeaf installation and implementation in an Android application 73 Control Description 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; public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); Tealeaf tealeaf = new Tealeaf(this); Tealeaf.enable(); } 74 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide @Override public void onLowMemory() { Tealeaf.onLowMemory(); super.onLowMemory(); } @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" > 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); 6. In onDestroy() method: a. Add Tealeaf.onDestroy(this, logicalPageName); 7. In onCreate(), add after super.onCreate( a. Tealeaf.logScreenview(this, logicalPageName, ScreenviewType.LOAD); Chapter 1. Tealeaf installation and implementation in an Android application 75 b. appView.addJavascriptInterface(new JavaScriptInterface(this.getContext(), Tealeaf.getPropertyName(webviewObject).getId()), "tlBridge"); Example from IBM Worklight package com.TLWorklightTealeaf; import android.os.Bundle; import import import import com.tl.uic.Tealeaf; com.tl.uic.javascript.JavaScriptInterface; com.tl.uic.model.ScreenviewType; com.worklight.androidgap.WLDroidGap; public class TLWorklightTealeaf extends WLDroidGap { private String logicalPageName = "MainPage"; @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // Log Screenview for this activity Tealeaf.logScreenview(this, logicalPageName, ScreenviewType.LOAD); //DeviceAuthManager.getInstance().setProvisioningDelegate(<Use default ProvisioningDelegateImpl class or replace with your IProvisioningDelegate implementation>); // Add bridge for Tealeaf data to be sent back appView.addJavascriptInterface(new JavaScriptInterface(this.getContext(), Tealeaf.getPropertyName(webviewObject).getId()), "tlBridge"); super.loadUrl(getWebMainFilePath()); } public void onPause() { // Handle Tealeaf during onPause event Tealeaf.onPause(this, logicalPageName); super.onPause(); } public void onResume() { // 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. 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. 76 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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 89. Set the target page's address in the TealeafBasicConfig.properties configuration file under the key PostMessageUrl. See "Configuration File" in the IBM Tealeaf Android SDK Guide. Data privacy IBM Tealeaf provides mechanisms for masking or blocking sensitive customer information, such as credit card numbers, from being transmitted and captured by IBM Tealeaf. Through the Android SDK, you can specify the fields that need to be blocked or masked in your web application. When applied, data privacy ensures that these data elements are never transmitted to IBM Tealeaf. Note: Due to changes in how client framework data is submitted to IBM Tealeaf for capture, the best method for masking or blocking sensitive data is to apply the filtering through the capturing client framework. While other IBM Tealeaf features to manage data privacy can be deployed, they are not easy to implement on the new format of data captured from the client frameworks. IBM Tealeaf recommends using the methods referenced below. v See "Configuration File" in the IBM Tealeaf Android SDK Guide. v For more information about handling sensitive data in general, see "Managing Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual. Configuring sessionization for Android applications on the client The Android SDK auto-generates a session ID if one is not provided. This session ID is used to identify the session on the IBM Tealeaf server. IBM Tealeaf injects cookies to create session in the IBM Tealeaf system. Note: When an Android native or hybrid application is placed into background, the library flushes the collected data and sleeps, instead of disabling it. This happens unless the session expired due to the session timeout property. The timeout property is indicated with SessionTimeout in TealeafBasicConfig.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 Chapter 1. Tealeaf installation and implementation in an Android application 77 function as a unique session identifier within the Android SDK environment for IBM Tealeaf to track on customer sessions. CookieParam can be set to use customer session ID or JSESSIONID. The following is a typical setting in TealeafBasicConfig.properties using customer session ID. #Sessionization settings on customer cookies CookieUrl = http://www.sample.com CookieDomain = .sample.com CookiePath = / CookieParam = JSESSIONID CookieExpires = false SessionTimeout=30 SessoinTimeoutKillSwitch=false In this example, the cookie expires 30 minutes from current time. When the session timeout occurs, Android SDK retrieves the new cookie from your application server and posts the rest of request to application server using this new acquired cookie in request header. PCA groups all the used JSESSIONIDs into one single session even though the JSESSIONID was consistently changing. When using cookies generated from customer application server, SessoinTimeoutKillSwitch can be set to true or false. Setting the SessoinTimeoutKillSwitch to false means the session timeout user does not go to recheck on KillSwitchUrl to see if it is responding. Network traffic used in application contains requests only: Android SDK uses cookies to add values to the TLFConfigurableItems.properties file. Uses session ID generated by IBM Tealeaf Android SDK Android SDK uses cookies to add the following values in TLFConfigurableItems.properties. v CookieUrl is for url of site that is posted and getting cookie to sessionize on. v CookieParam is the parameter that has a session id. v CookiePath is the path of the cookie. v CookieDomain is the domain that the cookie belongs to. v CookieSecure is to add a secure cookie that can only be posted to an https url that has a valid certificate. v CookieExpiresFormat can have the date format of ASCTIME, RFC1036, or RFC1123, which will have an expiration date of current time + session timeout indicated in the variable below. v SessionTimeout is session timeout is in minutes. When this value expires a new session id is created. An example follows. #Sessionization settings CookieUrl=http://m.ibm.com CookieParam=TLTSID CookiePath=/ CookieDomain=.ibm.com #Whether you want to create a secure cookie which can only be sent using a https url in PostMessageUrl. CookieSecure=false #Valid date formats: ASCTIME, RFC1036, RFC1123 78 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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 CX PCA to collect all the resources together in a single captured session. Add the following cookie into the GET and POST requests to enable the PCA to listen to requests and responses. httpClient.setRequestProperty("Cookie", Tealeaf.getTLCookie(Tealeaf.getCurrentSessionId())); Extend org.apache.http.impl.client.DefaultHTTPClient: If you do not use the IBM Tealeaf extended TLDefaultHttpClient class, you must add the following code to the following classes. import org.apache.http.conn.ClientConnectionManager; import org.apache.http.impl.client.DefaultHttpClient; import org.apache.http.params.HttpParams; /** * @author ohernandez * */ public class TLDefaultHttpClient extends DefaultHttpClient { /** * */ public TLDefaultHttpClient() { super(); this.init(null); } /** * @param params Http parameters. */ public TLDefaultHttpClient(final HttpParams params) { super(params); this.init(null); } /** * @param params Http parameters. * @param sessionId Tealeaf session id. */ public TLDefaultHttpClient(final HttpParams params, final String sessionId) { super(params); this.init(sessionId); } /** * @param conman ClientConnectionManager. * @param params Http parameters. */ public TLDefaultHttpClient(final ClientConnectionManager conman, Chapter 1. Tealeaf installation and implementation in an Android application 79 final HttpParams params) { super(conman, params); this.init(null); } /** * @param sessionId Tealeaf session id. */ private void init(final String sessionId) { final TLHttpRequestInterceptor tlHttpRequestInterceptor = new TLHttpRequestInterceptor(sessionId); this.addRequestInterceptor(tlHttpRequestInterceptor); this.addResponseInterceptor(new TLHttpResponseInterceptor (tlHttpRequestInterceptor)); } } Extend org.apache.http.HttpRequestInterceptor: This class is used to inject session id as a cookie and additional headers that the IBM Tealeaf system uses. import java.io.IOException; import java.util.Map.Entry; import import import import org.apache.http.HttpException; org.apache.http.HttpRequest; org.apache.http.HttpRequestInterceptor; org.apache.http.protocol.HttpContext; import android.webkit.CookieManager; import com.tl.uic.Tealeaf; import com.tl.uic.util.LogInternal; /** * @author ohernandez */ public class TLHttpRequestInterceptor implements HttpRequestInterceptor { private String url; private final String sessionId; /** * Constructor. */ public TLHttpRequestInterceptor() { super(); this.sessionId = null; } /** * Constructor. * @param sessionId Tealeaf session id. */ public TLHttpRequestInterceptor(final String sessionId) { this.sessionId = sessionId; } /** * Get url of the request. * @return Url of the request. */ public final String getUrl() { return url; } /** 80 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide * Url of the request. * @param url Url of the request. */ public final void setUrl(final String url) { this.url = url; } /** * {@inheritDoc} */ public final void process(final HttpRequest request, final HttpContext context) throws HttpException, IOException { try { this.url = request.getRequestLine().getUri(); if (!request.containsHeader(Tealeaf.TLF_HEADER)) { request.addHeader(Tealeaf.TLF_HEADER, "device (Android) Lib/" + Tealeaf.getLibraryVersion()); } if (!request.containsHeader(Tealeaf.TLF_PROPERTY_HEADER)) { request.addHeader(Tealeaf.TLF_PROPERTY_HEADER, 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 import import import org.apache.http.HttpException; org.apache.http.HttpResponse; org.apache.http.HttpResponseInterceptor; org.apache.http.protocol.HttpContext; import com.tl.uic.TLFCache; import com.tl.uic.Tealeaf; import com.tl.uic.util.LogInternal; Chapter 1. Tealeaf installation and implementation in an Android application 81 /** * @author ohernandez * */ public class TLHttpResponseInterceptor implements HttpResponseInterceptor { private final TLHttpRequestInterceptor tlHttpRequestInterceptor; private final Date startTime; private final long initTime; /** * Constructor. * * @param tlHttpRequestInterceptor TLHttpRequestInterceptor used. */ public TLHttpResponseInterceptor(final TLHttpRequestInterceptor tlHttpRequestInterceptor) { this.tlHttpRequestInterceptor = tlHttpRequestInterceptor; this.startTime = new Date(); this.initTime = TLFCache.timestampFromSession(); } /** * {@inheritDoc} */ public final void process(final HttpResponse response, final HttpContext context) throws HttpException, IOException { try { final Date endTime = new Date(); final Date startLoad = new Date(); final long loadTime = (new Date()).getTime() - startLoad.getTime(); final long responseTime = endTime.getTime() - this.startTime.getTime(); Tealeaf.logConnection(this.tlHttpRequestInterceptor.getUrl(), response, this.initTime, loadTime, responseTime); } catch (final Exception e) { LogInternal.logException(e); } } } Uses non IBM Tealeaf session ID You must get your generated session ID and use it when you enable or start a new session in Android SDK. // If enabling of Android Logging Framework use Tealeaf.enable(); Tealeaf.enable("your session id"); // If Android Logging Framework is enabled and a new session is to be created use Tealeaf.startSession(); Tealeaf.startSession("your session id"); Android application gestures You can capture gestures that the users make on your Android application. Several types of gestures are captured. Configuration For any Activity class that you want Gesture logging, you edit TealeafBasicConfig.properties file and set the SetGestureDetector property to true. Touch event methods You add your variables to one of these methods: 82 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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 11. Tap gestures. Gesture name Description Image displayed in Replay Tap This gesture is a one-finger gesture. For a tap gesture, one-finger taps and lifts from the screen in 1 location. Tap and Hold This gesture is a one-finger gesture. For a Tap and Hold gesture, one-finger presses and stays on the screen until information is displayed or an action occurs. Note: The response to a Tap and Hold gesture can vary from one application to another. For example, a Tap and Hold gesture might display an information bubble, magnify content under the finger, or present the user with a context menu. Double tap This gesture is a one-finger gesture. For a double tap gesture, one-finger taps twice in close succession in 1 location of the screen. Chapter 1. Tealeaf installation and implementation in an Android application 83 Swipe gestures This table lists and describes the swipe gestures that are captured from web and mobile apps: Table 12. Swipe gestures Gesture name Description Swipe vertically Image displayed in Replay 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 9.0.1 Release Notes for information about a known limitation for handling some iOS pinch gestures. Table 13. Resize gestures Gesture name Description Pinch open Sometimes referred to as a spread gesture, this is a two-finger gesture. Image displayed in Replay 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. 84 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Note: Accompanying arrows indicate the direction (open or close) of the pinch Table 13. Resize gestures (continued) Gesture name Description Image displayed in Replay Pinch close This gesture is a two-finger gesture. For a pinch close resize gesture, 2 fingers: 1. tap and hold in 1 location on the screen, 2. maintain contact with the screen while the fingers move toward each other, 3. lift from the screen at a new location. Note: Accompanying arrows indicate the direction (open or close) of the pinch Unresponsive gesture events captured Unresponsive gestures are gestures that do not respond when a user tries to select items in an application or tries to adjust views in the application. Like other gesture events, unresponsive gestures are captured by Tealeaf. Unresponsive gestures are displayed graphically in BBR as orange outlined icons accompanied by a circled "X" . The circled "X" denotes that the gesture was unresponsive. For example, if a double tap gesture did not yield a response in the mobile application, then at replay time that gesture is displayed with the following icon in BBR: The following table lists the unresponsive gestures that are captured from web and mobile apps and shows the images that are displayed in BBR: Table 14. Unresponsive gestures and icons Unresponsive Gesture Image displayed in Replay Tap gestures Unresponsive tap Unresponsive double tap Unresponsive tap and hold Swipe gestures Chapter 1. Tealeaf installation and implementation in an Android application 85 Table 14. Unresponsive gestures and icons (continued) Unresponsive Gesture Image displayed in Replay Tap gestures Swipe vertically Note: Accompanying arrows indicate the direction of the swipe. Swipe horizontally Note: Accompanying arrows indicate the direction of the swipe. Resize gestures Pinch open Note: Accompanying arrows indicate the direction of the pinch. Pinch close Note: Accompanying arrows indicate the direction 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. 86 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 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... THEN... using a customized gesture view Override the dispatchTouchEvent publc boolean dispatchTouchEvent ( MotionEvent e) { Tealeaf.dispatchTouchEvent(this, e); return super.dispatchTouchEvent(e); } not using a customized gesture view Override the onTouchEvent publc boolean onTouchEvent ( MotionEvent e) { Tealeaf.dispatchTouchEvent(this, e); return super.onTouchEvent(e); } This example shows the code snippets that are added in this task for an application that does not use a customized gesture view: mport com.tl.uic.Tealeaf; import com.tl.uic.app.UICActivity; import android.os.Bundle; import android.view.MotionEvent; public class MainActivity extends UICActivity{ @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); Tealeaf.logScreenLayout(this, this.getLogicalPageName(), 1000); } public boolean dispatchTouchEvent( MotionEvent e) { Tealeaf.dispatchTouchEvent(this,e); return super.dispatchTouchEvent(e); } } Modifying the TealeafBasicConfig.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 TealeafBasicConfig.properties file. Chapter 1. Tealeaf installation and implementation in an Android application 87 2. Set SetGestureDetector to true. 3. Save and exit the TealeafBasicConfig.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 Parameters public static Boolean logException(final Throwable exception, final HashMap<String, String> data, final Boolean unhandled) Where: v @param exception - the exception to be logged. v @param data - the value to be given to event. v @param unhandled - whether the exception is unhandled. v @return - whether exception was logged. Example In this example, you have a method that causes an exception: public void clientMethod1( ) { } You add an @try , @catch, and the Tealeaf.logException(e, data, false) method to handle the exception: public void clientMethod1( ) { try { int[] array = new int[1]; int i = array[2]; // Index out of bound exception } Catch (Exception e) { HashMap<String, String> data = new HashMap<String, String>(); data.put("extraMessage", "custom value1"); Tealeaf.logException(e, data, false); } } 88 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Logging exceptions: Use the examples in this task as a guide to adding exception logging to your application. 1. Determine the method for which you want to log exceptions. For example, you have a method: public void clientMethod1( ) { } 2. Optional: Add the exception method to the method for which you want to log the exceptions. Add @try , @catch, and the Tealeaf.logException(e, data, false) method to handle the exception: public void clientMethod1( ) { try { int[] array = new int[1]; int i = array[2]; // Index out of bound exception } Catch (Exception e) { HashMap<String, String> data = new HashMap<String, String>(); data.put("extraMessage", "custom value1"); Tealeaf.logException(e, data, false); } } Quick start for server configuration This section describes the basic steps to configure the IBM Tealeaf CX Passive Capture Application and Windows based servers to capture and process data that is submitted from the Android SDK. To enable processing of submitted data, you complete the steps in the following sections. Target page for traffic capture IBM Tealeaf is designed to capture traffic between a client and a web server. To facilitate capture, you must add a target page to your web server environment to which the Android SDK can submit posts. You can use the same target page that is available for IBM Tealeaf CX UI Capture for AJAX. See "UI Capture for Ajax Installation and Implementation" in the IBM Tealeaf CX UI Capture for AJAX Guide. After you add the target page to your web environment and enable the appropriate access permissions, you must configure the URL for the target page in the TLFConfigurableItems.properties page. Note: If needed, you can configure the client framework to submit by HTTPS by adding the protocol identifier to the post URL. See Chapter 2, “Configuration file,” on page 97. Traffic volume management You can add a sampling function to work with the Android SDK KillSwitch. You can use this sampling function to throttle the sampling rate and thus the volume of traffic that is forwarded for capture. Chapter 1. Tealeaf installation and implementation in an Android application 89 For more information about sampling functions for various server environments, see "Sample Code" in the IBM Tealeaf Android SDK Guide. CX Passive Capture Application traffic capture verification You verify that the IBM Tealeaf CX Passive Capture Application in your IBM Tealeaf environment is configured to capture and process the data that is submitted from the Logging Frameworks. The data is submitted using specific content types, which the CX Passive Capture Application is typically configured to capture by default. You must verify that these content types were enabled for capture through the CX Passive Capture Application Web Console. Note: After the completion of the steps in this section, data is processed by IBM Tealeaf. Verifying CX Passive Capture Application capture type configuration You use this procedure to verify that the CX Passive Capture Application is configured to capture the content types submitted by the Android SDK. Note: Depending on the version of the CX Passive Capture Application you installed, the required content types may already be configured for capture. The Android SDK submits messages using the text/json content type. Note: Each IBM Tealeaf Logging Framework can use a different content type for submitting events for capture to IBM Tealeaf. Be sure to review and verify the content type for each deployed client framework. 1. Log in to the CX Passive Capture Application web console: <PCAServer>:8080 where <PCAServer> is the host name of the CX Passive Capture Application server. 2. Click the Pipeline tab. 3. Click Edit Type Lists. 4. In the Capture All POST Types box, verify that the following values ae included: text/json text/x-json application/json application/x-json 5. Click Add. 6. The CX Passive Capture Application is now configured to capture the required content types. All subsequent hits of this type are captured. 7. Save changes. See "PCA Web Console - Pipeline Tab" in the IBM TealeafCX Passive Capture Application Manual. 90 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Configuring CX Passive Capture Application for Logging Framework screen captures Optionally, you can enable the Android SDK to capture screen captures during the initial load of each view or screen of your web application. These screen captures are forwarded to the IBM Tealeaf Target Page in .PNG format for capture and use during session display. See “UICActivity class” on page 113. When this option is enabled, you must configure the CX Passive Capture Application to capture these screen captures. By default, the CX Passive Capture Application drops capture of binary or static content, so you must configure it to capture these images that are submitted as binary POSTs to the target page. 1. Log in to the CX Passive Capture Application web console: <PCAServer>:8080 Where <PCAServer> is the host name of the CX Passive Capture Application server. 2. Click the Pipeline tab. 3. Click Edit Type Lists. 4. In the Excluded File Extensions list, verify that png is listed. 5. In the Included File Extensions list, verify that png is not listed. Note: If a file extension is included in this list, then all instances that are sent as responses are captured, which greatly expands the volume of data that is captured by the CX Passive Capture Application. Capture in this manner is not required. 6. In the Binary POST Types box, enter the following value: image/png 7. Click Add. 8. The image/png POST type is added and enabled for capture. This setting allows the PNG posts to be captured by the CX Passive Capture Application. 9. Save changes. See "PCA Web Console - Pipeline Tab" in the IBM Tealeaf CX Passive Capture Application Manual. Enabling automated extraction of compressed POSTs The Android SDK automatically compresses POST data. You must configure the CX Passive Capture Application to extract them. Note: For CX Passive Capture Application Build 3502 or later, this decompression is done automatically. If you are using one of these CX Passive Capture Application builds, this configuration step is not necessary. 1. In the CX Passive Capture Application Web Console, click the Pipeline tab. 2. Select Inflate compressed requests and responses. 3. Save changes. The compress POSTs are now automatically extracted by the CX Passive Capture Application and processed normally. Options for monitoring captures and processing You use different tools for testing your configuration and monitoring captures on an ongoing basis. Chapter 1. Tealeaf installation and implementation in an Android application 91 At target page You can test the basic functionality of the target page by triggering GET and POST actions on the URL where the target page was installed. See "UI Capture for Ajax Installation and Implementation" in the IBM Tealeaf CX UI Capture for AJAX Guide. In Windows pipeline You can monitor the capture and processing of hits in the Windows pipeline in real time through the IBM Tealeaf Management System. See "TMS Pipeline Status Tab" in the IBM Tealeaf cxImpact Administration Manual. Configuring sessionization for Android applications in IBM Tealeaf IBM Tealeaf provides multiple mechanisms for identifying and tracking individual visitor sessions. For the Android SDK, more configuration can be required. Review the following steps and complete any necessary ones to sessionize your mobile application. To enable sessionization of hits that are captured through the Android SDK, you must deploy the Sessioning session agent. See "Sessioning Session Agent" in the IBM Tealeaf CX Configuration Manual 1. Log in to the Portal as an administrator. 2. From the Portal menu, select Tealeaf > TMS. The IBM Tealeaf Management System opens. See "Tealeaf Management System" in the IBM Tealeaf cxImpact Administration Manual. 3. Click the WorldView tab. 4. For the View, select Servers. See "TMS WorldView Tab" in the IBM Tealeaf cxImpact Administration Manual. 5. Click the Transport Service node. 6. Select Transport Service configuration. Then, click View/Edit. 7. The Pipeline Editor opens. Note: Verify that the Sessioning session agent was installed. v If it was not installed, drag it from the Available SessionAgents window to the pipeline. v For more information about deploying it, see "TMS Pipeline Editor" in the IBM Tealeaf cxImpact Administration Manual. 8. Select the Sessioning session agent. Click Edit. 9. In the Sessioning session agent configuration, modify the PrimarySessField value as follows: PrimarySessField=AppEnv:SessionID,env:HTTP_X_TEALEAF 10. Save the configuration file. 11. Push the change to all servers. A restart is needed for the new sessionization keys to take effect. 92 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Android view name as URL during replay Errors that can occur during session replay can be resolved by using the Android view name as the URL during replay. When you attempt to replay a session captured by the Android SDK, an error message can indicate that there are no viewable pages in the session. This error is related to the manner in which pages on Android devices are mapped. Instead of displaying the URL during replay, you can configure IBM Tealeaf replay clients to show the Android view name instead, which eliminates this cosmetic error message. To use the Android view name as the URL when you replay the session, complete the following steps to configure the appropriate replay profile rule. Note: Currently, configuration of this rule must be applied through the replay profile that is stored on the Replay Server. Instructions follow. When this change is applied, the Navigable Pages list in Replay view in Browser Based Replay and CX RealiTea Viewer is populated with the Android view name as the URL, instead of the generic IBM Tealeaf Target page URL. v Browser Based Replay, or BBR 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 94 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. Chapter 1. Tealeaf installation and implementation in an Android application 93 Note: CX RealiTea Viewer must be installed locally on your Windows desktop. See "RealiTea Viewer (RTV) User Manual" in the IBM Tealeaf CX RealiTea Viewer User Manual. 2. Load a session that is captured from the Android SDK. 3. From the CX RealiTea Viewer menu, select Tools > Options.... 4. Click the Profiles tab. See "RealiTea Viewer - Profile Options" in the IBM Tealeaf CX RealiTea Viewer User Manual. 5. If you did not do so already, enter the name of the Replay Server that controls the replay profile in the Server check box. Click Check for Updates Now. If a server version of the profile is available, your local version is synchronized to it. 6. Click Edit Raw Profile. 7. Complete the editing steps that are listed in the section that follows. You are editing the raw XML file that is stored on your local desktop. See “Applying the view name change to the Replay Server.” 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. 94 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 1. Log in to the server hosting the Replay Server as an administrator. 2. Edit the following file: <Tealeaf_install_directory>\system\ReplayServerProfile.xml 3. Locate the RequestMapping section, which should be near the top of the file. 4. Add a Request Mapping, URL element entry. Locate the following header: <RequestEntry name="URL"> 5. Add the following key name as a new entry to the list of entries: <Key name="HTTP_X_TEALEAF_VIEW_CLASS" enabled="1"/> 6. Save the file. Runtime configuration As needed, you can change server-side settings from the client application. All configuration items can be configured dynamically from the client. You can plan to manage server configuration during initialization of the application, then update it selectively and as needed during run time. See "TeaLeaf Class" in the IBM Tealeaf Android SDK Guide. IBM Tealeaf events for Android SDK The JSON format is used to track data that is captured by the Android SDK. Data type Description Client Framework data (JSON) If you are using step-based eventing, data from the client framework is submitted in JSON format and is available through Browser Based Replay for review and eventing. See "Step-Based Eventing" in the IBM Tealeaf Event Manager Manual. For a walk-through of how to capture this data into IBM Tealeaf events, see "Integrating Client Framework Data into Tealeaf" in the IBM Tealeaf Client Framework Data Integration Guide. Client Framework data (hit-splitting) See “Client Framework versions supported in this documentation” on page 2. Upgrading the Android SDK When you upgrade the IBM Tealeaf Android SDK, you complete the following general tasks. Note: Some steps can vary depending on your development and application environments. The following example uses Eclipse as the development environment. 1. Review current requirements. See Minimum requirements. 2. Review the package contents. See “Tealeaf package contents” on page 2. 3. If you are using a version of the IBM Tealeaf Android SDK that is earlier than 10.1.0, remove uicandroid.jar and TLFConfigurableItems.properties from the project lib and assets folders. Chapter 1. Tealeaf installation and implementation in an Android application 95 4. Add encore.jar and tealeafMod.jar to your project libraries. From your Eclipse project, select Build Path > Configure Build Path > Android, add encore.jar and tealeafMod.jar as libraries to your project. 5. Add TealeafBasicConfig.properties, TealeafAdvancedConfig.json, EOCoreBasicConfig.properties, and EOCoreAdvancedConfig.json as assets in your project. From your Eclipse project select Assets > General > Choose file system > Next, then add TealeafBasicConfig.properties, TealeafAdvancedConfig.json, EOCoreBasicConfig.properties, and EOCoreAdvancedConfig.json. 6. Edit PostMessageUrl in TealeafBasicConfig.properties to point your target server. After completing the upgrade procedure, use the following steps to verify the installation. 1. 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 90. 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 89. 2. Verify that your application environment is configured to meet the project requirements. 3. Verify that the requirement code changes were applied. See Android project changes. 4. Apply the basic configuration. Note: The latest version of the Android SDK includes new configuration requirements. See “Basic configuration” on page 33. 5. Test your upgraded solution. 96 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 2. Configuration file The configuration files for the Android SDK library are placed into the asset folder of an Android application. The configuration files are saved Java properties files and are named TealeafBasicConfig.properties and EOCoreBasicConfig.properties. Application key An application key (AppKey) setting is used to identify and sessionize the mobile application with Tealeaf Customer Experience on Cloud. For SaaS applications, you need to know if SaaS is using Tealeaf cookies for sessionization. If the Tealeaf cookies are used, you need to provide a cookie name and application key. You can use TLTSID as the cookie name. Contact your Tealeaf SaaS administrator for the value of the application key. Note: It is recommended that each mobile application is assigned a unique application key. However, application keys can be used with more than one application if the same data is being captured from each application and you want captured data from multiple applications to be grouped as a single entity. Log level settings The log level settings configure base logging settings. Table 15. Log level settings Item ID Description Values LoggingLevel The current logging level, applies only when log level is not indicated in log statement. Integer, 0-3 v 0 does not send log data. v 1 has the highest priority. v 3 has the lowest priority. To disable logging, start Tealeaf.Disable(). See Chapter 6, “Reference,” on page 113. DisplayLogging When set to true, debug log statements are displayed in LogCat. Filter for the UICAndroid tag. Boolean LogViewLayout OnScreenTransition When set to true, UICAndroid logs the screen layout. When set to False, the screen layout is not logged. Boolean © Copyright IBM Corp. 1999, 2016 97 Kill switch settings These settings control the kill switch and whether to use a white list of phone whose events can be captured. Table 16. 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 If KillSwitchEnabled=false, the framework always starts. KillSwitchUrl Defines the URL to check for the kill URL switch. The framework requires a successful response to initialize when KillSwitchEnabled is set to true. KillSwitchMaxNumberOfTries The number of times the framework Integer checks for the kill switch URL before giving up. This value should be set to at least 1. KillSwitchTimeInterval The time to wait before rechecking the kill switch URL if it is not responding UseWhiteList If true and KillSwitchEnabled, the true/false framework requires a phone id to assign before calling Enable to check the white list of phone ids. Seconds If false and KillSwitchEnabled, the framework defaults to use random sampling. WhiteListParam 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 17. 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 The current caching level. Applies only Integer, 0-3 when HasToPersistLocalCache is true. v 0 does not send data. v 1 has the highest priority. v 3 has the lowest priority. 0 has the highest priority. 98 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 17. Local cache file settings (continued) Item ID Description Values CachedFileMaxBytesSize Maximum number of bytes to be stored on device. Bytes Post settings These settings control the logging level, URL, volume, and frequency of posts to the target page. Table 18. 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 https://. For more information about the target page, see Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1. URL PostMessageLevelWiFi The logging level of events to be sent to the server over Wi-Fi when network performance is good. 0 has the highest priority. 0-3 PostMessageLevelCellular The logging level of events to be sent to the server over the cellular (3G) network. 0 has the highest priority. 0-3 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 If set to false, you must configure the following settings. Note: You cannot enable this setting and DoPostOnIntervals together. DoPostOnIntervals If true, the framework sends data to the server at regular time intervals that are specified by PostMessageTimeIntervals when the application is in the foreground. This value must be set to true if ManualPostEnabled=false. Note: You cannot enable this setting and ManualPostEnabled together. PostMessageTimeIntervals How often the framework sends data to Seconds the server when DoPostOnIntervals is set to true. Note: This value must be set to be greater than PostMessageTimeout plus PostMessageDelayTimeToSendData. true/false Chapter 2. Configuration file 99 Table 18. Post settings (continued) Item ID Description Values PostMessageTimeout The timeout for the framework's posts to the server. While the framework does not receive a server response within this timeframe, the framework keeps trying to send data. Seconds Masking settings These settings control privacy masking. Table 19. 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 expressions to find ids. String HasCustomMask It can be true or false to use next values below if true. Boolean SensitiveSmallCaseAlphabet Character to be used by small case letter. String SensitiveCapitalCaseAlphabet Character to be used by capital case letter. String SensitiveSymbol Character to be used by symbol. String 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 20. 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 21. Cookie settings 100 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 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 21. Cookie settings (continued) Item ID Description Values 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 22. 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 23. Screenshot settings Item ID Description Values ScreenshotFormat The format of the screen shot. PNG/ JPG PercentOfScreenshotsSize The percentage of screen capture's original pixel dimensions at which posted screen captures are submitted, 1-100. Integer 1-100 PercentToCompressImage Percentage to compress image. This setting can only be used for JPG images. PNG images ignore this setting and default to 100. Integer 1-100 Internal settings: do not change Do not change these settings unless directed to do so by IBM Tealeaf. Table 24. Internal settings: do not change Item ID Description Values PostMessageSocketTimeout The socket timeout for the framework's Seconds posts to the server. While the framework does not receive a server response within this timeframe, the framework keeps trying to send data. Chapter 2. Configuration file 101 Table 24. Internal settings: do not change (continued) 102 Item ID Description Values CompressPostMessage 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. true/ false BufferLimit The number of messages to store in memory to be sent to server. Integer BufferPercent Percentage to remove from BufferLimit Percentage before it gets saved to cache if enabled. TimeIntervalBetweenSnapshots The time interval for taking snapshots of environmental data IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Seconds Chapter 3. Application images and replay For application replay, the images that you added to your application should be copied to the replay server. When the images are on the replay server, the images do not need to be sent in the payload which could cause performance issues. Instead, replay uses a unique identifier for each image to retrieve the needed images from the replay server. Part of developing your application includes collecting the images that you use in your application so that they can be copied to the replay server. There are two tools that you run on your local machine that assign the unique identifiers to the images and collect the images. Available tools There are two tools that you can use to collect the images that you inserted in your application: Tool Description Platforms Target Simulator A command line program v For use with the Android that runs on your local SDK and iOS SDK. machine and acts as a Tealeaf v Runs in Windows and iOS target page to collect the environments. images in your application. Images are collected into a folder. Using the tool involves: 1. Installing the Target Simulator from the Android package. 2. Configuring TLFConfigurableItems configuration file to non-standard run-time settings. 3. Exercise all of the pages in your application. 4. Reset your TLFConfigurableItems configuration file to standard run-time settings. 5. Transfer the images to the replay server images folder. © Copyright IBM Corp. 1999, 2016 103 Tool Description Platforms Android Image Capture Tool A command line program v For use with the Android that collects all of the images SDK. in your android application v Runs in Android to an archive. Using the tool environments only. involves: 1. Downloading and installing Ruby. 2. Downloading and installing Rake. 3. Installing the Android Image Capture Tool in your development environment. 4. Running the tool from a command line. 5. Transferring the archive to the replay server images folder. Target Simulator You use the Target Simulator Tool to capture the static images that you inserted in your mobile application, such as backgrounds for buttons or controls. The tool collects all images that it finds, including dynamic images that are part of the application database. When you start the tool, you must exercise every page in your application for the tool to capture the images. The Target Simulator uses the IBM SDK for Node.js. You can obtain an installer from the Tealeaf Android or iOS SDK package or from http://www.ibm.com/developerworks/web/nodesdk/. While there are other versions of Node.js, only the IBM SDK for Node.js is supported. Target Simulator details The Target Simulator acts as a target page on your local machine. After you start the simulator, you exercise every page in your application. The simulator takes the images that are embedded in the application, uses the image check sum to create unique file name for each image, and saves the images in the same location where the Target Simulator tool is located. After you have the images, the images must be transferred to the replay server images folder. Target Simulator SDK settings Because images are not sent in the payload in production, you modify the SDK properties to send the images in payloads and to use a target page on the machine running the Target Simulator and not the production Tealeaf Target page. When you start the Target Simulator, the program gives you the URL where the Target Simulator is listening SDK for payloads that contain images.. The Target Simulator provides you a URL with an IP address. The PostMessageUrl location is http://<IP addres>:<portnumber>. By default, the <portnumber> is 9000. If you change the port number on the command line, that is the port number that is used. 104 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide You modify the TealeafBasicConfig.properties file for Android applications, and the TLFConfigurableItems.plist file for iOS applications. You modify the settings to point to the target page on the machine running the Target Simulator, to get image data, and to increase the payload size to allow images. You modify: v Android and iOS - PostMessageURL - http://localhost:<port number> v Android and iOS - GetImageDataOnScreenLayout - Yes v Android - MaxNumberOfBytesPerActivation - 2,000,000,000 After you exercise your application you modify the properties file and change the properties back to the production settings for normal operation. You reset the settings to: v Android and iOS - PostMessageURL - the URL for the production Tealeaf Target page v Android and iOS - GetImageDataOnScreenLayout - No v Android - MaxNumberOfBytesPerActivation - <the number used in production> Target Simulator command If you already have the IBM SDK for Node.js in your path, you can start the target simulator by entering node target_sim.js. If Node.js is not in your path,the Target Simulator full path command for Mac is /Applications/IBM/node/bin/node target_sim.js. If Node.js is not in your path, the Target Simulator full path command for Windows is "C:\Program Files\IBM\Node\node.exe" target_sim.js. By default the Target Simulator listens for SDK posts on port 9000. If you already have something running on port 9000 and want the Target Simulator to use a different port, specify a port number at the end of the command. For example, to change the port to 8080, enter: /Applications/IBM/node/bin/node target_sim.js 8080 Transfer the images to the replay server images folder Once the folder with the images is created, with either tool, the archive must be transferred to the replay server images folder. This folder is typically C:\Tealeaf\Replay Server\Images. Whoever has access to the replay server can transfer the archive. It may be you, the portal administrator, or someone else, depending on your local practices. Collecting images from your application with the Target Simulator Use this task to capture the images in your application so that they can be transferred to the replay server for replay. The Target Simulator tool runs in Mac OS and Windows environments to capture Android and Mac OS application images. You use this tool after you have developed your application and have all of your images imbedded and any time that you embed new images in your application. If you do not already have the IBM SDK for Node.js installed on your local machine, download and install the SDK. Chapter 3. Application images and replay 105 1. Extract the Target Simulator archive on the device that you used to create your application. 2. Start the simulator with the default settings by entering node target_sim.js. 3. Modify the configuration properties for your platform: IF you created your application for an... Android device THEN... 1. Edit the TealeafBasicConfig.properties file. 2. Set PostMessageUrl: to the URL that application reports is listening on. 3. Set GetImageDataOnScreenLayout: to YES 4. Set MaxNumberOfBytesPerActivation: to 2,000,000,000 5. Save and exit the file. iOS device 1. Edit the TLFConfigurableItems.plist file. 2. Set PostMessageUrl: to the URL that application reports it is listening on. 3. Set GetImageDataOnScreenLayout: to YES 4. Save and exit the file. 4. Exercise every page in your application to capture all of the images that you added. In the target_sim.js console window, you see a running log of what POSTs were received and what images (if any) were found and saved to the file system. 5. In the target_sim.js console window, press Control-C to exit the simulator. 6. Reset the TealeafBasic configuration file to standard run-time settings. IF you created your application for an... Android device THEN... 1. Edit the TealeafBasicConfig.properties file. 2. Set PostMessageUrl: to the URL for the application Target page. 3. Set GetImageDataOnScreenLayout: to NO 4. Set MaxNumberOfBytesPerActivation: to your production environment setting. 5. Save and exit the file. iOS device 1. Edit the TLFConfigurableItems.plist file. 2. Set GetImageDataOnScreenLayout: to NO 3. Save and exit the file. 7. Transfer the images to the replay server. Android Image Capture Tool You use the Android Image Capture Tool to capture the static images that you inserted in your android application, such as PNG or JPG images used by IOmageView. The tool collects all images that it finds under the "res" folder. When you start the tool, it automatically captures the images from the application. Android Image Capture Tool details The Android Image Capture Tool automatically collects the images in an android application into a folder called images. You do not need to exercise or run the 106 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide application. The Android Image Capture tool extracts and creates proper file path mapping from your APK file, so that the metadata collected from the Tealeaf Android client library for images can be displayed properly. Android Image Capture Tool software The Android Image Capture Tool requires Ruby and Rake software. The tool uses the apk for your application to locate the application images. Android Image Capture Tool files The Android Image Capture Tool uniquely names the image files and places them in an images folder in the AndroidImageCaptureTool root folder. In the Images folder, the tool creates a res folder that contains sub-folders for the different image resolutions. Images are grouped by resolution. Transfer the images to the replay server images folder Once the archive is created, with either tool, the archive must be transferred to the replay server images folder. This folder is typically C:\Tealeaf\Replay Server\Images. Whoever has access to the replay server can transfer the archive. It may be you, the portal administrator, or someone else, depending on your local practices. Collecting images from your application with the Android Image Capture Tool Use this task to capture the images in your application so that they can be transferred to the replay server for replay. The Android Image Capture Tool captures images from android applications only. Before you begin this task you must download and install: 1. Ruby version 2.1.2. 2. Rake version 10.3.2. After Ruby and Rake are installed, install the zip and nokogiri gem modules. To install the zip and nokogiri gem modules in a Mac OS environment: 1. Open a terminal window. 2. Enter xcode-select --install to install the Xcode Command Line tools. 3. Enter gem install rubyzip '1.1.7' to install the rubyzip module. 4. Enter gem install nokogiri '1.6.7.2' to install the nokogiri module. To install the zip and nokogiri gem modules in a Windows environment: 1. Open a command prompt. 2. Enter gem install zip '1.1.7' to install the zip module. 3. Enter gem install nokogiri '1.6.7.2' to install the nokogiri module. You must run this tool in your development environment where you developed your application. 1. Extract the AndroidImageCaptureTool file from the Android SDK package to your local path. Chapter 3. Application images and replay 107 2. Open a terminal or command line prompt. 3. Go to the Android Image Capture Tool root folder AndroidImageCaptureTool/. 4. Enter the rake command to run the rake task on the .apk file for your application: rake apk_path={YOUR/APK/PATH} 5. After the tool is finished, transfer the images to the replay server. 108 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 4. 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, 2016 109 110 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 5. Guidelines Apply the following tips to your application development and integration of the IBM Tealeaf Android SDK. v Use the kill switch to control logging of the Android application. See Chapter 7, “Sample Code,” on page 131. v Add IDs for all UI controls that you want to capture. v Apply privacy masking or blocking of all sensitive customer data through the Android SDK. Note: In Release 8.5, IBM Tealeaf introduced step-based eventing, which simplifies and unifies event capture from all client frameworks, while it enhances performance. Due to changes in how the data is bundled, you now apply data privacy through the individual client frameworks, instead of using the IBM Tealeaf server methods for data privacy. – See Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1. – For more information about managing privacy in general, see "Managing Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual. v Follow guidelines for the file that extends Application. See Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1. v Follow guidelines for the file that extends Activity. See Chapter 1, “Tealeaf installation and implementation in an Android application,” on page 1. v Debug locally in Eclipse by using LogCat. To see debug messages in the LogCat tab of Eclipse, enter the following string: tag:UICAndroid. v Follow guidelines for using text fields to get more metrics. See “Tealeaf class” on page 116. v Due to the way JSON messages are captured and transmitted, force a submission of all queued messages before you allow users of your mobile native application to open a web view. If this step is not done, hits can appear to be out of order during replay in IBM Tealeaf. See "Search and Replay for Mobile App" in the IBM Tealeaf CX Mobile User Manual. © Copyright IBM Corp. 1999, 2016 111 112 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 6. Reference This section contains class reference information about the IBM Tealeaf Android SDK library. UICActivity class 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, 2016 113 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. 114 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Reference Table 25. UICActivity class Package Class Description com.tl.uic.app UICActivity UICActivity used to help control IBM Tealeaf Android SDK library. “UICApplication class” Application that is used to help control IBM Tealeaf Android SDK library. com.tl.uic “Tealeaf class” on page 116 IBM Tealeaf Android SDK library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. TLHttpResponseInterceptor class Extends HttpResponseInterceptor to acquire details for the Tealeaf connection object. “UICWebView class” on page 126 WebView used to add session ID to header requests. com.tl.uic.webkit “UICWebChromeClient Class” on page 128 Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. “UICWebViewClient Class” on page 129 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. Method detail getTealeaf public Tealeaf getTealeaf() Get current instance of IBM Tealeaf. Returns the current instance of IBM Tealeaf. Chapter 6. Reference 115 Reference Table 26. UICApplication class Package Class Description com.tl.uic.app “UICActivity class” on page 113 UICActivity used to help control IBM Tealeaf Android SDK library. UICApplication Application that is used to help control IBM Tealeaf Android SDK library. com.tl.uic “Tealeaf class” IBM Tealeaf Android SDK library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. TLHttpResponseInterceptor class Extends HttpResponseInterceptor to acquire details for the IBM Tealeaf connection object. “UICWebView class” on page 126 WebView used to add session ID to header requests. “UICWebChromeClient Class” on page 128 Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. “UICWebViewClient Class” on page 129 Extends WebViewClient to monitor when the URL loaded to add IBM Tealeaf headers for sessionization. com.tl.uic.webkit Tealeaf class The com.tl.uic.TeaLeaf class extends java.lang.Object. The Tealeaf library helps capture user actions in an Android application. Fields Table 27. Tealeaf class 116 Field Summary Description static java.lang.String TLF_SESSION_HEADER Header key that is used to sessionize on X-Tealeaf-Session. static java.lang.String TAG UICAndroid used in LogCat. IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Fields used in event handlers to get display user actions correctly Table 28. Tealeaf class Field Summary Description static java.lang.String TLF_ON_FOCUS_CHANGE_IN Used in TextView based controls to indicate focus in. static java.lang.String TLF_ON_FOCUS_CHANGE_OUT Used in TextView based controls to indicate focus out. static java.lang.String TLF_ON_GROUP_COLLAPSE Used in ExpandableListView based controls to indicate group is collapsed. static java.lang.String TLF_ON_GROUP_EXPAND Used in ExpandableListView based controls to indicate group is expanded. static java.lang.String TLF_ON_DRAWER_OPENED Used in SlidingDrawer based controls to indicate drawer is opened. static java.lang.String TLF_ON_DRAWER_CLOSED Used in SlidingDrawer based controls to indicate drawer is closed. Fields used to access configuration file values Table 29. Tealeaf class Field Summary Description static java.lang.String TLF_LOGGING_LEVEL Default log level. static java.lang.String DISPLAY_LOGGING Whether to display debug statements in LogCat static java.lang.String TLF_KILL_SWITCH_ENABLED Whether kill switch is enabled. static java.lang.String TLF_KILL_SWITCH_URL Url for kill switch. static java.lang.String TLF_KILL_SWITCH_MAX_NUMBER_OF_TRIES Maximum number of tries static java.lang.String TLF_KILL_SWITCH_TIME_INTERVAL Kill switch time interval to retry to access kill switch. static java.lang.String TLF_USE_WHITE_LIST Whether to use white list. static java.lang.String TLF_WHITE_LIST_PARAM Parameter that white list uses. static java.lang.String TLF_USE_RANDOM_SAMPLE Whether to use random sample. Chapter 6. Reference 117 Table 29. Tealeaf class (continued) 118 Field Summary Description static java.lang.String TLF_RANDOM_SAMPLE_PARAM Parameter that random sample uses. static java.lang.String TLF_HAS_TO_PERSIST_LOCAL_CACHE Whether it is able to save cache to device. static java.lang.String TLF_CACHED_LEVEL Cache level to be saved to device. static java.lang.String TLF_CACHED_FILE_MAX_BYTES_SIZE Maximum cache byte size to be saved to device. static java.lang.String TLF_POST_MESSAGE_URL Url of the target page. static java.lang.String TLF_POST_MESSAGE_LEVEL_WIFI Log level if current connection level is WiFi. static java.lang.String TLF_POST_MESSAGE_LEVEL_CELLULAR Log level if current connection level is cellular. static java.lang.String TLF_MAX_STRINGS_LENGTH Maximum string length. static java.lang.String TLF_MANUAL_POST_ENABLED Whether to enable control of posting to target page. Developer is responsible for posting to target page. static java.lang.String TLF_DO_POSTS_ON_INTERVALS Whether to have framework post at a set interval. static java.lang.String TLF_POST_MESSAGE_TIME_INTERVALS Time interval between posts. static java.lang.String TLF_POST_MESSAGE_MAX_BYTES_SIZE Maximum byte size for posting a message. static java.lang.String TLF_HAS_MASKING Whether to mask values of controls. static java.lang.String TLF_MASK_ID_LIST Comma-delimited string that can have IDs of controls or regular expression to find IDs of controls. IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 29. Tealeaf class (continued) Field Summary Description static java.lang.String TLF_HAS_CUSTOM_MASK Whether to use custom mask values to replace. If set to false, Logging Framework returns an empty string. static java.lang.String TLF_SENSITIVE_SMALL_CASE_ALPHABET Small letter to replace during custom mask. static java.lang.String TLF_SENSITIVE_CAPITAL_CASE_ALPHABET Capital letter to replace during custom mask. static java.lang.String TLF_SENSITIVE_SYMBOL Symbol to replace during custom mask. static java.lang.String TLF_SENSITIVE_NUMBER Number to replace during custom mask. Constructor Public Tealeaf (Application app) Tealeaf is a library to help capture user actions in an Android application. Parameters: v application - Reference to current Android application. Method detail getCurrentSessionId public static java.lang.String getCurrentSessionId() Get current session ID. getDeviceId public static java.lang.String getDeviceId() Get device ID used with the whitelist on the kill switch server. getPhoneId This method has been deprecated. Use getDeviceId instead. public static java.lang.String getPhoneId() Get phone ID used with the whitelist on the kill switch server. setDeviceId public static void setDeviceId(java.lang.String deviceId) Set device ID that is used with the whitelist on the kill switch server. setPhoneId - This method has been deprecated. Use setDeviceId instead. public static void setPhoneId(java.lang.String phoneId) Set phone ID that is used with the whitelist on the kill switch server. Chapter 6. Reference 119 isEnabled public static java.lang.Boolean isEnabled() To enable library. Returns whether Tealeaf library was enabled. getApplication() public static android.app.Application getApplication() Reference to current Android Application. Returns reference to current Android Application. getMessageVersion() public static String getMessageVersion() Get current JSON message version. Returns current JSON message version. getLibraryVersion() public static java.lang.String getLibraryVersion() Reference to current library version. Returns reference to current library version. enable public static java.ladng.Boolean enable() public static java.lang.Boolean enable(sessionId) To enable library with a given session ID or a generated one. v sessionId - Given session ID to use. Returns if Tealeaf library was enabled. disable public static java.lang.Boolean disable() To disable library. Returns if library was disabled. onPause public static Boolean onPause(final Activity activity, final String logicalPageName) If not using UICActivity, add this call on your Activity file onPause method before calling super. v activity - Activity that calls onPause. v logicalPageName - Descriptive name of the activity that calls onPause. Returns True/False whether it was able to pause properly. onResume public static Boolean onResume(final Activity activity, final String logicalPageName) If not using UICActivity, add this call on your Activity file onResume method before calling super. v activity - Activity that calls onResume. v logicalPageName - Descriptive name of the activity that calls onResume. 120 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Returns True/False whether it was able to resume properly. onDestroy public static Boolean onDestroy(final Activity activity, final String logicalPageName) If not using UICActivity, add this call on your Activity file onDestroy method before calling super. v activity - Activity that calls onResume. v logicalPageName - Descriptive name of the activity that calls onResume. Returns True/False whether it was able to destroy properly. OnLowMemory public static java.lang.Boolean OnLowMemory() If not using UICApplication, add this call on your Application file OnLowMemory method before calling super. Returns: True/False whether it was able to properly clean up. terminate public static java.lang.Boolean terminate() If not using UICApplicaion, add this call on your Application file on terminate method before calling super. Returns True/False whether it was able to terminate properly. flush public static java.lang.Boolean flush() To be used to flush data. Returns: True/False whether it was able to flush data back to server. logEvent public static java.lang.Boolean logEvent(final View view)public static java.lang. Boolean logEvent(final View view, final java.lang.String eventType)public static java.lang.Boolean logEvent(final View view, final java.lang.String eventType, final int logLevel) Log an event from an event handler. v view - Control from event handler. v eventType - Event type of event handler. v logLevel - Log level for TeaLeaf library. Returns True/False whether it was able to log event. logCustomEvent public static java.lang.Boolean logCustomEvent(final java.lang.String eventName) public static java.lang.Boolean logCustomEvent(final java.lang.String eventName, final int logLevel)public static java.lang.Boolean logCustomEvent(final java.lang.String eventName, final Chapter 6. Reference 121 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. logSpinnerEvent public static Boolean logSpinnerEvent(final View view, final String eventType, final Spinner spinner) Logs an event from an event handler that has TextView data that needs to be extracted from a spinner object and nested layouts. The following parameters are used with the API. 122 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide v view - View control from the event handler. v eventType - The event type of the event handler. v spinner -: Spinner control type. The API returns as true when it has successfully logged an event. 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. Chapter 6. Reference 123 logScreenLayoutOnCreate public static Boolean logScreenLayoutOnCreate(final Activity activity, final String name) Log the layout of the activity with OnGlobalLayoutListener to know when the view is complete. v activity - Activity to be logged. v name - Name of the layout. 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. 124 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Returns long: The current application context offset. registerFormField public static Boolean registerFormField(final View formField, final Activity activity) public static Boolean registerFormField(final View formField, final Activity activity, final int logLevel) Register form field that helps get statistics. v formField - Form field to register. v activity - Activity that has form field. v logLevel - Log level for library. Returns True/False whether form field was registered. isApplicationInBackground public static Boolean isApplicationInBackground() Returns whether application was moved to background by not having any activity that is displayed in the foreground. Returns True/False whether application was moved to background. Reference Table 30. Tealeaf class Package Class Description com.tl.uic.app “UICActivity class” on page 113 UICActivity used to help control library. “UICApplication class” on page 115 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 Extends DefaultHttpClient to monitor when a URL was requested TLHttpRequestInterceptor class Extends HttpRequestInterceptor to add headers for sessionization TLHttpResponseInterceptor class Extends HttpResponseInterceptor to acquire details for the connection object “UICWebView class” on page 126 WebView used to add session ID to header requests. “UICWebChromeClient Class” on page 128 Extends WebChromeClient to monitor when browser has finished render, after which screen capture is enabled com.tl.uic.webkit Chapter 6. Reference 125 Table 30. Tealeaf class (continued) Package Class Description “UICWebViewClient Class” on page 129 Extends WebViewClient to monitor when the URL was loaded to add headers for sessionization UICWebView class The com.tl.uic.webkit.UICWebView class extends android.webkit.WebView. You use UICWebView to add a session ID to header requests for purposes of sessionization. This class also adds a connection object to provide information of WebView. Method detail getEndLoad public Date getEndLoad() When page finished loading. Returns Date: When page finished loading. setEndLoad public void setEndLoad(final Date endLoad) 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() 126 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Initial time from the connection. Returns Date: Initial time from the connection. setInitTime public void setInitTime (final Date initTime) Initial time from the connection. InitTime - Initial time from the connection. getResponseTime public long getResponseTime() Response time from the connection. long: Response time from the connection. setResponseTime public void setResponseTime (final long responseTime) Response time from the connection. ResponseTime - Response time from the connection. logConnection public void logConnection() Logs the current connection time of the webview. Reference Table 31. UICWebView Class Package Class Description com.tl.uic.app “UICActivity class” on page 113 UICActivity used to help control IBM Tealeaf Android SDK library. “UICApplication class” on page 115 Application that is used to help control IBM Tealeaf Android SDK library. com.tl.uic “Tealeaf class” on page 116 IBM Tealeaf Android SDK library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class Extends HttpRequestInterceptor to add Android SDK headers for sessionization. TLHttpResponseInterceptor class Extends HttpResponseInterceptor to acquire details for the Android SDK connection object. Chapter 6. Reference 127 Table 31. UICWebView Class (continued) Package Class Description com.tl.uic.webkit UICWebView WebView used to add session ID to header requests. “UICWebChromeClient Class” Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. “UICWebViewClient Class” on page 129 Extends WebViewClient to monitor when the URL loaded to add Android SDK headers for sessionization. UICWebChromeClient Class The com.tl.uic.webkit.UICWebChromeClient class extends android.webkit.WebChromeClient. You use UICWebChromeClient to monitor when progress of the browser finished in order to capture a screen capture of the device screen. Methods overridden v onProgressChanged Reference Table 32. UICWebChromeClient class 128 Package Class Description com.tl.uic.app “UICActivity class” on page 113 UICActivity used to help control IBM Tealeaf Android SDK library. “UICApplication class” on page 115 Application that is used to help control IBM Tealeaf Android SDK library. com.tl.uic “Tealeaf class” on page 116 IBM Tealeaf Android SDK library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Table 32. UICWebChromeClient class (continued) Package com.tl.uic.webkit Class Description TLHttpResponseInterceptor class Extends HttpResponseInterceptor to acquire details for the IBM Tealeaf connection object. “UICWebView class” on page 126 WebView used to add session ID to header requests. UICWebChromeClient Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. “UICWebViewClient Class” 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 33. UICWebViewClient class Package Class Description com.tl.uic.app “UICActivity class” on page 113 UICActivity used to help control IBM Tealeaf Android SDK library. “UICApplication class” on page 115 Application that is used to help control IBM Tealeaf Android SDK library. com.tl.uic “Tealeaf class” on page 116 IBM Tealeaf Android SDK library that is used to capture user actions. com.tl.uic.http TLDefaultHttpClient class Extends DefaultHttpClient to monitor when a URL was requested. TLHttpRequestInterceptor class Extends HttpRequestInterceptor to add IBM Tealeaf headers for sessionization. TLHttpResponseInterceptor class Extends HttpResponseInterceptor to acquire details for the IBM Tealeaf connection object. com.tl.uic.webkit “UICWebView class” on page 126 WebView used to add session ID to header requests. Chapter 6. Reference 129 Table 33. UICWebViewClient class (continued) Package 130 Class Description “UICWebChromeClient Class” on page 128 Extends WebChromeClient to monitor when browser finished render after which screen capture is enabled. UICWebViewClient Extends WebViewClient to monitor when the URL loaded in to add IBM Tealeaf headers for sessionization. IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 7. Sample Code This chapter contains sample code for IBM Tealeaf Android SDK. How to instrument TextView based controls Because TextView based controls are used for text fields, to get dwell time and other data you instrument the OnFocusChangeListener to know when a user starts and completes typing. // Get TextView based control final EditText nameEditText = (EditText) findViewById(R.id.nameEditText); // Create a OnFocusChangeListener OnFocusChangeListener focusListen = new OnFocusChangeListener () { public void onFocusChange(View view, boolean hasFocus){ if(hasFocus == false){ Tealeaf.logEvent(view, Tealeaf.TLF_ON_FOCUS_CHANGE_OUT); } else{ Tealeaf.logEvent(view, Tealeaf.TLF_ON_FOCUS_CHANGE_IN); } } }); // Set OnFocusChangeListener on TextView based control nameEditText.setOnFocusChangeListener(focusListen); // Register TextView based control Tealeaf.registerFormField(nameEditText, this); How to instrument ExpandableListView based controls For ExpandableListView controls, in order to know when a user expands or collapses a control you instrument the OnGroupCollapseListener and OnGroupExpandListener. // Get ExpandableListView based control final ExpandableListView elv = (ExpandableListView) findViewById(R.id.elv); elv.setOnChildClickListener(new OnChildClickListener() { public boolean onChildClick(ExpandableListView parent, View view, int groupPosition, int childPosition, long id) { Tealeaf.logEvent(view); return true; } }); elv.setOnGroupCollapseListener(new OnGroupCollapseListener() { public void onGroupCollapse(int groupPosition) { Tealeaf.logEvent(elv, Tealeaf.TLF_ON_GROUP_COLLAPSE); } }); elv.setOnGroupExpandListener(new OnGroupExpandListener(){ public void onGroupExpand(int groupPosition) { Tealeaf.logEvent(elv, Tealeaf.TLF_ON_GROUP_EXPAND); } }); © Copyright IBM Corp. 1999, 2016 131 How to instrument SlidingDrawer based controls For SlidingDrawer controls, to know when a user opens or closes a control you instrument the OnDrawerOpenListener and OnDrawerCloseListener. // Get SlidingDrawer based control final SlidingDrawer sd = (SlidingDrawer) findViewById(R.id.sd); sd.setOnDrawerOpenListener(new OnDrawerOpenListener() { public void onDrawerOpened(){ Tealeaf.logEvent(slidingDrawer_c5, Tealeaf.TLF_ON_DRAWER_OPENED); } }); sd.setOnDrawerCloseListener(new OnDrawerCloseListener(){ public void onDrawerClosed(){ Tealeaf.logEvent(slidingDrawer_c5, Tealeaf.TLF_ON_DRAWER_CLOSED); } }); How to mask controls Custom masking is a feature that matches specified IDs and regular expressions and then does character substitutions. In the example that follows, custom masking converts actual values to the letters that are supplied as replacements. If custom masking is set to false, it returns an empty string. You specify masking in the TLFConfigurableItem.properties file that is in the assets folder of the Android application. #Masking settings HasMasking=true #It can be a series of ids and regular expressions comma delimited MaskIdList=com.tealeaf.sp:id\/EditText*,com.tealeaf.sp:id\/login.password #If set to false it will return an empty string HasCustomMask=true #It will turn small letters to value given SensitiveSmallCaseAlphabet=x #It will turn capital letters to value given SensitiveCapitalCaseAlphabet=X #It will turn symbols to value given SensitiveSymbol=# #It will turn digits to value given SensitiveNumber=9 How to implement AdvertisingId in your application to capture Google Advertising ID (GAID) data Tealeaf can capture Google Advertising ID (GAID) data using AdvertisingId. The Google Play services advertising ID is a unique, user-resettable ID for advertising. The advertising ID gives users better controls and provides developers with a standard system to continue to monetize their apps. The advertising ID also gives users the ability to reset their identifier or opt out of personalized ads within Google Play applications. Complete the following steps to enable the ability to capture GAID data in your application: 1. Open AndroidManifest.xml, add the following snippet to the application section. <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" /> 132 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide 2. Open the app.gradle file for your application and add the following snippet to add the Google Play Service ads library. dependencies { // Requires for Google Play ads library compile ’com.google.android.gms:play-services-ads:9.4.0’ ... } The following example shows the JSON data with the implemented advertisingId. "clientEnvironment": { "osVersion": "5.0", "height": 1920, "width": 1080, "deviceWidth": 360, "deviceHeight": 640, "pixelDensity": 3, "mobileEnvironment": { "totalStorage": 6619593, "totalMemory": 369287168, "locale": "English (United States)", "language": "English", "manufacturer": "samsung", "deviceModel": "SM-N900V", "appName": "AuroraAuto", "appVersion": "1.0", "deviceId": "", "orientationType": "PORTRAIT", "android": {}, "advertisingId": "567eca34-2ea3-4f80-9436-ea63a7abc5b0" "osType": "Android", "orientation": 0 } }, If the end user has chosen to opt out of ads, advertisingId returns the following value: “advertisingId”: “N/A” Server-Side KillSwitch Sampling Function When the KillSwitch feature is enabled in the client configuration, the Framework queries the KillSwitch URL to determine whether to enable or disable the framework for that session. The KillSwitch URL can be .aspx, .jsp or .php. If the Android logging framework is disabled, then the session is not captured and is excluded from the sampled data. The KillSwitch URL returns 1 to enable the Framework and 0 to disable the Framework. Each KillSwitch URL has a corresponding web.config configuration file. Sampling function examples for ASPX These examples show the killswitch.aspx and web.config configuration file for ASPX Example killswitch.aspx This example shows the killswitch.aspx: Chapter 7. Sample Code 133 <%@ Page Language="C#" AutoEventWireup="true"%> <script runat="server"> public int Sampler() { Random rand = new Random(); int nextRandom = rand.Next(1,100); int samplepercent = Convert.ToInt32(ConfigurationManager.AppSettings ["rate"]); if(nextRandom <= samplepercent){ return 1; } else{ return0; } } </script> <% if (ConfigurationManager.AppSettings["killswitchtype"].Equals ("percentagesample")) { %> <%= Sampler() %> <% } else { } %> Example web.config configuration file for ASPX This example shows the web.config configuration file for the killswitch.aspx: <?xml version="1.0"?> <!-For more information on how to configure your ASP.NET application, please visit http://go.microsoft.com/fwlink/?LinkId=169433 --> <configuration> <appSettings> <add key="killswitchtype" value="percentagesample"/> <add key="rate" value="50"/> </appSettings> </configuration> Sampling Function for JSP These examples show the killswitch.jsp and web.config configuration file for JSP. For the JSP, if the: v request does not have parameters, then the client framework is always disabled. v id request parameter exists, it is used to check the whitelist. v randomsample parameter exists, the percentage rate from the config.properties file is used to determine how the server responds. Example killswitch.jsp This example shows the killswitch.jsp: <%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <%@page import="java.util.Properties"%> <%@page import="java.util.Date" %> <%@ page import="java.net.*"%> <%@ page import="java.io.*" errorPage=""%> <% InputStream stream = application .getResourceAsStream("/config.properties"); 134 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Properties props = new Properties(); props.load(stream); Boolean DEBUG = false; DEBUG = ("true").equals(props.getProperty("debug")); String id = request.getParameter("id"); String randomsample = request.getParameter("randomsample"); String killSwitchResponse = ""; String debugstr = ""; // white list if (id != null && !id.isEmpty()) { InputStream whitestream = application.getResourceAsStream(props .getProperty("WhiteListFile")); BufferedReader input = new BufferedReader( new InputStreamReader(whitestream)); String line = ""; Boolean match = false; while ((line = input.readLine()) != null) { line = line.trim(); if (line.equals(id)) { killSwitchResponse = "1"; match = true; break; } } input.close(); if (!match) { killSwitchResponse = "0"; } } // If kill switch is by sample rate else if (randomsample != null) { int rand = (int) (Math.random() * 100); int sampleRate = Integer.parseInt(props .getProperty("samplerate")); if (rand <= sampleRate) { killSwitchResponse = "1"; } else { killSwitchResponse = "0"; } } else { killSwitchResponse = "0"; } out.print(killSwitchResponse); //always give the path from root. This way it almost always works. String nameOfTextFile = props.getProperty("logfile"); PrintWriter pw; if (DEBUG) { try { pw = new PrintWriter(new FileOutputStream(nameOfTextFile, true)); Date date = new java.util.Date(); debugstr = date.toString() + "\t"; if (request.getQueryString() != null) { debugstr += request.getQueryString(); } if("0".equals(killSwitchResponse)) pw.println(debugstr + "\tDisable"); else pw.println(debugstr + "\tEnable"); //clean up pw.close(); Chapter 7. Sample Code 135 } catch (IOException e) { out.println(e.getMessage()); } } %> Example web.config configuration file This example shows the web.config configuration file for the killswitch.jsp: WhiteListFile=whitelist.txt samplerate =50 debug=true logfile=/killswitchlog.txt Sampling Function for PHP These examples show the killswitch.php and web.config configuration file for PHP. Example killswitch.php This example shows the killswitch.php: <?php $ini_array = parse_ini_file("config.ini", true); //print_r($ini_array); // if sample by percent if($ini_array[’configtype’][’killswitchtype’] === ’percentagesample’){ $sampleRate = intval($ini_array[’percentagesample’][’rate’]); killbysamplerate($sampleRate); } // if sample by whitelist else { } function killbysamplerate($sampleRate){ $randomnumber = rand(1,100); if($randomnumber <= $sampleRate){ echo ’1’; } else { echo ’0’; } } function killbywhitelist($whitelistpath){ } ?> Example web.config configuration file This example shows the web.config configuration file for the killswitch.php: ; This is a sample configuration file ; Comments start with ’;’, as in php.ini [configtype] killswitchtype=percentagesample [percentagesample] rate = 50 136 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide [whitelist] x y z JSON message type schemas and examples JSON messages are categorized by type for processing. Tealeaf supports the following JSON message types. Message header properties All messages contain message header properties consisting of two properties that contain the message type and the time that is offset from the start of the session in milliseconds. All time measurements in the JSON object schema are in milliseconds. Message list This table lists and describes the supported JSON message types: Table 34. Schema by Message Type Type Message Type Description 1 “Client state (Type 1) messages” on page 139 Any object that shows the current state of client. 2 “ScreenView (Type 2) messages” on page 141 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. 3 “Connections (Type 3) messages” on Any request or response that the page 143 application performs during capture. 4 “Control (Type 4) messages” on page User interface control that fires an 144 event to which Tealeaf listens for capture. 5 “Custom Event (Type 5) messages” on page 147 Any custom log event from any location in application. 6 “Exception (Type 6) messages” on page 148 Any exception that the application can throw. 7 “Performance (Type 7) messages” on Performance data from a browser. page 149 8 “Web Storage (Type 8) messages” on Any object that contains information page 150 about local storage information on the browser. 9 “Overstat Hover Event (Type 9) messages” on page 151 Any object that contains information about mouse hover and hover-to-click activity. 10 “Layout (Type 10) messages” on page 151 Any message that shows the current display layout of a native page. 11 “Gesture (Type 11) messages” on page 154 Any message that shows a gesture that fires a higher touch event that Tealeaf listens to for capture. Chapter 7. Sample Code 137 Table 34. Schema by Message Type (continued) Type Message Type Description 12 “DOM Capture (Type 12) message example” on page 166 Any object that contains serialized HTML data (DOM snapshot) of the page. 13 “GeoLocation (Type 13) messages” on page 168 Messages that contain the geolocation information about the device. 14 “Cookie (Type 14) message schema” on page 168 Messages that contain the cookie data for the application. Message header properties All messages contain message header properties consisting of two properties that contain the message type and the time that is offset from the start of the session in milliseconds. All time measurements in the JSON object schema are in milliseconds. Message header properties schema This example shows the schema for the JSON message headers. "offset": { "title": "Milliseconds offset from start of stream", "type": "integer", "required": true },"screenViewOffset": { "title": "Milliseconds offset from start of ScreenView", "type": "integer", "required": true },"count": { "title": "The number of the message being sent", "type": "integer", "required": only used for UIC },"fromWeb": { "title": "Used to identify if it came from Web or Native application", "type": "boolean", "required": true },"webviewId": { "title": "Used to identify which webview it came from. This is only used when fromWeb is true and it is a hybrid application ", "type":"string", "required": true only when fromWeb is true and it is a hybrid application },"type": { "title": "Message header type", "type": [ { "enum": [1], description: "CLIENT_STATE" }, "enum": [2], description: "APPLICATION_CONTEXT" }], "enum": [3], description: "CONNECTION" }, "enum": [4], description: "CONTROL" }, "enum": [5], description: "CUSTOM_EVENT" }], "enum": [6], 138 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide description: "EXCEPTION" }], "required": true }, Client state (Type 1) messages Client state messages are delivered on a schedule basis or on changes to the environment state on the client. These are Type 1 JSON messages. Note: Replay of client state messages is not supported, except for scroll events. Replay of scroll events that are captured from the client is supported for mobile sessions only in BBR only. See Search and Replay for Mobile Web. Client State (Type 1) message schema This is the schema for the Client State (Type 1) messages. { "$ref" : "MessageHeader", "mobileState": { "description": "Logical page being loaded for iOS and Android", "type": "object", "properties": { "orientation": { "title": "Current orientation of the device", "type": "integer", "required": true }, "freeStorage": { "title": "Amount of available storage in Mbytes", "type": "number", "required": true }, "androidState": { "description": "Current state in an Android device", "type": "object", "properties": { "keyboardState": { "title": "Current keyboard state", "type": [ { "enum": [0], description: "Keyboard not hidden" }, "enum": [1], 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", Chapter 7. Sample Code 139 "required": true }, "carrier": { "title": "Carrier of device", "type": "string", "required": true }, "networkReachability": { "title": "Current network reachability", "type": [ { "enum": [0], description: "Unknown" }, "enum": [1], description: "NotReachable" }, "enum": [2], description: "ReachableViaWIFI" }, "enum": [3], description: "ReachableViaWWAN" }], "required": true }, "ip": { "title": "Ip address of device", "type": "string", "required": true } }, "additionalProperties" : false "clientState": { "description": "Logical web page being loaded for UIC", "type": "object", "properties": { "pageWidth": { "title": "Width of the document of the web page", "type": "integer", "required": true }, "pageHeight": { "title": "Height of the document of the web page", "type": "integer", "required": true }, "viewPortWidth": { "title": "Width of viewport", "type": "integer", "required": true }, "viewPortHeight": { "title": "Height of viewport", "type": "integer", "required": true }, "viewPortX": { "title": "x position of scrollbar on viewport", "type": "integer", "required": true }, "viewPortY": { "title": "y position of scrollbar on viewport", "type": "integer", "required": true }, "event": { "title": "event that triggered the client state", 140 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "type": "string", "required": true }, "deviceScale": { "title": "scaling factor for fitting page into window for replay", "type": "integer", "required": true }, "viewTime": { "title": "time in milliseconds user was on the event triggered", "type": "integer", "required": true }, "viewPortXStart": { "title": "initial start x position of scrollbar on viewport", "type": "integer", "required": only used in scroll events }, "viewPortYStart": { "title": "initial start y position of scrollbar on viewport", "type": "integer", "required": only used in scroll events }, }, "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": 33972224, "androidState": { "keyboardState": 0 }, "battery": 50, "freeMemory": 64630784, "connectionType": "UMTS", "carrier": "Android", "networkReachability": "ReachableViaWWAN", "ip": "0.0.0.0" } } ScreenView (Type 2) messages ScreenView messages indicate steps in a visitor's experience with your application. These steps can be logical page views in a web application, screen changes in a mobile application, or steps in a business process. ScreenView messages are Type 2 JSON messages. In Release 8.5 and earlier, these messages were called Application Context messages. ScreenView (Type 2) message schema This is the schema for the ScreenView (Type 2) JSON messages. Chapter 7. Sample Code 141 { "$ref" : "MessageHeader", "dcid": { "title": "Unique identifier that is used to match the corresponding DOM Capture message associated with this message.", "type": "string", "required": false }, "screenview/context": { "description": "Logical page being loaded or unloaded", "type": "object", "properties": { "type": { "title": "Type of application context - LOAD or UNLOAD", "type": "string", "required": true }, "name": { "title": "Name of the logical page. This is given by customer or it uses name of the class used by the page.", "type": "string", "required": true }, "url": { "title": "URL path of the logical page", "type": "string", "required": false only used in UIC }, "host": { "title": "URL Host of the logical page", "type": "string", "required": false only used in UIC }, "referrer": { "title": "Previous logical page loaded, only used in LOAD", "type": "string", "required": false }, "referrerUrl": { "title": "Url of the previous logical page loaded", "type": "string", "required": false, not used in UIC } }, "additionalProperties" : false, "required": false } } ScreenView (Type 2) message example This is an example of a ScreenView (Type 2) message. This example contains three ScreenView messages, indicating page load and page unload events. { "offset": 124, "contextOffset": 4556, "type": 2, "context": { "type": "LOAD", "name": "PAGE 2", "referrer": "PAGE 1" } } { 142 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "type": 2, "offset": 19216 "context": { "type": "UNLOAD", "name": "PAGE 2" } } { "type": 2, "offset": 2144, "contextOffset": 0, "count": 9, "fromWeb": true, "webviewId": "webview1", "screenview": { "type": "LOAD", "name": "Ford", "url": "/dynamic/ford.aspx", "host": "http://www.cartest.com", "referrer": "BMW", "referrerUrl": "/dynamic/bmw.aspx" } } Connections (Type 3) messages Connection messages provide information about how requests or responses are managed by the client application. Connections messages are Type 3 JSON messages. Connections (Type 3) messages schema This is the schema for Connections (Type 3) JSON messages. { "$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 Chapter 7. Sample Code 143 }, "loadTime": { "title": "Load time from connection", "type": "number", "required": true } }, "additionalProperties" : false } } Connections (Type 3) message example This example shows the Connections (Type 3) JSON message. { "offset": 03829, "type": 3, "screenViewOffset": 45560, "type": 3, "connection": { "statusCode": 200, "responseDataSize": 0272, "initTime": 01333669478556, "responseTime": 02237, "url": "http://google.com", "url": "/store/js/tealeaf/ TeaLeafTarget.php??width=540&height=960&orientation=0", "loadTime": 0 } } Control (Type 4) messages Control messages are used to log user action and behavior. These messages consist of a control identifier and a value that is returned by the identified control. Control messages are Type 4 JSON messages. The control identifiers are mapped to specific controls for the submitting client framework. The value can be a number, a text string, or structured data. Control (Type 4) message schema This is the schema for Control (Type 4) messages. The X and Y properties are not present in the UI Capture frameworks. { "$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 }, 144 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "y": { "title": "Y of the control", "type": "integer", "required": true }, "height": { "title": "height of control", "type": "integer", "required": true }, "width": { "title": "width of control", "type": "integer", "required": true }, "relXY": { "title": "relative X & Y ratio that can be from 0 to 1 with a default value of 0.5", "type": "string", "required": true for click events }, }, "additionalProperties" : false } "id": { "title": "Id/Name/Tag of control", "type": "string", "required": true }, idType": { "title": "Indicates what id is based on: Native id (e.g. HTML ’id’ attribute): -1, xPath: -2, or Custom attribute for UIC and Hashcode value for Native: -3, or xPath for Native iOS/Android: -4", "type": "integer", "required": true }, "dwell": { "title": "Dwell time of control", "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", Chapter 7. Sample Code 145 "required": true }, "tlType": { "title": "tlType of control that normalizes the control type for eventing", "type": "string", "required": true }, "prevState": { "title": "Previous state of control", "type": "object", "required": true, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } }, "currState": { "title": "Current state of control", "type": "object", "required": true, "properties": { "?": { // 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 example shows a control with an idType of XPATH, which means no id was assigned to the control in the application so Tealeaf traversed the layout and created an XPATH id for the control:, 146 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide { "screenviewOffset":380, "target":{ "id":"[KV,0]", "position":{ "y":331, "x":0, "width":320, "height":202 }, "idType":"-4", "currState":{ "y":"0", "x":"0" }, "style":{ "paddingTop":2, "textBGAlphaColor":255, "bgAlphaColor":255, "paddingBottom":0, "paddingLeft":0, "hidden":false, "paddingRight":0 }, "subType":"View", "type":"KeyboardView", "tlType":"keyboard" }, "type":4, "offset":728, "count":3, "fromWeb":false, "event":{ "type":"UIKeyboardDidShowNotification", "tlEvent": "kbDisplayed" } }, Custom Event (Type 5) messages The Custom Event messages are used to custom log any event from any place in the application. Custom Event messages are Type 5 JSON messages. Custom Event (Type 5) message schema This is the schema for the Custom Event (Type 5) messages. The only required field is the name of the custom event (name value). Application-specific code must be created to process this logged message type. { "$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", Chapter 7. Sample Code 147 "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": 56734 } } } Exception (Type 6) messages The exceptions messages type records the name and description of an exception occurring on the client application. Exception messages are Type 6 JSON messages. Exception (Type 6) message schema This is the schema for the Exception (Type 6) messages. { "$ref" : "MessageHeader", "exception": { "description": "Exception description message", "type": "object", "properties": { "description": { "title": "Exception message from api call", "type": "string", "required": true }, "name": { "title": "Exception name/type", "type": "string", "required": true, not for UIC }, "stackTrace": { "title": "Exception stacktrace given by framework", "type": "string", "required": true, not for UIC }, "url": { "title": "Url where exception ocurred", "type": "string", "required": true for UIC }, "fileName": { "title": "File name where exception ocurred", "type": "string", "required": true for iOS, not for UIC }, 148 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "line": { "title": "Line number where eception occurred.", "type": "string", "required": true for UIC and iOS }, "unhandled": { "title": "Whether exception had a try catch around it.", "type": "boolean", "required": true, not for UIC }, "data": { "title": "User defined data being passed with user info from system", "type": "object", "required": true for iOS, not for UIC "properties": { "userInfo": { "type": "object", "title": "OS information from error or exception", "required": iOS optional (data is JSON serializable or not) }, "message": { "type": "string", "title":"User supplied message on error event", "required":iOS optional (not on exceptions required on error) } }, }, }, "additionalProperties" : false } } Exception (Type 6) message example This is an example of an Exception (Type 6) message. This example exception indicates an attempt to read a property named 'type' of a variable or value which is undefined. { "type" : 6, "offset" : 4606, "screenviewOffset" : 4603, "count" : 3, "fromWeb" : true, "exception" : { "description" : "Uncaught TypeError: Cannot read property ’type’ of undefined", "url" : "http://www.xyz.com/js/badscript.js", "line" : 258 } } Performance (Type 7) messages Performance messages show performance data from a browser. Performance messages are Type 7 JSON messages. Performance (Type 7) message schema This is the schema for Performance (Type 7) messages. Chapter 7. Sample Code 149 { "$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 } } } 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”, } 150 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Web Storage (Type 8) message example This is an example of a Web Storage (Type 8) message. { type: 8, offset: 25, screenviewOffset: 23, count: 2, fromWeb: true, webStorage: { key: "vistCount" value: "5" } } Overstat Hover Event (Type 9) messages Overstat® Hover Event messages are any object containing information about mouse hover and hover-to-click activity. Overstat Hover Event messages are Type 9 JSON messages. Overstat Hover Event (Type 9) message schema This is the schema for Overstat Hover Event (Type 9) messages "$ref" : "MessageHeader", event: { xPath: "string", hoverDuration: int, hoverToClick: boolean, gridPosition: { x: int, y: int } } Overstat Hover Event (Type 9) message example This is an example of a Overstat Hover Event (Type 9) message. { type: 9, offset: 25, screenviewOffset: 23, count: 2, fromWeb: true, event: { xPath: "[\"ii\"]", hoverDuration: 5457, hoverToClick: false, gridPosition: { x: 3, y: 2 } } Layout (Type 10) messages Layout messages show the current display layout of a native page. Layout messages are Type 10 JSON messages. Layout (Type 10) message schema This is the schema for Layout (Type 10) messages. "$ref" : "MessageHeader", "version": { "description": "Message Version, must be in x.x format", "type": "string", "required": true Chapter 7. Sample Code 151 }, "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 "title": "Additional data in string format", "type": "string", "required": false } } }, "style" : { "title": "Style of the control", "type": "object", 152 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "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, "version" : "1.0", "orientation" : 0, "deviceHeight": 592, "deviceWidth": 360, "layout": { "name": "loginPage", "class": "loginPageActivty", "controls": [ { "position": { "y": 38, "height": 96, "width": 720, "x": 0 }, "id": "com.tl.uiwidget:id\/userNameLabel", "idType": -1, "type": "UILabel", "subType": "UIView", Chapter 7. Sample Code 153 "tlType": "label", "currState": { "text": "User name*" }, "style": { "textColor": 16777215, "textAlphaColor": 1, "textBGColor": 0, "textBGAlphaColor": 0, "bgColor": 0, "bgAlphaColor": 0 } }, {...}, {...} ] } } Gesture (Type 11) messages Gesture messages are used to log user action and behavior. A Gesture message consists of a control identifier and a the value returned by that control. The control identifiers are mapped to specific controls on the client logging platform. The value can be a number, a text string or structured data. Gesture messages are Type 12 JSON messages. Gesture (Type 11) message schema This is the schema for Gesture (Type 11) messages. Touch events This is a JSON object that represents a gesture finger that is linked to control underneath the finger. It is reused in targets property of gesture type 11.This is the schema for touch events: { "$ref" : "MessageHeader", "focusInOffset": { "title": "Milliseconds offset from offset for when focusIn of text fields occur", "type": "integer", "required": false }, "target": { "description": "Control being logged", "type": "object", "properties": { "position": { "description": "Position of control being logged", "type": "object", "properties": { "x": { "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", 154 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "required": true }, "width": { "title": "width of control", "type": "integer", "required": true }, "relXY": { "title": "relative X & Y ratio that can be from 0 to 1 with a default value of 0.5", "type": "string", "required": true for click events }, "scrollX": { "title": "scroll X of the page", "type": "integer", "required": true }, "scrollY": { "title": "scroll Y of the page", "type": "integer", "required": true }, }, "additionalProperties" : false } "id": { "title": "Id/Name/Tag of control", "type": "string", "required": true }, "idType":{ "title": "Indicates what id is based on: Native id (e.g. HTML ’id’ attribute): -1, xPath: -2, or Custom attribute for UIC and Hashcode value for Native: -3, or xPath for Native iOS/Android: -4", "type": "integer", "required": true }, "dwell": { "title": "Dwell time of control", "type": "integer value that is in milliseconds", "required": false }, "focusInOffset": { "title": "Offset when control got focus", "type": "integer value that is in milliseconds", "required": true in UIC }, "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 }, Chapter 7. Sample Code 155 "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": false, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } } }, "currState": { "title": "Current state of control", "type": "object", "required": true, "properties": { "?": { // 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": false }, "subType": { "title": "Subtype of event", "type": "string", "required": false } }, "additionalProperties" : false }} 156 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Tap event schema This contains only one touch object. 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", "required": true "items": { "description": "Touch objects per finger starting with intial and ends with last object when finger is lifted from device.", Chapter 7. Sample Code 157 "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" } } }, "direction": { "title": "Direction of pinch which can be open or close", 158 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "type": "string", "required": true } } Gesture (Type 11) message example These are examples of UIC SDK Gesture (Type 11) messages. Tap events This example is a gesture message for a tap event: { "fromWeb": false, "type": 11, "offset": 46788, "screenviewOffset": 42208, "count": 14, "event": { "type": "ACTION_DOWN", "tlEvent": "tap" }, "touches": [ [ { "position": { "x": 179, "y": 543 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.17,0.93" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] } Double tap events This example is a gesture message for a double tap event: { "fromWeb": false, "type": 11, "offset": 49585, "screenviewOffset": 45005, "count": 15, "event": { "type": "ACTION_DOWN", "tlEvent": "doubleTap" }, "touches": [ [ { "position": { Chapter 7. Sample Code 159 "x": 182, "y": 520 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.17,0.8" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] } Tap hold events This example is a gesture message for a tap hold event: { "fromWeb": false, "type": 11, "offset": 52389, "screenviewOffset": 47809, "count": 16, "event": { "type": "ACTION_DOWN", "tlEvent": "tapHold" }, "touches": [ [ { "position": { "x": 182, "y": 536 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.17,0.89" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] } 160 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Swipe event example The swipe event contains only one touch object which will be the initial location with its corresponding direction and velocity. This example is a message for a swipe event: { "fromWeb": false, "type": 11, "offset": 54409, "screenviewOffset": 49829, "count": 17, "event": { "type": "ACTION_DOWN", "tlEvent": "swipe" }, "direction": "right", "velocityX": 7762.8466796875, "velocityY": 127.47991943359375, "touches": [ [ { "position": { "x": 75, "y": 538 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.07,0.9" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } }, { "position": { "x": 212, "y": 526 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.2,0.84" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] } Chapter 7. Sample Code 161 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" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } }, { "position": { "y": 388, "x": 400 }, "control": { "position": { "height": 100, "width": 100, "relXY": "0.4,0.7" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } } ], [ { "position": { "y": 388, "x": 800 }, "control": { "position": { 162 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "height": 100, "width": 100, "relXY": "0.6,0.8" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } }, { "position": { "y": 388, "x": 500 }, "control": { "position": { "height": 100, "width": 100, "relXY": "0.4,0.7" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } } ] ], "direction": "close" } 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 } "fullDOM": { "title": "Flag indicating if the contents of this message contain a full DOM or a DOM diff.", "type": "boolean", "required": false }, "charset": { "title": "Browser reported charset of the document.", "type": "string", "required": false }, Chapter 7. Sample Code 163 "root": { "title": "Serialized HTML of the document.", "type": "string", "required": false }, "diffs": { "title": "List of DOM diff entries. Each entry can contain a HTML Diff or an attribute diff.", "type": "array", "required": false, "Item": { "title": "An object containing the DOM diff. The diff can be a HTML diff or an attribute diff.", "type": "object", "required": false, "properties": { "xpath": { "title": "The xpath of the node.", "type": "string", "required": true }, "root": { "title": "Serialized HTML of the node referred by the xpath. Presence of this property constitutes a HTML diff.", "type": "string", "required": false }, "attributes": { "title": "List of attribute diff entries. Each entry contains a single attribute diff corresponding to the node referred by the xpath. Presence of this property constitutes an attribute diff.", "type": "array", "required": false, "Item": { "title": "An object containing the attribute diff.", "type": "object", "required": true, "properties": { "name": { "title": "The attribute name.", "type": "string", "required": true }, "value": { "title": "The attribute value.", "type": "string", "required": true } } } } } } }, "eventOn": { "title": "Flag indicating if Tealeaf eventing should be enabled for this DOM Capture snapshot.", "type": "boolean", "required": false }, "url": { "title": "URL path of the snapshot document", "type": "string", "required": false }, 164 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "host": { "title": "URL Host of the snapshot document", "type": "string", "required": false }, "error": { "title": "Error message", "type": "string", "required": false }, "errorCode": { "title": "Error code corresponding to the error message.", "type": "integer", "required": false }, "frames": { "title": "Serialized HTML of any child frames of the document", "type": "array", "required": false, "Item": { "title": "An object containing serialized HTML of the frame", "type": "object", "required": false, "properties": { "tltid": { "title": "Unique identifier for this frame. Same tltid is added to the serialized HTML source of the parent." "type": "string", "required": true }, "charset": { "title": "Browser reported charset of the document.", "type": "string", "required": true }, "url": { "title": "URL path of the snapshot document", "type": "string", "required": true }, "host": { "title": "URL Host of the snapshot document", "type": "string", "required": true }, "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 } Chapter 7. Sample Code 165 DOM Capture (Type 12) message example This is an example of a DOM Capture (Type 12) message. This example shows a DOM message with full DOM capture enabled: { // DOM Capture messages use type 12 "type": 12, // The standard UIC message properties "offset": 16821, "screenviewOffset": 16817, "count": 5, "fromWeb": true, "domCapture": { "dcid": "dcid-3" "fullDOM":true "charset": "ISO-8859-1", "root": "<html><body><iframe id="greeting.html" tltid="tlt-4"/> </body></html>", "host": "http://www.uictest.com", "url": "/h4/dcTest.html", "eventOn": true, "frames": [ { "tltid": "tlt-4", "root": "<html><body>Hello, World!</body></html>", "charset": "ISO-8859-1", "host": "http://www.uictest.com", "url": "/h4/greeting.html" } ], "canvas": [] } } This example shows a DOM capture message with DOM diff enabled: { "type": 12, "offset": 13874, "screenviewOffset": 13861, "count": 6, "fromWeb": true, "domCapture": { "fullDOM": false, "diffs": [ { "xpath": "[[\"html\",0],[\"body\",0],[\"div\",1]]", "root": "<div class=\"bluebg\"><div><div>Input 1<input type=\"text\" name=\"ip-x-1\" value=\"\"></div></div></div>" } ], "dcid": "dcid-3.1437256358764", "eventOn": false } } DOM Diff (with HTML and attribute diff): { "type": 12, "offset": 5794, "screenviewOffset": 5777, 166 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide "count": 8, "fromWeb": true, "domCapture": { "fullDOM": false, "diffs": [ { "xpath": "[[\"html\",0],[\"body\",0],[\"div\",2],[\"div\",1]]", "root": "<div>Select List:<select name=\"select.pvt\"><option value=\"O1\" selected=\"selected\">1</option><option value=\"O2\">2</option> <option value=\"O3\">3</option></select></div>" }, { "xpath": "[[\"cb1\"]]", "attributes": [ { "name": "style", "value": "height: 13px; width: 13px; visibility: hidden;" } ] }, { "xpath": "[[\"container_1\"],[\"table\",0],[\"tbody\",0], [\"tr\",2],[\"td\",1],[\"select\",0]]", "attributes": [ { "name": "style", "value": "visibility: hidden;" } ] } ], "dcid": "dcid-3.1437256879815", "eventOn": false } } This example shows the error message when the captured DOM message length exceeds the configured threshold: { // DOM Capture messages use type 12 "type": 12, // The standard UIC message properties "offset": 16821, "screenviewOffset": 16817, "count": 5, "fromWeb": true, // The DOM Capture data is namespaced in the domCapture object "domCapture": { // The "error" contains the verbose error message explaining why the DOM Capture couldn’t be performed. "error": "Captured length (18045) exceeded limit (10000).", // The "errorCode" contains the numeric code for this error message. Currently, there is only 1 error message. "errorCode": 101, // The "dcid" property contains the unique string identifying this DOM Capture within the page instance. "dcid": "dcid-1.1414088027401" } } Chapter 7. Sample Code 167 GeoLocation (Type 13) messages A GeoLocation message logs a user's location information. The message consists of a control identifier and a GeoLocation value. If the user has given the permission to use location data, GeoLocation returns latitude, longitude, accuracy values. If the user has not given permission to use location data, GeoLocation returns an error code and error string. GeoLocation (Type 13) message schemas This is the schema for the GeoLocation (Type 13) JSON messages: This is the schema for messages from a device that the user has given permission to use location data: "$ref" : "MessageHeader", "geolocation": { "lat": double, "long": double, "accuracy": float } This is the schema for messages from a device that the user has not given permission to use location data: "$ref" : "MessageHeader", "geolocation": { "errorCode": int, "error": "string", } GeoLocation (Type 13) message examples This is an example of the GeoLocation (Type 13) JSON message. This is an example of a message from a device that the user has given permission to use location data: { "type": 13, "geolocation": { "lat": 37.5680, "long": -122.3292, "accuracy": 65 } } This is an example of a message from a device that the user has not given permission to use location data: { "type": 13, "geolocation": { "errorCode": 201, "error": "permission denied", } } Cookie (Type 14) message schema This is the schema that is used to capture cookie information from an application as name-value pairs. "$ref" : "MessageHeader", cookies: { cookieName: cookieValue} The following example records the cookie values after each screenview load. 168 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide { "type" : 14, "offset" : 5796, "screenviewOffset" : 10, "count" : 4, "fromWeb" : true, "cookies" :{ "cookieName1" : "valueA", "cookieName2": "valueB" } } Chapter 7. Sample Code 169 170 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 8. Troubleshooting Troubleshooting and debugging - enabling raw request and response headers For debugging purposes, it may be useful to include the raw request and the response headers in the data that is passed by the PCA to the Canister. This method is useful if you are not seeing any JSON data that is parsed in Tealeaf. Including these sections in your Tealeaf sessions can significantly increase the storage requirements for mobile sessions. These options should be enabled only for debugging purposes. In the PCA Pipeline tab, set the following properties: Setting Value Include Raw Request true Include Response Headers true See "PCA Web Console - Pipeline Tab" in the IBM Tealeaf Passive Capture Application Manual section. Troubleshooting - managing client-side issues The section that follows describes how the IBM Tealeaf Android SDK manages application crashes, exceptions, or other issues that can occur on the mobile device or the network. Exceptions or crashes Application exceptions are logged and reported to IBM Tealeaf in JSON format. For devices that run iOS, a transmission of the current exception to the server is attempted. A copy is added to the set of messages queued locally and is sent the next time that the application is started. For Android devices, all local data in the device is flushed. The exception object is transmitted to the server. Power failures A TL Library Error: File Not Found exception might be caused by disruption to the monitored application. If the user turned off the application or if it is closed, the posting task is disabled. When the application restarts, the library begins sending the queued JSON messages. However, if some of these reference images that are no longer available, the File Not Found error is generated. If power failures are a persistent problem, you can configure the client application to save to local disk at smaller intervals, sending to server at more frequent intervals. You can modify the local cache size and POSTs from the client. These settingssettings are managed with the configuration file. © Copyright IBM Corp. 1999, 2016 171 Kill switch If the device is unable to connect to the target page, the device does not capture data. Network issues If there are network connectivity issues, these events are logged as connection objects with details on the issues. v For GET issues as a result of application interruptions, an exception object is generated. v If the network connection is interrupted, user actions are saved and sent later. Low memory or local storage If low memory or low local storage conditions occur, a custom log message is generated. For devices that run iOS, user data is trimmed in memory until more memory becomes available. For Android devices, all collected data on the device is flushed, and the Android SDK is disabled for the device. 172 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Chapter 9. IBM Tealeaf documentation and help IBM Tealeaf provides documentation and help for users, developers, and administrators. Viewing product documentation All IBM Tealeaf product documentation is available at the following website: https://tealeaf.support.ibmcloud.com/ Use the information in the following table to view the product documentation for IBM Tealeaf: Table 35. Getting help To view... Do this... Product documentation On the IBM Tealeaf portal, go to ? > Product Documentation. IBM Tealeaf Knowledge Center On the IBM Tealeaf portal, go to ? > Product Documentation and select IBM Tealeaf Customer Experience in the ExperienceOne Knowledge Center. Help for a page on the IBM Tealeaf Portal On the IBM Tealeaf portal, go to ? > Help for This Page. Help for IBM Tealeaf CX PCA On the IBM Tealeaf CX PCA web interface, select Guide to access the IBM Tealeaf CX PCA Manual. Available documents for IBM Tealeaf products The following table is a list of available documents for all IBM Tealeaf products: Table 36. 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, 2016 173 Table 36. 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 IBM Tealeaf cxImpact User Manual v 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 v IBM Tealeaf cxReveal API Guide v IBM Tealeaf cxReveal User Manual IBM Tealeaf cxVerify v IBM Tealeaf cxVerify Installation Guide v IBM Tealeaf cxVerify User's Guide IBM Tealeaf cxView IBM Tealeaf cxView User's Guide IBM Tealeaf CX Mobile v IBM Tealeaf CX Mobile Android Logging Framework Guide v IBM Tealeaf Android Logging Framework Release Notes v IBM Tealeaf CX Mobile Administration Manual v IBM Tealeaf CX Mobile User Manual v IBM Tealeaf CX Mobile iOS Logging Framework Guide v IBM Tealeaf iOS Logging Framework Release Notes 174 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: © Copyright IBM Corp. 1999, 2016 175 IBM Bay Area Lab 1001 E Hillsdale Boulevard Foster City, California 94404 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. Trademarks IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml. 176 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide Privacy Policy Considerations IBM Software products, including software as a service solutions, ("Software Offerings") may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user or for other purposes. A cookie is a piece of data that a web site can send to your browser, which may then be stored on your computer as a tag that identifies your computer. In many cases, no personal information is collected by these cookies. If a Software Offering you are using enables you to collect personal information through cookies and similar technologies, we inform you about the specifics below. Depending upon the configurations deployed, this Software Offering may use session and persistent cookies that collect each user's user name, and other personal information for purposes of session management, enhanced user usability, or other usage tracking or functional purposes. These cookies can be disabled, but disabling them will also eliminate the functionality they enable. Various jurisdictions regulate the collection of personal information through cookies and similar technologies. If the configurations deployed for this Software Offering provide you as customer the ability to collect personal information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for providing notice and consent where appropriate. IBM requires that Clients (1) provide a clear and conspicuous link to Customer's website terms of use (e.g. privacy policy) which includes a link to IBM's and Client's data collection and use practices, (2) notify that cookies and clear gifs/web beacons are being placed on the visitor's computer by IBM on the Client's behalf along with an explanation of the purpose of such technology, and (3) to the extent required by law, obtain consent from website visitors prior to the placement of cookies and clear gifs/web beacons placed by Client or IBM on Client's behalf on website visitor's devices For more information about the use of various technologies, including cookies, for these purposes, See IBM's Online Privacy Statement at: http://www.ibm.com/ privacy/details/us/en section entitled "Cookies, Web Beacons and Other Technologies." Notices 177 178 IBM Tealeaf Android SDK: IBM Tealeaf Android SDK Guide IBM® Printed in USA